White Box Testing
Test your code
   Home      JUnit4 Matchers and assertThat

assertThat and Matchers

assertThat and matchers added from Hamcrest. Latest JUnit shipped with Hamcrest internally.
JUnit currently ships with a few matchers, defined in org.hamcrest.CoreMatchers and org.junit.matchers.JUnitMatchers.
matchers are used with assertThat and makes syntax more readable in terms of subject,object and verb. the syntax more usually looks like
public void assertThat(Object o, Matcher matcher)
assertThat(result, is(5));

assertThat with chained matchers

assertThat(result, is(not(10)));
assertThat(responseString, either(containsString("color")).or(containsString("colour")));

Writing your own custom matchers

We can write our own custom matcher extending BaseMatcher implementing following method
  •     public boolean matches(Object item) : here  check object under test
  •     public void describeTo(Description description) : Return description of our matcher for failures

import static org.junit.Assert.*;

import org.hamcrest.BaseMatcher;

import org.hamcrest.Description;

import org.hamcrest.Matcher;

import org.junit.Test;


public class MatcherTest {


    public static Matcher hasStr(final Object input){


        return new BaseMatcher() {


            protected Object expected = input;



            public boolean matches(Object o) {

                return expected.equals(o);




            public void describeTo(Description description) {

               description.appendText("object should return ").appendText(expected.toString());






    public void test1() {

        String result = "hello";

        assertThat(result, hasStr("hello"));




    public void test2() {

        String result = "hi";

        assertThat(result, hasStr("hello"));



Hamcrest library Matchers

Hamcrest library comes with useful matchers. Here is a list of the important methods
        anything - always matches, useful if you don't care what the object under test is
        describedAs - decorator to adding custom failure description
        is - decorator to improve readability - see "Sugar", below
        allOf - matches if all matchers match, short circuits (like Java &&)
        anyOf - matches if any matchers match, short circuits (like Java ||)
        not - matches if the wrapped matcher doesn't match and vice versa
        equalTo - test object equality using Object.equals
        hasToString - test Object.toString
        instanceOf, isCompatibleType - test type
        notNullValue, nullValue - test for null
        sameInstance - test object identity
        array - test an array's elements against an array of matchers
        hasEntry, hasKey, hasValue - test a map contains an entry, key or value
        hasItem, hasItems - test a collection contains elements
        hasItemInArray - test an array contains an element
        closeTo - test floating point values are close to a given value
        greaterThan, greaterThanOrEqualTo, lessThan, lessThanOrEqualTo - test ordering
        equalToIgnoringCase - test string equality ignoring case
        equalToIgnoringWhiteSpace - test string equality ignoring differences in runs of whitespace
        containsString, endsWith, startsWith - test string matching

External References