/*
* Copyright (c) 2016 Mockito contributors
* This program is made available under the terms of the MIT License.
*/
package org.mockito;
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.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;
import static org.mockito.internal.progress.
ThreadSafeMockingProgress.mockingProgress;
import static org.mockito.internal.util.
Primitives.defaultValue;
/**
* Allow flexible verification or stubbing. See also {@link AdditionalMatchers}.
*
* <p>
* {@link Mockito} extends ArgumentMatchers so to get access to all matchers just import Mockito class statically.
*
* <pre class="code"><code class="java">
* //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());
* </code></pre>
*
* <p>
* Since Mockito <code>any(Class)</code> and <code>anyInt</code> family matchers perform a type check, thus they won't
* match <code>null</code> arguments. Instead use the <code>isNull</code> matcher.
*
* <pre class="code"><code class="java">
* // 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
*
* </code></pre>
*
* The same apply for verification.
* </p>
*
*
* Scroll down to see all methods - full list of matchers.
*
* <p>
* <b>Warning:</b><br/>
*
* If you are using argument matchers, <b>all arguments</b> have to be provided by matchers.
*
* E.g: (example shows verification but the same applies to stubbing):
* </p>
*
* <pre class="code"><code class="java">
* verify(mock).someMethod(anyInt(), anyString(), <b>eq("third argument")</b>);
* //above is correct - eq() is also an argument matcher
*
* verify(mock).someMethod(anyInt(), anyString(), <b>"third argument"</b>);
* //above is incorrect - exception will be thrown because third argument is given without argument matcher.
* </code></pre>
*
* <p>
* Matcher methods like <code>anyObject()</code>, <code>eq()</code> <b>do not</b> 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 <code>anyObject()</code>, <code>eq()</code> methods outside of verified/stubbed method.
* </p>
*
* <h1>Additional matchers</h1>
* <p>
* 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.
* </p>
*
* <h1>Custom Argument ArgumentMatchers</h1>
* <p>
* It is important to understand the use cases and available options for dealing with non-trivial arguments
* <b>before</b> 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.
* </p>
*
* @see AdditionalMatchers
*/
@
SuppressWarnings("unchecked")
public class
ArgumentMatchers {
/**
* Matches <strong>anything</strong>, including nulls and varargs.
*
* <p>
* See examples in javadoc for {@link ArgumentMatchers} class
*
* This is an alias of: {@link #anyObject()} and {@link #any(java.lang.Class)}
* </p>
*
* <p>
* <strong>Notes : </strong><br/>
* <ul>
* <li>For primitive types use {@link #anyChar()} family or {@link #isA(Class)} or {@link #any(Class)}.</li>
* <li>Since mockito 2.1.0 {@link #any(Class)} is not anymore an alias of this method.</li>
* </ul>
* </p>
*
* @return <code>null</code>.
*
* @see #any(Class)
* @see #anyObject()
* @see #anyVararg()
* @see #anyChar()
* @see #anyInt()
* @see #anyBoolean()
* @see #anyCollectionOf(Class)
*/
public static <T> T
any() {
return
anyObject();
}
/**
* Matches anything, including <code>null</code>.
*
* <p>
* This is an alias of: {@link #any()} and {@link #any(java.lang.Class)}.
* See examples in javadoc for {@link ArgumentMatchers} class.
* </p>
*
* @return <code>null</code>.
* @see #any()
* @see #any(Class)
* @see #notNull()
* @see #notNull(Class)
* @deprecated This will be removed in Mockito 3.0 (which will be java 8 only)
*/
@
Deprecated
public static <T> T
anyObject() {
reportMatcher(
Any.
ANY);
return null;
}
/**
* Matches any object of given type, excluding nulls.
*
* <p>
* 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)}}
* </p>
*
* <p>
* Since Mockito 2.1.0, only allow non-null instance of <code></code>, thus <code>null</code> is not anymore a valid value.
* As reference are nullable, the suggested API to <strong>match</strong> <code>null</code>
* would be {@link #isNull()}. We felt this change would make tests harness much safer that it was with Mockito
* 1.x.
* </p>
*
* <p><strong>Notes : </strong><br/>
* <ul>
* <li>For primitive types use {@link #anyChar()} family.</li>
* <li>Since Mockito 2.1.0 this method will perform a type check thus <code>null</code> values are not authorized.</li>
* <li>Since mockito 2.1.0 {@link #any()} and {@link #anyObject()} are not anymore aliases of this method.</li>
* </ul>
* </p>
*
* @param <T> The accepted type
* @param type the class of the accepted type.
* @return <code>null</code>.
* @see #any()
* @see #anyObject()
* @see #anyVararg()
* @see #isA(Class)
* @see #notNull()
* @see #notNull(Class)
* @see #isNull()
* @see #isNull(Class)
*/
public static <T> T
any(
Class<T>
type) {
reportMatcher(new
InstanceOf.
VarArgAware(
type, "<any " +
type.
getCanonicalName() + ">"));
return
defaultValue(
type);
}
/**
* <code>Object</code> argument that implements the given class.
* <p>
* See examples in javadoc for {@link ArgumentMatchers} class
*
* @param <T> the accepted type.
* @param type the class of the accepted type.
* @return <code>null</code>.
* @see #any(Class)
*/
public static <T> T
isA(
Class<T>
type) {
reportMatcher(new
InstanceOf(
type));
return
defaultValue(
type);
}
/**
* Any vararg, meaning any number and values of arguments.
*
* <p>
* Example:
* <pre class="code"><code class="java">
* //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));
* </code></pre>
* </p>
*
* <p>
* See examples in javadoc for {@link ArgumentMatchers} class.
* </p>
*
* @return <code>null</code>.
* @see #any()
* @see #any(Class)
* @deprecated as of 2.1.0 use {@link #any()}
*/
@
Deprecated
public static <T> T
anyVararg() {
any();
return null;
}
/**
* Any <code>boolean</code> or <strong>non-null</strong> <code>Boolean</code>
*
* <p>
* Since Mockito 2.1.0, only allow valued <code>Boolean</code>, thus <code>null</code> is not anymore a valid value.
* As primitive wrappers are nullable, the suggested API to <strong>match</strong> <code>null</code> wrapper
* would be {@link #isNull()}. We felt this change would make tests harness much safer that it was with Mockito
* 1.x.
* </p>
*
* <p>
* See examples in javadoc for {@link ArgumentMatchers} class.
* </p>
*
* @return <code>false</code>.
* @see #isNull()
* @see #isNull(Class)
*/
public static boolean
anyBoolean() {
reportMatcher(new
InstanceOf(
Boolean.class, "<any boolean>"));
return false;
}
/**
* Any <code>byte</code> or <strong>non-null</strong> <code>Byte</code>.
*
* <p>
* Since Mockito 2.1.0, only allow valued <code>Byte</code>, thus <code>null</code> is not anymore a valid value.
* As primitive wrappers are nullable, the suggested API to <strong>match</strong> <code>null</code> wrapper
* would be {@link #isNull()}. We felt this change would make tests harness much safer that it was with Mockito
* 1.x.
* </p>
*
* <p>
* See examples in javadoc for {@link ArgumentMatchers} class.
* </p>
*
* @return <code>0</code>.
* @see #isNull()
* @see #isNull(Class)
*/
public static byte
anyByte() {
reportMatcher(new
InstanceOf(
Byte.class, "<any byte>"));
return 0;
}
/**
* Any <code>char</code> or <strong>non-null</strong> <code>Character</code>.
*
* <p>
* Since Mockito 2.1.0, only allow valued <code>Character</code>, thus <code>null</code> is not anymore a valid value.
* As primitive wrappers are nullable, the suggested API to <strong>match</strong> <code>null</code> wrapper
* would be {@link #isNull()}. We felt this change would make tests harness much safer that it was with Mockito
* 1.x.
* </p>
*
* <p>
* See examples in javadoc for {@link ArgumentMatchers} class.
* </p>
*
* @return <code>0</code>.
* @see #isNull()
* @see #isNull(Class)
*/
public static char
anyChar() {
reportMatcher(new
InstanceOf(
Character.class, "<any char>"));
return 0;
}
/**
* Any int or <strong>non-null</strong> <code>Integer</code>.
*
* <p>
* Since Mockito 2.1.0, only allow valued <code>Integer</code>, thus <code>null</code> is not anymore a valid value.
* As primitive wrappers are nullable, the suggested API to <strong>match</strong> <code>null</code> wrapper
* would be {@link #isNull()}. We felt this change would make tests harness much safer that it was with Mockito
* 1.x.
* </p>
*
* <p>
* See examples in javadoc for {@link ArgumentMatchers} class.
* </p>
*
* @return <code>0</code>.
* @see #isNull()
* @see #isNull(Class)
*/
public static int
anyInt() {
reportMatcher(new
InstanceOf(
Integer.class, "<any integer>"));
return 0;
}
/**
* Any <code>long</code> or <strong>non-null</strong> <code>Long</code>.
*
* <p>
* Since Mockito 2.1.0, only allow valued <code>Long</code>, thus <code>null</code> is not anymore a valid value.
* As primitive wrappers are nullable, the suggested API to <strong>match</strong> <code>null</code> wrapper
* would be {@link #isNull()}. We felt this change would make tests harness much safer that it was with Mockito
* 1.x.
* </p>
*
* <p>
* See examples in javadoc for {@link ArgumentMatchers} class.
* </p>
*
* @return <code>0</code>.
* @see #isNull()
* @see #isNull(Class)
*/
public static long
anyLong() {
reportMatcher(new
InstanceOf(
Long.class, "<any long>"));
return 0;
}
/**
* Any <code>float</code> or <strong>non-null</strong> <code>Float</code>.
*
* <p>
* Since Mockito 2.1.0, only allow valued <code>Float</code>, thus <code>null</code> is not anymore a valid value.
* As primitive wrappers are nullable, the suggested API to <strong>match</strong> <code>null</code> wrapper
* would be {@link #isNull()}. We felt this change would make tests harness much safer that it was with Mockito
* 1.x.
* </p>
*
* <p>
* See examples in javadoc for {@link ArgumentMatchers} class.
* </p>
*
* @return <code>0</code>.
* @see #isNull()
* @see #isNull(Class)
*/
public static float
anyFloat() {
reportMatcher(new
InstanceOf(
Float.class, "<any float>"));
return 0;
}
/**
* Any <code>double</code> or <strong>non-null</strong> <code>Double</code>.
*
* <p>
* Since Mockito 2.1.0, only allow valued <code>Double</code>, thus <code>null</code> is not anymore a valid value.
* As primitive wrappers are nullable, the suggested API to <strong>match</strong> <code>null</code> wrapper
* would be {@link #isNull()}. We felt this change would make tests harness much safer that it was with Mockito
* 1.x.
* </p>
*
* <p>
* See examples in javadoc for {@link ArgumentMatchers} class.
* </p>
*
* @return <code>0</code>.
* @see #isNull()
* @see #isNull(Class)
*/
public static double
anyDouble() {
reportMatcher(new
InstanceOf(
Double.class, "<any double>"));
return 0;
}
/**
* Any <code>short</code> or <strong>non-null</strong> <code>Short</code>.
*
* <p>
* Since Mockito 2.1.0, only allow valued <code>Short</code>, thus <code>null</code> is not anymore a valid value.
* As primitive wrappers are nullable, the suggested API to <strong>match</strong> <code>null</code> wrapper
* would be {@link #isNull()}. We felt this change would make tests harness much safer that it was with Mockito
* 1.x.
* </p>
*
* <p>
* See examples in javadoc for {@link ArgumentMatchers} class.
* </p>
*
* @return <code>0</code>.
* @see #isNull()
* @see #isNull(Class)
*/
public static short
anyShort() {
reportMatcher(new
InstanceOf(
Short.class, "<any short>"));
return 0;
}
/**
* Any <strong>non-null</strong> <code>String</code>
*
* <p>
* Since Mockito 2.1.0, only allow non-null <code>String</code>.
* As this is a nullable reference, the suggested API to <strong>match</strong> <code>null</code> wrapper
* would be {@link #isNull()}. We felt this change would make tests harness much safer that it was with Mockito
* 1.x.
* </p>
*
* <p>
* See examples in javadoc for {@link ArgumentMatchers} class.
* </p>
*
* @return empty String ("")
* @see #isNull()
* @see #isNull(Class)
*/
public static
String anyString() {
reportMatcher(new
InstanceOf(
String.class, "<any string>"));
return "";
}
/**
* Any <strong>non-null</strong> <code>List</code>.
*
* <p>
* Since Mockito 2.1.0, only allow non-null <code>List</code>.
* As this is a nullable reference, the suggested API to <strong>match</strong> <code>null</code> wrapper
* would be {@link #isNull()}. We felt this change would make tests harness much safer that it was with Mockito
* 1.x.
* </p>
*
* <p>
* See examples in javadoc for {@link ArgumentMatchers} class.
* </p>
*
* @return empty List.
* @see #anyListOf(Class)
* @see #isNull()
* @see #isNull(Class)
*/
public static <T>
List<T>
anyList() {
reportMatcher(new
InstanceOf(
List.class, "<any List>"));
return new
ArrayList<T>(0);
}
/**
* Any <strong>non-null</strong> <code>List</code>.
*
* Generic friendly alias to {@link ArgumentMatchers#anyList()}. It's an alternative to
* <code>@SuppressWarnings("unchecked")</code> to keep code clean of compiler warnings.
*
* <p>
* This method doesn't do type checks of the list content with the given type parameter, it is only there
* to avoid casting in the code.
* </p>
*
* <p>
* Since Mockito 2.1.0, only allow non-null <code>List</code>.
* As this is a nullable reference, the suggested API to <strong>match</strong> <code>null</code> wrapper
* would be {@link #isNull()}. We felt this change would make tests harness much safer that it was with Mockito
* 1.x.
* </p>
*
* <p>
* See examples in javadoc for {@link ArgumentMatchers} class.
* </p>
*
* @param clazz Type owned by the list to avoid casting
* @return empty List.
* @see #anyList()
* @see #isNull()
* @see #isNull(Class)
* @deprecated With Java 8 this method will be removed in Mockito 3.0. This method is only used for generic
* friendliness to avoid casting, this is not anymore needed in Java 8.
*/
@
Deprecated
public static <T>
List<T>
anyListOf(
Class<T>
clazz) {
return
anyList();
}
/**
* Any <strong>non-null</strong> <code>Set</code>.
*
* <p>
* Since Mockito 2.1.0, only allow non-null <code>Set</code>.
* As this is a nullable reference, the suggested API to <strong>match</strong> <code>null</code> wrapper
* would be {@link #isNull()}. We felt this change would make tests harness much safer that it was with Mockito
* 1.x.
* </p>
*
* <p>
* See examples in javadoc for {@link ArgumentMatchers} class.
* </p>
*
* @return empty Set
* @see #anySetOf(Class)
* @see #isNull()
* @see #isNull(Class)
*/
public static <T>
Set<T>
anySet() {
reportMatcher(new
InstanceOf(
Set.class, "<any set>"));
return new
HashSet<T>(0);
}
/**
* Any <strong>non-null</strong> <code>Set</code>.
*
* <p>
* Generic friendly alias to {@link ArgumentMatchers#anySet()}.
* It's an alternative to <code>@SuppressWarnings("unchecked")</code> to keep code clean of compiler warnings.
* </p>
*
* <p>
* This method doesn't do type checks of the set content with the given type parameter, it is only there
* to avoid casting in the code.
* </p>
*
* <p>
* Since Mockito 2.1.0, only allow non-null <code>Set</code>.
* As this is a nullable reference, the suggested API to <strong>match</strong> <code>null</code> wrapper
* would be {@link #isNull()}. We felt this change would make tests harness much safer that it was with Mockito
* 1.x.
* </p>
*
* <p>
* See examples in javadoc for {@link ArgumentMatchers} class.
* </p>
*
* @param clazz Type owned by the Set to avoid casting
* @return empty Set
* @see #anySet()
* @see #isNull()
* @see #isNull(Class)
* @deprecated With Java 8 this method will be removed in Mockito 3.0. This method is only used for generic
* friendliness to avoid casting, this is not anymore needed in Java 8.
*/
@
Deprecated
public static <T>
Set<T>
anySetOf(
Class<T>
clazz) {
return
anySet();
}
/**
* Any <strong>non-null</strong> <code>Map</code>.
*
* <p>
* Since Mockito 2.1.0, only allow non-null <code>Map</code>.
* As this is a nullable reference, the suggested API to <strong>match</strong> <code>null</code> wrapper
* would be {@link #isNull()}. We felt this change would make tests harness much safer that it was with Mockito
* 1.x.
* </p>
*
* <p>
* See examples in javadoc for {@link ArgumentMatchers} class.
* </p>
*
* @return empty Map.
* @see #anyMapOf(Class, Class)
* @see #isNull()
* @see #isNull(Class)
*/
public static <K, V>
Map<K, V>
anyMap() {
reportMatcher(new
InstanceOf(
Map.class, "<any map>"));
return new
HashMap<K, V>(0);
}
/**
* Any <strong>non-null</strong> <code>Map</code>.
*
* <p>
* Generic friendly alias to {@link ArgumentMatchers#anyMap()}.
* It's an alternative to <code>@SuppressWarnings("unchecked")</code> to keep code clean of compiler warnings.
* </p>
*
* <p>
* This method doesn't do type checks of the map content with the given type parameter, it is only there
* to avoid casting in the code.
* </p>
*
* <p>
* Since Mockito 2.1.0, only allow non-null <code>Map</code>.
* As this is a nullable reference, the suggested API to <strong>match</strong> <code>null</code> wrapper
* would be {@link #isNull()}. We felt this change would make tests harness much safer that it was with Mockito
* 1.x.
* </p>
*
* <p>
* See examples in javadoc for {@link ArgumentMatchers} class.
* </p>
*
* @param keyClazz Type of the map key to avoid casting
* @param valueClazz Type of the value to avoid casting
* @return empty Map.
* @see #anyMap()
* @see #isNull()
* @see #isNull(Class)
* @deprecated With Java 8 this method will be removed in Mockito 3.0. This method is only used for generic
* friendliness to avoid casting, this is not anymore needed in Java 8.
*/
@
Deprecated
public static <K, V>
Map<K, V>
anyMapOf(
Class<K>
keyClazz,
Class<V>
valueClazz) {
return
anyMap();
}
/**
* Any <strong>non-null</strong> <code>Collection</code>.
*
* <p>
* Since Mockito 2.1.0, only allow non-null <code>Collection</code>.
* As this is a nullable reference, the suggested API to <strong>match</strong> <code>null</code>
* would be {@link #isNull()}. We felt this change would make tests harness much safer that it was with Mockito
* 1.x.
* </p>
*
* <p>
* See examples in javadoc for {@link ArgumentMatchers} class.
* </p>
*
* @return empty Collection.
* @see #anyCollectionOf(Class)
* @see #isNull()
* @see #isNull(Class)
*/
public static <T>
Collection<T>
anyCollection() {
reportMatcher(new
InstanceOf(
Collection.class, "<any collection>"));
return new
ArrayList<T>(0);
}
/**
* Any <strong>non-null</strong> <code>Collection</code>.
*
* <p>
* Generic friendly alias to {@link ArgumentMatchers#anyCollection()}.
* It's an alternative to <code>@SuppressWarnings("unchecked")</code> to keep code clean of compiler warnings.
* </p>
*
* <p>
* This method doesn't do type checks of the collection content with the given type parameter, it is only there
* to avoid casting in the code.
* </p>
*
* <p>
* Since Mockito 2.1.0, only allow non-null <code>Collection</code>.
* As this is a nullable reference, the suggested API to <strong>match</strong> <code>null</code>
* would be {@link #isNull()}. We felt this change would make tests harness much safer that it was with Mockito
* 1.x.
* </p>
*
* <p>
* See examples in javadoc for {@link ArgumentMatchers} class.
* </p>
*
* @param clazz Type owned by the collection to avoid casting
* @return empty Collection.
* @see #anyCollection()
* @see #isNull()
* @see #isNull(Class)
* @deprecated With Java 8 this method will be removed in Mockito 3.0. This method is only used for generic
* friendliness to avoid casting, this is not anymore needed in Java 8.
*/
@
Deprecated
public static <T>
Collection<T>
anyCollectionOf(
Class<T>
clazz) {
return
anyCollection();
}
/**
* Any <strong>non-null</strong> <code>Iterable</code>.
*
* <p>
* Since Mockito 2.1.0, only allow non-null <code>Iterable</code>.
* As this is a nullable reference, the suggested API to <strong>match</strong> <code>null</code>
* would be {@link #isNull()}. We felt this change would make tests harness much safer that it was with Mockito
* 1.x.
* </p>
*
* <p>
* See examples in javadoc for {@link ArgumentMatchers} class.
* </p>
*
* @return empty Iterable.
* @see #anyIterableOf(Class)
* @see #isNull()
* @see #isNull(Class)
* @since 2.1.0
*/
public static <T>
Iterable<T>
anyIterable() {
reportMatcher(new
InstanceOf(
Iterable.class, "<any iterable>"));
return new
ArrayList<T>(0);
}
/**
* Any <strong>non-null</strong> <code>Iterable</code>.
*
* <p>
* Generic friendly alias to {@link ArgumentMatchers#anyIterable()}.
* It's an alternative to <code>@SuppressWarnings("unchecked")</code> to keep code clean of compiler warnings.
* </p>
*
* <p>
* This method doesn't do type checks of the iterable content with the given type parameter, it is only there
* to avoid casting in the code.
* </p>
*
* <p>
* Since Mockito 2.1.0, only allow non-null <code>String</code>.
* As strings are nullable reference, the suggested API to <strong>match</strong> <code>null</code> wrapper
* would be {@link #isNull()}. We felt this change would make tests harness much safer that it was with Mockito
* 1.x.
* </p>
*
* <p>
* See examples in javadoc for {@link ArgumentMatchers} class.
* </p>
*
* @param clazz Type owned by the collection to avoid casting
* @return empty Iterable.
* @see #anyIterable()
* @see #isNull()
* @see #isNull(Class)
* @since 2.1.0
* @deprecated With Java 8 this method will be removed in Mockito 3.0. This method is only used for generic
* friendliness to avoid casting, this is not anymore needed in Java 8.
*/
@
Deprecated
public static <T>
Iterable<T>
anyIterableOf(
Class<T>
clazz) {
return
anyIterable();
}
/**
* <code>boolean</code> argument that is equal to the given value.
*
* <p>
* See examples in javadoc for {@link ArgumentMatchers} class
* </p>
*
* @param value the given value.
* @return <code>0</code>.
*/
public static boolean
eq(boolean
value) {
reportMatcher(new
Equals(
value));
return false;
}
/**
* <code>byte</code> argument that is equal to the given value.
*
* <p>
* See examples in javadoc for {@link ArgumentMatchers} class
* </p>
*
* @param value the given value.
* @return <code>0</code>.
*/
public static byte
eq(byte
value) {
reportMatcher(new
Equals(
value));
return 0;
}
/**
* <code>char</code> argument that is equal to the given value.
*
* <p>
* See examples in javadoc for {@link ArgumentMatchers} class
* </p>
*
* @param value the given value.
* @return <code>0</code>.
*/
public static char
eq(char
value) {
reportMatcher(new
Equals(
value));
return 0;
}
/**
* <code>double</code> argument that is equal to the given value.
*
* <p>
* See examples in javadoc for {@link ArgumentMatchers} class
* </p>
*
* @param value the given value.
* @return <code>0</code>.
*/
public static double
eq(double
value) {
reportMatcher(new
Equals(
value));
return 0;
}
/**
* <code>float</code> argument that is equal to the given value.
*
* <p>
* See examples in javadoc for {@link ArgumentMatchers} class
* </p>
*
* @param value the given value.
* @return <code>0</code>.
*/
public static float
eq(float
value) {
reportMatcher(new
Equals(
value));
return 0;
}
/**
* <code>int</code> argument that is equal to the given value.
*
* <p>
* See examples in javadoc for {@link ArgumentMatchers} class
* </p>
*
* @param value the given value.
* @return <code>0</code>.
*/
public static int
eq(int
value) {
reportMatcher(new
Equals(
value));
return 0;
}
/**
* <code>long</code> argument that is equal to the given value.
*
* <p>
* See examples in javadoc for {@link ArgumentMatchers} class
* </p>
*
* @param value the given value.
* @return <code>0</code>.
*/
public static long
eq(long
value) {
reportMatcher(new
Equals(
value));
return 0;
}
/**
* <code>short</code> argument that is equal to the given value.
* <p>
* See examples in javadoc for {@link ArgumentMatchers} class
*
* @param value the given value.
* @return <code>0</code>.
*/
public static short
eq(short
value) {
reportMatcher(new
Equals(
value));
return 0;
}
/**
* Object argument that is equal to the given value.
*
* <p>
* See examples in javadoc for {@link ArgumentMatchers} class
* </p>
*
* @param value the given value.
* @return <code>null</code>.
*/
public static <T> 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.
*
* <p>
* 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.
* </p>
*
* <p>
* Works similarly to <code>EqualsBuilder.reflectionEquals(this, other, excludeFields)</code> from
* apache commons library.
* <p>
* <b>Warning</b> The equality check is shallow!
* </p>
*
* <p>
* See examples in javadoc for {@link ArgumentMatchers} class
* </p>
*
* @param value the given value.
* @param excludeFields fields to exclude, if field does not exist it is ignored.
* @return <code>null</code>.
*/
public static <T> T
refEq(T
value,
String...
excludeFields) {
reportMatcher(new
ReflectionEquals(
value,
excludeFields));
return null;
}
/**
* Object argument that is the same as the given value.
*
* <p>
* See examples in javadoc for {@link ArgumentMatchers} class
* </p>
*
* @param <T> the type of the object, it is passed through to prevent casts.
* @param value the given value.
* @return <code>null</code>.
*/
public static <T> T
same(T
value) {
reportMatcher(new
Same(
value));
if (
value == null)
return null;
return (T)
Primitives.
defaultValue(
value.
getClass());
}
/**
* <code>null</code> argument.
*
* <p>
* See examples in javadoc for {@link ArgumentMatchers} class
* </p>
*
* @return <code>null</code>.
* @see #isNull(Class)
* @see #isNotNull()
* @see #isNotNull(Class)
*/
public static <T> T
isNull() {
reportMatcher(
Null.
NULL);
return null;
}
/**
* <code>null</code> argument.
*
* <p>
* The class argument is provided to avoid casting.
* </p>
*
* <p>
* See examples in javadoc for {@link ArgumentMatchers} class
* </p>
*
* @param clazz Type to avoid casting
* @return <code>null</code>.
* @see #isNull()
* @see #isNotNull()
* @see #isNotNull(Class)
* @deprecated With Java 8 this method will be removed in Mockito 3.0. This method is only used for generic
* friendliness to avoid casting, this is not anymore needed in Java 8.
*/
@
Deprecated
public static <T> T
isNull(
Class<T>
clazz) {
return
isNull();
}
/**
* Not <code>null</code> argument.
*
* <p>
* Alias to {@link ArgumentMatchers#isNotNull()}
* </p>
*
* <p>
* See examples in javadoc for {@link ArgumentMatchers} class
* </p>
*
* @return <code>null</code>.
*/
public static <T> T
notNull() {
reportMatcher(
NotNull.
NOT_NULL);
return null;
}
/**
* Not <code>null</code> argument, not necessary of the given class.
*
* <p>
* The class argument is provided to avoid casting.
*
* Alias to {@link ArgumentMatchers#isNotNull(Class)}
* <p>
*
* <p>
* See examples in javadoc for {@link ArgumentMatchers} class
* </p>
*
* @param clazz Type to avoid casting
* @return <code>null</code>.
* @see #isNotNull()
* @see #isNull()
* @see #isNull(Class)
* @deprecated With Java 8 this method will be removed in Mockito 3.0. This method is only used for generic
* friendliness to avoid casting, this is not anymore needed in Java 8.
*/
@
Deprecated
public static <T> T
notNull(
Class<T>
clazz) {
return
notNull();
}
/**
* Not <code>null</code> argument.
*
* <p>
* Alias to {@link ArgumentMatchers#notNull()}
* </p>
*
* <p>
* See examples in javadoc for {@link ArgumentMatchers} class
* </p>
*
* @return <code>null</code>.
* @see #isNotNull(Class)
* @see #isNull()
* @see #isNull(Class)
*/
public static <T> T
isNotNull() {
return
notNull();
}
/**
* Not <code>null</code> argument, not necessary of the given class.
*
* <p>
* The class argument is provided to avoid casting.
* Alias to {@link ArgumentMatchers#notNull(Class)}
* </p>
*
* <p>
* See examples in javadoc for {@link ArgumentMatchers} class
* </p>
*
* @param clazz Type to avoid casting
* @return <code>null</code>.
* @deprecated With Java 8 this method will be removed in Mockito 3.0. This method is only used for generic
* friendliness to avoid casting, this is not anymore needed in Java 8.
*/
@
Deprecated
public static <T> T
isNotNull(
Class<T>
clazz) {
return
notNull(
clazz);
}
/**
* Argument that is either <code>null</code> or of the given type.
*
* <p>
* See examples in javadoc for {@link ArgumentMatchers} class
* </p>
*
* @param clazz Type to avoid casting
* @return <code>null</code>.
*/
public static <T> T
nullable(
Class<T>
clazz) {
AdditionalMatchers.
or(
isNull(),
isA(
clazz));
return (T)
Primitives.
defaultValue(
clazz);
}
/**
* <code>String</code> argument that contains the given substring.
* <p>
* 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 "";
}
/**
* <code>String</code> argument that matches the given regular expression.
* <p>
* 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 "";
}
/**
* <code>Pattern</code> argument that matches the given regular expression.
* <p>
* 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 "";
}
/**
* <code>String</code> argument that ends with the given suffix.
* <p>
* 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 "";
}
/**
* <code>String</code> argument that starts with the given prefix.
* <p>
* 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.
*
* <p>
* This API has changed in 2.1.0, please read {@link ArgumentMatcher} for rationale and migration guide.
* <b>NullPointerException</b> auto-unboxing caveat is described below.
* </p>
*
* <p>
* It is important to understand the use cases and available options for dealing with non-trivial arguments
* <b>before</b> 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.
* </p>
*
* <p>
* <b>NullPointerException</b> auto-unboxing caveat.
* In rare cases when matching primitive parameter types you <b>*must*</b> use relevant intThat(), floatThat(), etc. method.
* This way you will avoid <code>NullPointerException</code> 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.
* </p>
*
* <p>
* See examples in javadoc for {@link ArgumentMatcher} class
* </p>
*
* @param matcher decides whether argument matches
* @return <code>null</code>.
*/
public static <T> T
argThat(
ArgumentMatcher<T>
matcher) {
reportMatcher(
matcher);
return null;
}
/**
* Allows creating custom <code>char</code> argument matchers.
*
* Note that {@link #argThat} will not work with primitive <code>char</code> matchers due to <code>NullPointerException</code> auto-unboxing caveat.
* <p>
* See examples in javadoc for {@link ArgumentMatchers} class
*
* @param matcher decides whether argument matches
* @return <code>0</code>.
*/
public static char
charThat(
ArgumentMatcher<
Character>
matcher) {
reportMatcher(
matcher);
return 0;
}
/**
* Allows creating custom <code>boolean</code> argument matchers.
*
* Note that {@link #argThat} will not work with primitive <code>boolean</code> matchers due to <code>NullPointerException</code> auto-unboxing caveat.
* <p>
* See examples in javadoc for {@link ArgumentMatchers} class
*
* @param matcher decides whether argument matches
* @return <code>false</code>.
*/
public static boolean
booleanThat(
ArgumentMatcher<
Boolean>
matcher) {
reportMatcher(
matcher);
return false;
}
/**
* Allows creating custom <code>byte</code> argument matchers.
*
* Note that {@link #argThat} will not work with primitive <code>byte</code> matchers due to <code>NullPointerException</code> auto-unboxing caveat.
* <p>
* See examples in javadoc for {@link ArgumentMatchers} class
*
* @param matcher decides whether argument matches
* @return <code>0</code>.
*/
public static byte
byteThat(
ArgumentMatcher<
Byte>
matcher) {
reportMatcher(
matcher);
return 0;
}
/**
* Allows creating custom <code>short</code> argument matchers.
*
* Note that {@link #argThat} will not work with primitive <code>short</code> matchers due to <code>NullPointerException</code> auto-unboxing caveat.
* <p>
* See examples in javadoc for {@link ArgumentMatchers} class
*
* @param matcher decides whether argument matches
* @return <code>0</code>.
*/
public static short
shortThat(
ArgumentMatcher<
Short>
matcher) {
reportMatcher(
matcher);
return 0;
}
/**
* Allows creating custom <code>int</code> argument matchers.
*
* Note that {@link #argThat} will not work with primitive <code>int</code> matchers due to <code>NullPointerException</code> auto-unboxing caveat.
* <p>
* See examples in javadoc for {@link ArgumentMatchers} class
*
* @param matcher decides whether argument matches
* @return <code>0</code>.
*/
public static int
intThat(
ArgumentMatcher<
Integer>
matcher) {
reportMatcher(
matcher);
return 0;
}
/**
* Allows creating custom <code>long</code> argument matchers.
*
* Note that {@link #argThat} will not work with primitive <code>long</code> matchers due to <code>NullPointerException</code> auto-unboxing caveat.
* <p>
* See examples in javadoc for {@link ArgumentMatchers} class
*
* @param matcher decides whether argument matches
* @return <code>0</code>.
*/
public static long
longThat(
ArgumentMatcher<
Long>
matcher) {
reportMatcher(
matcher);
return 0;
}
/**
* Allows creating custom <code>float</code> argument matchers.
*
* Note that {@link #argThat} will not work with primitive <code>float</code> matchers due to <code>NullPointerException</code> auto-unboxing caveat.
* <p>
* See examples in javadoc for {@link ArgumentMatchers} class
*
* @param matcher decides whether argument matches
* @return <code>0</code>.
*/
public static float
floatThat(
ArgumentMatcher<
Float>
matcher) {
reportMatcher(
matcher);
return 0;
}
/**
* Allows creating custom <code>double</code> argument matchers.
*
* Note that {@link #argThat} will not work with primitive <code>double</code> matchers due to <code>NullPointerException</code> auto-unboxing caveat.
* <p>
* See examples in javadoc for {@link ArgumentMatchers} class
*
* @param matcher decides whether argument matches
* @return <code>0</code>.
*/
public static double
doubleThat(
ArgumentMatcher<
Double>
matcher) {
reportMatcher(
matcher);
return 0;
}
private static void
reportMatcher(
ArgumentMatcher<?>
matcher) {
mockingProgress().
getArgumentMatcherStorage().
reportMatcher(
matcher);
}
}