public class ArgumentCaptor<T> extends Object
Mockito verifies argument values in natural java style: by using an equals() method. This is also the recommended way of matching arguments because it makes tests clean & simple. In some situations though, it is helpful to assert on certain arguments after the actual verification. For example:
ArgumentCaptor<Person> argument = ArgumentCaptor.forClass(Person.class);
verify(mock).doSomething(argument.capture());
assertEquals("John", argument.getValue().getName());
Example of capturing varargs:
//capturing varargs:
ArgumentCaptor<Person> varArgs = ArgumentCaptor.forClass(Person.class);
verify(mock).varArgMethod(varArgs.capture());
List expected = asList(new Person("John"), new Person("Jane"));
assertEquals(expected, varArgs.getAllValues());
Warning: it is recommended to use ArgumentCaptor with verification but not with stubbing. Using ArgumentCaptor with stubbing may decrease test readability because captor is created outside of assert (aka verify or 'then') block. Also it may reduce defect localization because if stubbed method was not called then no argument is captured.
In a way ArgumentCaptor is related to custom argument matchers (see javadoc for ArgumentMatcher
class).
Both techniques can be used for making sure certain arguments where passed to mocks.
However, ArgumentCaptor may be a better fit if:
ArgumentMatcher
are usually better for stubbing.
This utility class *don't do any type checks*, the generic signatures are only there to avoid casting in your code.
There is an annotation that you might find useful: @Captor
See the full documentation on Mockito in javadoc for Mockito
class.
Captor
Modifier and Type | Method and Description |
---|---|
T |
capture()
Use it to capture the argument.
|
static <U,S extends U> |
forClass(Class<S> clazz)
Build a new
ArgumentCaptor . |
List<T> |
getAllValues()
Returns all captured values.
|
T |
getValue()
Returns the captured value of the argument.
|
public T capture()
Internally, this method registers a special implementation of an ArgumentMatcher
.
This argument matcher stores the argument value so that you can use it later to perform assertions.
See examples in javadoc for ArgumentCaptor
class.
public T getValue()
getAllValues()
.
If verified method was called multiple times then this method it returns the latest captured value.
See examples in javadoc for ArgumentCaptor
class.
public List<T> getAllValues()
Example:
mock.doSomething(new Person("John");
mock.doSomething(new Person("Jane");
ArgumentCaptor<Person> peopleCaptor = ArgumentCaptor.forClass(Person.class);
verify(mock, times(2)).doSomething(peopleCaptor.capture());
List<Person> capturedPeople = peopleCaptor.getAllValues();
assertEquals("John", capturedPeople.get(0).getName());
assertEquals("Jane", capturedPeople.get(1).getName());
Example of capturing varargs:
mock.countPeople(new Person("John"), new Person("Jane"); //vararg method
ArgumentCaptor<Person> peopleCaptor = ArgumentCaptor.forClass(Person.class);
verify(mock).countPeople(peopleCaptor.capture());
List expected = asList(new Person("John"), new Person("Jane"));
assertEquals(expected, peopleCaptor.getAllValues());
See more examples in javadoc for ArgumentCaptor
class.public static <U,S extends U> ArgumentCaptor<U> forClass(Class<S> clazz)
ArgumentCaptor
.
Note that an ArgumentCaptor
*don't do any type checks*, it is only there to avoid casting
in your code. This might however change (type checks could be added) in a
future major release.
S
- Type of clazzU
- Type of object captured by the newly built ArgumentCaptorclazz
- Type matching the parameter to be captured.