Mockito's Matcher vs Hamcrest Matcher?

Question

That's going to be an easy one, but I cannot find the difference between them and which one to use, if I have both the lib's included in my classpath?

Solution

Hamcrest matcher methods return Matcher<T> and Mockito matchers return T. So, for example: org.hamcrest.Matchers.any(Integer.class) returns an instance of org.hamcrest.Matcher<Integer>, and org.mockito.Matchers.any(Integer.class) returns an instance of Integer.

That means that you can only use Hamcrest matchers when a Matcher<?> object is expected in the signature - typically, in assertThat calls. When setting up expectations or verifications where you are calling methods of the mock object, you use the Mockito matchers.

For example (with fully qualified names for clarity):

@Test
public void testGetDelegatedBarByIndex() {
    Foo mockFoo = mock(Foo.class);
    // inject our mock
    objectUnderTest.setFoo(mockFoo);
    Bar mockBar = mock(Bar.class);
    when(mockFoo.getBarByIndex(org.mockito.Matchers.any(Integer.class))).
        thenReturn(mockBar);

    Bar actualBar = objectUnderTest.getDelegatedBarByIndex(1);
    
    assertThat(actualBar, org.hamcrest.Matchers.any(Bar.class));
    verify(mockFoo).getBarByIndex(org.mockito.Matchers.any(Integer.class));
}

If you want to use a Hamcrest matcher in a context that requires a Mockito matcher, you can use the org.mockito.Matchers.argThat (or org.mockito.hamcrest.MockitoHamcrest.argThat in Mockito 2). It converts a Hamcrest matcher into a Mockito matcher. So, say you wanted to match a double value with some precision (but not much). In that case, you could do:

when(mockFoo.getBarByDouble(argThat(is(closeTo(1.0, 0.001))))).
    thenReturn(mockBar);

Comments

[Jeff Bowman]

Related: How do Mockito matchers work?

[Bryan Turner]

Just noting that, in Mockito 2, the argThat overload that works with Hamcrest Matchers was moved MockitoHamcrest. What's new in Mockito 2 discusses this in its "Incompatible changes with 1.10" section.