public class Matchers
extends java.lang.Object
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 *don'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.
argThat(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 and Description |
---|
Matchers() |
Modifier and Type | Method and Description |
---|---|
static <T> T |
any()
Any object or
null . |
static <T> T |
any(java.lang.Class<T> clazz)
Any kind object, not necessary of the given class.
|
static boolean |
anyBoolean()
Any
boolean , Boolean or null . |
static byte |
anyByte()
Any
byte , Byte or null . |
static char |
anyChar()
Any
char , Character or null . |
static java.util.Collection |
anyCollection()
Any
Collection or null . |
static <T> java.util.Collection<T> |
anyCollectionOf(java.lang.Class<T> clazz)
Generic friendly alias to
anyCollection() . |
static double |
anyDouble()
Any
double , Double or null . |
static float |
anyFloat()
Any
float , Float or null . |
static int |
anyInt()
Any int, Integer or
null . |
static java.util.List |
anyList()
Any
List or null . |
static <T> java.util.List<T> |
anyListOf(java.lang.Class<T> clazz)
Generic friendly alias to
anyList() . |
static long |
anyLong()
Any
long , Long or null . |
static java.util.Map |
anyMap()
Any
Map or null . |
static <K,V> java.util.Map<K,V> |
anyMapOf(java.lang.Class<K> keyClazz,
java.lang.Class<V> valueClazz)
Generic friendly alias to
anyMap() . |
static <T> T |
anyObject()
Any
Object or null . |
static java.util.Set |
anySet()
Any
Set or null . |
static <T> java.util.Set<T> |
anySetOf(java.lang.Class<T> clazz)
Generic friendly alias to
anySet() . |
static short |
anyShort()
Any
short , Short or null . |
static java.lang.String |
anyString()
Any
String or null . |
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 custom
Boolean argument matchers. |
static byte |
byteThat(org.hamcrest.Matcher<java.lang.Byte> matcher)
Allows creating custom
Byte argument matchers. |
static char |
charThat(org.hamcrest.Matcher<java.lang.Character> matcher)
Allows creating custom
Character 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 custom
Double 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 custom
Float argument matchers. |
static int |
intThat(org.hamcrest.Matcher<java.lang.Integer> matcher)
Allows creating custom
Integer argument matchers. |
static <T> T |
isA(java.lang.Class<T> clazz)
Object argument that implements the given class. |
static java.lang.Object |
isNotNull()
Not
null argument. |
static <T> T |
isNotNull(java.lang.Class<T> clazz)
Not
null 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 custom
Long argument matchers. |
static java.lang.String |
matches(java.lang.String regex)
String argument that matches the given regular expression. |
static java.lang.Object |
notNull()
Not
null argument. |
static <T> T |
notNull(java.lang.Class<T> clazz)
Not
null 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 custom
Short argument matchers. |
static java.lang.String |
startsWith(java.lang.String prefix)
String argument that starts with the given prefix. |
public static boolean anyBoolean()
boolean
, Boolean
or null
.
This method *don'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
false
.public static byte anyByte()
byte
, Byte
or null
.
This method *don'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
0
.public static char anyChar()
char
, Character
or null
.
This method *don'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
0
.public static int anyInt()
null
.
This method *don'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
0
.public static long anyLong()
long
, Long
or null
.
This method *don'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
0
.public static float anyFloat()
float
, Float
or null
.
This method *don'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
0
.public static double anyDouble()
double
, Double
or null
.
This method *don'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
0
.public static short anyShort()
short
, Short
or null
.
This method *don'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
0
.public static <T> T anyObject()
Object
or null
.
This method *don'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()
and any(Class clazz)
See examples in javadoc for Matchers
class
null
.public static <T> T anyVararg()
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
classnull
.public static <T> T any(java.lang.Class<T> clazz)
Sometimes looks better than anyObject()
- especially when explicit casting is required
Alias to anyObject()
This method *don'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
clazz
- The type to avoid castingnull
.public static <T> T any()
null
.
Shorter alias to anyObject()
This method *don'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
null
.public static java.lang.String anyString()
String
or null
.
This method *don'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
public static java.util.List anyList()
List
or null
.
This method *don'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
public static <T> java.util.List<T> anyListOf(java.lang.Class<T> clazz)
anyList()
.
It's an alternative to @SuppressWarnings("unchecked") to keep code clean of compiler warnings.
Any List
or null
.
This method *don'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
clazz
- Type owned by the list to avoid castingpublic static java.util.Set anySet()
Set
or null
.
This method *don'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
public static <T> java.util.Set<T> anySetOf(java.lang.Class<T> clazz)
anySet()
.
It's an alternative to @SuppressWarnings("unchecked") to keep code clean of compiler warnings.
Any Set
or null
This method *don'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
clazz
- Type owned by the Set to avoid castingpublic static java.util.Map anyMap()
Map
or null
.
This method *don'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
public static <K,V> java.util.Map<K,V> anyMapOf(java.lang.Class<K> keyClazz, java.lang.Class<V> valueClazz)
anyMap()
.
It's an alternative to @SuppressWarnings("unchecked") to keep code clean of compiler warnings.
Any Map
or null
This method *don'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
keyClazz
- Type of the map key to avoid castingvalueClazz
- Type of the value to avoid castingpublic static java.util.Collection anyCollection()
Collection
or null
.
This method *don'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
public static <T> java.util.Collection<T> anyCollectionOf(java.lang.Class<T> clazz)
anyCollection()
.
It's an alternative to @SuppressWarnings("unchecked") to keep code clean of compiler warnings.
Any Collection
or null
.
This method *don'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
clazz
- Type owned by the collection to avoid castingpublic static <T> T isA(java.lang.Class<T> clazz)
Object
argument that implements the given class.
See examples in javadoc for Matchers
class
T
- the accepted type.clazz
- the class of the accepted type.null
.public static boolean eq(boolean value)
boolean
argument that is equal to the given value.
See examples in javadoc for Matchers
class
value
- the given value.0
.public static byte eq(byte value)
byte
argument that is equal to the given value.
See examples in javadoc for Matchers
class
value
- the given value.0
.public static char eq(char value)
char
argument that is equal to the given value.
See examples in javadoc for Matchers
class
value
- the given value.0
.public static double eq(double value)
double
argument that is equal to the given value.
See examples in javadoc for Matchers
class
value
- the given value.0
.public static float eq(float value)
float
argument that is equal to the given value.
See examples in javadoc for Matchers
class
value
- the given value.0
.public static int eq(int value)
int
argument that is equal to the given value.
See examples in javadoc for Matchers
class
value
- the given value.0
.public static long eq(long value)
long
argument that is equal to the given value.
See examples in javadoc for Matchers
class
value
- the given value.0
.public static short eq(short value)
short
argument that is equal to the given value.
See examples in javadoc for Matchers
class
value
- the given value.0
.public static <T> T eq(T value)
See examples in javadoc for Matchers
class
value
- the given value.null
.public static <T> T refEq(T value, java.lang.String... excludeFields)
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
value
- the given value.excludeFields
- fields to exclude, if field does not exist it is ignored.null
.public static <T> T same(T value)
See examples in javadoc for Matchers
class
T
- the type of the object, it is passed through to prevent casts.value
- the given value.null
.public static java.lang.Object isNull()
null
argument.
See examples in javadoc for Matchers
class
null
.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
clazz
- Type to avoid castingnull
.public static java.lang.Object notNull()
null
.public static <T> T notNull(java.lang.Class<T> clazz)
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
clazz
- Type to avoid castingnull
.public static java.lang.Object isNotNull()
null
.public static <T> T isNotNull(java.lang.Class<T> clazz)
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
clazz
- Type to avoid castingnull
.public static java.lang.String contains(java.lang.String substring)
String
argument that contains the given substring.
See examples in javadoc for Matchers
class
substring
- the substring.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
regex
- the regular expression.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
suffix
- the suffix.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
prefix
- the prefix.public static <T> T argThat(org.hamcrest.Matcher<T> matcher)
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
matcher
- decides whether argument matchesnull
.public static char charThat(org.hamcrest.Matcher<java.lang.Character> matcher)
Character
argument matchers.
See examples in javadoc for Matchers
class
matcher
- decides whether argument matches0
.public static boolean booleanThat(org.hamcrest.Matcher<java.lang.Boolean> matcher)
Boolean
argument matchers.
See examples in javadoc for Matchers
class
matcher
- decides whether argument matchesfalse
.public static byte byteThat(org.hamcrest.Matcher<java.lang.Byte> matcher)
Byte
argument matchers.
See examples in javadoc for Matchers
class
matcher
- decides whether argument matches0
.public static short shortThat(org.hamcrest.Matcher<java.lang.Short> matcher)
Short
argument matchers.
See examples in javadoc for Matchers
class
matcher
- decides whether argument matches0
.public static int intThat(org.hamcrest.Matcher<java.lang.Integer> matcher)
Integer
argument matchers.
See examples in javadoc for Matchers
class
matcher
- decides whether argument matches0
.public static long longThat(org.hamcrest.Matcher<java.lang.Long> matcher)
Long
argument matchers.
See examples in javadoc for Matchers
class
matcher
- decides whether argument matches0
.public static float floatThat(org.hamcrest.Matcher<java.lang.Float> matcher)
Float
argument matchers.
See examples in javadoc for Matchers
class
matcher
- decides whether argument matches0
.public static double doubleThat(org.hamcrest.Matcher<java.lang.Double> matcher)
Double
argument matchers.
See examples in javadoc for Matchers
class
matcher
- decides whether argument matches0
.