Hamcrest Matchers.contains matcher not working (?)

Question

I am trying to test if a collection has an item which toString() method returns a particular String. I tried do it using excellent Hamcrest matching classes, by combining contains with Matchers.hasToString, but somehow, its Matchers.contains is not being able to match an item even though it is present in the collection.

Here's an example:

class Item {

    private String name;

    public Item(String name){
        this.name = name;
    }

    public String toString(){
        return name;
    }
}

// here's a sample collection, with the desired item added in the end
Collection<Item> items = new LinkedList<Item>(){{ 
    add(new Item("a")); 
    add(new Item("b"));
    add(new Item("c")); 
}};

Assert.assertThat(items, Matchers.contains(Matchers.hasToString("c")));

The above assertion is not successful. Here's the message:

java.lang.AssertionError: 
Expected: iterable containing [with toString() "c"]
     but: item 0: toString() was "a"
    at org.hamcrest.MatcherAssert.assertThat(MatcherAssert.java:20)
    at org.junit.Assert.assertThat(Assert.java:865)
    at org.junit.Assert.assertThat(Assert.java:832)

It looks like the Matchers.contains matcher tries to iterate over the list, but the Matchers.hasToString matcher fails in the first item and invalidates the rest of the iteration. Hamcrest javadoc for Matchers.contains says:

"Creates a matcher for Iterables that matches when a single pass over the examined Iterable yields a single item that satisfies the specified matcher. For a positive match, the examined iterable must only yield one item"

Am I doing something wrong?

Answer 1

I think you're looking for Matchers.hasItem(..)

Assert.assertThat(items, Matchers.hasItem(Matchers.hasToString("c")));

which states

Creates a matcher for Iterables that only matches when a single pass over the examined Iterable yields at least one item that is matched by the specified itemMatcher. Whilst matching, the traversal of the examined Iterable will stop as soon as a matching item is found.

Matchers.contains, as you stated,

Creates a matcher for Iterables that matches when a single pass over the examined Iterable yields a single item that satisfies the specified matcher. For a positive match, the examined iterable must only yield one item.

It seems to me like that's saying there should only be one element in the Iterable.