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