/*
* Copyright (c) 2007 Mockito contributors
* This program is made available under the terms of the MIT License.
*/
package org.mockito;
import java.lang.annotation.Documented;
import java.lang.annotation.Retention;
import java.lang.annotation.Target;
import org.mockito.junit.MockitoJUnitRunner;
import static java.lang.annotation.ElementType.FIELD;
import static java.lang.annotation.RetentionPolicy.RUNTIME;
/**
* Mark a field on which injection should be performed.
*
* <ul>
* <li>Allows shorthand mock and spy injection.</li>
* <li>Minimizes repetitive mock and spy injection.</li>
* </ul>
* <p>
* Mockito will try to inject mocks only either by constructor injection,
* setter injection, or property injection in order and as described below.
* If any of the following strategy fail, then Mockito <strong>won't report failure</strong>;
* i.e. you will have to provide dependencies yourself.
* <ol>
* <li><strong>Constructor injection</strong>; the biggest constructor is chosen,
* then arguments are resolved with mocks declared in the test only. If the object is successfully created
* with the constructor, then <strong>Mockito won't try the other strategies</strong>. Mockito has decided to no
* corrupt an object if it has a parametered constructor.
* <p><u>Note:</u> If arguments can not be found, then null is passed.
* If non-mockable types are wanted, then constructor injection won't happen.
* In these cases, you will have to satisfy dependencies yourself.</p></li>
*
* <li><strong>Property setter injection</strong>; mocks will first be resolved by type (if a single type match
* injection will happen regardless of the name),
* then, if there is several property of the same type, by the match of the property name and the mock name.
* <p><u>Note 1:</u> If you have properties with the same type (or same erasure), it's better to name all @Mock
* annotated fields with the matching properties, otherwise Mockito might get confused and injection won't happen.</p>
* <p><u>Note 2:</u> If @InjectMocks instance wasn't initialized before and have a no-arg constructor,
* then it will be initialized with this constructor.</p></li>
*
* <li><strong>Field injection</strong>; mocks will first be resolved by type (if a single type match
* injection will happen regardless of the name),
* then, if there is several property of the same type, by the match of the field name and the mock name.
* <p><u>Note 1:</u> If you have fields with the same type (or same erasure), it's better to name all @Mock
* annotated fields with the matching fields, otherwise Mockito might get confused and injection won't happen.</p>
* <p><u>Note 2:</u> If @InjectMocks instance wasn't initialized before and have a no-arg constructor,
* then it will be initialized with this constructor.</p></li>
* </ol>
* </p>
*
* <p>
* Example:
* <pre class="code"><code class="java">
* public class ArticleManagerTest extends SampleBaseTestCase {
*
* @Mock private ArticleCalculator calculator;
* @Mock(name = "database") private ArticleDatabase dbMock; // note the mock name attribute
* @Spy private UserProvider userProvider = new ConsumerUserProvider();
*
* @InjectMocks private ArticleManager manager;
*
* @Test public void shouldDoSomething() {
* manager.initiateArticle();
* verify(database).addListener(any(ArticleListener.class));
* }
* }
*
* public class SampleBaseTestCase {
*
* @Before public void initMocks() {
* MockitoAnnotations.initMocks(this);
* }
* }
* </code></pre>
* </p>
*
* <p>
* In the above example the field <code>ArticleManager</code> annotated with <code>@InjectMocks</code> can have
* a parameterized constructor only or a no-arg constructor only, or both.
* All these constructors can be package protected, protected or private, however
* <u>Mockito cannot instantiate inner classes, local classes, abstract classes and of course interfaces.</u>
* <u>Beware of private nest static classes too.</u>
*
* <p>The same stands for setters or fields, they can be declared with private
* visibility, Mockito will see them through reflection.
* However fields that are static or final will be ignored.</p>
*
* <p>So on the field that needs injection, for example constructor injection will happen here :</p>
* <pre class="code"><code class="java">
* public class ArticleManager {
* ArticleManager(ArticleCalculator calculator, ArticleDatabase database) {
* // parameterized constructor
* }
* }
* </code></pre>
*
* <p>Property setter injection will happen here :</p>
* <pre class="code"><code class="java">
* public class ArticleManager {
* // no-arg constructor
* ArticleManager() { }
*
* // setter
* void setDatabase(ArticleDatabase database) { }
*
* // setter
* void setCalculator(ArticleCalculator calculator) { }
* }
* </code></pre>
*
* <p>Field injection will be used here :</p>
* <pre class="code"><code class="java">
* public class ArticleManager {
* private ArticleDatabase database;
* private ArticleCalculator calculator;
* }
* </code></pre>
* </p>
*
* <p>And finally, no injection will happen on the type in this case:</p>
* <pre class="code"><code class="java">
* public class ArticleManager {
* private ArticleDatabase database;
* private ArticleCalculator calculator;
*
* ArticleManager(ArticleObserver observer, boolean flag) {
* // observer is not declared in the test above.
* // flag is not mockable anyway
* }
* }
* </code></pre>
* </p>
*
*
* <p>
* Again, note that @InjectMocks will only inject mocks/spies created using the @Spy or @Mock annotation.
* </p>
*
* <p>
* <strong><code>MockitoAnnotations.initMocks(this)</code></strong> method has to be called to initialize annotated objects.
* In above example, <code>initMocks()</code> is called in @Before (JUnit4) method of test's base class.
* For JUnit3 <code>initMocks()</code> can go to <code>setup()</code> method of a base class.
* <strong>Instead</strong> you can also put initMocks() in your JUnit runner (@RunWith) or use the built-in
* {@link MockitoJUnitRunner}.
* </p>
*
* <p>
* Mockito is not an dependency injection framework, don't expect this shorthand utility to inject a complex graph of objects
* be it mocks/spies or real objects.
* </p>
*
* @see Mock
* @see Spy
* @see MockitoAnnotations#initMocks(Object)
* @see MockitoJUnitRunner
* @since 1.8.3
*/
@Documented
@Target(FIELD)
@Retention(RUNTIME)
public @interface InjectMocks {}