Testing Toolbelt: Hamcrest Matchers

The Hamcrest Matchers framework contains a series of Matcher classes which help implement comparison and assertion methods in a type-safe, declarative manner. When used in tests, the Matchers framework will produce more legible test code and more helpful failure messages. The Matchers framework is partially included in the JUnit 4.4 package and some portions can be used effectively. But, the full power of the framework can only be unleashed by including the real Hamcrest Matchers jar within your testing environment.

Matchers

The org.hamcrest.Matchers class in the Hamcrest framework provides a series of methods, intended to be used with import static, which supply various pre-defined org.hamcrest.core.Matcher instances.

• is -- The simplest matcher, most times behaves just as syntactical sugar around other matchers. But, if an instance of Class is passed, it behaves like the Matcher produced by instanceOf. If passed any other value, behaves like the Matcher produced by equalsTo. see org.hamcrest.core.Is
• equalTo -- Verifies that the test value is equal to the value used to instantiate the Matcher. see org.hamcrest.core.IsEqual
• instanceOf -- Verifies that the test value is assignable to the Class value used to instantiate the Matcher. see org.hamcrest.core.IsInstanceOf
• nullValue/nonNullValue -- Verifies that the test value is null-valued/not-null-valued. see org.hamcrest.core.IsNull
• startsWith/containsString/endsWith -- Verifies that the test value (String\-typed) begins with, contains, or ends with the value used to instatiate the Matcher. see org.hamcrest.core.StringStartsWith, org.hamcrest.core.StringContains, and org.hamcrest.core.StringEndsWith
• arrayWithSize/emptyArray/hasSize/empty -- Verifies that the test value is an array/collection that either has the given number of elements/is empty. see org.hamcrest.core.IsArrayWithSize, org.hamcrest.core.IsCollectionWithSize, and org.hamcrest.core.IsEmptyCollection
• lessThan/lessThanOrEqualTo/greaterThanOrEqualTo/greaterThan -- Verifies that the test value is strictly less than/less than/greater than/strictly greater than the provided value. see org.hamcrest.core.OrderingComparison

Examples

public class MatcherSample {

  @Test public void matcherSample() {
    // doesn't compile, type-safety in action
    // assertThat(1, is("VALUE"));

    // is, with a Class-typed operand...
    assertThat("VALUE", is(String.class));
    // ...is resolved to this...
    assertThat("VALUE", is(instanceOf(String.class)));
    // ...which is then unwrapped to this
    assertThat("VALUE", instanceOf(String.class));

    // is, with a reference-type operand...
    assertThat("VALUE", is("VALUE"));
    // ...is resolved to this...
    assertThat("VALUE", is(equalTo("VALUE")));
    // ... which is then unwrapped to this
    assertThat("VALUE", equalTo("VALUE"));

    // is, with a primitive value
    assertThat(1, is(1));

    // assert null-valued
    assertThat(null, is(nullValue()));
    // assert null-valued, checking type
    assertThat((String) null, is(nullValue(String.class)));
    // assert non-null
    assertThat("VALUE", is(notNullValue()));

    // Matchers for Strings
    // you could use is() with these, but is more readable without
    assertThat("VALUABLE", startsWith("VALU"));
    assertThat("VALUABLE", containsString("LUA"));
    assertThat("VALUABLE", endsWith("ABLE"));

    // Matchers for Arrays and Collections
    final String[] strings1 = {};
    assertThat(strings1, is(emptyArray()));
    assertThat(strings1, is(arrayWithSize(0)));
    assertThat(Arrays.asList(strings1), hasSize(0));
    final String[] strings2 = { "VALUE_1", "VALUE_2" };
    assertThat(strings2, is(arrayWithSize(2)));
    assertThat(strings2, is(arrayContaining("VALUE_1", "VALUE_2")));
    assertThat(Arrays.asList(strings2), hasSize(2));
    assertThat(Arrays.asList(strings2), contains("VALUE_1", "VALUE_2"));

    // Matchers for Numerics
    assertThat(1, is(lessThan(10)));
    assertThat(1, is(greaterThan(0)));
    assertThat(1, is(lessThanOrEqualTo(1)));
    assertThat(1, is(greaterThanOrEqualTo(1)));

    // use both/allOf/either/anyOf for composition of matchers
    // both/allOf is equivalent to and'ing the Matchers
    assertThat(1, is(both(greaterThan(0)).and(lessThan(10))));
    assertThat(1, is(allOf(greaterThan(0), lessThan(10))));
    // either/anyOf is equivalent to or'ing the Matchers
    assertThat(100, is(either(lessThan(0)).or(greaterThan(10))));
    assertThat(100, is(anyOf(lessThan(0), greaterThan(10))));
  }
}