Writing Expressive Unit Tests using Hamcrest

Introduction

Unit test cases are an important and integral part of every application. Unit test cases help to ensure that the code works as expected. Any deviation from the expected behavior is caught before the source code reaches production environment. This article provides a quick introduction about using Hamcrest framework to write unit tests which are readable, maintainable.

Background

In the Java world, there have been many unit-testing frameworks, Junit and TestNG being the most popular. It's been a general trend that as and when the size and complexity of test cases grow, the unit test cases start becoming unreadable and in-expressive. This is where Hamcrest can help, write expressive unit test cases.

Core Features of Hamcrest

Improves Readability of Test Cases

The dialect/selection of method names in Hamcrest framework improves readability of test cases.

Following are some of the examples:

// Clearly helps to understand that if actual value is equal to expectedValue
 
assertThat(actualValue, is(equalTo(expectedValue)));

// Employee object has a property named "firstName"

assertThat(employee, hasProperty("firstName"));
    
// Marital status should be a value of any of these possible values.

assertThat(employee.getMaritalStatus(), isIn(new String[]{"Married", "Single - Never Married", "Widow", "Divorced"}));

Enforces Type Safety

Hamcrest method doesn't allow to compare apples with oranges, rather it enforces comparing apples with apples. This helps a lot while writing test cases as we won't be comparing the types that don't match. The first level of check is to ensure that we are comparing same objects. Hamcrest heavily uses Java generics to ensure type safety.

Some of the examples are as follows:

// Generates compile-time error; isManager returns boolean whereas we are comparing with String.

assertThat(employee.isManager(), is("true"));

Supports Chaining of Conditions

Hamcrest allows to write multiple conditions in single assertThat statement. Multiple conditions can be grouped using logical conditions like or/and. We can write test cases where a condition can must match all the conditions or must match anyone of the condition. Some of the examples are as follows:

// Passes only allOf the condition are true; i.e. the firstName is not null, and equal to John
    
assertThat(employee.getFirstName(), allOf(notNullValue(), is("John")));   

Supports Rich-set of Matchers

Hamcrest supports good number of Matchers already available, some of them are listed below:

Highly Extensible

Hamcrest not only provides its own rich feature set but it fully supports creation of custom Matchers. In order to write custom matcher, we need to extend from TypeSafeMatcher base class.

Following is a simple example taken from Hamcrest documentation:

//Custom matcher
public class IsNotANumber extends TypeSafeMatcher<Double> {

   // Actual comparison. If the number is NaN that means its not a number
   @Override
   public boolean matchesSafely(Double number) {
    return number.isNaN();
   }
    
   // Adds custom description.    
   public void describeTo(Description description) {
    description.appendText("This is not a number");
   }

   // Actual method that is called from the codebase. 
   @Factory
   public static <T> Matcher<Double> notANumber() {
    return new IsNotANumber();
   }
}

The above created custom matcher can be used as:

// The notANumber is a static method available for usage
assertThat(1.0, is(notANumber()));

As we can see, writing test cases using the Hamcrest constructs improves the readability of the test cases making them easy to understand and maintain.

Maven Dependency

The following Maven dependencies need to be added to pom.xml to use all the features of Hamcrest.

<dependencies>
    <dependency>
        <groupId>junit</groupId>
        <artifactId>junit</artifactId>
        <version>4.11</version>
    </dependency>
    <dependency>
        <groupId>org.hamcrest</groupId>
        <artifactId>hamcrest-all</artifactId>
        <version>1.3</version>
    </dependency>
</dependencies>

Sample Test Case

import com.test.matchers.Employee;
import static org.hamcrest.Matchers.anyOf;
import static org.hamcrest.Matchers.greaterThan;
import static org.hamcrest.Matchers.hasProperty;
import static org.hamcrest.Matchers.is;
import static org.hamcrest.Matchers.notNullValue;
import static org.junit.Assert.assertThat;
import org.junit.Before;
import org.junit.Test;

public class EmployeeTest {
    private Employee employee;    
    
    @Before
    public void initEmployee() {
        employee = new Employee();
        employee.setFirstName("John");
        employee.setDesignation("Manager");
        employee.setAge(30);
    }
    
    @Test
    public void firstNameCannotBeNull() {
        assertThat("", employee.getFirstName(), notNullValue());                
    }
    
    @Test
    public void firstNameEqualsJohn() {
        assertThat("", employee.getFirstName(), is("John"));
    }
    
    @Test
    public void designationShouldBeManagerOrContractor() {
        assertThat(employee.getDesignation(), anyOf(is("Manager"), is("Contractor")));
    }
    
    @Test
    public void employeeShouldBeOlderThan20() {
        assertThat(employee.getAge(), greaterThan(20L));
    }
    
    
    @Test
    public void employeeHasAgeProperty() {
        assertThat(employee, hasProperty("age"));
    }
}

References

• https://code.google.com/p/hamcrest/
• http://hamcrest.org/JavaHamcrest/javadoc/1.3/org/hamcrest/Matchers.html

History

• 29^th September, 2014: Initial version