Mockito Programming Model
Internal
Overview
Mockito provides a fluent API to mock Java objects.
Annotations
@Mock
import org.mockito.Mock;
import org.mockito.MockitoAnnotations;
import com.example.ExternalDependency;
import static org.mockito.Mockito.when;
public class SomeClassTest {
private AutoCloseable mocks;
@Mock
private ExternalDependency mockExternalDependency;
@Before
public void openMocks() {
mocks = MockitoAnnotations.openMocks(this);
}
@After
public void releaseMocks() throws Exception {
mocks.close();
}
@Test
public void someTest() throws Exception {
when(mockExternalDependency.someMethod()).thenReturn(...);
...
}
}
@Spy
This creates a spy of a given object. It can be used instead of spy(Object).
@Captor
This simplifies the creation of ArgumentCaptor.
@InjectMocks
The annotation injects mock or spy fields into tested objects automatically using constructor injection, setter injection or field injection.
API
import static org.mockito.Mockito.mock;
import com.example.ExternalDependency;
public class SomeClassTest {
private ExternalDependency mockExternalDependency;
@Before
public void setUp() {
mockExternalDependency = mock(ExternalDependency.class);
}
@Test
public void someTest() throws Exception {
...
}
}
How to release mocks created this way?
Implementing Stubs
A stub returns synthetic responses or throws exceptions when its methods are invoked. Mockito supports stubbing and by returning a given value when a specific method of the managed test double is called. Mockito implements the stub functionality with Mockito.when(<method>).then*(...) pattern - using this API pattern is often referred to as "setting the expectations". The synthetic response is selected based on the arguments of the call, using the arguments values themselves or argument matchers:
public class ExternalDependency {
public String someMethod() {
...
}
}
import static org.mockito.Mockito.when;
public class SomeClassTest {
@Mock
private ExternalDependency mockExternalDependency;
@Test
public void someTest() throws Exception {
when(mockExternalDependency.someMethod()).thenReturn("some synthetic result");
...
}
}
The when() configures the method(s) to stub, or the trigger action. The then*() methods specify what to do when the trigger is activated. Void methods are a special case.
Void Methods
Unit testing void methods is difficult. Conventionally, a unit test provides arguments to a method and checks the result, working with the direct output of the method. For void methods, the method presumably changes the internal state of the objects under test, to the unit test must make assertions on the indirect output of the method. A common pattern to implement this is to provide managed mocks so the void methods acts on those instead of real dependencies.
By default, the managed test double does nothing on void methods, so there's no need to configure anything on it. The invocation on a void method will just complete successfully. Whether the invocation was performed or not can be checked with verify().
doAnswer() - Executing Arbitrary Logic for Void Methods
If we need to execute arbitrary logic when a void method is invoked, use this pattern:
doAnswer(answer).when(mockObject).<void-method-name>(arguments);
doAnswer(new Answer() { ... }).when(mockExternalDependency).writeLine("....");
For more details about Answer objects, see Answer below.
If we need to simulate an exception that is thrown by a void method, use this pattern:
toThrow() - Throwing Exceptions for Void Methods
doThrow(exception).when(mockObject).<void-method-name>(arguments);
doThrow(IOException.class).when(mockExternalDependency).writeLine("....");
doNothing()
Stub Responses for Non-Void Methods
The common pattern on non-void methods is:
when(mockExternalDependency.<some-method>(...)).then*(...);
thenReturn()
thenReturn(...) returns the given value. It has several variants:
thenReturn(value): return the same value every time.thenReturn(value1, value2, value3, ...): return the first value on first invocation, second value on the second invocation, etc. The equivalent is:thenReturn(value1).thenReturn(value2).thenReturn(value3). ...
⚠️ If a builder of any kind is used as argument of thenReturn(), the code that builds the response is executed at the time of the mock configuration, and the result computed at configuration time is returned when the stubbed method is invoked. Do not use thenReturn() if the result should be dynamic and evaluated at the time of invocation. Use thenAnswer() instead.
thenThrow()
thenThrow(Throwable) throws the given exception. This can be used together with JUnit feature that provides syntactic support for tests that are supposed to check exceptions (@Test(expected = <exception-class>)).
when(mockExternalDependency.someMethod()).thenThrow(IOException.class);
There is alternative syntax for throwing exceptions on void methods.
thenCallRealMethod()
thenCallRealMethod() delegates the invocation to the real external dependency.
thenAnswer()
thenAnswer(Answer answer) executes custom logic and compute a value to return. This turns the stub object into a fake. It uses Answers:
Answer
Answer implementation is a callback. This is considered a somewhat controversial feature, as increases the complexity of the code. thenReturn() and thenThrow() should be used instead, if possible.
when(mock.someMethod(anyString(), anyLong())).thenAnswer((Answer<SomeResult>) invocation -> {
String arg0 = invocation.getArgument(0);
long arg1 = invocation.getArgument(1);
Object[] args = i.getArguments();
Object mock = i.getMock();
if ("red".equals(arg0)) {
return new SomeResult("RED", arg1);
}
return new SomeResult(arg0, arg1);
});
Legacy:
when(mock.someMethod(...)).thenAnswer(new Answer() {
public Object answer(InvocationOnMock i) {
Object[] args = i.getArguments();
Object mock = i.getMock();
return "called with arguments: " + Arrays.toString(args);
}
});
when(mock.someMethod(...)).then(new Answer() { ... });
Also see executing arbitrary logic when void methods are invoked, above.
Argument Matchers
The test double should be configured prior to running the test and programmed how to react when a method is invoked with specific arguments by using the Mockito.when(...) API. This is achieved using a mechanism called argument matchers. The actual arguments of the call are matched against a list of pre-configured options, and if there is a match, the matching entry is used to simulate the invocation response by returning a pre-set result, throw an exception, or trigger custom logic to compute the result.
The default behavior in absence of any configured argument matcher is that the method returns the default value for the return type: 0 for int, null for String, etc. Also see Default Behavior below.
The test double can be configured to issue specific responses to a method invocation based on individual argument values, predefined wildcard matchers or custom matchers. When using matchers, all arguments of a method must be provided by matchers. Mixing individual argument values and wildcard matchers is not allowed. The following invocation will fail:
verify(mock).someMethod(1, anyString(), "some string");
However, this situation can be easily worked around by using the eq(...) in lieu of an individual value:
verify(mock).someMethod(eq(1), anyString(), eq("some string"));
Individual Argument Values
Wildcard Matchers
Mockito wildcard marchers are static methods of the org.mockito.ArgumentMatchers class. Note that the equivalent, older org.mockito.Matchers has been deprecated and it should not be used.
| Matcher | Notes |
|---|---|
| any() | |
| anyObject() | |
| any(Class<T> c) | |
| isA(Class<T> c) | Example below |
| anyVararg() | |
| anyBoolean() anyByte() anyChar() anyInt() anyLong() anyFloat() anyDouble() anyShort() anyString() | |
| anyList() anyListOf(Class<T> c) | |
| anySet() anySetOf(Class<T> c) | |
| anyMap() anyMapOf(Class<K> keyC, Class<V> valueC) | |
| anyCollection() anyCollectionOf(Class<T> c) | |
| anyIterable() anyIterableOf(Class<T> c) | |
| eq(T value)
eq(boolean value) eq(byte value) eq(char value) | |
| refEq(T value, String... excludeFields) | |
| same(T value) | |
| isNull() isNull(Class<T> c) notNull() notNull(Class<T> c) isNotNull() isNotNull(Class<T> c) | |
| nullable(Class<T> c) | |
| contains(String substring) | |
| matches(String regex) matches(String regex) | |
| endsWith(String suffix) startsWith(String prefix) | |
| argThat(ArgumentMatcher<T> m) charThat(ArgumentMatcher<Character> m) booleanThat(ArgumentMatcher<Boolean> m) byteThat(ArgumentMatcher<Byte> m) shortThat(ArgumentMatcher<Short> m) intThat(ArgumentMatcher<Integer> m) longThat(ArgumentMatcher<Long> m) floatThat(ArgumentMatcher<Float> m) doubleThat(ArgumentMatcher<Double> m) |
isA()
public class ExternalDependency {
public String someMethodWithArg(String s) {
...
}
}
import static org.mockito.ArgumentMatchers.isA;
import static org.mockito.Mockito.when;
...
when(mockExternalDependency.someMethodWithArg(isA(String.class))).thenReturn(...);
Why is isA() needed, why not provide the class, directly?
anyString()
⚠️ Note that since 2.1.0, anyString() does not match null. To match a String or null, use nullable(String.class).
nullable(Class<T> c)
Note that since Mockito 2.1.0, matches like anyString() do not match null values anymore. If you need a match to happen for a non-null String or null, use:
when(mock.someMethod(nullable(String.class))).thenReturn(...);
Custom ArgumentMatcher
TODO. "Working with a custom ArgumentMatcher class" section in Mockito Essentials.
Default Behavior
Non-stubbed methods for a mock objects, as well as invocations for which there's no argument match, return default values: null for an Object, 0 for an integer, false for a boolean.
This behavior can be changed by configuring Mockito with the following options:
- RETURNS_DEFAULTS. The default behavior.
- RETURNS_SMART_NULLS. Return stubs that act like nulls, in that they throw exceptions if a method is attempted to be called on them. The exceptions are more useful that the normal
NullPointerExceptionbehavior. - RETURNS_MOCKS. Return mocks for objects and default values for primitives.
- RETURNS_DEEP_STUBS.
- CALL_REAL_METHODS.
Determining whether a Test Double is a Mock
import static org.mockito.Mockito.mockingDetails;
mockingDetails(mockObject).isMock();
Implementing Spies
Testing Interaction with the Test Double
Number of Invocations
Many times during testing it is useful to know if our mocked external dependency was called into with a specific method, or any method, how many times per method, and so on. Mockito exposes API for this in form of the Mockito.verify(...) set of methods. The mock object should be declared and configured as described in the Annotations section. Then the number of invocations of certain methods, or whether the methods have been invoked at all, can be tested with:
import static org.mockito.Mockito.verify;
...
verify(mock).someMethod("some argument");
This invocation succeeds if the method someMethod() was invoked with the argument "some argument" once and only once. The invocation is equivalent with:
import static org.mockito.Mockito.verify;
import static org.mockito.Mockito.times;
...
verify(mock, times(1)).someMethod("some argument");
Other options:
verify(mock, never()).someMethod("some argument");
verify(mock, atMostOnce()).someMethod("some argument");
verify(mock, atLeastOnce()).someMethod("some argument");
verify(mock, atLeast(2)).someMethod("some argument");
verify(mock, atMost(5)).someMethod("some argument");
verify(mock, only()).someMethod("some argument");
Mock-wide Interactions
verifyZeroInteractions(mockOne, mockTwo);
verifyNoMoreInteractions(mock);
Invocation Order
TODO Mockito Essentials "Verifying an invocation order".
Verifying Arguments with ArgumentCaptor
TODO Mockito Essentials "Verifying arguments using ArgumentCaptor".
Generic collection arguments.
Variable arguments and arrays.
Also see @Captor
Spying on Real Objects
TODO Mockito Essentials "Spying Objects".
spy(Object). Also see @Spy
Determining whether a Test Double is a Spy
import static org.mockito.Mockito.mockingDetails;
mockingDetails(testDoubleObject).isSpy();
Resetting Mock Objects
A mock object can be reset via API.
import static org.mockito.Mockito.reset;
...
reset(mockObject);
Troubleshooting
- No configured invocation matches the current invocation. The configured invocation is declared with an int argument, and the invocation is made with a long.