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. Migration guide is included close to the bottom of this javadoc.

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 do 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) method. This option is useful if custom matcher is needed for stubbing and can be reused a lot. Note that Matchers.argThat(org.mockito.ArgumentMatcher) demonstrates NullPointerException auto-unboxing caveat.
• 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! Note that MockitoHamcrest.argThat(org.hamcrest.Matcher) demonstrates NullPointerException auto-unboxing caveat.

Implementations of this interface can be used with Matchers.argThat(org.mockito.ArgumentMatcher) method. Use toString() method for description of the matcher - it is printed in verification errors.

 class ListOfTwoElements implements ArgumentMatcher<List> {
     public boolean matches(Object list) {
         return ((List) list).size() == 2;
     }
     public String toString() {
         //printed in verification errors
         return "[list of 2 elements]";
     }
 }

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

In Java 8 you can treat ArgumentMatcher as a functional interface and use a lambda, e.g.:

   verify(mock).addAll(argThat(list -> list.size() == 2));
 

Read more about other matchers in javadoc for Matchers class.

2.0 migration guide

All existing custom implementations of ArgumentMatcher will no longer compile. All locations where hamcrest matchers are passed to argThat() will no longer compile. There are 2 approaches to fix the problems:

• a) Refactor the hamcrest matcher to Mockito matcher: Use "implements ArgumentMatcher" instead of "extends ArgumentMatcher". Then refactor describeTo() method into toString() method.
• b) Use org.mockito.hamcrest.MockitoHamcrest.argThat() instead of Mockito.argThat(). Ensure that there is hamcrest dependency on classpath (Mockito does not depend on hamcrest any more).

What option is right for you? If you don't mind compile dependency to hamcrest then option b) is probably right for you. Your choice should not have big impact and is fully reversible - you can choose different option in future (and refactor the code)

Since:

2.0

Method Summary

Methods

Modifier and Type	Method and Description
boolean	matches(T argument) Informs if this matcher accepts the given argument.

Method Detail

matches

boolean matches(T argument)

Informs if this matcher accepts the given argument.

The method should never assert if the argument doesn't match. It should only return false.

The argument is not using the generic type in order to force explicit casting in the implementation. This way it is easier to debug when incompatible arguments are passed to the matchers. You have to trust us on this one. If we used parametrized type then ClassCastException would be thrown in certain scenarios. For example:

   //test, method accepts Collection argument and ArgumentMatcher<List> is used
   when(mock.useCollection(someListMatcher())).thenDoNothing();

   //production code, yields confusing ClassCastException
   //although Set extends Collection but is not compatible with ArgumentMatcher<List>
   mock.useCollection(new HashSet());
 

See the example in the top level javadoc for ArgumentMatcher

Parameters:

argument - the argument

Returns:

true if this matcher accepts the given argument.