Class ArgumentCaptor<T>
- java.lang.Object
-
- org.mockito.ArgumentCaptor<T>
-
public class ArgumentCaptor<T> extends java.lang.Object
Use it to capture argument values for further assertions.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 and simple. In some situations though, it is helpful to assert on certain arguments after the actual verification. For example:
Example of capturing varargs:ArgumentCaptor<Person> argument = ArgumentCaptor.forClass(Person.class); verify(mock).doSomething(argument.capture()); assertEquals("John", argument.getValue().getName());
//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 assertion (aka verify or 'then') blocks. It may also reduce defect localization because if the 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 were passed to mock objects. However, ArgumentCaptor may be a better fit if:- custom argument matcher is not likely to be reused
- you just need it to assert on argument values to complete verification
ArgumentMatcher
are usually better for stubbing.This utility class will perform type checking on the generic type (since Mockito 5.0.0).
There is an annotation that you might find useful: @
Captor
See the full documentation on Mockito in javadoc for
Mockito
class.- Since:
- 1.8.0
- See Also:
Captor
-
-
Field Summary
Fields Modifier and Type Field Description private CapturingMatcher<T>
capturingMatcher
private java.lang.Class<? extends T>
clazz
-
Constructor Summary
Constructors Modifier Constructor Description private
ArgumentCaptor(java.lang.Class<? extends T> clazz)
-
Method Summary
All Methods Static Methods Instance Methods Concrete Methods Modifier and Type Method Description static <U> ArgumentCaptor<U>
captor(U... reified)
Build a newArgumentCaptor
by inferring the class type.T
capture()
Use it to capture the argument.static <U,S extends U>
ArgumentCaptor<U>forClass(java.lang.Class<S> clazz)
Build a newArgumentCaptor
.java.util.List<T>
getAllValues()
Returns all captured values.(package private) java.lang.Class<? extends T>
getCaptorType()
Get the raw class being captured.T
getValue()
Returns the captured value of the argument.
-
-
-
Field Detail
-
capturingMatcher
private final CapturingMatcher<T> capturingMatcher
-
clazz
private final java.lang.Class<? extends T> clazz
-
-
Constructor Detail
-
ArgumentCaptor
private ArgumentCaptor(java.lang.Class<? extends T> clazz)
-
-
Method Detail
-
capture
public T capture()
Use it to capture the argument. This method must be used inside of verification.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.- Returns:
- null or default values
-
getValue
public T getValue()
Returns the captured value of the argument. When capturing varargs usegetAllValues()
.If verified method was called multiple times then this method it returns the latest captured value.
See examples in javadoc for
ArgumentCaptor
class.- Returns:
- captured argument value
-
getAllValues
public java.util.List<T> getAllValues()
Returns all captured values. Use it when capturing varargs or when the verified method was called multiple times. When varargs method was called multiple times, this method returns merged list of all values from all invocations.Example:
Example of capturing varargs: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());
See more examples in javadoc formock.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());
ArgumentCaptor
class.- Returns:
- captured argument value
-
forClass
public static <U,S extends U> ArgumentCaptor<U> forClass(java.lang.Class<S> clazz)
Build a newArgumentCaptor
.An
ArgumentCaptor
will perform type checks (since Mockito 5.0.0).- Type Parameters:
S
- Type of clazzU
- Type of object captured by the newly built ArgumentCaptor- Parameters:
clazz
- Type matching the parameter to be captured.- Returns:
- A new ArgumentCaptor
-
captor
@SafeVarargs public static <U> ArgumentCaptor<U> captor(U... reified)
Build a newArgumentCaptor
by inferring the class type.This enables inferring the generic type of an argument captor without providing a raw class reference, which enables working around generic limitations of the Java compiler without producing compile-time warnings unlike
forClass(java.lang.Class<S>)
which would require explicit casting or warning suppression.Example usage:
// Given UserRepository repository = mock(); UserService service = new UserService(repository); Map<String, User> expectedUsers = Map.of( "12345", new User("12345", "Bob"), "45678", new User("45678", "Dave") ); ArgumentCaptor<Map<String, User>> captor = ArgumentCaptor.captor(); doNothing().when(repository).storeUsers(captor.capture()); // When service.createUsers(List.of( new User("12345", "Bob"), new User("45678", "Dave") )); // Then Map<String, User> actualUsers = captor.getValue(); assertThat(expectedUsers).isEqualTo(actualUsers);
- Type Parameters:
U
- the type of argument to be captured by this captor.- Parameters:
reified
- do not pass any value here. This is used to trick the compiler into reifying the return type without needing casts.- Returns:
- A new ArgumentCaptor.
- Throws:
java.lang.IllegalArgumentException
- if any arguments are passed to this method.
-
getCaptorType
java.lang.Class<? extends T> getCaptorType()
Get the raw class being captured.- Returns:
- the raw class that is being captured by this captor.
-
-