EasyMock Argument Matchers

1. Overview

In this tutorial, we’ll explore EasyMock argument matchers. We’ll discuss different types of predefined matchers and how to create a custom matcher as well.

We already covered EasyMock basics in the introduction to EasyMock article, so you may need to read it first to get yourself familiar with EasyMock.

2. Simple Mocking Example

Before we start exploring different matchers, let’s take a look at our context. Throughout this tutorial, we’ll use a pretty basic user service in our examples.

Here’s our simple IUserService interface:

public interface IUserService {
    public boolean addUser(User user);
    public List<User> findByEmail(String email);
    public List<User> findByAge(double age);  
}

And the related User model:

public class User {
    private long id;
    private String firstName;
    private String lastName;
    private double age;
    private String email;

    // standard constructor, getters, setters
}

So, we’ll start by merely mocking our IUserService to use it in our examples:

private IUserService userService = mock(IUserService.class);

Now, let’s explore the EasyMock argument matchers.

3. Equality Matchers

First, we’ll use eq() matcher to match the new added User:

@Test
public void givenUserService_whenAddNewUser_thenOK() {        
    expect(userService.addUser(eq(new User()))).andReturn(true);
    replay(userService);

    boolean result = userService.addUser(new User());
    verify(userService);
    assertTrue(result);
}

This matcher is available for both primitive and objects, and uses the equals() method for objects.

Similarly, we can use same() matcher for matching a specific User:

@Test
public void givenUserService_whenAddSpecificUser_thenOK() {
    User user = new User();
    
    expect(userService.addUser(same(user))).andReturn(true);
    replay(userService);

    boolean result = userService.addUser(user);
    verify(userService);
    assertTrue(result);
}

The same() matcher compares arguments using “==”, meaning it compares User instances in our case.

If we don’t use any matchers, arguments are compared by default using equals().

For arrays, we also have the aryEq() matcher which is based on the Arrays.equals() method.

4. Any Matchers

There are multiple any matchers like anyInt(), anyBoolean(), anyDouble(),… etc. These specify that the argument should have the given type.

Let’s see an example of using anyString() to match the expected email to be any String value:

@Test
public void givenUserService_whenSearchForUserByEmail_thenFound() {
    expect(userService.findByEmail(anyString()))
      .andReturn(Collections.emptyList());
    replay(userService);

    List<User> result = userService.findByEmail("test@example.com");
    verify(userService);
    assertEquals(0,result.size());
}

We can also use isA() to match an argument to be an instance of a specific class:

@Test
public void givenUserService_whenAddUser_thenOK() {
    expect(userService.addUser(isA(User.class))).andReturn(true);
    replay(userService);

    boolean result = userService.addUser(new User());
    verify(userService);
    assertTrue(result);
}

Here, we’re asserting that we expect the addUser() method parameter to be of type User.

5. Null Matchers

Next, we can use the isNull() and notNull() matchers to match null values.

In the following example, we’ll use the isNull() matcher to match if the added User value is null:

@Test
public void givenUserService_whenAddNull_thenFail() {
    expect(userService.addUser(isNull())).andReturn(false);
    replay(userService);

    boolean result = userService.addUser(null);
    verify(userService);
    assertFalse(result);
}

We can also notNull() to match if added user value is not null in a similar way:

@Test
public void givenUserService_whenAddNotNull_thenOK() {
    expect(userService.addUser(notNull())).andReturn(true);
    replay(userService);

    boolean result = userService.addUser(new User());
    verify(userService);
    assertTrue(result);
}

6. String Matchers

There are multiple useful matchers that we can use with String arguments.

First, we’ll use the startsWith() matcher to match a user’s email prefix:

@Test
public void whenSearchForUserByEmailStartsWith_thenFound() {        
    expect(userService.findByEmail(startsWith("test")))
      .andReturn(Collections.emptyList());
    replay(userService);

    List<User> result = userService.findByEmail("test@example.com");
    verify(userService);
    assertEquals(0,result.size());
}

Similarly, we’ll use the endsWith() matcher for the email suffix:

@Test
public void givenUserService_whenSearchForUserByEmailEndsWith_thenFound() {        
    expect(userService.findByEmail(endsWith(".com")))
      .andReturn(Collections.emptyList());
    replay(userService);

    List<User> result = userService.findByEmail("test@example.com");
    verify(userService);
    assertEquals(0,result.size());
}

More generally, we can use contains() to match the email with a given substring:

@Test
public void givenUserService_whenSearchForUserByEmailContains_thenFound() {        
    expect(userService.findByEmail(contains("@")))
      .andReturn(Collections.emptyList());
    replay(userService);

    List<User> result = userService.findByEmail("test@example.com");
    verify(userService);
    assertEquals(0,result.size());
}

Or even match our email to a specific regex using matches():

@Test
public void givenUserService_whenSearchForUserByEmailMatches_thenFound() {        
    expect(userService.findByEmail(matches(".+\\@.+\\..+")))
      .andReturn(Collections.emptyList());
    replay(userService);

    List<User> result = userService.findByEmail("test@example.com");
    verify(userService);
    assertEquals(0,result.size());
}

7. Number Matchers

We also have a few matchers for numeric values that we can use.

Let’ see an example of using the lt() matcher to match the age argument to be less than 100:

@Test
public void givenUserService_whenSearchForUserByAgeLessThan_thenFound() {    
    expect(userService.findByAge(lt(100.0)))
      .andReturn(Collections.emptyList());
    replay(userService);

    List<User> result = userService.findByAge(20);        
    verify(userService);
    assertEquals(0,result.size());
}

Similarly, we also use geq() to match the age argument to be greater than or equal to 10:

@Test
public void givenUserService_whenSearchForUserByAgeGreaterThan_thenFound() {    
    expect(userService.findByAge(geq(10.0)))
      .andReturn(Collections.emptyList());
    replay(userService);

    List<User> result = userService.findByAge(20);        
    verify(userService);
    assertEquals(0,result.size());
}

The available number matchers are:

• lt() – less than the given value
• leq() – less than or equal
• gt() – greater than
• geq() – greater than or equal

8. Combine Matchers

We can also combine multiple matchers using and(), or() and not() matchers.

Let’s see how we can combine two matchers to verify that the age value is both greater than 10 and less than 100:

@Test
public void givenUserService_whenSearchForUserByAgeRange_thenFound() {
    expect(userService.findByAge(and(gt(10.0),lt(100.0))))
      .andReturn(Collections.emptyList());
    replay(userService);

    List<User> result = userService.findByAge(20);        
    verify(userService);
    assertEquals(0,result.size());
}

Another example we can look at is combining not() with endsWith() to match emails that don’t end with “.com”:

@Test
public void givenUserService_whenSearchForUserByEmailNotEndsWith_thenFound() {
    expect(userService.findByEmail(not(endsWith(".com"))))
      .andReturn(Collections.emptyList());
    replay(userService);

    List<User> result = userService.findByEmail("test@example.org");
    verify(userService);
    assertEquals(0,result.size());
}

9. Custom Matcher

Finally, we’ll discuss how to create a custom EasyMock matcher.

The goal is to create a simple minCharCount() matcher to match strings with a length greater than or equal to the given value:

@Test
public void givenUserService_whenSearchForUserByEmailCharCount_thenFound() {        
    expect(userService.findByEmail(minCharCount(5)))
      .andReturn(Collections.emptyList());
    replay(userService);

    List<User> result = userService.findByEmail("test@example.com");
    verify(userService);
    assertEquals(0,result.size());
}

To create a custom argument matcher, we need to:

• create a new class that implements the IArgumentMatcher interface
•  create a static method with the new matcher name and register an instance of the class above using reportMatcher()

Let’s see both steps in our minCharCount() method that declares an anonymous class within it:

public static String minCharCount(int value){
    EasyMock.reportMatcher(new IArgumentMatcher() {
        @Override
        public boolean matches(Object argument) {
            return argument instanceof String 
              && ((String) argument).length() >= value;
        }
 
        @Override
        public void appendTo(StringBuffer buffer) {
            buffer.append("charCount(\"" + value + "\")");
        }
    });    
    return null;
}

Also, note that the IArgumentMatcher interface has two methods: matches() and appendTo(). 

The first method contains the argument validation and logic for our matcher, while the second is used to append the matcher String representation to be printed in case of failure.

10. Conclusion

We covered EasyMock predefined argument matchers for different data types and how to create our custom matcher.

The full source code for the examples is available over on GitHub.