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.