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 @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 @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 @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 @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 * @Mock private ArticleCalculator calculator; 61 * @Mock(name = "database") private ArticleDatabase dbMock; // note the mock name attribute 62 * @Spy private UserProvider userProvider = new ConsumerUserProvider(); 63 * 64 * @InjectMocks private ArticleManager manager; 65 * 66 * @Test public void shouldDoSomething() { 67 * manager.initiateArticle(); 68 * verify(database).addListener(any(ArticleListener.class)); 69 * } 70 * } 71 * 72 * public class SampleBaseTestCase { 73 * 74 * @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>@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 @InjectMocks will only inject mocks/spies created using the @Spy or @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 @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 (@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