Rafael has posted 5 posts at DZone. You can read more from them at their website. View Full User Profile

Using Hamcrest and JUnit

04.05.2010
| 24931 views |
  • submit to reddit

Lately I started using the core Hamcrest matchers bundled with the JUnit framework to create more readable unit tests.

Hamcrest matchers were created to improve the readability of unit testing code. It’s a framework which facilitates the creation of matcher objects to match rules specified in unit tests. Some examples will let it to be clearer:

import static org.hamcrest.CoreMatchers.equalTo;
import static org.hamcrest.CoreMatchers.is;
import static org.junit.Assert.assertThat;

@Test
public void shouldBeTheSamePerson()
{
Person me = new Person( "Rafael" );
Person theOther = new Person( "Rafael" );
assertThat( me, is( theOther ) );
}

@Test
public void shouldHaveFixedSizeNumbers()
{
List<Integer> numbers = Arrays.asList( 1, 2, 3, 4, 5 );
assertThat( numbers.size(), is( equalTo( 5 ) ) );
}

The first example checks if one Person object is equal to another using the Object equals method, which was overridden in the Person class. The is syntax defines a matcher which is a shorthand to is(equalTo(value)). The second one uses the is(equalTo(value)) matcher to check the size of an integer list of fixed size numbers. The assertThat method is used in conjunction with the is(equalTo(value)) matcher, which makes the test sentence very human readable.

An interesting thing is the possibility to create a custom matcher, like this one which tests if a given list only has even numbers:

public class AreEvenNumbers extends TypeSafeMatcher<Collection<Integer>> {

@Override
public boolean matchesSafely(Collection<Integer> numbers) {
for (Integer number : numbers) {
if (number % 2 != 0) {
return false;
}
}
return true;
}

@Override
public void describeTo(Description description) {
description.appendText("even numbers");
}

@Factory
public static <T> Matcher<Collection<Integer>> evenNumbers() {
return new AreEvenNumbers();
}
}

And below are two tests which uses the AreEvenNumbers custom matcher:

import static org.hamcrest.CoreMatchers.is;
import static org.junit.Assert.assertThat;
import static br.com.rafael.hamcrest.AreEvenNumbers.evenNumbers;

@Test
public void shouldHaveOnlyEvenNumbers()
{
List<Integer> numbers = Arrays.asList( 2, 4, 6, 8, 10 );
assertThat( numbers, is( evenNumbers() ) );
}

@Test
public void shouldNotHaveOddNumbers()
{
List<Integer> numbers = Arrays.asList( 1, 2, 4, 6, 8, 10 );
assertThat( numbers, not( evenNumbers() ) );
}

 These two tests use the static factory method evenNumbers to instantiate the matcher on the test code. Not the use of the not matcher on the shouldNotHaveOddNumbers test to assert that no odd numbers are present on the given list. All tests use the static import feature, which turns the test not clean and not cluttered with the class qualification.

I haven’t experienced the other common matchers on unit testing code, like the Beans, Collections and Number ones. I think they turn the tests more readable, clean and easy to change. And you? Have you ever used Hamcrest matcher? If you have other examples of using it, post them here!

 From http://rafaelnaufal.com/blog/2010/03/15/using-hamcrest-and-junit/

 

Published at DZone with permission of its author, Rafael Naufal.

(Note: Opinions expressed in this article and its replies are the opinions of their respective authors and not those of DZone, Inc.)

Tags:

Comments

Mario Fusco replied on Mon, 2010/04/05 - 8:12am

The hamcrest's matchers can be useful not only for unit tests. The lambdaj library allows to filter a list of objects based on the condition defined by the matcher itself. For example given a list of number:
List<Integer> numbers = Arrays.asList( 1, 2, 3, 4, 5, 6 );
you could use the evenNumbers() matcher in your post to select only the even numbers in the list:
List<Integer> evenNumbers = select(numbers, evenNumbers());
obtaining a list with the numbers 2, 4 and 6. The select() method is one of the many static methods provided by lambdaj so you can use it through a static import in the same way you do with Hamcrest.

Jan Kronquist replied on Wed, 2010/04/07 - 9:13am

If you are using Eclipse don't miss the wonderful shortcut Ctrl+Shift+M (Add Import) that you can use to statically import a method. You also want to checkout Java / Editor / Content Assist / Favorites that allow code completion on static methods.

Comment viewing options

Select your preferred way to display the comments and click "Save settings" to activate your changes.