Mockito ArgumentMatchers

Last updated: May 11, 2024

Written by: baeldung

Reviewed by: Michal Aibin

Testing

Azure Container Apps is a fully managed serverless container service that enables you to build and deploy modern, cloud-native Java applications and microservices at scale. It offers a simplified developer experience while providing the flexibility and portability of containers.

Of course, Azure Container Apps has really solid support for our ecosystem, from a number of build options, managed Java components, native metrics, dynamic logger, and quite a bit more.

To learn more about Java features on Azure Container Apps, visit the documentation page.

You can also ask questions and leave feedback on the Azure Container Apps GitHub page.

Of course, Azure Container Apps has really solid support for our ecosystem, from a number of build options, managed Java components, native metrics, dynamic logger, and quite a bit more.

To learn more about Java features on Azure Container Apps, you can get started over on the documentation page.

And, you can also ask questions and leave feedback on the Azure Container Apps GitHub page.

Modern software architecture is often broken. Slow delivery leads to missed opportunities, innovation is stalled due to architectural complexities, and engineering resources are exceedingly expensive.

Orkes is the leading workflow orchestration platform built to enable teams to transform the way they develop, connect, and deploy applications, microservices, AI agents, and more.

With Orkes Conductor managed through Orkes Cloud, developers can focus on building mission critical applications without worrying about infrastructure maintenance to meet goals and, simply put, taking new products live faster and reducing total cost of ownership.

Try a 14-Day Free Trial of Orkes Conductor today.

Orkes is the leading workflow orchestration platform built to enable teams to transform the way they develop, connect, and deploy applications, microservices, AI agents, and more.

Try a 14-Day Free Trial of Orkes Conductor today.

End-to-end testing is a very useful method to make sure that your application works as intended. This highlights issues in the overall functionality of the software, that the unit and integration test stages may miss.

Playwright is an easy-to-use, but powerful tool that automates end-to-end testing, and supports all modern browsers and platforms.

When coupled with LambdaTest (an AI-powered cloud-based test execution platform) it can be further scaled to run the Playwright scripts in parallel across 3000+ browser and device combinations:

>> Automated End-to-End Testing With Playwright

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. Conclusion

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

The code backing this article is available on GitHub. Once you're logged in as a Baeldung Pro Member, start learning and coding on the project.

Of course, Azure Container Apps has really solid support for our ecosystem, from a number of build options, managed Java components, native metrics, dynamic logger, and quite a bit more.

To learn more about Java features on Azure Container Apps, visit the documentation page.

You can also ask questions and leave feedback on the Azure Container Apps GitHub page.

Orkes is the leading workflow orchestration platform built to enable teams to transform the way they develop, connect, and deploy applications, microservices, AI agents, and more.

Try a 14-Day Free Trial of Orkes Conductor today.

Orkes is the leading workflow orchestration platform built to enable teams to transform the way they develop, connect, and deploy applications, microservices, AI agents, and more.

Try a 14-Day Free Trial of Orkes Conductor today.