Package org.mockito.hamcrest

Class MockitoHamcrest

java.lang.Object

org.mockito.hamcrest.MockitoHamcrest

public final class MockitoHamcrest
extends Object

Allows matching arguments with hamcrest matchers. Requires hamcrest on classpath, Mockito does not depend on hamcrest! Note the NullPointerException auto-unboxing caveat described below.

Before implementing or reusing an existing hamcrest matcher please read how to deal with sophisticated argument matching in ArgumentMatcher.

Mockito 2.1.0 was decoupled from Hamcrest to avoid version incompatibilities that have impacted our users in past. Mockito offers a dedicated API to match arguments via ArgumentMatcher. Hamcrest integration is provided so that users can take advantage of existing Hamcrest matchers.

Example:

     import static org.mockito.hamcrest.MockitoHamcrest.argThat;

     //stubbing
     when(mock.giveMe(argThat(new MyHamcrestMatcher())));

     //verification
     verify(mock).giveMe(argThat(new MyHamcrestMatcher()));
 

NullPointerException auto-unboxing caveat. In rare cases when matching primitive parameter types you *must* use relevant intThat(), floatThat(), etc. method. This way you will avoid NullPointerException during auto-unboxing. Due to how java works we don't really have a clean way of detecting this scenario and protecting the user from this problem. Hopefully, the javadoc describes the problem and solution well. If you have an idea how to fix the problem, let us know via the mailing list or the issue tracker.

By default, a matcher passed to a varargs parameter will match against the first element in the varargs array. To match against the raw varargs array pass the type of the varargs parameter to argThat(Matcher, Class)

For example, to match any number of String values:

     import static org.hamcrest.CoreMatchers.isA;
     import static org.mockito.hamcrest.MockitoHamcrest.argThat;

     // Given:
     void varargMethod(String... args);

     //stubbing
     when(mock.varargMethod(argThat(isA(String[].class), String[].class));

     //verification
     verify(mock).giveMe(argThat(isA(String[].class), String[].class));
 

Since:

2.1.0

Method Summary

Modifier and Type	Method	Description
static <T> T	argThat(Matcher<T> matcher)	Allows matching arguments with hamcrest matchers.
static <T> T	argThat(Matcher<T> matcher, Class<T> type)	Allows matching arguments with hamcrest matchers.
static boolean	booleanThat(Matcher<Boolean> matcher)	Enables integrating hamcrest matchers that match primitive boolean arguments.
static byte	byteThat(Matcher<Byte> matcher)	Enables integrating hamcrest matchers that match primitive byte arguments.
static char	charThat(Matcher<Character> matcher)	Enables integrating hamcrest matchers that match primitive char arguments.
static double	doubleThat(Matcher<Double> matcher)	Enables integrating hamcrest matchers that match primitive double arguments.
static float	floatThat(Matcher<Float> matcher)	Enables integrating hamcrest matchers that match primitive float arguments.
static int	intThat(Matcher<Integer> matcher)	Enables integrating hamcrest matchers that match primitive int arguments.
static long	longThat(Matcher<Long> matcher)	Enables integrating hamcrest matchers that match primitive long arguments.
static short	shortThat(Matcher<Short> matcher)	Enables integrating hamcrest matchers that match primitive short arguments.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Details

argThat

public static <T> T argThat(Matcher<T> matcher)

Allows matching arguments with hamcrest matchers.

See examples in javadoc for MockitoHamcrest class

Parameters:

matcher - decides whether argument matches

Returns:

null or default value for primitive (0, false, etc.)

Since:

2.1.0

argThat

public static <T> T argThat(Matcher<T> matcher,
 Class<T> type)

Allows matching arguments with hamcrest matchers.

This variant can be used to pass an explicit type, which can be useful to provide a matcher that matches against all elements in a varargs parameter.

See examples in javadoc for MockitoHamcrest class

Parameters:

matcher - decides whether argument matches

type - the type the matcher matches.

Returns:

null or default value for primitive (0, false, etc.)

Since:

5.0.0

charThat

public static char charThat(Matcher<Character> matcher)

Enables integrating hamcrest matchers that match primitive char arguments. Note that argThat(org.hamcrest.Matcher<T>) will not work with primitive char matchers due to NullPointerException auto-unboxing caveat.

See examples in javadoc for MockitoHamcrest class

Parameters:

matcher - decides whether argument matches

Returns:

0.

booleanThat

public static boolean booleanThat(Matcher<Boolean> matcher)

Enables integrating hamcrest matchers that match primitive boolean arguments. Note that argThat(org.hamcrest.Matcher<T>) will not work with primitive boolean matchers due to NullPointerException auto-unboxing caveat.

See examples in javadoc for MockitoHamcrest class

Parameters:

matcher - decides whether argument matches

Returns:

false.

byteThat

public static byte byteThat(Matcher<Byte> matcher)

Enables integrating hamcrest matchers that match primitive byte arguments. Note that argThat(org.hamcrest.Matcher<T>) will not work with primitive byte matchers due to NullPointerException auto-unboxing caveat.

* See examples in javadoc for MockitoHamcrest class

Parameters:

matcher - decides whether argument matches

Returns:

0.

shortThat

public static short shortThat(Matcher<Short> matcher)

Enables integrating hamcrest matchers that match primitive short arguments. Note that argThat(org.hamcrest.Matcher<T>) will not work with primitive short matchers due to NullPointerException auto-unboxing caveat.

* See examples in javadoc for MockitoHamcrest class

Parameters:

matcher - decides whether argument matches

Returns:

0.

intThat

public static int intThat(Matcher<Integer> matcher)

Enables integrating hamcrest matchers that match primitive int arguments. Note that argThat(org.hamcrest.Matcher<T>) will not work with primitive int matchers due to NullPointerException auto-unboxing caveat.

* See examples in javadoc for MockitoHamcrest class

Parameters:

matcher - decides whether argument matches

Returns:

0.

longThat

public static long longThat(Matcher<Long> matcher)

Enables integrating hamcrest matchers that match primitive long arguments. Note that argThat(org.hamcrest.Matcher<T>) will not work with primitive long matchers due to NullPointerException auto-unboxing caveat.

* See examples in javadoc for MockitoHamcrest class

Parameters:

matcher - decides whether argument matches

Returns:

0.

floatThat

public static float floatThat(Matcher<Float> matcher)

Enables integrating hamcrest matchers that match primitive float arguments. Note that argThat(org.hamcrest.Matcher<T>) will not work with primitive float matchers due to NullPointerException auto-unboxing caveat.

* See examples in javadoc for MockitoHamcrest class

Parameters:

matcher - decides whether argument matches

Returns:

0.

doubleThat

public static double doubleThat(Matcher<Double> matcher)

Enables integrating hamcrest matchers that match primitive double arguments. Note that argThat(org.hamcrest.Matcher<T>) will not work with primitive double matchers due to NullPointerException auto-unboxing caveat.

* See examples in javadoc for MockitoHamcrest class

Parameters:

matcher - decides whether argument matches

Returns:

0.