Mockito ArgumentMatchers

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.11.0</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. Supporting Varargs

Mockito 5 improves how varargs (for example, String… args) are handled, addressing issues that previously made matching them inconsistent and unintuitive.

In earlier versions, matching zero or multiple arguments worked as expected, but matching exactly one argument was problematic. For example, using when(mock.call(any())) would match any number of arguments — zero, one, or more — because any() was vararg-aware and applied to each element, not the entire array.

The new type() method on ArgumentMatcher provides more precise control. It allows tests to specify whether they want to match the entire vararg array or individual elements:

• To match any number of arguments, use when(mock.call(any(String[].class))).
• To match an invocation with no arguments, use when(mock.call()).
• To match exactly one argument, use when(mock.call(any())) or when(mock.call(any(String.class))).
• To match exactly two arguments, use when(mock.call(any(), any())).

This makes varargs matching far more predictable and removes confusion when testing methods with variable-length arguments.

Mockito 5 also improves ArgumentCaptor for varargs. It can now capture a single element or the entire vararg array, and it’s fully type-aware. For instance:

@Captor private ArgumentCaptor<String> captor;
@Captor private ArgumentCaptor<String[]> arrayCaptor;

This ensures we can capture individual arguments or the whole array as needed.

In addition, ArgumentCaptor now supports capturing specific subtypes. For example, when a method takes a Collection<?>, we can capture only List arguments:

ArgumentCaptor<Collection<?>> captor = ArgumentCaptor.forClass(List.class);
verify(mock).simpleMethod(captor.capture());
assertThat(captor.getAllValues()).containsExactly(List.of());

These improvements make testing varargs and generic collections in Mockito clearer, safer, and more precise.

7. Conclusion

In this article, we explored ArgumentMatcher, a feature of Mockito. We also discussed how it differs from ArgumentCaptor and highlighted how Mockito 5 has improved support for varargs, making it easier to match variable-length arguments in tests.