Introduction to Hamcrest Core Matchers

I didn't write the post, but was involved a great deal

In our previous post, we got a small introduction into Hamcrest, a framework for writing test matcher objects, and why you should use them. This post will dive deeper into Hamcrest Matchers. A Matcher is a ‘match’ rule to be defined declaratively. The Hamcrest library comes with numerous matchers included, and it’s of course possible to write your own Matcher.

The topic of this week: the Core Matchers.

The common Matchers of Hamcrest are the following:
is, equalTo, not, anything, instanceOf, any, isA, nullValue, notNullValue, sameInstance, theInstance, isIn, isOneOf and hasToString.

I will give an example of all of them in the code block below:

    public void testMovie() {
        // Creation of class under test.
        Movie movie = new Movie("Charlies Angels");

        Movie otherMovie = movie;

        // This is method takes just a value, instead of a matcher.
        assertThat(movie.isRentable(), is(false));

        // This not method also just takes a value
        assertThat(movie.isRentable(), not(true));
        // This is a chained example for better readability, where the 'is' method takes the not matcher as an argument
        assertThat(movie.isRentable(), is(not(true)));

        // This is a simple String comparison
        assertThat(movie.getTitle(), equalTo("Charlies Angels"));
        // And can also be done this way:
        assertThat(movie.getTitle(), is("Charlies Angels"));

        // Anything always matches. Seriously, no idea what to use this for.
        assertThat(movie, is(anything()));

        // Checks the type of the object. Movie implements the Rentable interface
        assertThat(movie, is(instanceOf(Rentable.class)));

        // Matches when the examined object is an instance of the specified type, used eg. by JMock's with method.
        assertThat(movie, any(Movie.class));

        // Shortcut for is(instanceOf(SomeClass.class))
        assertThat(movie, isA(Rentable.class));

        // Checks if the object is null
        assertThat(new Movie(null).getTitle(), is(nullValue()));
        // Checks if the object is not null
        assertThat(movie.getTitle(), is(notNullValue()));

        // Check that the objects are the same instance
        assertThat(movie, is(sameInstance(otherMovie)));
        // Check that the objects are the same instance. Same as 'sameInstance'.
        assertThat(movie, is(theInstance(otherMovie)));

        // Checks if the examined object is found within the specified array.
        assertThat(movie.getMainGenre(), isIn(Arrays.asList(ACTION, DRAMA)));
        // Seems the same as 'isIn', but this is the varargs variant.
        assertThat(movie.getMainGenre(), isOneOf(ACTION, DRAMA));

        // Checks the toString of the tested object.
        assertThat(movie, hasToString("Movie{inStock=false, title=Charlies Angels, ratings=[]}"));

As you can see, the Hamcrest assertions are very readable, and makes your testcode a bit easier to maintain.

PS: I always wanted to write some posts about Hamcrest, but the thing which really triggered me was the Hamcrest cheat sheet created by Marc Philipp. Be sure to check it out, it’s a great piece of work!

Erik Pragt
Erik Pragt
Erik Pragt is a passionate software developer with a broad range of experience in both static dynamic (Java, Scala) languages. Having worked as a consultant for a broad range of customers mostly in the Telecom, ISP, and banking sector, Erik is now an independent freelance consultant. In the limited time he's not sitting behind the computer he can be found in the gym, riding his motorcycle or diving, always looking for new inspiration.
Recommended Posts

Start typing and press Enter to search