org.mockito

Class Matchers

java.lang.Object

org.mockito.Matchers

Direct Known Subclasses:

Mockito

public class Matchers
extends Object

Allow flexible verification or stubbing. See also AdditionalMatchers.

Mockito extends Matchers so to get access to all matchers just import Mockito class statically.

  //stubbing using anyInt() argument matcher
  when(mockedList.get(anyInt())).thenReturn("element");
  
  //following prints "element"
  System.out.println(mockedList.get(999));
  
  //you can also verify using argument matcher
  verify(mockedList).get(anyInt());
 

Scroll down to see all methods - full list of matchers.

Warning:

If you are using argument matchers, all arguments have to be provided by matchers.

E.g: (example shows verification but the same applies to stubbing):

   verify(mock).someMethod(anyInt(), anyString(), eq("third argument"));
   //above is correct - eq() is also an argument matcher
   
   verify(mock).someMethod(anyInt(), anyString(), "third argument");
   //above is incorrect - exception will be thrown because third argument is given without argument matcher.
 

Matcher methods like anyObject(), eq() do not return matchers. Internally, they record a matcher on a stack and return a dummy value (usually null). This implementation is due static type safety imposed by java compiler. The consequence is that you cannot use anyObject(), eq() methods outside of verified/stubbed method.

Custom Argument Matchers

It is important to understand the use cases and available options for dealing with non-trivial arguments before implementing custom argument matchers. This way, you can select the best possible approach for given scenario and produce highest quality test (clean and maintainable). Please read on in the javadoc for ArgumentMatcher to learn about approaches and see the examples.

Constructor Summary

Constructors

Constructor and Description
Matchers()

Method Summary

Methods

Modifier and Type	Method and Description
static <T> T	any() Matches anything, including nulls
static <T> T	any(Class<T> clazz) Matches any object, including nulls
static boolean	anyBoolean() Any boolean or non-null Boolean
static byte	anyByte() Any byte or non-null Byte.
static char	anyChar() Any char or non-null Character.
static Collection	anyCollection() Any non-null Collection.
static <T> Collection<T>	anyCollectionOf(Class<T> clazz) Generic friendly alias to anyCollection().
static double	anyDouble() Any double or non-null Double.
static float	anyFloat() Any float or non-null Float.
static int	anyInt() Any int or non-null Integer.
static List	anyList() Any non-null List.
static <T> List<T>	anyListOf(Class<T> clazz) Generic friendly alias to anyList().
static long	anyLong() Any long or non-null Long.
static Map	anyMap() Any non-null Map.
static <K,V> Map<K,V>	anyMapOf(Class<K> keyClazz, Class<V> valueClazz) Generic friendly alias to anyMap().
static <T> T	anyObject() Matches anything, including null.
static Set	anySet() Any non-null Set.
static <T> Set<T>	anySetOf(Class<T> clazz) Generic friendly alias to anySet().
static short	anyShort() Any short or non-null Short.
static String	anyString() Any non-null String
static <T> T	anyVararg() Any vararg, meaning any number and values of arguments.
static <T> T	argThat(ArgumentMatcher<T> matcher) Allows creating custom argument matchers.
static boolean	booleanThat(ArgumentMatcher<Boolean> matcher) Allows creating custom boolean argument matchers.
static byte	byteThat(ArgumentMatcher<Byte> matcher) Allows creating custom byte argument matchers.
static char	charThat(ArgumentMatcher<Character> matcher) Allows creating custom char argument matchers.
static String	contains(String substring) String argument that contains the given substring.
static double	doubleThat(ArgumentMatcher<Double> matcher) Allows creating custom double argument matchers.
static String	endsWith(String suffix) String argument that ends with the given suffix.
static boolean	eq(boolean value) boolean argument that is equal to the given value.
static byte	eq(byte value) byte argument that is equal to the given value.
static char	eq(char value) char argument that is equal to the given value.
static double	eq(double value) double argument that is equal to the given value.
static float	eq(float value) float argument that is equal to the given value.
static int	eq(int value) int argument that is equal to the given value.
static long	eq(long value) long argument that is equal to the given value.
static short	eq(short value) short argument that is equal to the given value.
static <T> T	eq(T value) Object argument that is equal to the given value.
static float	floatThat(ArgumentMatcher<Float> matcher) Allows creating custom float argument matchers.
static int	intThat(ArgumentMatcher<Integer> matcher) Allows creating custom int argument matchers.
static <T> T	isA(Class<T> type) Object argument that implements the given class.
static Object	isNotNull() Not null argument.
static <T> T	isNotNull(Class<T> clazz) Not null argument, not necessary of the given class.
static Object	isNull() null argument.
static <T> T	isNull(Class<T> clazz) null argument.
static long	longThat(ArgumentMatcher<Long> matcher) Allows creating custom long argument matchers.
static String	matches(String regex) String argument that matches the given regular expression.
static Object	notNull() Not null argument.
static <T> T	notNull(Class<T> clazz) Not null argument, not necessary of the given class.
static <T> T	refEq(T value, String... excludeFields) Object argument that is reflection-equal to the given value with support for excluding selected fields from a class.
static <T> T	same(T value) Object argument that is the same as the given value.
static short	shortThat(ArgumentMatcher<Short> matcher) Allows creating custom short argument matchers.
static String	startsWith(String prefix) String argument that starts with the given prefix.

Methods inherited from class java.lang.Object

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

Constructor Detail

Matchers

public Matchers()

Method Detail

anyBoolean

public static boolean anyBoolean()

Any boolean or non-null Boolean

See examples in javadoc for Matchers class

Returns:

false.

anyByte

public static byte anyByte()

Any byte or non-null Byte.

See examples in javadoc for Matchers class

Returns:

0.

anyChar

public static char anyChar()

Any char or non-null Character.

See examples in javadoc for Matchers class

Returns:

0.

anyInt

public static int anyInt()

Any int or non-null Integer.

See examples in javadoc for Matchers class

Returns:

0.

anyLong

public static long anyLong()

Any long or non-null Long.

See examples in javadoc for Matchers class

Returns:

0.

anyFloat

public static float anyFloat()

Any float or non-null Float.

See examples in javadoc for Matchers class

Returns:

0.

anyDouble

public static double anyDouble()

Any double or non-null Double.

See examples in javadoc for Matchers class

Returns:

0.

anyShort

public static short anyShort()

Any short or non-null Short.

See examples in javadoc for Matchers class

Returns:

0.

anyObject

public static <T> T anyObject()

Matches anything, including null.

This is an alias of: any() and any(java.lang.Class)

See examples in javadoc for Matchers class

Returns:

null.

anyVararg

public static <T> T anyVararg()

Any vararg, meaning any number and values of arguments.

Example:

   //verification:
   mock.foo(1, 2);
   mock.foo(1, 2, 3, 4);

   verify(mock, times(2)).foo(anyVararg());

   //stubbing:
   when(mock.foo(anyVararg()).thenReturn(100);

   //prints 100
   System.out.println(mock.foo(1, 2));
   //also prints 100
   System.out.println(mock.foo(1, 2, 3, 4));
 

See examples in javadoc for Matchers class

Returns:

null.

any

public static <T> T any(Class<T> clazz)

Matches any object, including nulls

This method doesn't do type checks with the given parameter, it is only there to avoid casting in your code. This might however change (type checks could be added) in a future major release.

See examples in javadoc for Matchers class

This is an alias of: any() and anyObject()

Returns:

null.

any

public static <T> T any()

Matches anything, including nulls

Shorter alias to anyObject()

See examples in javadoc for Matchers class

This is an alias of: anyObject() and any(java.lang.Class)

Returns:

null.

anyString

public static String anyString()

Any non-null String

See examples in javadoc for Matchers class

Returns:

empty String ("")

anyList

public static List anyList()

Any non-null List.

See examples in javadoc for Matchers class

Returns:

empty List.

anyListOf

public static <T> List<T> anyListOf(Class<T> clazz)

Generic friendly alias to anyList(). It's an alternative to @SuppressWarnings("unchecked") to keep code clean of compiler warnings.

Any non-null List.

This method doesn't do type checks with the given parameter, it is only there to avoid casting in your code. This might however change (type checks could be added) in a future major release.

See examples in javadoc for Matchers class

Parameters:

clazz - Type owned by the list to avoid casting

Returns:

empty List.

anySet

public static Set anySet()

Any non-null Set.

See examples in javadoc for Matchers class

Returns:

empty Set

anySetOf

public static <T> Set<T> anySetOf(Class<T> clazz)

Generic friendly alias to anySet(). It's an alternative to @SuppressWarnings("unchecked") to keep code clean of compiler warnings.

Any non-null Set.

This method doesn't do type checks with the given parameter, it is only there to avoid casting in your code. This might however change (type checks could be added) in a future major release.

See examples in javadoc for Matchers class

Parameters:

clazz - Type owned by the Set to avoid casting

Returns:

empty Set

anyMap

public static Map anyMap()

Any non-null Map.

See examples in javadoc for Matchers class

Returns:

empty Map.

anyMapOf

public static <K,V> Map<K,V> anyMapOf(Class<K> keyClazz,
                      Class<V> valueClazz)

Generic friendly alias to anyMap(). It's an alternative to @SuppressWarnings("unchecked") to keep code clean of compiler warnings.

Any non-null Map.

This method doesn't do type checks with the given parameter, it is only there to avoid casting in your code. This might however change (type checks could be added) in a future major release.

See examples in javadoc for Matchers class

Parameters:

keyClazz - Type of the map key to avoid casting

valueClazz - Type of the value to avoid casting

Returns:

empty Map.

anyCollection

public static Collection anyCollection()

Any non-null Collection.

See examples in javadoc for Matchers class

Returns:

empty Collection.

anyCollectionOf

public static <T> Collection<T> anyCollectionOf(Class<T> clazz)

Generic friendly alias to anyCollection(). It's an alternative to @SuppressWarnings("unchecked") to keep code clean of compiler warnings.

Any non-null Collection.

This method doesn't do type checks with the given parameter, it is only there to avoid casting in your code. This might however change (type checks could be added) in a future major release.

See examples in javadoc for Matchers class

Parameters:

clazz - Type owned by the collection to avoid casting

Returns:

empty Collection.

isA

public static <T> T isA(Class<T> type)

Object argument that implements the given class.

See examples in javadoc for Matchers class

Type Parameters:

T - the accepted type.

Parameters:

type - the class of the accepted type.

Returns:

null.

eq

public static boolean eq(boolean value)

boolean argument that is equal to the given value.

See examples in javadoc for Matchers class

Parameters:

value - the given value.

Returns:

0.

eq

public static byte eq(byte value)

byte argument that is equal to the given value.

See examples in javadoc for Matchers class

Parameters:

value - the given value.

Returns:

0.

eq

public static char eq(char value)

char argument that is equal to the given value.

See examples in javadoc for Matchers class

Parameters:

value - the given value.

Returns:

0.

eq

public static double eq(double value)

double argument that is equal to the given value.

See examples in javadoc for Matchers class

Parameters:

value - the given value.

Returns:

0.

eq

public static float eq(float value)

float argument that is equal to the given value.

See examples in javadoc for Matchers class

Parameters:

value - the given value.

Returns:

0.

eq

public static int eq(int value)

int argument that is equal to the given value.

See examples in javadoc for Matchers class

Parameters:

value - the given value.

Returns:

0.

eq

public static long eq(long value)

long argument that is equal to the given value.

See examples in javadoc for Matchers class

Parameters:

value - the given value.

Returns:

0.

eq

public static short eq(short value)

short argument that is equal to the given value.

See examples in javadoc for Matchers class

Parameters:

value - the given value.

Returns:

0.

eq

public static <T> T eq(T value)

Object argument that is equal to the given value.

See examples in javadoc for Matchers class

Parameters:

value - the given value.

Returns:

null.

refEq

public static <T> T refEq(T value,
          String... excludeFields)

Object argument that is reflection-equal to the given value with support for excluding selected fields from a class.

This matcher can be used when equals() is not implemented on compared objects. Matcher uses java reflection API to compare fields of wanted and actual object.

Works similarly to EqualsBuilder.reflectionEquals(this, other, exlucdeFields) from apache commons library.

Warning The equality check is shallow!

See examples in javadoc for Matchers class

Parameters:

value - the given value.

excludeFields - fields to exclude, if field does not exist it is ignored.

Returns:

null.

same

public static <T> T same(T value)

Object argument that is the same as the given value.

See examples in javadoc for Matchers class

Type Parameters:

T - the type of the object, it is passed through to prevent casts.

Parameters:

value - the given value.

Returns:

null.

isNull

public static Object isNull()

null argument.

See examples in javadoc for Matchers class

Returns:

null.

isNull

public static <T> T isNull(Class<T> clazz)

null argument. The class argument is provided to avoid casting.

See examples in javadoc for Matchers class

Parameters:

clazz - Type to avoid casting

Returns:

null.

notNull

public static Object notNull()

Not null argument.

alias to isNotNull()

See examples in javadoc for Matchers class

Returns:

null.

notNull

public static <T> T notNull(Class<T> clazz)

Not null argument, not necessary of the given class. The class argument is provided to avoid casting.

alias to isNotNull(Class)

See examples in javadoc for Matchers class

Parameters:

clazz - Type to avoid casting

Returns:

null.

isNotNull

public static Object isNotNull()

Not null argument.

alias to notNull()

See examples in javadoc for Matchers class

Returns:

null.

isNotNull

public static <T> T isNotNull(Class<T> clazz)

Not null argument, not necessary of the given class. The class argument is provided to avoid casting.

alias to notNull(Class)

See examples in javadoc for Matchers class

Parameters:

clazz - Type to avoid casting

Returns:

null.

contains

public static String contains(String substring)

String argument that contains the given substring.

See examples in javadoc for Matchers class

Parameters:

substring - the substring.

Returns:

empty String ("").

matches

public static String matches(String regex)

String argument that matches the given regular expression.

See examples in javadoc for Matchers class

Parameters:

regex - the regular expression.

Returns:

empty String ("").

endsWith

public static String endsWith(String suffix)

String argument that ends with the given suffix.

See examples in javadoc for Matchers class

Parameters:

suffix - the suffix.

Returns:

empty String ("").

startsWith

public static String startsWith(String prefix)

String argument that starts with the given prefix.

See examples in javadoc for Matchers class

Parameters:

prefix - the prefix.

Returns:

empty String ("").

argThat

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

Allows creating custom argument matchers. This API has changed in 2.0, please read ArgumentMatcher for rationale and migration guide. NullPointerException auto-unboxing caveat is described below.

It is important to understand the use cases and available options for dealing with non-trivial arguments before implementing custom argument matchers. This way, you can select the best possible approach for given scenario and produce highest quality test (clean and maintainable). Please read the documentation for ArgumentMatcher to learn about approaches and see the examples.

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.

See examples in javadoc for ArgumentMatcher class

Parameters:

matcher - decides whether argument matches

Returns:

null.

charThat

public static char charThat(ArgumentMatcher<Character> matcher)

Allows creating custom char argument matchers. Note that argThat(org.mockito.ArgumentMatcher) will not work with primitive char matchers due to NullPointerException auto-unboxing caveat.

See examples in javadoc for Matchers class

Parameters:

matcher - decides whether argument matches

Returns:

0.

booleanThat

public static boolean booleanThat(ArgumentMatcher<Boolean> matcher)

Allows creating custom boolean argument matchers. Note that argThat(org.mockito.ArgumentMatcher) will not work with primitive boolean matchers due to NullPointerException auto-unboxing caveat.

See examples in javadoc for Matchers class

Parameters:

matcher - decides whether argument matches

Returns:

false.

byteThat

public static byte byteThat(ArgumentMatcher<Byte> matcher)

Allows creating custom byte argument matchers. Note that argThat(org.mockito.ArgumentMatcher) will not work with primitive byte matchers due to NullPointerException auto-unboxing caveat.

See examples in javadoc for Matchers class

Parameters:

matcher - decides whether argument matches

Returns:

0.

shortThat

public static short shortThat(ArgumentMatcher<Short> matcher)

Allows creating custom short argument matchers. Note that argThat(org.mockito.ArgumentMatcher) will not work with primitive short matchers due to NullPointerException auto-unboxing caveat.

See examples in javadoc for Matchers class

Parameters:

matcher - decides whether argument matches

Returns:

0.

intThat

public static int intThat(ArgumentMatcher<Integer> matcher)

Allows creating custom int argument matchers. Note that argThat(org.mockito.ArgumentMatcher) will not work with primitive int matchers due to NullPointerException auto-unboxing caveat.

See examples in javadoc for Matchers class

Parameters:

matcher - decides whether argument matches

Returns:

0.

longThat

public static long longThat(ArgumentMatcher<Long> matcher)

Allows creating custom long argument matchers. Note that argThat(org.mockito.ArgumentMatcher) will not work with primitive long matchers due to NullPointerException auto-unboxing caveat.

See examples in javadoc for Matchers class

Parameters:

matcher - decides whether argument matches

Returns:

0.

floatThat

public static float floatThat(ArgumentMatcher<Float> matcher)

Allows creating custom float argument matchers. Note that argThat(org.mockito.ArgumentMatcher) will not work with primitive float matchers due to NullPointerException auto-unboxing caveat.

See examples in javadoc for Matchers class

Parameters:

matcher - decides whether argument matches

Returns:

0.

doubleThat

public static double doubleThat(ArgumentMatcher<Double> matcher)

Allows creating custom double argument matchers. Note that argThat(org.mockito.ArgumentMatcher) will not work with primitive double matchers due to NullPointerException auto-unboxing caveat.

See examples in javadoc for Matchers class

Parameters:

matcher - decides whether argument matches

Returns:

0.