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.*;

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 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.

I just announced the new Spring 5 modules in REST With Spring:


Sort by:   newest | oldest | most voted

Great post 🙂 I like this format so I encourage you to keep going 😉

(This comment was meant to be posted in your post about Mockito but… xD)

Eugen Paraschiv

Glad you find this kind of format useful – initially I was actually on the fence whether or not I should publish these internal cookbooks I’ve been keeping and growing – but people haven’t started shouting so – I’m going to open them up more.

Lancer Kind

Nice! Lists is either a 3rd party lib or something you’ve built around ArrayList. I substituted ArrayList to create the List. It’s pretty sensible to have a Lists Factory so I like the idea.

Eugen Paraschiv

Yeah, I like the idea as well, but it’s not mine 🙂
No – it’s actually coming out of Guava – they have pretty nice utilities to create collections (among many other cool stuff).

Lancer Kind

It’s annoying how Java libraries make some APIs overly complicated (so we have to build things like “Lists”) by putting implementation details to the front. Remember how hard it was (and still is) to work with Date and Time. I don’t like how every time I work with a Collection I have to think about underlying implementation details. C++ STL didn’t do this (https://en.wikipedia.org/wiki/Standard_Template_Library) and I only needed to think about what kind of container rather than decide if I need an ArrayList…


Nice post and please keep going 🙂

Kajsa Anderson

These would be a lot more useful if they included (even as a footnote) the import statements. There’s enough versions of hamcrest out there that specific methods being statically imported becomes relevant.

Eugen Paraschiv

Hey Kajsa, that’s an interesting point. Generally, the import statements aren’t included because the IDE is able to resolve the automatically, but in this case I think you’re right, they might be worth including (because some of these classes might exist in different packages). I’ll have a look – thanks for the suggestion.