Class Matchers
- java.lang.Object
-
- org.mockito.Matchers
-
- Direct Known Subclasses:
Mockito
public class Matchers extends java.lang.Object
Allow flexible verification or stubbing. See alsoAdditionalMatchers
.Mockito
extends Matchers so to get access to all matchers just import Mockito class statically.
Scroll down to see all methods - full list of matchers.//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());
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 useanyObject()
,eq()
methods outside of verified/stubbed method.Warning 2:
The any family methods *doesn't do any type checks*, those are only here to avoid casting in your code. If you want to perform type checks use the
isA(Class)
method. This might however change (type checks could be added) in a future major release.Custom Argument Matchers
UseargThat(org.hamcrest.Matcher<T>)
method and pass an instance of hamcrestMatcher
.Before you start implementing your own custom argument matcher, make sure you check out
ArgumentCaptor
api.So, how to implement your own argument matcher? First, you might want to subclass
ArgumentMatcher
which is an hamcrest matcher with predefined describeTo() method. Default description generated by describeTo() uses decamelized class name - to promote meaningful class names.Example:
To keep it readable you may want to extract method, e.g:class IsListOfTwoElements extends ArgumentMatcher<List> { public boolean matches(Object list) { return ((List) list).size() == 2; } } List mock = mock(List.class); when(mock.addAll(argThat(new IsListOfTwoElements()))).thenReturn(true); mock.addAll(Arrays.asList("one", "two")); verify(mock).addAll(argThat(new IsListOfTwoElements()));
Warning: Be reasonable with using complicated argument matching, especially custom argument matchers, as it can make the test less readable. Sometimes it's better to implement equals() for arguments that are passed to mocks (Mockito naturally uses equals() for argument matching). This can make the test cleaner.verify(mock).addAll(argThat(new IsListOfTwoElements())); //becomes verify(mock).addAll(listOfTwoElements());
Also, sometimes
ArgumentCaptor
may be a better fit than custom matcher. For example, if custom argument matcher is not likely to be reused or you just need it to assert on argument values to complete verification of behavior.
-
-
Constructor Summary
Constructors Constructor Description Matchers()
-
Method Summary
All Methods Static Methods Concrete Methods Modifier and Type Method Description static <T> T
any()
Any object ornull
.static <T> T
any(java.lang.Class<T> clazz)
Any kind object, not necessary of the given class.static boolean
anyBoolean()
Anyboolean
,Boolean
ornull
.static byte
anyByte()
Anybyte
,Byte
ornull
.static char
anyChar()
Anychar
,Character
ornull
.static java.util.Collection
anyCollection()
AnyCollection
ornull
.static <T> java.util.Collection<T>
anyCollectionOf(java.lang.Class<T> clazz)
Generic friendly alias toanyCollection()
.static double
anyDouble()
Anydouble
,Double
ornull
.static float
anyFloat()
Anyfloat
,Float
ornull
.static int
anyInt()
Any int, Integer ornull
.static java.util.List
anyList()
AnyList
ornull
.static <T> java.util.List<T>
anyListOf(java.lang.Class<T> clazz)
Generic friendly alias toanyList()
.static long
anyLong()
Anylong
,Long
ornull
.static java.util.Map
anyMap()
AnyMap
ornull
.static <K,V>
java.util.Map<K,V>anyMapOf(java.lang.Class<K> keyClazz, java.lang.Class<V> valueClazz)
Generic friendly alias toanyMap()
.static <T> T
anyObject()
AnyObject
ornull
.static java.util.Set
anySet()
AnySet
ornull
.static <T> java.util.Set<T>
anySetOf(java.lang.Class<T> clazz)
Generic friendly alias toanySet()
.static short
anyShort()
Anyshort
,Short
ornull
.static java.lang.String
anyString()
AnyString
ornull
.static <T> T
anyVararg()
Any vararg, meaning any number and values of arguments.static <T> T
argThat(org.hamcrest.Matcher<T> matcher)
Allows creating custom argument matchers.static boolean
booleanThat(org.hamcrest.Matcher<java.lang.Boolean> matcher)
Allows creating customBoolean
argument matchers.static byte
byteThat(org.hamcrest.Matcher<java.lang.Byte> matcher)
Allows creating customByte
argument matchers.static char
charThat(org.hamcrest.Matcher<java.lang.Character> matcher)
Allows creating customCharacter
argument matchers.static java.lang.String
contains(java.lang.String substring)
String
argument that contains the given substring.static double
doubleThat(org.hamcrest.Matcher<java.lang.Double> matcher)
Allows creating customDouble
argument matchers.static java.lang.String
endsWith(java.lang.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(org.hamcrest.Matcher<java.lang.Float> matcher)
Allows creating customFloat
argument matchers.static int
intThat(org.hamcrest.Matcher<java.lang.Integer> matcher)
Allows creating customInteger
argument matchers.static <T> T
isA(java.lang.Class<T> clazz)
Object
argument that implements the given class.static java.lang.Object
isNotNull()
Notnull
argument.static <T> T
isNotNull(java.lang.Class<T> clazz)
Notnull
argument, not necessary of the given class.static java.lang.Object
isNull()
null
argument.static <T> T
isNull(java.lang.Class<T> clazz)
null
argument.static long
longThat(org.hamcrest.Matcher<java.lang.Long> matcher)
Allows creating customLong
argument matchers.static java.lang.String
matches(java.lang.String regex)
String
argument that matches the given regular expression.static java.lang.Object
notNull()
Notnull
argument.static <T> T
notNull(java.lang.Class<T> clazz)
Notnull
argument, not necessary of the given class.static <T> T
refEq(T value, java.lang.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(org.hamcrest.Matcher<java.lang.Short> matcher)
Allows creating customShort
argument matchers.static java.lang.String
startsWith(java.lang.String prefix)
String
argument that starts with the given prefix.
-
-
-
Method Detail
-
anyBoolean
public static boolean anyBoolean()
Anyboolean
,Boolean
ornull
.This method *doesn't do any type checks*, 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- Returns:
false
.
-
anyByte
public static byte anyByte()
Anybyte
,Byte
ornull
.This method *doesn't do any type checks*, 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- Returns:
0
.
-
anyChar
public static char anyChar()
Anychar
,Character
ornull
.This method *doesn't do any type checks*, 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- Returns:
0
.
-
anyInt
public static int anyInt()
Any int, Integer ornull
.This method *doesn't do any type checks*, 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- Returns:
0
.
-
anyLong
public static long anyLong()
Anylong
,Long
ornull
.This method *doesn't do any type checks*, 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- Returns:
0
.
-
anyFloat
public static float anyFloat()
Anyfloat
,Float
ornull
.This method *doesn't do any type checks*, 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- Returns:
0
.
-
anyDouble
public static double anyDouble()
Anydouble
,Double
ornull
.This method *doesn't do any type checks*, 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- Returns:
0
.
-
anyShort
public static short anyShort()
Anyshort
,Short
ornull
.This method *doesn't do any type checks*, 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- Returns:
0
.
-
anyObject
public static <T> T anyObject()
AnyObject
ornull
.This method *doesn't do any type checks*, it is only there to avoid casting in your code. This might however change (type checks could be added) in a future major release.
Has aliases:
any()
andany(Class clazz)
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:
See examples in javadoc for//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));
Matchers
class- Returns:
null
.
-
any
public static <T> T any(java.lang.Class<T> clazz)
Any kind object, not necessary of the given class. The class argument is provided only to avoid casting.Sometimes looks better than
anyObject()
- especially when explicit casting is requiredAlias to
anyObject()
This method *doesn't do any type checks*, 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
- The type to avoid casting- Returns:
null
.
-
any
public static <T> T any()
Any object ornull
.Shorter alias to
anyObject()
This method *doesn't do any type checks*, 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- Returns:
null
.
-
anyString
public static java.lang.String anyString()
AnyString
ornull
.This method *doesn't do any type checks*, 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- Returns:
- empty String ("")
-
anyList
public static java.util.List anyList()
AnyList
ornull
.This method *doesn't do any type checks*, 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- Returns:
- empty List.
-
anyListOf
public static <T> java.util.List<T> anyListOf(java.lang.Class<T> clazz)
Generic friendly alias toanyList()
. It's an alternative to @SuppressWarnings("unchecked") to keep code clean of compiler warnings.Any
List
ornull
.This method *doesn't do any type checks*, 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 java.util.Set anySet()
AnySet
ornull
.This method *doesn't do any type checks*, 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- Returns:
- empty Set
-
anySetOf
public static <T> java.util.Set<T> anySetOf(java.lang.Class<T> clazz)
Generic friendly alias toanySet()
. It's an alternative to @SuppressWarnings("unchecked") to keep code clean of compiler warnings.Any
Set
ornull
This method *dones't do any type checks*, 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 java.util.Map anyMap()
AnyMap
ornull
.This method *doesn't do any type checks*, 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- Returns:
- empty Map.
-
anyMapOf
public static <K,V> java.util.Map<K,V> anyMapOf(java.lang.Class<K> keyClazz, java.lang.Class<V> valueClazz)
Generic friendly alias toanyMap()
. It's an alternative to @SuppressWarnings("unchecked") to keep code clean of compiler warnings.Any
Map
ornull
This method *doesn't do any type checks*, 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 castingvalueClazz
- Type of the value to avoid casting- Returns:
- empty Map.
-
anyCollection
public static java.util.Collection anyCollection()
AnyCollection
ornull
.This method *dones't do any type checks*, 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- Returns:
- empty Collection.
-
anyCollectionOf
public static <T> java.util.Collection<T> anyCollectionOf(java.lang.Class<T> clazz)
Generic friendly alias toanyCollection()
. It's an alternative to @SuppressWarnings("unchecked") to keep code clean of compiler warnings.Any
Collection
ornull
.This method *doesn't do any type checks*, 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(java.lang.Class<T> clazz)
Object
argument that implements the given class.See examples in javadoc for
Matchers
class- Type Parameters:
T
- the accepted type.- Parameters:
clazz
- 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, java.lang.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 java.lang.Object isNull()
null
argument.See examples in javadoc for
Matchers
class- Returns:
null
.
-
isNull
public static <T> T isNull(java.lang.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 java.lang.Object notNull()
- Returns:
null
.
-
notNull
public static <T> T notNull(java.lang.Class<T> clazz)
Notnull
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 java.lang.Object isNotNull()
- Returns:
null
.
-
isNotNull
public static <T> T isNotNull(java.lang.Class<T> clazz)
Notnull
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 java.lang.String contains(java.lang.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 java.lang.String matches(java.lang.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 java.lang.String endsWith(java.lang.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 java.lang.String startsWith(java.lang.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(org.hamcrest.Matcher<T> matcher)
Allows creating custom argument matchers.In rare cases when the parameter is a primitive then you *must* use relevant intThat(), floatThat(), etc. method. This way you will avoid
NullPointerException
during auto-unboxing.See examples in javadoc for
ArgumentMatcher
class- Parameters:
matcher
- decides whether argument matches- Returns:
null
.
-
charThat
public static char charThat(org.hamcrest.Matcher<java.lang.Character> matcher)
Allows creating customCharacter
argument matchers.See examples in javadoc for
Matchers
class- Parameters:
matcher
- decides whether argument matches- Returns:
0
.
-
booleanThat
public static boolean booleanThat(org.hamcrest.Matcher<java.lang.Boolean> matcher)
Allows creating customBoolean
argument matchers.See examples in javadoc for
Matchers
class- Parameters:
matcher
- decides whether argument matches- Returns:
false
.
-
byteThat
public static byte byteThat(org.hamcrest.Matcher<java.lang.Byte> matcher)
Allows creating customByte
argument matchers.See examples in javadoc for
Matchers
class- Parameters:
matcher
- decides whether argument matches- Returns:
0
.
-
shortThat
public static short shortThat(org.hamcrest.Matcher<java.lang.Short> matcher)
Allows creating customShort
argument matchers.See examples in javadoc for
Matchers
class- Parameters:
matcher
- decides whether argument matches- Returns:
0
.
-
intThat
public static int intThat(org.hamcrest.Matcher<java.lang.Integer> matcher)
Allows creating customInteger
argument matchers.See examples in javadoc for
Matchers
class- Parameters:
matcher
- decides whether argument matches- Returns:
0
.
-
longThat
public static long longThat(org.hamcrest.Matcher<java.lang.Long> matcher)
Allows creating customLong
argument matchers.See examples in javadoc for
Matchers
class- Parameters:
matcher
- decides whether argument matches- Returns:
0
.
-
floatThat
public static float floatThat(org.hamcrest.Matcher<java.lang.Float> matcher)
Allows creating customFloat
argument matchers.See examples in javadoc for
Matchers
class- Parameters:
matcher
- decides whether argument matches- Returns:
0
.
-
doubleThat
public static double doubleThat(org.hamcrest.Matcher<java.lang.Double> matcher)
Allows creating customDouble
argument matchers.See examples in javadoc for
Matchers
class- Parameters:
matcher
- decides whether argument matches- Returns:
0
.
-
-