org.mockito

Interface ArgumentMatcher<T>

Type Parameters:

T - type of argument

All Known Implementing Classes:

And, Any, AnyVararg, ArrayEquals, CapturingMatcher, CompareEqual, CompareTo, Contains, EndsWith, Equals, EqualsWithDelta, Find, GreaterOrEqual, GreaterThan, HamcrestArgumentMatcher, InstanceOf, LessOrEqual, LessThan, Matches, Not, NotNull, Null, Or, ReflectionEquals, Same, StartsWith, VarargCapturingMatcher

public interface ArgumentMatcher<T>

Allows creating customized argument matchers. This API was changed in Mockito 2.* in an effort to decouple Mockito from Hamcrest and reduce the risk of version incompatibility.

For non-trivial method arguments used in stubbing or verification, you have following options (in no particular order):

refactor the code so that the interactions with collaborators are easier to test with mocks. Perhaps it is possible to pass a different argument to the method so that mocking is easier? If stuff is hard to test it usually indicates the design could be better, so refactor for testability.

don't match the argument strictly, just use one of the lenient argument matchers like Matchers.notNull(). Some times it is better to have a simple test that works than a complicated test that seem to work.

implement equals() method in the objects that are used as arguments to mocks. Mockito naturally uses equals() for argument matching. Many times, this is option is clean and simple.

use ArgumentCaptor to capture the arguments and perform assertions on their state. Useful when you need to verify the arguments. Captor is not useful if you need argument matching for stubbing. Many times, this option leads to clean and readable tests with fine-grained validation of arguments.

use customized argument matchers by implementing ArgumentMatcher interface and passing the implementation to the Matchers.argThat(org.mockito.ArgumentMatcher<T>) method. This option is useful if custom matcher is needed for stubbing and can be reused a lot

use an instance of hamcrest matcher and pass it to MockitoHamcrest.argThat(org.hamcrest.Matcher) Useful if you already have a hamcrest matcher. Reuse and win!

Implementations of this interface can be used with Matchers.argThat(org.mockito.ArgumentMatcher<T>) method:

 class ListOfTwoElements implements ArgumentMatcher<List> {
     public boolean matches(Object list) {
         return ((List) list).size() == 2;
     }
 }

 List mock = mock(List.class);

 when(mock.addAll(argThat(new ListOfTwoElements))).thenReturn(true);

 mock.addAll(Arrays.asList("one", "two"));

 verify(mock).addAll(argThat(new ListOfTwoElements()));
 

To keep it readable you can extract method, e.g:

   verify(mock).addAll(argThat(new ListOfTwoElements()));
   //becomes
   verify(mock).addAll(listOfTwoElements());
 

Read more about other matchers in javadoc for Matchers class