1. Introduction

This cookbook illustrates how to make use of Hamcrest matchers to work with and test collections.

The format of the cookbook is example focused and practical – no extraneous details and explanations necessary.

First, let’s do a quick static import to cover most of the utility APIs we’re going to use next:

import static org.hamcrest.Matchers.*;

Further reading:

Hamcrest Common Core Matchers

Explore the different methods of CoreMatchers class in the Hamcrest library.

Read more

Hamcrest Bean Matchers

Learn about Hamcrest bean matchers – a tool that provides an effective way of making assertions, a frequently used feature when writing unit tests.

Read more

Testing with Hamcrest

In this very practical tutorial, we focus on using the Hamcrest API and on writing neater and more intuitive unit tests for our software.

Read more

2. The Cookbook

check if single element is in a collection

List<String> collection = Lists.newArrayList("ab", "cd", "ef");
assertThat(collection, hasItem("cd"));
assertThat(collection, not(hasItem("zz")));

check if multiple elements are in a collection

List<String> collection = Lists.newArrayList("ab", "cd", "ef");
assertThat(collection, hasItems("cd", "ef"));

check all elements in a collection

– with strict order

List<String> collection = Lists.newArrayList("ab", "cd", "ef");
assertThat(collection, contains("ab", "cd", "ef"));

– with any order

List<String> collection = Lists.newArrayList("ab", "cd", "ef");
assertThat(collection, containsInAnyOrder("cd", "ab", "ef"));

check if collection is empty

List<String> collection = Lists.newArrayList();
assertThat(collection, empty());

check if array is empty

String[] array = new String[] { "ab" };
assertThat(array, not(emptyArray()));

check if Map is empty

Map<String, String> collection = Maps.newHashMap();
assertThat(collection, equalTo(Collections.EMPTY_MAP));

check if Iterable is empty

Iterable<String> collection = Lists.newArrayList();
assertThat(collection, emptyIterable());

check size of a collection

List<String> collection = Lists.newArrayList("ab", "cd", "ef");
assertThat(collection, hasSize(3));

checking size of an iterable

Iterable<String> collection = Lists.newArrayList("ab", "cd", "ef");
assertThat(collection, Matchers.<String> iterableWithSize(3));

check condition on every item

List<Integer> collection = Lists.newArrayList(15, 20, 25, 30);
assertThat(collection, everyItem(greaterThan(10)));

3. Conclusion

This format is an experiment – I’m publishing some of my internal development cookbooks on a given topic – Google Guava and now Hamcrest. The goal is to have this information readily available online – and to add to it whenever I run into a new useful example.

The implementation of all these examples and code snippets can be found over on GitHub – this is a Maven-based project, so it should be easy to import and run as it is.