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