Hamcrest Custom Matchers

1. Introduction

As well as built-in matchers, Hamcrest also provides support for creating custom matchers.

In this tutorial, we’ll take a closer look at how to create and use them. To get a sneak peek on the available matchers, refer to this article.

2. Custom Matchers Setup

To get Hamcrest, we need to add the following Maven dependency to our pom.xml:

<dependency>
    <groupId>org.hamcrest</groupId>
    <artifactId>java-hamcrest</artifactId>
    <version>2.0.0.0</version>
    <scope>test</scope>
</dependency>

The latest Hamcrest version can be found on Maven Central.

3. Introducing TypeSafeMatcher

Before starting with our examples, it’s important to understand the class TypeSafeMatcher. We’ll have to extend this class to create a matcher of our own.

TypeSafeMatcher is an abstract class, so all subclasses have to implement the following methods:

• matchesSafely(T t): contains our matching logic 
• describeTo(Description description):  customizes the message the client will get when our matching logic is not fulfilled

As we may see in the first method, TypeSafeMatcher is parametrized, so we’ll have to declare a type when we use it. That will be the type of the object we’re testing.

Let’s make this clearer by looking at our first example in the next section.

4. Creating the onlyDigits Matcher

For our first use case, we’ll create a matcher that returns true if a certain String contains only digits.

So, onlyDigits applied to “123” should return true while “hello1” and “bye” should return false.

Let’s get started!

4.1. Matcher Creation

To start with our matcher, we’ll create a class that extends TypeSafeMatcher:

public class IsOnlyDigits extends TypeSafeMatcher<String> {
   
    @Override
    protected boolean matchesSafely(String s) {
        // ...
    }

    @Override
    public void describeTo(Description description) {
        // ...
    }
}

Please note that as the object we’ll test is a text, we’re parametrizing our subclass of TypeSafeMatcher with the class String. 

Now we’re ready to add our implementation:

public class IsOnlyDigits extends TypeSafeMatcher<String> {

    @Override
    protected boolean matchesSafely(String s) {
        try {
            Integer.parseInt(s);
            return true;
        } catch (NumberFormatException nfe){
            return false;
        }
    }

    @Override
    public void describeTo(Description description) {
        description.appendText("only digits");
    }
}

As we can see, matchesSafey is trying to parse our input String into an Integer. If it succeeds, it returns true. If it fails, it returns false. It responds successfully to our use case.

On the other side, describeTo is attaching a text that represents our expectations. We’ll see how this shows next when we use our matcher.

We only need one more thing to complete our matcher: a static method to access it, so it behaves as the rest of the built-in matchers.

So, we’ll add something like this:

public static Matcher<String> onlyDigits() {
    return new IsOnlyDigits();
}

And we’re done! Let’s see how to use this matcher in the next section.

4.2. Matcher Usage

To use our brand new matcher, we’ll create a test:

@Test
public void givenAString_whenIsOnlyDigits_thenCorrect() {
    String digits = "1234";

    assertThat(digits, onlyDigits());
}

And that’s it. This test will pass because the input String contains only digits. Remember that, to make it a little more legible, we can use the matcher is that acts as a wrapper over any other matcher:

assertThat(digits, is(onlyDigits()));

Finally, if we ran the same test but with the input “123ABC”, the output message would be:

java.lang.AssertionError: 
Expected: only digits
     but: was "123ABC"

This is where we see the text that we appended to the describeTo method. As we may have noticed, it’s important to create a proper description of what’s expected in the test.

5. divisibleBy

So, what if we wanted to create a matcher that defines if a number is divisible by another number? For that scenario, we’ll have to store one of the parameters somewhere.

Let’s see how we can do that:

public class IsDivisibleBy extends TypeSafeMatcher<Integer> {

    private Integer divider;

    // constructors

    @Override
    protected boolean matchesSafely(Integer dividend) {
        if (divider == 0) {
            return false;
        }
        return ((dividend % divider) == 0);
    }

    @Override
    public void describeTo(Description description) {
        description.appendText("divisible by " + divider);
    }

    public static Matcher<Integer> divisibleBy(Integer divider) {
        return new IsDivisibleBy(divider);
    }
}

Simple enough, we just added a new attribute to our class and assigned it during construction. Then, we just passed it as a parameter to our static method:

@Test
public void givenAnEvenInteger_whenDivisibleByTwo_thenCorrect() {
    Integer ten = 10;
    Integer two = 2;

    assertThat(ten,is(divisibleBy(two)));
}

@Test
public void givenAnOddInteger_whenNotDivisibleByTwo_thenCorrect() {
    Integer eleven = 11;
    Integer two = 2;

    assertThat(eleven,is(not(divisibleBy(two))));
}

And that’s it! We already have our matcher using more than one input!

6. Conclusion

Hamcrest provides matchers that cover most use cases a developer usually has to deal with when creating assertions.

What’s more, if any specific case isn’t covered, Hamcrest also gives support to create custom matchers to be used under specific scenarios – as we’ve explored here. They’re simple to create, and they are used exactly like the ones included in the library.

To get the complete implementation of this examples, please refer to the GitHub Project.