1. Overview

In this tutorial, we’ll learn how to use the ArgumentMatcher, and discuss how it differs from the ArgumentCaptor.

For an introduction to the Mockito framework, please refer to this article.

2. Maven Dependencies

We need to add a single artifact:

<dependency>
    <groupId>org.mockito</groupId> 
    <artifactId>mockito-core</artifactId>
    <version>5.3.1</version> 
    <scope>test</scope>
</dependency>

The latest version of Mockito can be found on Maven Central.

3. ArgumentMatchers

We can configure a mocked method in various ways. One option is to return a fixed value:

doReturn("Flower").when(flowerService).analyze("poppy");

In the above example, the String “Flower” is returned only when the analyze method of FlowerService receives the String “poppy”.

But there may be a case where we need to respond to a wider range of values or unknown values.

In these scenarios, we can configure our mocked methods with argument matchers:

when(flowerService.analyze(anyString())).thenReturn("Flower");

Now, because of the anyString argument matcher, the result will be the same no matter what value we pass to analyze. ArgumentMatchers allow us flexible verification or stubbing.

If a method has more than one argument, we can’t just use ArgumentMatchers for only some of the arguments. Mockito requires that we provide all arguments either by matchers or exact values.

Here we can see an example of an incorrect approach:

when(flowerService.isABigFlower("poppy", anyInt())).thenReturn(true);

We can verify this by running the below test:

assertThrows(InvalidUseOfMatchersException.class, 
    () -> when(flowerService.isABigFlower("poppy", anyInt())).thenReturn(true));

To fix this and keep the String name “poppy” as desired, we’ll use eq matcher:

when(flowerService.isABigFlower(eq("poppy"), anyInt())).thenReturn(true);

Let’s run the test to confirm this:

when(flowerService.isABigFlower(eq("poppy"), anyInt())).thenReturn(true);

Flower flower = new Flower("poppy", 15);

Boolean response = flowerController.isABigFlower(flower);
assertThat(response).isTrue();

There are two more points to note when we use matchers:

  • We can’t use them as a return value; we require an exact value when stubbing calls.
  • We can’t use argument matchers outside of verification or stubbing.

As per the second point, Mockito will detect the misplaced argument and throw an InvalidUseOfMatchersException.

A bad example of this would be:

flowerController.isAFlower("poppy");

String orMatcher = or(eq("poppy"), endsWith("y"));
assertThrows(InvalidUseOfMatchersException.class, () -> verify(flowerService).analyze(orMatcher));

The way we’d implement the above code is:

verify(flowerService).analyze(or(eq("poppy"), endsWith("y")));

Mockito also provides AdditionalMatchers to implement common logical operations (‘not’, ‘and’, ‘or’) on ArgumentMatchers that match both primitive and non-primitive types.

4. Custom Argument Matcher

Creating our own matcher allows us to select the best possible approach for a given scenario and produce high-quality tests that are clean and maintainable.

For instance, we can have a MessageController that delivers messages. It’ll receive a MessageDTO, and from that, it’ll create a Message that MessageService will deliver.

Our verification will be simple; we’ll verify that we called the MessageService exactly 1 time with any Message:

MessageDTO messageDTO = new MessageDTO();
messageDTO.setFrom("me");
messageDTO.setTo("you");
messageDTO.setText("Hello, you!");

messageController.createMessage(messageDTO);

verify(messageService, times(1)).deliverMessage(any(Message.class));

Since the Message is constructed inside the method under test, we must use any as the matcher.

This approach doesn’t let us validate the data inside the Message, which can be different from the data inside the MessageDTO.

For this reason, we’ll implement a custom argument matcher:

public class MessageMatcher implements ArgumentMatcher<Message> {

    private Message left;

    // constructors

    @Override
    public boolean matches(Message right) {
        return left.getFrom().equals(right.getFrom()) &&
          left.getTo().equals(right.getTo()) &&
          left.getText().equals(right.getText()) &&
          right.getDate() != null &&
          right.getId() != null;
    }
}

To use our matcher, we need to modify our test and replace any by argThat:

MessageDTO messageDTO = new MessageDTO();
messageDTO.setFrom("me");
messageDTO.setTo("you");
messageDTO.setText("Hello, you!");

messageController.createMessage(messageDTO);

Message message = new Message();
message.setFrom("me");
message.setTo("you");
message.setText("Hello, you!");

verify(messageService, times(1)).deliverMessage(argThat(new MessageMatcher(message)));

Now we know our Message instance will have the same data as our MessageDTO.

5. Custom Argument Matcher vs ArgumentCaptor

Both techniques, custom argument matchers and ArgumentCaptor can be used to make sure certain arguments are passed to mocks.

However, ArgumentCaptor may be a better fit if we need it to assert on argument values to complete the verification, or our custom argument matcher isn’t likely to be reused.

Custom argument matchers via ArgumentMatcher are usually better for stubbing.

6. Conclusion

In this article, we explored ArgumentMatcher, a feature of Mockito. We also discussed how it differs from ArgumentCaptor*.*

As always, the full source code of the examples is available over on GitHub.