Mockito Programming Model

Internal

• Mockito
• Mockito Concepts

Overview

Mockito provides a fluent API to mock Java objects.

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 {
    ...
  }
}

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.

Implementing Stubs

https://github.com/ovidiuf/playground/tree/master/java/mockito/annotation-stub

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("....");

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). ...

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()

https://javadoc.io/static/org.mockito/mockito-core/3.11.2/org/mockito/Mockito.html#answer_stubs

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(...)).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 can 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. Argument matchers are used to simulate different responses, either specific return values or exceptions, from a method, depending on the values of the arguments.

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.

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"));

Wildcard Matchers

Mockito wildcard marchers are static methods of the org.mockito.ArgumentMatchers class.

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) eq(double value) eq(float value) eq(int value) eq(long value) eq(short 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?

Custom ArgumentMatcher

TODO. "Working with a custom ArgumentMatcher class" section in Mockito Essentials.

Hamcrest

Implementing Spies

Testing Interaction with the Test Double

Number of Invocations

https://javadoc.io/doc/org.mockito/mockito-core/latest/org/mockito/Mockito.html#exact_verification

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

https://javadoc.io/static/org.mockito/mockito-core/3.11.2/org/mockito/Mockito.html#never_verification

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

Resetting Mock Objects

A mock object can be reset via API.