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)
 
 
result=5;
assertThat(result, is(5));
 
 

assertThat with chained matchers

result=5;
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;

 

            @Override

            public boolean matches(Object o) {

                return expected.equals(o);

            }

 

            @Override

            public void describeTo(Description description) {

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

            }

        };

    }

  

    @Test

    public void test1() {

        String result = "hello";

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

    }

  

    @Test

    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
 
    Core
        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
 
    Logical
        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
 
    Object
        equalTo - test object equality using Object.equals
        hasToString - test Object.toString
        instanceOf, isCompatibleType - test type
        notNullValue, nullValue - test for null
        sameInstance - test object identity
 
    Collections
        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
 
    Number
        closeTo - test floating point values are close to a given value
        greaterThan, greaterThanOrEqualTo, lessThan, lessThanOrEqualTo - test ordering
 
    Text
        equalToIgnoringCase - test string equality ignoring case
        equalToIgnoringWhiteSpace - test string equality ignoring differences in runs of whitespace
        containsString, endsWith, startsWith - test string matching
 
 

External References