org.mockito.InjectMocks Maven / Gradle / Ivy
Show all versions of mockito-core Show documentation
/*
* Copyright (c) 2007 Mockito contributors
* This program is made available under the terms of the MIT License.
*/
package org.mockito;
import static java.lang.annotation.ElementType.FIELD;
import static java.lang.annotation.RetentionPolicy.RUNTIME;
import java.lang.annotation.Documented;
import java.lang.annotation.Retention;
import java.lang.annotation.Target;
import org.mockito.junit.MockitoJUnitRunner;
/**
* Mark a field on which injection should be performed.
*
*
* - Allows shorthand mock and spy injection.
* - Minimizes repetitive mock and spy injection.
*
*
* Mockito will try to inject mocks only either by constructor injection,
* property injection or setter injection in order and as described below.
* If any of the following strategy fail, then Mockito won't report failure;
* i.e. you will have to provide dependencies yourself.
*
* - Constructor injection; 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 Mockito won't try the other strategies. Mockito has decided to no
* corrupt an object if it has a parametered constructor.
*
Note: 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.
*
* - Property setter injection; 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.
*
Note 1: 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.
* Note 2: If @InjectMocks instance wasn't initialized before and has a no-arg constructor,
* then it will be initialized with this constructor.
*
* - Field injection; 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.
*
Note 1: 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.
* Note 2: If @InjectMocks instance wasn't initialized before and have a no-arg constructor,
* then it will be initialized with this constructor.
*
*
*
*
* Example:
*
* 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 {
*
* private AutoCloseable closeable;
*
* @Before public void openMocks() {
* closeable = MockitoAnnotations.openMocks(this);
* }
*
* @After public void releaseMocks() throws Exception {
* closeable.close();
* }
* }
*
*
*
*
* In the above example the field ArticleManager annotated with @InjectMocks 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
* Mockito cannot instantiate inner classes, local classes, abstract classes and of course interfaces.
* Beware of private nested static classes too.
*
*
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.
*
* So on the field that needs injection, for example constructor injection will happen here:
*
* public class ArticleManager {
* ArticleManager(ArticleCalculator calculator, ArticleDatabase database) {
* // parameterized constructor
* }
* }
*
*
* Property setter injection will happen here:
*
* public class ArticleManager {
* // no-arg constructor
* ArticleManager() { }
*
* // setter
* void setDatabase(ArticleDatabase database) { }
*
* // setter
* void setCalculator(ArticleCalculator calculator) { }
* }
*
*
* Field injection will be used here:
*
* public class ArticleManager {
* private ArticleDatabase database;
* private ArticleCalculator calculator;
* }
*
*
*
* And finally, no injection will happen on the type in this case:
*
* 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
* }
* }
*
*
*
*
*
* Again, note that @InjectMocks will only inject mocks/spies created using the @Spy or @Mock annotation.
*
*
*
* MockitoAnnotations.openMocks(this) method has to be called to initialize annotated objects.
* In above example, openMocks() is called in @Before (JUnit4) method of test's base class.
* Instead you can also put openMocks() in your JUnit runner (@RunWith) or use the built-in
* {@link MockitoJUnitRunner}. Also, make sure to release any mocks after disposing your test class with a corresponding hook.
*
*
*
* 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.
*
*
*
* Elements annotated with this annotation can also be spied upon by also adding the {@link Spy}
* annotation to the element.
*
*
* @see Mock
* @see Spy
* @see MockitoAnnotations#openMocks(Object)
* @see MockitoJUnitRunner
* @since 1.8.3
*/
@Documented
@Target(FIELD)
@Retention(RUNTIME)
public @interface InjectMocks {}