How do Hamcrest's hasItems, contains and containsInAnyOrder differ?

Question

Hamcrest provides a number of matchers for asserting the contents of a collection. All of these cases pass:

Collection<String> c = ImmutableList.of("one", "two", "three");
assertThat(c, hasItems("one", "two", "three");
assertThat(c, contains("one", "two", "three");
assertThat(c, containsInAnyOrder("one", "two", "three");

How do hasItems, contains and containsInAnyOrder differ?

Answer 1

hasItems checks:

consecutive passes over the examined Iterable yield at least one item that is equal to the corresponding item from the specified items.

That is, it makes sure that the collections contains at least these items, in any order. So,

assertThat(c, hasItems("one", "two"));

would also pass, with the extra item being ignored. And:

assertThat(c, hasItems("three", "two", "one"));

would also pass.

contains checks:

a single pass over the examined Iterable yields a series of items, each logically equal to the corresponding item in the specified items. For a positive match, the examined iterable must be of the same length as the number of specified items.

So it makes sure that the collection contains exactly these items:

assertThat(c, contains("one", "two")); // Fails

This would fail, as the leftover "three" is not matched.

assertThat(c, contains("three", "two", "one")); // Fails

This fails because the corresponding items don't match.

Another related matcher, containsInAnyOrder, checks that exactly those items are present, but in any order:

Creates an order agnostic matcher for Iterables that matches when a single pass over the examined Iterable yields a series of items, each logically equal to one item anywhere in the specified items.

A test with a missing item fails:

assertThat(c, containsInAnyOrder("one", "two")); // Fails

But all items in a different order will pass:

assertThat(c, containsInAnyOrder("three", "two", "one"));