- 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
Constructors -
Method Summary
Modifier and TypeMethodDescriptionstatic <T> Tany()Matches anything, including nulls.static <T> TMatches any object of given type, excluding nulls.static booleanAnybooleanor non-nullBooleanstatic byteanyByte()Anybyteor non-nullByte.static charanyChar()Anycharor non-nullCharacter.static <T> Collection<T> Any non-nullCollection.static doubleAnydoubleor non-nullDouble.static floatanyFloat()Anyfloator non-nullFloat.static intanyInt()Any int or non-nullInteger.static <T> Iterable<T> Any non-nullIterable.static <T> List<T> anyList()Any non-nullList.static longanyLong()Anylongor non-nullLong.static <K,V> Map <K, V> anyMap()Any non-nullMap.static <T> Set<T> anySet()Any non-nullSet.static shortanyShort()Anyshortor non-nullShort.static StringAny non-nullStringstatic <T> TargThat(ArgumentMatcher<T> matcher) Allows creating custom argument matchers.static <T> TAllows creating custom argument matchers where matching is considered successful when the consumer given by parameter does not throw an exception.static <T> TassertArg(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 booleanbooleanThat(ArgumentMatcher<Boolean> matcher) Allows creating custombooleanargument matchers.static bytebyteThat(ArgumentMatcher<Byte> matcher) Allows creating custombyteargument matchers.static charcharThat(ArgumentMatcher<Character> matcher) Allows creating customcharargument matchers.static StringStringargument that contains the given substring.static doubledoubleThat(ArgumentMatcher<Double> matcher) Allows creating customdoubleargument matchers.static StringStringargument that ends with the given suffix.static booleaneq(boolean value) booleanargument that is equal to the given value.static byteeq(byte value) byteargument that is equal to the given value.static chareq(char value) charargument that is equal to the given value.static doubleeq(double value) doubleargument that is equal to the given value.static floateq(float value) floatargument that is equal to the given value.static inteq(int value) intargument that is equal to the given value.static longeq(long value) longargument that is equal to the given value.static shorteq(short value) shortargument that is equal to the given value.static <T> Teq(T value) Object argument that is equal to the given value.static floatfloatThat(ArgumentMatcher<Float> matcher) Allows creating customfloatargument matchers.static intintThat(ArgumentMatcher<Integer> matcher) Allows creating customintargument matchers.static <T> TObjectargument that implements the given class.static <T> TNotnullargument.static <T> TNotnullargument.static <T> TisNull()nullargument.static <T> Tnullargument.static longlongThat(ArgumentMatcher<Long> matcher) Allows creating customlongargument matchers.static StringStringargument that matches the given regular expression.static StringPatternargument that matches the given regular expression.static <T> TnotNull()Notnullargument.static <T> TNotnullargument.static <T> TArgument that is eithernullor of the given type.static <T> TObject argument that is reflection-equal to the given value with support for excluding selected fields from a class.static <T> Tsame(T value) Object argument that is the same as the given value.static shortshortThat(ArgumentMatcher<Short> matcher) Allows creating customshortargument matchers.static StringstartsWith(String prefix) Stringargument 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
ArgumentMatchersclassNotes :
- 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
ArgumentMatchersclass. This is an alias of:isA(Class)}Since Mockito 2.1.0, only allow non-null instance of
, thusnullis not anymore a valid value. As reference are nullable, the suggested API to matchnullwould 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
nullvalues 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
Objectargument that implements the given class.See examples in javadoc for
ArgumentMatchersclass- Type Parameters:
T- the accepted type.- Parameters:
type- the class of the accepted type.- Returns:
null.- See Also:
-
anyBoolean
public static boolean anyBoolean()Anybooleanor non-nullBooleanSince Mockito 2.1.0, only allow valued
Boolean, thusnullis not anymore a valid value. As primitive wrappers are nullable, the suggested API to matchnullwrapper would beisNull(). We felt this change would make test harnesses much safer than they were with Mockito 1.x.See examples in javadoc for
ArgumentMatchersclass.- Returns:
false.- See Also:
-
anyByte
public static byte anyByte()Anybyteor non-nullByte.Since Mockito 2.1.0, only allow valued
Byte, thusnullis not anymore a valid value. As primitive wrappers are nullable, the suggested API to matchnullwrapper would beisNull(). We felt this change would make test harnesses much safer than they were with Mockito 1.x.See examples in javadoc for
ArgumentMatchersclass.- Returns:
0.- See Also:
-
anyChar
public static char anyChar()Anycharor non-nullCharacter.Since Mockito 2.1.0, only allow valued
Character, thusnullis not anymore a valid value. As primitive wrappers are nullable, the suggested API to matchnullwrapper would beisNull(). We felt this change would make test harnesses much safer than they were with Mockito 1.x.See examples in javadoc for
ArgumentMatchersclass.- Returns:
0.- See Also:
-
anyInt
public static int anyInt()Any int or non-nullInteger.Since Mockito 2.1.0, only allow valued
Integer, thusnullis not anymore a valid value. As primitive wrappers are nullable, the suggested API to matchnullwrapper would beisNull(). We felt this change would make test harnesses much safer than they were with Mockito 1.x.See examples in javadoc for
ArgumentMatchersclass.- Returns:
0.- See Also:
-
anyLong
public static long anyLong()Anylongor non-nullLong.Since Mockito 2.1.0, only allow valued
Long, thusnullis not anymore a valid value. As primitive wrappers are nullable, the suggested API to matchnullwrapper would beisNull(). We felt this change would make test harnesses much safer than they were with Mockito 1.x.See examples in javadoc for
ArgumentMatchersclass.- Returns:
0.- See Also:
-
anyFloat
public static float anyFloat()Anyfloator non-nullFloat.Since Mockito 2.1.0, only allow valued
Float, thusnullis not anymore a valid value. As primitive wrappers are nullable, the suggested API to matchnullwrapper would beisNull(). We felt this change would make test harnesses much safer than they were with Mockito 1.x.See examples in javadoc for
ArgumentMatchersclass.- Returns:
0.- See Also:
-
anyDouble
public static double anyDouble()Anydoubleor non-nullDouble.Since Mockito 2.1.0, only allow valued
Double, thusnullis not anymore a valid value. As primitive wrappers are nullable, the suggested API to matchnullwrapper would beisNull(). We felt this change would make test harnesses much safer than they were with Mockito 1.x.See examples in javadoc for
ArgumentMatchersclass.- Returns:
0.- See Also:
-
anyShort
public static short anyShort()Anyshortor non-nullShort.Since Mockito 2.1.0, only allow valued
Short, thusnullis not anymore a valid value. As primitive wrappers are nullable, the suggested API to matchnullwrapper would beisNull(). We felt this change would make test harnesses much safer than they were with Mockito 1.x.See examples in javadoc for
ArgumentMatchersclass.- Returns:
0.- See Also:
-
anyString
Any non-nullStringSince Mockito 2.1.0, only allow non-null
String. As this is a nullable reference, the suggested API to matchnullwrapper would beisNull(). We felt this change would make test harnesses much safer than they were with Mockito 1.x.See examples in javadoc for
ArgumentMatchersclass.- 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 matchnullwrapper would beisNull(). We felt this change would make test harnesses much safer than they were with Mockito 1.x.See examples in javadoc for
ArgumentMatchersclass.- 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 matchnullwrapper would beisNull(). We felt this change would make test harnesses much safer than they were with Mockito 1.x.See examples in javadoc for
ArgumentMatchersclass.- 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 matchnullwrapper would beisNull(). We felt this change would make test harnesses much safer than they were with Mockito 1.x.See examples in javadoc for
ArgumentMatchersclass.- 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 matchnullwould beisNull(). We felt this change would make test harnesses much safer than they were with Mockito 1.x.See examples in javadoc for
ArgumentMatchersclass.- 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 matchnullwould beisNull(). We felt this change would make test harnesses much safer than they were with Mockito 1.x.See examples in javadoc for
ArgumentMatchersclass.- Returns:
- empty Iterable.
- Since:
- 2.1.0
- See Also:
-
eq
public static boolean eq(boolean value) booleanargument that is equal to the given value.See examples in javadoc for
ArgumentMatchersclass- Parameters:
value- the given value.- Returns:
0.
-
eq
public static byte eq(byte value) byteargument that is equal to the given value.See examples in javadoc for
ArgumentMatchersclass- Parameters:
value- the given value.- Returns:
0.
-
eq
public static char eq(char value) charargument that is equal to the given value.See examples in javadoc for
ArgumentMatchersclass- Parameters:
value- the given value.- Returns:
0.
-
eq
public static double eq(double value) doubleargument that is equal to the given value.See examples in javadoc for
ArgumentMatchersclass- Parameters:
value- the given value.- Returns:
0.
-
eq
public static float eq(float value) floatargument that is equal to the given value.See examples in javadoc for
ArgumentMatchersclass- Parameters:
value- the given value.- Returns:
0.
-
eq
public static int eq(int value) intargument that is equal to the given value.See examples in javadoc for
ArgumentMatchersclass- Parameters:
value- the given value.- Returns:
0.
-
eq
public static long eq(long value) longargument that is equal to the given value.See examples in javadoc for
ArgumentMatchersclass- Parameters:
value- the given value.- Returns:
0.
-
eq
public static short eq(short value) shortargument that is equal to the given value.See examples in javadoc for
ArgumentMatchersclass- 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
ArgumentMatchersclass- 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
ArgumentMatchersclass- 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
ArgumentMatchersclass- 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()nullargument.See examples in javadoc for
ArgumentMatchersclass- Returns:
null.- See Also:
-
isNull
nullargument.See examples in javadoc for
ArgumentMatchersclass- 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 eithernullor of the given type.See examples in javadoc for
ArgumentMatchersclass- Parameters:
clazz- Type to avoid casting- Returns:
null.
-
contains
Stringargument that contains the given substring.See examples in javadoc for
ArgumentMatchersclass- Parameters:
substring- the substring.- Returns:
- empty String ("").
-
matches
Stringargument that matches the given regular expression.See examples in javadoc for
ArgumentMatchersclass- Parameters:
regex- the regular expression.- Returns:
- empty String ("").
- See Also:
-
matches
Patternargument that matches the given regular expression.See examples in javadoc for
ArgumentMatchersclass- Parameters:
pattern- the regular expression pattern.- Returns:
- empty String ("").
- See Also:
-
endsWith
Stringargument that ends with the given suffix.See examples in javadoc for
ArgumentMatchersclass- Parameters:
suffix- the suffix.- Returns:
- empty String ("").
-
startsWith
Stringargument that starts with the given prefix.See examples in javadoc for
ArgumentMatchersclass- Parameters:
prefix- the prefix.- Returns:
- empty String ("").
-
argThat
Allows creating custom argument matchers.This API has changed in 2.1.0, please read
ArgumentMatcherfor 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
ArgumentMatcherto 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
NullPointerExceptionduring 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
ArgumentMatcherclass- 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 customcharargument matchers.Note that
argThat(org.mockito.ArgumentMatcher<T>)will not work with primitivecharmatchers due toNullPointerExceptionauto-unboxing caveat.See examples in javadoc for
ArgumentMatchersclass- Parameters:
matcher- decides whether argument matches- Returns:
0.
-
booleanThat
Allows creating custombooleanargument matchers.Note that
argThat(org.mockito.ArgumentMatcher<T>)will not work with primitivebooleanmatchers due toNullPointerExceptionauto-unboxing caveat.See examples in javadoc for
ArgumentMatchersclass- Parameters:
matcher- decides whether argument matches- Returns:
false.
-
byteThat
Allows creating custombyteargument matchers.Note that
argThat(org.mockito.ArgumentMatcher<T>)will not work with primitivebytematchers due toNullPointerExceptionauto-unboxing caveat.See examples in javadoc for
ArgumentMatchersclass- Parameters:
matcher- decides whether argument matches- Returns:
0.
-
shortThat
Allows creating customshortargument matchers.Note that
argThat(org.mockito.ArgumentMatcher<T>)will not work with primitiveshortmatchers due toNullPointerExceptionauto-unboxing caveat.See examples in javadoc for
ArgumentMatchersclass- Parameters:
matcher- decides whether argument matches- Returns:
0.
-
intThat
Allows creating customintargument matchers.Note that
argThat(org.mockito.ArgumentMatcher<T>)will not work with primitiveintmatchers due toNullPointerExceptionauto-unboxing caveat.See examples in javadoc for
ArgumentMatchersclass- Parameters:
matcher- decides whether argument matches- Returns:
0.
-
longThat
Allows creating customlongargument matchers.Note that
argThat(org.mockito.ArgumentMatcher<T>)will not work with primitivelongmatchers due toNullPointerExceptionauto-unboxing caveat.See examples in javadoc for
ArgumentMatchersclass- Parameters:
matcher- decides whether argument matches- Returns:
0.
-
floatThat
Allows creating customfloatargument matchers.Note that
argThat(org.mockito.ArgumentMatcher<T>)will not work with primitivefloatmatchers due toNullPointerExceptionauto-unboxing caveat.See examples in javadoc for
ArgumentMatchersclass- Parameters:
matcher- decides whether argument matches- Returns:
0.
-
doubleThat
Allows creating customdoubleargument matchers.Note that
argThat(org.mockito.ArgumentMatcher<T>)will not work with primitivedoublematchers due toNullPointerExceptionauto-unboxing caveat.See examples in javadoc for
ArgumentMatchersclass- Parameters:
matcher- decides whether argument matches- Returns:
0.
-