Class Matchers
- Direct Known Subclasses:
Mockito
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.
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 hamcrest Matcher
.
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:
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()));
To keep it readable you may want to extract method, e.g:
verify(mock).addAll(argThat(new IsListOfTwoElements()));
//becomes
verify(mock).addAll(listOfTwoElements());
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.
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 -
Method Summary
Modifier and TypeMethodDescriptionstatic <T> T
any()
Any object ornull
.static <T> T
Any kind object, not necessary of the given class.static boolean
Anyboolean
,Boolean
ornull
.static byte
anyByte()
Anybyte
,Byte
ornull
.static char
anyChar()
Anychar
,Character
ornull
.static Collection
AnyCollection
ornull
.static <T> Collection<T>
anyCollectionOf
(Class<T> clazz) Generic friendly alias toanyCollection()
.static double
Anydouble
,Double
ornull
.static float
anyFloat()
Anyfloat
,Float
ornull
.static int
anyInt()
Any int, Integer ornull
.static List
anyList()
AnyList
ornull
.static <T> List<T>
Generic friendly alias toanyList()
.static long
anyLong()
Anylong
,Long
ornull
.static Map
anyMap()
AnyMap
ornull
.static <K,
V> Map<K, V> Generic friendly alias toanyMap()
.static <T> T
AnyObject
ornull
.static Set
anySet()
AnySet
ornull
.static <T> Set<T>
Generic friendly alias toanySet()
.static short
anyShort()
Anyshort
,Short
ornull
.static String
AnyString
ornull
.static <T> T
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<Boolean> matcher) Allows creating customBoolean
argument matchers.static byte
Allows creating customByte
argument matchers.static char
Allows creating customCharacter
argument matchers.static String
String
argument that contains the given substring.static double
doubleThat
(org.hamcrest.Matcher<Double> matcher) Allows creating customDouble
argument matchers.static String
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
Allows creating customFloat
argument matchers.static int
Allows creating customInteger
argument matchers.static <T> T
Object
argument that implements the given class.static Object
Notnull
argument.static <T> T
Notnull
argument, not necessary of the given class.static Object
isNull()
null
argument.static <T> T
null
argument.static long
Allows creating customLong
argument matchers.static String
String
argument that matches the given regular expression.static Object
notNull()
Notnull
argument.static <T> T
Notnull
argument, not necessary of the given class.static <T> T
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
Allows creating customShort
argument matchers.static String
startsWith
(String prefix) String
argument that starts with the given prefix.
-
Constructor Details
-
Matchers
public Matchers()
-
-
Method Details
-
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
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
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
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
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
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
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
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
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
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
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
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
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
null
argument.See examples in javadoc for
Matchers
class- Returns:
null
.
-
isNull
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
- Returns:
null
.
-
notNull
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
- Returns:
null
.
-
isNotNull
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
String
argument that contains the given substring.See examples in javadoc for
Matchers
class- Parameters:
substring
- the substring.- Returns:
- empty String ("").
-
matches
String
argument that matches the given regular expression.See examples in javadoc for
Matchers
class- Parameters:
regex
- the regular expression.- Returns:
- empty String ("").
-
endsWith
String
argument that ends with the given suffix.See examples in javadoc for
Matchers
class- Parameters:
suffix
- the suffix.- Returns:
- empty String ("").
-
startsWith
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
Allows creating customCharacter
argument matchers.See examples in javadoc for
Matchers
class- Parameters:
matcher
- decides whether argument matches- Returns:
0
.
-
booleanThat
Allows creating customBoolean
argument matchers.See examples in javadoc for
Matchers
class- Parameters:
matcher
- decides whether argument matches- Returns:
false
.
-
byteThat
Allows creating customByte
argument matchers.See examples in javadoc for
Matchers
class- Parameters:
matcher
- decides whether argument matches- Returns:
0
.
-
shortThat
Allows creating customShort
argument matchers.See examples in javadoc for
Matchers
class- Parameters:
matcher
- decides whether argument matches- Returns:
0
.
-
intThat
Allows creating customInteger
argument matchers.See examples in javadoc for
Matchers
class- Parameters:
matcher
- decides whether argument matches- Returns:
0
.
-
longThat
Allows creating customLong
argument matchers.See examples in javadoc for
Matchers
class- Parameters:
matcher
- decides whether argument matches- Returns:
0
.
-
floatThat
Allows creating customFloat
argument matchers.See examples in javadoc for
Matchers
class- Parameters:
matcher
- decides whether argument matches- Returns:
0
.
-
doubleThat
Allows creating customDouble
argument matchers.See examples in javadoc for
Matchers
class- Parameters:
matcher
- decides whether argument matches- Returns:
0
.
-