Hamcrest is a library of matchers, is an external add-on of the Junit Framework and Junit 4.12 comprises of depreciated Hamcrest matchers, not all of them.

How to add hamcrest methods into your project by IntelliJ as shown below.

For example we are writing a Junit test with hamcrest “Is” method. First, click “assertThat” and then press alt+Enter then click “Static Import Method…”

junit_9

Then, select which library you want. I chose org.hamcrest

junit_10

Then click “is” and press alt+enter and select “Static Import Method…”

junit_11

Then, select “Is.is(org.hamcrest.core) method and import related hamcrest method.

junit_12

You can import all Hamcrest methods in this way.

If you want to download all of the matchers into your project, you should add the source .jar files or you should add Hamcrest maven dependency.

Java sources and maven dependency descriptions can be found in this link http://search.maven.org/#search|ga|1|g%3Aorg.hamcrest and a sample maven dependency is shown below.

In this tutorial I will explain and show examples of core hamcrest methods. If you want to learn much more about hamcrest, you can find all detailed in formation in Hamcrest documentation link http://hamcrest.org/JavaHamcrest/javadoc/1.3/

Matchers are used with the org.junit.Assert.assertThat() method. You can find their descriptions and examples in below table.

Matcher Description & Example
AllOf Calculates the logical conjunction of multiple matchers. Examined object must match ALL of the specified matcher.

Example
assertThat(“myString”, allOf(startsWith(“my”), containsString(“Str”)))

AnyOf Calculates the logical disjunction of multiple matchers. Examined object matches ANY of the specified matchers.

Example
assertThat(“myString”, allOf(startsWith(“your”), containsString(“Str”)))

DescribedAs Adds a description to a Matcher

Example
assertThat(“Sunday”, describedAs(“Sunday is not Saturday.”, is(not(“Saturday”))));

Is Decorates another Matcher, retaining its behavior. In other words it checks given objects equality. Is method allows tests to be more meaningful/expressive.

Example
assertThat(cheese, is(equalTo(smelly)))
instead of:
assertThat(cheese, equalTo(smelly))

IsAnything A matcher that always returns true.

Example
assertThat(“Onur”, is(anything(“Bla Bla Bla”)));

IsEqual It checks given objects equality.

Example
assertThat("str", equalTo("str "));
or
assertThat("str ", is(equalTo("str ")));

IsInstanceOf  Tests whether the value is an instance of a class.

Example
assertThat(myInstanceTest, instanceOf(InstanceTest.class));

IsNot<T>  Creates a matcher that wraps an existing matcher, but inverts the logic by which it will match.

Example
assertThat(“onur”, is(not(equalTo(“mike”))));
IsNull<T> Checks whether value is null

Example
assertThat(myStr, is(nullValue()));

 IsSame<T> Creates a matcher that matches only when the examined object is the same instance as the specified target object.

Example
assertThat(str1, IsSame.<String>sameInstance(str2));

In below code you can find usage of all matchers. I also tried to emphasize their descriptions with inline comments.

You can also check nice examples of hamcrest matchers in here: https://github.com/leveluplunch/levelup-java-examples/blob/master/src/test/java/com/levelup/java/hamcrest/CoreMatchers.java

Summary

  • You learned how to use and the meanings of hamcrest matchers.
  • You practiced with hamcrest matchers examples.

Keywords

JUnit, hamcrest matchers, unit testing, test framework