org.mockito.ArgumentMatchers Maven / Gradle / Ivy
Show all versions of mockito-core Show documentation
/*
* Copyright (c) 2016 Mockito contributors
* This program is made available under the terms of the MIT License.
*/
package org.mockito;
import static org.mockito.internal.progress.ThreadSafeMockingProgress.mockingProgress;
import static org.mockito.internal.util.Primitives.defaultValue;
import java.util.ArrayList;
import java.util.Collection;
import java.util.HashMap;
import java.util.HashSet;
import java.util.List;
import java.util.Map;
import java.util.Set;
import java.util.function.Consumer;
import java.util.regex.Pattern;
import org.mockito.internal.matchers.Any;
import org.mockito.internal.matchers.Contains;
import org.mockito.internal.matchers.EndsWith;
import org.mockito.internal.matchers.Equals;
import org.mockito.internal.matchers.InstanceOf;
import org.mockito.internal.matchers.Matches;
import org.mockito.internal.matchers.NotNull;
import org.mockito.internal.matchers.Null;
import org.mockito.internal.matchers.Same;
import org.mockito.internal.matchers.StartsWith;
import org.mockito.internal.matchers.apachecommons.ReflectionEquals;
import org.mockito.internal.util.Primitives;
/**
* Allow flexible verification or stubbing. See also {@link 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 {@link 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 {@link ArgumentMatcher} to learn about approaches and see the examples.
*
*
* @see AdditionalMatchers
*/
@CheckReturnValue
@SuppressWarnings("unchecked")
public class ArgumentMatchers {
/**
* Matches anything, including nulls and varargs.
*
*
* See examples in javadoc for {@link ArgumentMatchers} class
*
*
*
* Notes :
*
* - For primitive types use {@link #anyChar()} family or {@link #isA(Class)} or {@link #any(Class)}.
* - Since mockito 2.1.0 {@link #any(Class)} is not anymore an alias of this method.
*
*
*
* @return null.
*
* @see #any(Class)
* @see #anyChar()
* @see #anyInt()
* @see #anyBoolean()
*/
public static T any() {
reportMatcher(Any.ANY);
return null;
}
/**
* 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 {@link ArgumentMatchers} class.
*
* This is an alias of: {@link #isA(Class)}}
*
*
*
* Since Mockito 2.1.0, only allow non-null instance of null is not anymore a valid value.
* As reference are nullable, the suggested API to match null
* would be {@link #isNull()}. We felt this change would make test harnesses much safer than they were with Mockito
* 1.x.
*
*
* Notes :
*
* - For primitive types use {@link #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 {@link #any()} is no longer an alias of this method.
*
*
*
* @param The accepted type
* @param type the class of the accepted type.
* @return null.
* @see #any()
* @see #isA(Class)
* @see #notNull()
* @see #isNull()
*/
public static T any(Class type) {
reportMatcher(new InstanceOf(type, ""));
return defaultValue(type);
}
/**
* Object argument that implements the given class.
*
* See examples in javadoc for {@link ArgumentMatchers} class
*
* @param the accepted type.
* @param type the class of the accepted type.
* @return null.
* @see #any(Class)
*/
public static T isA(Class type) {
reportMatcher(new InstanceOf(type));
return defaultValue(type);
}
/**
* Any boolean or non-null Boolean
*
*
* Since Mockito 2.1.0, only allow valued Boolean, thus null is not anymore a valid value.
* As primitive wrappers are nullable, the suggested API to match null wrapper
* would be {@link #isNull()}. We felt this change would make test harnesses much safer than they were with Mockito
* 1.x.
*
*
*
* See examples in javadoc for {@link ArgumentMatchers} class.
*
*
* @return false.
* @see #isNull()
*/
public static boolean anyBoolean() {
reportMatcher(new InstanceOf(Boolean.class, ""));
return false;
}
/**
* Any byte or non-null Byte.
*
*
* Since Mockito 2.1.0, only allow valued Byte, thus null is not anymore a valid value.
* As primitive wrappers are nullable, the suggested API to match null wrapper
* would be {@link #isNull()}. We felt this change would make test harnesses much safer than they were with Mockito
* 1.x.
*
*
*
* See examples in javadoc for {@link ArgumentMatchers} class.
*
*
* @return 0.
* @see #isNull()
*/
public static byte anyByte() {
reportMatcher(new InstanceOf(Byte.class, ""));
return 0;
}
/**
* Any char or non-null Character.
*
*
* Since Mockito 2.1.0, only allow valued Character, thus null is not anymore a valid value.
* As primitive wrappers are nullable, the suggested API to match null wrapper
* would be {@link #isNull()}. We felt this change would make test harnesses much safer than they were with Mockito
* 1.x.
*
*
*
* See examples in javadoc for {@link ArgumentMatchers} class.
*
*
* @return 0.
* @see #isNull()
*/
public static char anyChar() {
reportMatcher(new InstanceOf(Character.class, ""));
return 0;
}
/**
* Any int or non-null Integer.
*
*
* Since Mockito 2.1.0, only allow valued Integer, thus null is not anymore a valid value.
* As primitive wrappers are nullable, the suggested API to match null wrapper
* would be {@link #isNull()}. We felt this change would make test harnesses much safer than they were with Mockito
* 1.x.
*
*
*
* See examples in javadoc for {@link ArgumentMatchers} class.
*
*
* @return 0.
* @see #isNull()
*/
public static int anyInt() {
reportMatcher(new InstanceOf(Integer.class, ""));
return 0;
}
/**
* Any long or non-null Long.
*
*
* Since Mockito 2.1.0, only allow valued Long, thus null is not anymore a valid value.
* As primitive wrappers are nullable, the suggested API to match null wrapper
* would be {@link #isNull()}. We felt this change would make test harnesses much safer than they were with Mockito
* 1.x.
*
*
*
* See examples in javadoc for {@link ArgumentMatchers} class.
*
*
* @return 0.
* @see #isNull()
*/
public static long anyLong() {
reportMatcher(new InstanceOf(Long.class, ""));
return 0;
}
/**
* Any float or non-null Float.
*
*
* Since Mockito 2.1.0, only allow valued Float, thus null is not anymore a valid value.
* As primitive wrappers are nullable, the suggested API to match null wrapper
* would be {@link #isNull()}. We felt this change would make test harnesses much safer than they were with Mockito
* 1.x.
*
*
*
* See examples in javadoc for {@link ArgumentMatchers} class.
*
*
* @return 0.
* @see #isNull()
*/
public static float anyFloat() {
reportMatcher(new InstanceOf(Float.class, ""));
return 0;
}
/**
* Any double or non-null Double.
*
*
* Since Mockito 2.1.0, only allow valued Double, thus null is not anymore a valid value.
* As primitive wrappers are nullable, the suggested API to match null wrapper
* would be {@link #isNull()}. We felt this change would make test harnesses much safer than they were with Mockito
* 1.x.
*
*
*
* See examples in javadoc for {@link ArgumentMatchers} class.
*
*
* @return 0.
* @see #isNull()
*/
public static double anyDouble() {
reportMatcher(new InstanceOf(Double.class, ""));
return 0;
}
/**
* Any short or non-null Short.
*
*
* Since Mockito 2.1.0, only allow valued Short, thus null is not anymore a valid value.
* As primitive wrappers are nullable, the suggested API to match null wrapper
* would be {@link #isNull()}. We felt this change would make test harnesses much safer than they were with Mockito
* 1.x.
*
*
*
* See examples in javadoc for {@link ArgumentMatchers} class.
*
*
* @return 0.
* @see #isNull()
*/
public static short anyShort() {
reportMatcher(new InstanceOf(Short.class, ""));
return 0;
}
/**
* Any non-null String
*
*
* Since Mockito 2.1.0, only allow non-null String.
* As this is a nullable reference, the suggested API to match null wrapper
* would be {@link #isNull()}. We felt this change would make test harnesses much safer than they were with Mockito
* 1.x.
*
*
*
* See examples in javadoc for {@link ArgumentMatchers} class.
*
*
* @return empty String ("")
* @see #isNull()
*/
public static String anyString() {
reportMatcher(new InstanceOf(String.class, ""));
return "";
}
/**
* Any non-null List.
*
*
* Since Mockito 2.1.0, only allow non-null List.
* As this is a nullable reference, the suggested API to match null wrapper
* would be {@link #isNull()}. We felt this change would make test harnesses much safer than they were with Mockito
* 1.x.
*
*
*
* See examples in javadoc for {@link ArgumentMatchers} class.
*
*
* @return empty List.
* @see #isNull()
*/
public static List anyList() {
reportMatcher(new InstanceOf(List.class, ""));
return new ArrayList(0);
}
/**
* Any non-null Set.
*
*
* Since Mockito 2.1.0, only allow non-null Set.
* As this is a nullable reference, the suggested API to match null wrapper
* would be {@link #isNull()}. We felt this change would make test harnesses much safer than they were with Mockito
* 1.x.
*
*
*
* See examples in javadoc for {@link ArgumentMatchers} class.
*
*
* @return empty Set
* @see #isNull()
*/
public static Set anySet() {
reportMatcher(new InstanceOf(Set.class, ""));
return new HashSet(0);
}
/**
* Any non-null Map.
*
*
* Since Mockito 2.1.0, only allow non-null Map.
* As this is a nullable reference, the suggested API to match null wrapper
* would be {@link #isNull()}. We felt this change would make test harnesses much safer than they were with Mockito
* 1.x.
*
*
*
* See examples in javadoc for {@link ArgumentMatchers} class.
*
*
* @return empty Map.
* @see #isNull()
*/
public static Map anyMap() {
reportMatcher(new InstanceOf(Map.class, ""));
return new HashMap(0);
}
/**
* Any non-null Collection.
*
*
* Since Mockito 2.1.0, only allow non-null Collection.
* As this is a nullable reference, the suggested API to match null
* would be {@link #isNull()}. We felt this change would make test harnesses much safer than they were with Mockito
* 1.x.
*
*
*
* See examples in javadoc for {@link ArgumentMatchers} class.
*
*
* @return empty Collection.
* @see #isNull()
*/
public static Collection anyCollection() {
reportMatcher(new InstanceOf(Collection.class, ""));
return new ArrayList(0);
}
/**
* Any non-null Iterable.
*
*
* Since Mockito 2.1.0, only allow non-null Iterable.
* As this is a nullable reference, the suggested API to match null
* would be {@link #isNull()}. We felt this change would make test harnesses much safer than they were with Mockito
* 1.x.
*
*
*
* See examples in javadoc for {@link ArgumentMatchers} class.
*
*
* @return empty Iterable.
* @see #isNull()
* @since 2.1.0
*/
public static Iterable anyIterable() {
reportMatcher(new InstanceOf(Iterable.class, ""));
return new ArrayList(0);
}
/**
* boolean argument that is equal to the given value.
*
*
* See examples in javadoc for {@link ArgumentMatchers} class
*
*
* @param value the given value.
* @return 0.
*/
public static boolean eq(boolean value) {
reportMatcher(new Equals(value));
return false;
}
/**
* byte argument that is equal to the given value.
*
*
* See examples in javadoc for {@link ArgumentMatchers} class
*
*
* @param value the given value.
* @return 0.
*/
public static byte eq(byte value) {
reportMatcher(new Equals(value));
return 0;
}
/**
* char argument that is equal to the given value.
*
*
* See examples in javadoc for {@link ArgumentMatchers} class
*
*
* @param value the given value.
* @return 0.
*/
public static char eq(char value) {
reportMatcher(new Equals(value));
return 0;
}
/**
* double argument that is equal to the given value.
*
*
* See examples in javadoc for {@link ArgumentMatchers} class
*
*
* @param value the given value.
* @return 0.
*/
public static double eq(double value) {
reportMatcher(new Equals(value));
return 0;
}
/**
* float argument that is equal to the given value.
*
*
* See examples in javadoc for {@link ArgumentMatchers} class
*
*
* @param value the given value.
* @return 0.
*/
public static float eq(float value) {
reportMatcher(new Equals(value));
return 0;
}
/**
* int argument that is equal to the given value.
*
*
* See examples in javadoc for {@link ArgumentMatchers} class
*
*
* @param value the given value.
* @return 0.
*/
public static int eq(int value) {
reportMatcher(new Equals(value));
return 0;
}
/**
* long argument that is equal to the given value.
*
*
* See examples in javadoc for {@link ArgumentMatchers} class
*
*
* @param value the given value.
* @return 0.
*/
public static long eq(long value) {
reportMatcher(new Equals(value));
return 0;
}
/**
* short argument that is equal to the given value.
*
* See examples in javadoc for {@link ArgumentMatchers} class
*
* @param value the given value.
* @return 0.
*/
public static short eq(short value) {
reportMatcher(new Equals(value));
return 0;
}
/**
* Object argument that is equal to the given value.
*
*
* See examples in javadoc for {@link ArgumentMatchers} class
*
*
* @param value the given value.
* @return null.
*/
public static T eq(T value) {
reportMatcher(new Equals(value));
if (value == null) return null;
return (T) Primitives.defaultValue(value.getClass());
}
/**
* 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 {@link ArgumentMatchers} class
*
*
* @param value the given value.
* @param excludeFields fields to exclude, if field does not exist it is ignored.
* @return null.
*/
public static T refEq(T value, String... excludeFields) {
reportMatcher(new ReflectionEquals(value, excludeFields));
return null;
}
/**
* Object argument that is the same as the given value.
*
*
* See examples in javadoc for {@link ArgumentMatchers} class
*
*
* @param the type of the object, it is passed through to prevent casts.
* @param value the given value.
* @return null.
*/
public static T same(T value) {
reportMatcher(new Same(value));
if (value == null) {
return null;
}
return (T) Primitives.defaultValue(value.getClass());
}
/**
* null argument.
*
*
* See examples in javadoc for {@link ArgumentMatchers} class
*
*
* @return null.
* @see #isNotNull()
*/
public static T isNull() {
reportMatcher(Null.NULL);
return null;
}
/**
* null argument.
*
*
* See examples in javadoc for {@link ArgumentMatchers} class
*
*
* @param type the type of the argument being matched.
* @return null.
* @see #isNotNull(Class)
* @since 4.11.0
*/
public static T isNull(Class type) {
reportMatcher(new Null<>(type));
return null;
}
/**
* Not null argument.
*
*
* Alias to {@link ArgumentMatchers#isNotNull()}
*
*
*
* See examples in javadoc for {@link ArgumentMatchers} class
*
*
* @return null.
*/
public static T notNull() {
reportMatcher(NotNull.NOT_NULL);
return null;
}
/**
* Not null argument.
*
*
* Alias to {@link ArgumentMatchers#isNotNull()}
*
*
*
* See examples in javadoc for {@link ArgumentMatchers} class
*
*
* @param type the type of the argument being matched.
* @return null.
* @since 4.11.0
*/
public static T notNull(Class type) {
reportMatcher(new NotNull<>(type));
return null;
}
/**
* Not null argument.
*
*
* Alias to {@link ArgumentMatchers#notNull()}
*
*
*
* See examples in javadoc for {@link ArgumentMatchers} class
*
*
* @return null.
* @see #isNull()
*/
public static T isNotNull() {
return notNull();
}
/**
* Not null argument.
*
*
* Alias to {@link ArgumentMatchers#notNull(Class)}
*
*
*
* See examples in javadoc for {@link ArgumentMatchers} class
*
*
* @param type the type of the argument being matched.
* @return null.
* @see #isNull()
* @since 4.11.0
*/
public static T isNotNull(Class type) {
return notNull(type);
}
/**
* Argument that is either null or of the given type.
*
*
* See examples in javadoc for {@link ArgumentMatchers} class
*
*
* @param clazz Type to avoid casting
* @return null.
*/
public static T nullable(Class clazz) {
AdditionalMatchers.or(isNull(), isA(clazz));
return Primitives.defaultValue(clazz);
}
/**
* String argument that contains the given substring.
*
* See examples in javadoc for {@link ArgumentMatchers} class
*
* @param substring the substring.
* @return empty String ("").
*/
public static String contains(String substring) {
reportMatcher(new Contains(substring));
return "";
}
/**
* String argument that matches the given regular expression.
*
* See examples in javadoc for {@link ArgumentMatchers} class
*
* @param regex the regular expression.
* @return empty String ("").
*
* @see AdditionalMatchers#not(boolean)
*/
public static String matches(String regex) {
reportMatcher(new Matches(regex));
return "";
}
/**
* Pattern argument that matches the given regular expression.
*
* See examples in javadoc for {@link ArgumentMatchers} class
*
* @param pattern the regular expression pattern.
* @return empty String ("").
*
* @see AdditionalMatchers#not(boolean)
*/
public static String matches(Pattern pattern) {
reportMatcher(new Matches(pattern));
return "";
}
/**
* String argument that ends with the given suffix.
*
* See examples in javadoc for {@link ArgumentMatchers} class
*
* @param suffix the suffix.
* @return empty String ("").
*/
public static String endsWith(String suffix) {
reportMatcher(new EndsWith(suffix));
return "";
}
/**
* String argument that starts with the given prefix.
*
* See examples in javadoc for {@link ArgumentMatchers} class
*
* @param prefix the prefix.
* @return empty String ("").
*/
public static String startsWith(String prefix) {
reportMatcher(new StartsWith(prefix));
return "";
}
/**
* Allows creating custom argument matchers.
*
*
* This API has changed in 2.1.0, please read {@link 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 {@link 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 {@link ArgumentMatcher} class
*
*
* @param matcher decides whether argument matches
* @return null.
*/
public static T argThat(ArgumentMatcher matcher) {
reportMatcher(matcher);
return null;
}
/**
* Allows creating custom argument matchers where matching is considered successful when the consumer given by parameter does not throw an exception.
*
* Typically used with {@link Mockito#verify(Object)} to execute assertions on parameters passed to the verified method invocation.
*
* @param consumer executes assertions on the verified argument
* @return null.
*/
public static T assertArg(Consumer consumer) {
return argThat(
argument -> {
consumer.accept(argument);
return true;
});
}
/**
* Allows creating custom char argument matchers.
*
* Note that {@link #argThat} will not work with primitive char matchers due to NullPointerException auto-unboxing caveat.
*
* See examples in javadoc for {@link ArgumentMatchers} class
*
* @param matcher decides whether argument matches
* @return 0.
*/
public static char charThat(ArgumentMatcher matcher) {
reportMatcher(matcher);
return 0;
}
/**
* Allows creating custom boolean argument matchers.
*
* Note that {@link #argThat} will not work with primitive boolean matchers due to NullPointerException auto-unboxing caveat.
*
* See examples in javadoc for {@link ArgumentMatchers} class
*
* @param matcher decides whether argument matches
* @return false.
*/
public static boolean booleanThat(ArgumentMatcher matcher) {
reportMatcher(matcher);
return false;
}
/**
* Allows creating custom byte argument matchers.
*
* Note that {@link #argThat} will not work with primitive byte matchers due to NullPointerException auto-unboxing caveat.
*
* See examples in javadoc for {@link ArgumentMatchers} class
*
* @param matcher decides whether argument matches
* @return 0.
*/
public static byte byteThat(ArgumentMatcher matcher) {
reportMatcher(matcher);
return 0;
}
/**
* Allows creating custom short argument matchers.
*
* Note that {@link #argThat} will not work with primitive short matchers due to NullPointerException auto-unboxing caveat.
*
* See examples in javadoc for {@link ArgumentMatchers} class
*
* @param matcher decides whether argument matches
* @return 0.
*/
public static short shortThat(ArgumentMatcher matcher) {
reportMatcher(matcher);
return 0;
}
/**
* Allows creating custom int argument matchers.
*
* Note that {@link #argThat} will not work with primitive int matchers due to NullPointerException auto-unboxing caveat.
*
* See examples in javadoc for {@link ArgumentMatchers} class
*
* @param matcher decides whether argument matches
* @return 0.
*/
public static int intThat(ArgumentMatcher matcher) {
reportMatcher(matcher);
return 0;
}
/**
* Allows creating custom long argument matchers.
*
* Note that {@link #argThat} will not work with primitive long matchers due to NullPointerException auto-unboxing caveat.
*
* See examples in javadoc for {@link ArgumentMatchers} class
*
* @param matcher decides whether argument matches
* @return 0.
*/
public static long longThat(ArgumentMatcher matcher) {
reportMatcher(matcher);
return 0;
}
/**
* Allows creating custom float argument matchers.
*
* Note that {@link #argThat} will not work with primitive float matchers due to NullPointerException auto-unboxing caveat.
*
* See examples in javadoc for {@link ArgumentMatchers} class
*
* @param matcher decides whether argument matches
* @return 0.
*/
public static float floatThat(ArgumentMatcher matcher) {
reportMatcher(matcher);
return 0;
}
/**
* Allows creating custom double argument matchers.
*
* Note that {@link #argThat} will not work with primitive double matchers due to NullPointerException auto-unboxing caveat.
*
* See examples in javadoc for {@link ArgumentMatchers} class
*
* @param matcher decides whether argument matches
* @return 0.
*/
public static double doubleThat(ArgumentMatcher matcher) {
reportMatcher(matcher);
return 0;
}
private static void reportMatcher(ArgumentMatcher matcher) {
mockingProgress().getArgumentMatcherStorage().reportMatcher(matcher);
}
}