Writing Hamcrest Matchers

JUnit 4 introduced a fancy DSL based on the Hamcrest framework for expressing assertions. JUnit ships with the most important matchers and you can always add Hamcrest to your classpath if you need more. Sometimes no existing matcher fits your needs and you have to roll your own. Since it's not entirely obvious from the documentation, I'll show a template for creating a simple Hamcrest matcher.

A check in JUnit 4 always looks something like this:

assertThat(actual, predicateName(expected));

The predicateName() factory method is just syntactic sugar, so let's instantiate the matcher directly to make it more obvious what happens here:

assertThat(actual, new SomeMatcher(expected));

The first argument is of type ActualType, the expectation's type (the constructor's argument) is ExpectedType. This is our implementation of SomeMatcher:

import org.hamcrest.Description;
import org.hamcrest.Factory;
import org.hamcrest.TypeSafeMatcher;

public class SomeMatcher extends TypeSafeMatcher<ActualType> {
    private final ExpectedType expected;

    public SomeMatcher(ExpectedType expected) {
        this.expected = expected;

    public boolean matchesSafely(ActualType actual) {
        // return true iff "actual" matches "expected"

    public void describeTo(Description descr) {
        // describe expectation

    public static SomeMatcher predicateName(ExpectedType expected) {
        return new SomeMatcher(expected);

The @Factory annotation isn't necessary, but Hamcrest ships with a tool that picks up predicates annotated this way and collects them in a Matchers class for easy importing.