1/*
2 * Copyright (c) 2007 Mockito contributors
3 * This program is made available under the terms of the MIT License.
4 */
5package org.mockito;
6
7import java.lang.annotation.Documented;
8import java.lang.annotation.Retention;
9import java.lang.annotation.Target;
10
11import static java.lang.annotation.ElementType.FIELD;
12import static java.lang.annotation.RetentionPolicy.RUNTIME;
13
14/**
15 * Mark a field on which injection should be performed.
16 *
17 * <ul>
18 * <li>Allows shorthand mock and spy injection.</li>
19 * <li>Minimizes repetitive mock and spy injection.</li>
20 * </ul>
21 * <p>
22 * Mockito will try to inject mocks only either by constructor injection,
23 * setter injection, or property injection in order and as described below.
24 * If any of the following strategy fail, then Mockito <strong>won't report failure</strong>;
25 * i.e. you will have to provide dependencies yourself.
26 * <ol>
27 *     <li><strong>Constructor injection</strong>; the biggest constructor is chosen,
28 *     then arguments are resolved with mocks declared in the test only.
29 *     <p><u>Note:</u> If arguments can not be found, then null is passed.
30 *     If non-mockable types are wanted, then constructor injection won't happen.
31 *     In these cases, you will have to satisfy dependencies yourself.</p></li>
32 *
33 *     <li><strong>Property setter injection</strong>; mocks will first be resolved by type,
34 *     then, if there is several property of the same type, by the match of the property name and the mock name.
35 *     <p><u>Note 1:</u> If you have properties with the same type (or same erasure), it's better to name all &#064;Mock
36 *     annotated fields with the matching properties, otherwise Mockito might get confused and injection won't happen.</p>
37 *     <p><u>Note 2:</u> If &#064;InjectMocks instance wasn't initialized before and have a no-arg constructor,
38 *     then it will be initialized with this constructor.</p></li>
39 *
40 *     <li><strong>Field injection</strong>; mocks will first be resolved by type,
41 *     then, if there is several property of the same type, by the match of the field name and the mock name.
42 *     <p><u>Note 1:</u> If you have fields with the same type (or same erasure), it's better to name all &#064;Mock
43 *     annotated fields with the matching fields, otherwise Mockito might get confused and injection won't happen.</p>
44 *     <p><u>Note 2:</u> If &#064;InjectMocks instance wasn't initialized before and have a no-arg constructor,
45 *     then it will be initialized with this constructor.</p></li>
46 * </ol>
47 * </p>
48 *
49 * <p>
50 * Example:
51 * <pre class="code"><code class="java">
52 *   public class ArticleManagerTest extends SampleBaseTestCase {
53 *
54 *       &#064;Mock private ArticleCalculator calculator;
55 *       &#064;Mock(name = "database") private ArticleDatabase dbMock; // note the mock name attribute
56 *       &#064;Spy private UserProvider userProvider = new ConsumerUserProvider();
57 *
58 *       &#064;InjectMocks private ArticleManager manager;
59 *
60 *       &#064;Test public void shouldDoSomething() {
61 *           manager.initiateArticle();
62 *           verify(database).addListener(any(ArticleListener.class));
63 *       }
64 *   }
65 *
66 *   public class SampleBaseTestCase {
67 *
68 *       &#064;Before public void initMocks() {
69 *           MockitoAnnotations.initMocks(this);
70 *       }
71 *   }
72 * </code></pre>
73 * </p>
74 *
75 * <p>
76 * In the above example the field ArticleManager annotated with &#064;InjectMocks can have
77 * a parameterized constructor only or a no-arg constructor only, or both.
78 * All these constructors can be package protected, protected or private, however
79 * <u>Mockito cannot instantiate inner classes, local classes, abstract classes and of course interfaces.</u>
80 * <u>Beware of private nest static classes too.</u>
81 *
82 * <p>The same stands for setters or fields, they can be declared with private
83 * visibility, Mockito will see them through reflection.
84 * However fields that are static or final will be ignored.</p>
85 *
86 * <p>So on the field that needs injection, for example constructor injection will happen here :</p>
87 * <pre class="code"><code class="java">
88 *   public class ArticleManager {
89 *       ArticleManager(ArticleCalculator calculator, ArticleDatabase database) {
90 *           // parameterized constructor
91 *       }
92 *   }
93 * </code></pre>
94 *
95 * <p>Property setter injection will happen here :</p>
96 * <pre class="code"><code class="java">
97 *   public class ArticleManager {
98 *       // no-arg constructor
99 *       ArticleManager() {  }
100 *
101 *       // setter
102 *       void setDatabase(ArticleDatabase database) { }
103 *
104 *       // setter
105 *       void setCalculator(ArticleCalculator calculator) { }
106 *   }
107 * </code></pre>
108 *
109 * <p>Field injection will be used here :</p>
110 * <pre class="code"><code class="java">
111 *   public class ArticleManager {
112 *       private ArticleDatabase database;
113 *       private ArticleCalculator calculator;
114 *   }
115 * </code></pre>
116 * </p>
117 *
118 * <p>And finally, no injection will happen on the type in this case:</p>
119 * <pre class="code"><code class="java">
120 *   public class ArticleManager {
121 *       private ArticleDatabase database;
122 *       private ArticleCalculator calculator;
123 *
124 *       ArticleManager(ArticleObserver observer, boolean flag) {
125 *           // observer is not declared in the test above.
126 *           // flag is not mockable anyway
127 *       }
128 *   }
129 * </code></pre>
130 * </p>
131 *
132 *
133 * <p>
134 * Again, note that &#064;InjectMocks will only inject mocks/spies created using the &#64;Spy or &#64;Mock annotation.
135 * </p>
136 *
137 * <p>
138 * <strong><code>MockitoAnnotations.initMocks(this)</code></strong> method has to be called to initialize annotated objects.
139 * In above example, <code>initMocks()</code> is called in &#064;Before (JUnit4) method of test's base class.
140 * For JUnit3 <code>initMocks()</code> can go to <code>setup()</code> method of a base class.
141 * <strong>Instead</strong> you can also put initMocks() in your JUnit runner (&#064;RunWith) or use the built-in
142 * {@link org.mockito.runners.MockitoJUnitRunner}.
143 * </p>
144 *
145 * @see Mock
146 * @see Spy
147 * @see MockitoAnnotations#initMocks(Object)
148 * @see org.mockito.runners.MockitoJUnitRunner
149 * @since 1.8.3
150 */
151@Documented
152@Target(FIELD)
153@Retention(RUNTIME)
154public @interface InjectMocks {}
155