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?

Selfsatisfied

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"));

Selfsatisfied

I would rename contains into consistsOf – Jarvis

contains is a MASSIVE misnomer. I would have expected that contains does the same as Collection#contains. – Cowpea

AssertJ calls this method containsExactly, which may also help reduce surprise. – Selfsatisfied

what if i want to use containsInAnyOrder, but the lists contains duplicates? e.g i want to check, if List contains exact elements, but they have duplicates - in that case containsAnyOrder("three","three","one") would holds true, even if tested list only has ("three,"one") elements. How to deal with this? – Asleyaslope

@DaneelS.Yaitskov consistsOfOrdered – Monomer