Hamcrest Common Core Matchers

1. Overview

In this quick tutorial, we’ll explore the CoreMatchers class from the popular Hamcrest framework for writing simple and more expressive test cases.

The idea is to make assert statements read like natural language.

2. Hamcrest Setup

We can use Hamcrest with Maven by adding the following dependency to our pom.xml file:

<dependency>
    <groupId>org.hamcrest</groupId>
    <artifactId>java-hamcrest</artifactId>
    <version>2.0.0.0</version>
    <scope>test</scope>
</dependency>

The latest version of this library can always be found here.

3. Common Core Matchers

3.1. is(T)and is(Matcher<T>)

The is(T) takes an object as a parameter to check equality and is(Matcher<T>) takes another matcher allowing equality statement to be more expressive.

We can use this with almost all of the methods:

String testString = "hamcrest core";

assertThat(testString, is("hamcrest core"));
assertThat(testString, is(equalTo("hamcrest core")));

3.2. equalTo(T)

The equalTo(T) takes an object as a parameter and checks its equality against another object. This is frequently used with is(Matcher<T>):

String actualString = "equalTo match";
List<String> actualList = Lists.newArrayList("equalTo", "match");

assertThat(actualString, is(equalTo("equalTo match")));
assertThat(actualList, is(equalTo(Lists.newArrayList("equalTo", "match"))));

We can also use equalToObject(Object operand) – which checks equality and doesn’t enforce that two objects should of same static type:

Object original = 100;
assertThat(original, equalToObject(100));

3.3. not(T)and not(Matcher<T>)

The not(T) and not(Matcher<T>) are used to check non-equality of given objects. First takes an object as an argument and second take another matcher:

String testString = "troy kingdom";

assertThat(testString, not("german kingdom"));
assertThat(testString, is(not(equalTo("german kingdom"))));
assertThat(testString, is(not(instanceOf(Integer.class))));

3.4. nullValue()and nullValue(Class<T>)

The nullValue() check for null value against the examined object. The nullValue(Class<T>) checks for nullability of given class type object:

Integer nullObject = null;

assertThat(nullObject, is(nullValue()));
assertThat(nullObject, is(nullValue(Integer.class)));

3.5. notNullValue()and notNullValue(Class<T>)

These are a shortcut to frequently used is(not(nullValue)). These check for non-null-equality of an object or with the class type:

Integer testNumber = 123;

assertThat(testNumber, is(notNullValue()));
assertThat(testNumber, is(notNullValue(Integer.class)));

3.6. instanceOf(Class<?>)

The instanceOf(Class<?>) matches if the examined object is an instance of the specified Class type.

To verify, this method internally calls the isIntance(Object) of Class class:

assertThat("instanceOf example", is(instanceOf(String.class)));

3.7. isA(Class<T> type)

The isA(Class<T> type) is a shortcut to the above instanceOf(Class<?>). It takes the exact same type of argument as an instanceOf(Class<?>):

assertThat("Drogon is biggest dragon", isA(String.class));

3.8. sameInstance()

The sameInstance() matches if two reference variables point to the same object in a heap:

String string1 = "Viseron";
String string2 = string1;

assertThat(string1, is(sameInstance(string2)));

3.9. any(Class<T>)

The any(Class<T>)checks if the class is of the same type as actual object:

assertThat("test string", is(any(String.class)));
assertThat("test string", is(any(Object.class)));

3.10. allOf(Matcher<? extends T>…) and anyOf(Matcher<? extends T>…)

We can use allOf(Matcher<? extends T>…) to assert if actual object matches against all of the specified conditions:

String testString = "Achilles is powerful";
assertThat(testString, allOf(startsWith("Achi"), endsWith("ul"), containsString("Achilles")));

The anyOf(Matcher<? extends T>…) behaves like allOf(Matcher<? extends T>… ) but matches if the examined object matches any of the specified conditions:

String testString = "Hector killed Achilles";
assertThat(testString, anyOf(startsWith("Hec"), containsString("baeldung")));

3.11. hasItem(T)and hasItem(Matcher<? extends T>)

These match if the examined Iterable collection matches with given object or matcher inside hasItem() or hasItem(Matcher<? extends T>).

Let’s understand how this works:

List<String> list = Lists.newArrayList("java", "spring", "baeldung");

assertThat(list, hasItem("java"));
assertThat(list, hasItem(isA(String.class)));

Similarly, we can also assert against more than one items using hasItems(T…) and hasItems(Matcher<? extends T>…):

List<String> list = Lists.newArrayList("java", "spring", "baeldung");

assertThat(list, hasItems("java", "baeldung"));
assertThat(list, hasItems(isA(String.class), endsWith("ing")));

3.12. both(Matcher<? extends T>) and either(Matcher<? extends T>)

As the name suggests, the both(Matcher<? extends T>) matches when both of the specified conditions match the examined object:

String testString = "daenerys targaryen";
assertThat(testString, both(startsWith("daene")).and(containsString("yen")));

and either(Matcher<? extends T>)matches when either of the specified conditions matches the examined object:

String testString = "daenerys targaryen";
assertThat(testString, either(startsWith("tar")).or(containsString("targaryen")));

4. String Comparison

We can use containsString(String) or containsStringIgnoringCase(String) to assert if the actual string contains test string:

String testString = "Rhaegar Targaryen";
assertThat(testString, containsString("aegar"));
assertThat(testString, containsStringIgnoringCase("AEGAR"));

Or startsWith(String) and startsWithIgnoringCase(String) to assert if the actual string starts with test string:

assertThat(testString, startsWith("Rhae"));
assertThat(testString, startsWithIgnoringCase("rhae"));

We can also use endsWith(String) or endsWithIgnoringCase(String) to assert if the actual string ends with test string:

assertThat(testString, endsWith("aryen"));
assertThat(testString, endsWithIgnoringCase("ARYEN"));

5. Conclusion

In this article, we discussed different methods of CoreMatchers class in Hamcrest library.

And, as always, the source code for the examples can be found over on GitHub.