Class ArgumentMatchers
- Direct Known Subclasses:
Mockito
AdditionalMatchers
.
//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());
Since Mockito any(Class)
and anyInt
family matchers perform a type check, thus they won't
match null
arguments. Instead use the isNull
matcher.
// stubbing using anyBoolean() argument matcher
when(mock.dryRun(anyBoolean())).thenReturn("state");
// below the stub won't match, and won't return "state"
mock.dryRun(null);
// either change the stub
when(mock.dryRun(isNull())).thenReturn("state");
mock.dryRun(null); // ok
// or fix the code ;)
when(mock.dryRun(anyBoolean())).thenReturn("state");
mock.dryRun(true); // ok
The same apply for verification.
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 any()
, eq()
do not return matchers.
Internally, they record a matcher on a stack and return a dummy value (usually null).
This implementation is due to static type safety imposed by java compiler.
The consequence is that you cannot use any()
, eq()
methods outside of verified/stubbed method.
Additional matchers
The class AdditionalMatchers
offers rarely used matchers, although they can be useful, when
it is useful to combine multiple matchers or when it is useful to negate a matcher necessary.
Custom Argument ArgumentMatchers
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.
- See Also:
-
Constructor Summary
-
Method Summary
Modifier and TypeMethodDescriptionstatic <T> T
any()
Matches anything, including nulls.static <T> T
Matches any object of given type, excluding nulls.static boolean
Anyboolean
or non-nullBoolean
static byte
anyByte()
Anybyte
or non-nullByte
.static char
anyChar()
Anychar
or non-nullCharacter
.static <T> Collection
<T> Any non-nullCollection
.static double
Anydouble
or non-nullDouble
.static float
anyFloat()
Anyfloat
or non-nullFloat
.static int
anyInt()
Any int or non-nullInteger
.static <T> Iterable
<T> Any non-nullIterable
.static <T> List
<T> anyList()
Any non-nullList
.static long
anyLong()
Anylong
or non-nullLong
.static <K,
V> Map <K, V> anyMap()
Any non-nullMap
.static <T> Set
<T> anySet()
Any non-nullSet
.static short
anyShort()
Anyshort
or non-nullShort
.static String
Any non-nullString
static <T> T
argThat
(ArgumentMatcher<T> matcher) Allows creating custom argument matchers.static <T> T
Allows creating custom argument matchers where matching is considered successful when the consumer given by parameter does not throw an exception.static <T> T
assertArg
(ThrowingConsumer<T> consumer) Allows creating custom argument matchers where matching is considered successful when the consumer given by parameter does not throw an exception.static boolean
booleanThat
(ArgumentMatcher<Boolean> matcher) Allows creating customboolean
argument matchers.static byte
byteThat
(ArgumentMatcher<Byte> matcher) Allows creating custombyte
argument matchers.static char
charThat
(ArgumentMatcher<Character> matcher) Allows creating customchar
argument matchers.static String
String
argument that contains the given substring.static double
doubleThat
(ArgumentMatcher<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
floatThat
(ArgumentMatcher<Float> matcher) Allows creating customfloat
argument matchers.static int
intThat
(ArgumentMatcher<Integer> matcher) Allows creating customint
argument matchers.static <T> T
Object
argument that implements the given class.static <T> T
Notnull
argument.static <T> T
Notnull
argument.static <T> T
isNull()
null
argument.static <T> T
null
argument.static long
longThat
(ArgumentMatcher<Long> matcher) Allows creating customlong
argument matchers.static String
String
argument that matches the given regular expression.static String
Pattern
argument that matches the given regular expression.static <T> T
notNull()
Notnull
argument.static <T> T
Notnull
argument.static <T> T
Argument that is eithernull
or of the given type.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
shortThat
(ArgumentMatcher<Short> matcher) Allows creating customshort
argument matchers.static String
startsWith
(String prefix) String
argument that starts with the given prefix.
-
Constructor Details
-
ArgumentMatchers
public ArgumentMatchers()
-
-
Method Details
-
any
public static <T> T any()Matches anything, including nulls.See examples in javadoc for
ArgumentMatchers
classNotes :
- For primitive types use
anyChar()
family orisA(Class)
orany(Class)
. - Since Mockito 2.1.0
any(Class)
is not anymore an alias of this method. - Since Mockito 5.0.0 this no longer matches varargs. Use
any(Class)
instead.
- Returns:
null
.- See Also:
- For primitive types use
-
any
Matches any object of given type, excluding nulls.This matcher will perform a type check with the given type, thus excluding values. See examples in javadoc for
ArgumentMatchers
class. This is an alias of:isA(Class)
}Since Mockito 2.1.0, only allow non-null instance of
, thus
null
is not anymore a valid value. As reference are nullable, the suggested API to matchnull
would beisNull()
. We felt this change would make test harnesses much safer than they were with Mockito 1.x.Notes :
- For primitive types use
anyChar()
family. - Since Mockito 2.1.0 this method will perform a type check thus
null
values are not authorized. - Since Mockito 2.1.0
any()
is no longer an alias of this method. - Since Mockito 5.0.0 this method can match varargs if the array type is specified, for example
any(String[].class)
.
- Type Parameters:
T
- The accepted type- Parameters:
type
- the class of the accepted type.- Returns:
null
.- See Also:
- For primitive types use
-
isA
Object
argument that implements the given class.See examples in javadoc for
ArgumentMatchers
class- Type Parameters:
T
- the accepted type.- Parameters:
type
- the class of the accepted type.- Returns:
null
.- See Also:
-
anyBoolean
public static boolean anyBoolean()Anyboolean
or non-nullBoolean
Since Mockito 2.1.0, only allow valued
Boolean
, thusnull
is not anymore a valid value. As primitive wrappers are nullable, the suggested API to matchnull
wrapper would beisNull()
. We felt this change would make test harnesses much safer than they were with Mockito 1.x.See examples in javadoc for
ArgumentMatchers
class.- Returns:
false
.- See Also:
-
anyByte
public static byte anyByte()Anybyte
or non-nullByte
.Since Mockito 2.1.0, only allow valued
Byte
, thusnull
is not anymore a valid value. As primitive wrappers are nullable, the suggested API to matchnull
wrapper would beisNull()
. We felt this change would make test harnesses much safer than they were with Mockito 1.x.See examples in javadoc for
ArgumentMatchers
class.- Returns:
0
.- See Also:
-
anyChar
public static char anyChar()Anychar
or non-nullCharacter
.Since Mockito 2.1.0, only allow valued
Character
, thusnull
is not anymore a valid value. As primitive wrappers are nullable, the suggested API to matchnull
wrapper would beisNull()
. We felt this change would make test harnesses much safer than they were with Mockito 1.x.See examples in javadoc for
ArgumentMatchers
class.- Returns:
0
.- See Also:
-
anyInt
public static int anyInt()Any int or non-nullInteger
.Since Mockito 2.1.0, only allow valued
Integer
, thusnull
is not anymore a valid value. As primitive wrappers are nullable, the suggested API to matchnull
wrapper would beisNull()
. We felt this change would make test harnesses much safer than they were with Mockito 1.x.See examples in javadoc for
ArgumentMatchers
class.- Returns:
0
.- See Also:
-
anyLong
public static long anyLong()Anylong
or non-nullLong
.Since Mockito 2.1.0, only allow valued
Long
, thusnull
is not anymore a valid value. As primitive wrappers are nullable, the suggested API to matchnull
wrapper would beisNull()
. We felt this change would make test harnesses much safer than they were with Mockito 1.x.See examples in javadoc for
ArgumentMatchers
class.- Returns:
0
.- See Also:
-
anyFloat
public static float anyFloat()Anyfloat
or non-nullFloat
.Since Mockito 2.1.0, only allow valued
Float
, thusnull
is not anymore a valid value. As primitive wrappers are nullable, the suggested API to matchnull
wrapper would beisNull()
. We felt this change would make test harnesses much safer than they were with Mockito 1.x.See examples in javadoc for
ArgumentMatchers
class.- Returns:
0
.- See Also:
-
anyDouble
public static double anyDouble()Anydouble
or non-nullDouble
.Since Mockito 2.1.0, only allow valued
Double
, thusnull
is not anymore a valid value. As primitive wrappers are nullable, the suggested API to matchnull
wrapper would beisNull()
. We felt this change would make test harnesses much safer than they were with Mockito 1.x.See examples in javadoc for
ArgumentMatchers
class.- Returns:
0
.- See Also:
-
anyShort
public static short anyShort()Anyshort
or non-nullShort
.Since Mockito 2.1.0, only allow valued
Short
, thusnull
is not anymore a valid value. As primitive wrappers are nullable, the suggested API to matchnull
wrapper would beisNull()
. We felt this change would make test harnesses much safer than they were with Mockito 1.x.See examples in javadoc for
ArgumentMatchers
class.- Returns:
0
.- See Also:
-
anyString
Any non-nullString
Since Mockito 2.1.0, only allow non-null
String
. As this is a nullable reference, the suggested API to matchnull
wrapper would beisNull()
. We felt this change would make test harnesses much safer than they were with Mockito 1.x.See examples in javadoc for
ArgumentMatchers
class.- Returns:
- empty String ("")
- See Also:
-
anyList
Any non-nullList
.Since Mockito 2.1.0, only allow non-null
List
. As this is a nullable reference, the suggested API to matchnull
wrapper would beisNull()
. We felt this change would make test harnesses much safer than they were with Mockito 1.x.See examples in javadoc for
ArgumentMatchers
class.- Returns:
- empty List.
- See Also:
-
anySet
Any non-nullSet
.Since Mockito 2.1.0, only allow non-null
Set
. As this is a nullable reference, the suggested API to matchnull
wrapper would beisNull()
. We felt this change would make test harnesses much safer than they were with Mockito 1.x.See examples in javadoc for
ArgumentMatchers
class.- Returns:
- empty Set
- See Also:
-
anyMap
Any non-nullMap
.Since Mockito 2.1.0, only allow non-null
Map
. As this is a nullable reference, the suggested API to matchnull
wrapper would beisNull()
. We felt this change would make test harnesses much safer than they were with Mockito 1.x.See examples in javadoc for
ArgumentMatchers
class.- Returns:
- empty Map.
- See Also:
-
anyCollection
Any non-nullCollection
.Since Mockito 2.1.0, only allow non-null
Collection
. As this is a nullable reference, the suggested API to matchnull
would beisNull()
. We felt this change would make test harnesses much safer than they were with Mockito 1.x.See examples in javadoc for
ArgumentMatchers
class.- Returns:
- empty Collection.
- See Also:
-
anyIterable
Any non-nullIterable
.Since Mockito 2.1.0, only allow non-null
Iterable
. As this is a nullable reference, the suggested API to matchnull
would beisNull()
. We felt this change would make test harnesses much safer than they were with Mockito 1.x.See examples in javadoc for
ArgumentMatchers
class.- Returns:
- empty Iterable.
- Since:
- 2.1.0
- See Also:
-
eq
public static boolean eq(boolean value) boolean
argument that is equal to the given value.See examples in javadoc for
ArgumentMatchers
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
ArgumentMatchers
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
ArgumentMatchers
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
ArgumentMatchers
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
ArgumentMatchers
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
ArgumentMatchers
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
ArgumentMatchers
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
ArgumentMatchers
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
ArgumentMatchers
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, excludeFields)
from apache commons library.Warning The equality check is shallow!
See examples in javadoc for
ArgumentMatchers
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
ArgumentMatchers
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 <T> T isNull()null
argument.See examples in javadoc for
ArgumentMatchers
class- Returns:
null
.- See Also:
-
isNull
null
argument.See examples in javadoc for
ArgumentMatchers
class- Parameters:
type
- the type of the argument being matched.- Returns:
null
.- Since:
- 4.11.0
- See Also:
-
notNull
public static <T> T notNull()- Returns:
null
.
-
notNull
- Parameters:
type
- the type of the argument being matched.- Returns:
null
.- Since:
- 4.11.0
-
isNotNull
public static <T> T isNotNull()- Returns:
null
.- See Also:
-
isNotNull
- Parameters:
type
- the type of the argument being matched.- Returns:
null
.- Since:
- 4.11.0
- See Also:
-
nullable
Argument that is eithernull
or of the given type.See examples in javadoc for
ArgumentMatchers
class- Parameters:
clazz
- Type to avoid casting- Returns:
null
.
-
contains
String
argument that contains the given substring.See examples in javadoc for
ArgumentMatchers
class- Parameters:
substring
- the substring.- Returns:
- empty String ("").
-
matches
String
argument that matches the given regular expression.See examples in javadoc for
ArgumentMatchers
class- Parameters:
regex
- the regular expression.- Returns:
- empty String ("").
- See Also:
-
matches
Pattern
argument that matches the given regular expression.See examples in javadoc for
ArgumentMatchers
class- Parameters:
pattern
- the regular expression pattern.- Returns:
- empty String ("").
- See Also:
-
endsWith
String
argument that ends with the given suffix.See examples in javadoc for
ArgumentMatchers
class- Parameters:
suffix
- the suffix.- Returns:
- empty String ("").
-
startsWith
String
argument that starts with the given prefix.See examples in javadoc for
ArgumentMatchers
class- Parameters:
prefix
- the prefix.- Returns:
- empty String ("").
-
argThat
Allows creating custom argument matchers.This API has changed in 2.1.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
.
-
assertArg
Allows creating custom argument matchers where matching is considered successful when the consumer given by parameter does not throw an exception.Typically used with
Mockito.verify(Object)
to execute assertions on parameters passed to the verified method invocation.- Parameters:
consumer
- executes assertions on the verified argument- Returns:
null
.
-
assertArg
Allows creating custom argument matchers where matching is considered successful when the consumer given by parameter does not throw an exception. Consumer is allowed to throw exception other than RuntimeExceptionTypically used with
Mockito.verify(Object)
to execute assertions on parameters passed to the verified method invocation.- Parameters:
consumer
- executes assertions on the verified argument- Returns:
null
.
-
charThat
Allows creating customchar
argument matchers.Note that
argThat(org.mockito.ArgumentMatcher<T>)
will not work with primitivechar
matchers due toNullPointerException
auto-unboxing caveat.See examples in javadoc for
ArgumentMatchers
class- Parameters:
matcher
- decides whether argument matches- Returns:
0
.
-
booleanThat
Allows creating customboolean
argument matchers.Note that
argThat(org.mockito.ArgumentMatcher<T>)
will not work with primitiveboolean
matchers due toNullPointerException
auto-unboxing caveat.See examples in javadoc for
ArgumentMatchers
class- Parameters:
matcher
- decides whether argument matches- Returns:
false
.
-
byteThat
Allows creating custombyte
argument matchers.Note that
argThat(org.mockito.ArgumentMatcher<T>)
will not work with primitivebyte
matchers due toNullPointerException
auto-unboxing caveat.See examples in javadoc for
ArgumentMatchers
class- Parameters:
matcher
- decides whether argument matches- Returns:
0
.
-
shortThat
Allows creating customshort
argument matchers.Note that
argThat(org.mockito.ArgumentMatcher<T>)
will not work with primitiveshort
matchers due toNullPointerException
auto-unboxing caveat.See examples in javadoc for
ArgumentMatchers
class- Parameters:
matcher
- decides whether argument matches- Returns:
0
.
-
intThat
Allows creating customint
argument matchers.Note that
argThat(org.mockito.ArgumentMatcher<T>)
will not work with primitiveint
matchers due toNullPointerException
auto-unboxing caveat.See examples in javadoc for
ArgumentMatchers
class- Parameters:
matcher
- decides whether argument matches- Returns:
0
.
-
longThat
Allows creating customlong
argument matchers.Note that
argThat(org.mockito.ArgumentMatcher<T>)
will not work with primitivelong
matchers due toNullPointerException
auto-unboxing caveat.See examples in javadoc for
ArgumentMatchers
class- Parameters:
matcher
- decides whether argument matches- Returns:
0
.
-
floatThat
Allows creating customfloat
argument matchers.Note that
argThat(org.mockito.ArgumentMatcher<T>)
will not work with primitivefloat
matchers due toNullPointerException
auto-unboxing caveat.See examples in javadoc for
ArgumentMatchers
class- Parameters:
matcher
- decides whether argument matches- Returns:
0
.
-
doubleThat
Allows creating customdouble
argument matchers.Note that
argThat(org.mockito.ArgumentMatcher<T>)
will not work with primitivedouble
matchers due toNullPointerException
auto-unboxing caveat.See examples in javadoc for
ArgumentMatchers
class- Parameters:
matcher
- decides whether argument matches- Returns:
0
.
-