Introduction to Hamcrest Core Matchers

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:

@Test
    public void testMovie() {
        // Creation of class under test.
        Movie movie = new Movie("Charlies Angels");
        movie.setInStock(false);
        movie.addGenre(ACTION);
        movie.addGenre(COMEDY);

        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!

The post Introduction to Hamcrest Core Matchers appeared first on Jworks.