Matchers (Mockito 2.0.3-beta API)

java.lang.Object
- org.mockito.Matchers

Direct Known Subclasses:

Mockito
```
public class Matchers
extends java.lang.Object
```
Allow flexible verification or stubbing. See also AdditionalMatchers.
Mockito extends Matchers so to get access to all matchers just import Mockito class statically.
```
  //stubbing using anyInt() argument matcher
  when(mockedList.get(anyInt())).thenReturn("element");
  
  //following prints "element"
  System.out.println(mockedList.get(999));
  
  //you can also verify using argument matcher
  verify(mockedList).get(anyInt());
 
```
Scroll down to see all methods - full list of matchers.
Warning:
If you are using argument matchers, all arguments have to be provided by matchers.
E.g: (example shows verification but the same applies to stubbing):
```
   verify(mock).someMethod(anyInt(), anyString(), eq("third argument"));
   //above is correct - eq() is also an argument matcher
   
   verify(mock).someMethod(anyInt(), anyString(), "third argument");
   //above is incorrect - exception will be thrown because third argument is given without argument matcher.
 
```
Matcher methods like anyObject(), eq() do not return matchers. Internally, they record a matcher on a stack and return a dummy value (usually null). This implementation is due static type safety imposed by java compiler. The consequence is that you cannot use anyObject(), eq() methods outside of verified/stubbed method.
Custom Argument Matchers
Use argThat(org.hamcrest.Matcher<T>) method and pass an instance of hamcrest Matcher.
Before you start implementing your own custom argument matcher, make sure you check out ArgumentCaptor api.
So, how to implement your own argument matcher? First, you might want to subclass ArgumentMatcher which is an hamcrest matcher with predefined describeTo() method. Default description generated by describeTo() uses decamelized class name - to promote meaningful class names.
Example:
```
   class IsListOfTwoElements extends ArgumentMatcher<List> {
      public boolean matches(Object list) {
          return ((List) list).size() == 2;
      }
   }
   
   List mock = mock(List.class);
   
   when(mock.addAll(argThat(new IsListOfTwoElements()))).thenReturn(true);
   
   mock.addAll(Arrays.asList("one", "two"));
   
   verify(mock).addAll(argThat(new IsListOfTwoElements()));
 
```
To keep it readable you may want to extract method, e.g:
```
   verify(mock).addAll(argThat(new IsListOfTwoElements()));
   //becomes
   verify(mock).addAll(listOfTwoElements());
 
```
Warning: Be reasonable with using complicated argument matching, especially custom argument matchers, as it can make the test less readable. Sometimes it's better to implement equals() for arguments that are passed to mocks (Mockito naturally uses equals() for argument matching). This can make the test cleaner.
Also, sometimes ArgumentCaptor may be a better fit than custom matcher. For example, if custom argument matcher is not likely to be reused or you just need it to assert on argument values to complete verification of behavior.

Constructor Summary

Constructors
Constructor and Description

Matchers()

Constructors
Constructor and Description
`Matchers()`

Method Summary

Methods
Modifier and Type	Method and Description
`static <T> T`	`any()` Matches anything, including nulls
`static <T> T`	`any(java.lang.Class<T> clazz)` Matches any object, including nulls
`static boolean`	`anyBoolean()` Any `boolean` or non-null `Boolean`
`static byte`	`anyByte()` Any `byte` or non-null `Byte`.
`static char`	`anyChar()` Any `char` or non-null `Character`.
`static java.util.Collection`	`anyCollection()` Any non-null `Collection`.
`static <T> java.util.Collection<T>`	`anyCollectionOf(java.lang.Class<T> clazz)` Generic friendly alias to `anyCollection()`.
`static double`	`anyDouble()` Any `double` or non-null `Double`.
`static float`	`anyFloat()` Any `float` or non-null `Float`.
`static int`	`anyInt()` Any int or non-null Integer.
`static java.util.List`	`anyList()` Any non-null `List`.
`static <T> java.util.List<T>`	`anyListOf(java.lang.Class<T> clazz)` Generic friendly alias to `anyList()`.
`static long`	`anyLong()` Any `long` or non-null `Long`.
`static java.util.Map`	`anyMap()` Any non-null `Map`.
`static <K,V> java.util.Map<K,V>`	`anyMapOf(java.lang.Class<K> keyClazz, java.lang.Class<V> valueClazz)` Generic friendly alias to `anyMap()`.
`static <T> T`	`anyObject()` Matches anything, including null.
`static java.util.Set`	`anySet()` Any non-null `Set`.
`static <T> java.util.Set<T>`	`anySetOf(java.lang.Class<T> clazz)` Generic friendly alias to `anySet()`.
`static short`	`anyShort()` Any `short` or non-null `Short`.
`static java.lang.String`	`anyString()` Any non-null `String`
`static <T> T`	`anyVararg()` Any vararg, meaning any number and values of arguments.
`static <T> T`	`argThat(org.hamcrest.Matcher<T> matcher)` Allows creating custom argument matchers.
`static boolean`	`booleanThat(org.hamcrest.Matcher<java.lang.Boolean> matcher)` Allows creating custom `Boolean` argument matchers.
`static byte`	`byteThat(org.hamcrest.Matcher<java.lang.Byte> matcher)` Allows creating custom `Byte` argument matchers.
`static char`	`charThat(org.hamcrest.Matcher<java.lang.Character> matcher)` Allows creating custom `Character` argument matchers.
`static java.lang.String`	`contains(java.lang.String substring)` `String` argument that contains the given substring.
`static double`	`doubleThat(org.hamcrest.Matcher<java.lang.Double> matcher)` Allows creating custom `Double` argument matchers.
`static java.lang.String`	`endsWith(java.lang.String suffix)` `String` argument that ends with the given suffix.
`static boolean`	`eq(boolean value)` `boolean` argument that is equal to the given value.
`static byte`	`eq(byte value)` `byte` argument that is equal to the given value.
`static char`	`eq(char value)` `char` argument that is equal to the given value.
`static double`	`eq(double value)` `double` argument that is equal to the given value.
`static float`	`eq(float value)` `float` argument that is equal to the given value.
`static int`	`eq(int value)` `int` argument that is equal to the given value.
`static long`	`eq(long value)` `long` argument that is equal to the given value.
`static short`	`eq(short value)` `short` argument that is equal to the given value.
`static <T> T`	`eq(T value)` Object argument that is equal to the given value.
`static float`	`floatThat(org.hamcrest.Matcher<java.lang.Float> matcher)` Allows creating custom `Float` argument matchers.
`static int`	`intThat(org.hamcrest.Matcher<java.lang.Integer> matcher)` Allows creating custom `Integer` argument matchers.
`static <T> T`	`isA(java.lang.Class<T> clazz)` `Object` argument that implements the given class.
`static java.lang.Object`	`isNotNull()` Not `null` argument.
`static <T> T`	`isNotNull(java.lang.Class<T> clazz)` Not `null` argument, not necessary of the given class.
`static java.lang.Object`	`isNull()` `null` argument.
`static <T> T`	`isNull(java.lang.Class<T> clazz)` `null` argument.
`static long`	`longThat(org.hamcrest.Matcher<java.lang.Long> matcher)` Allows creating custom `Long` argument matchers.
`static java.lang.String`	`matches(java.lang.String regex)` `String` argument that matches the given regular expression.
`static java.lang.Object`	`notNull()` Not `null` argument.
`static <T> T`	`notNull(java.lang.Class<T> clazz)` Not `null` argument, not necessary of the given class.
`static <T> T`	`refEq(T value, java.lang.String... excludeFields)` Object argument that is reflection-equal to the given value with support for excluding selected fields from a class.
`static <T> T`	`same(T value)` Object argument that is the same as the given value.
`static short`	`shortThat(org.hamcrest.Matcher<java.lang.Short> matcher)` Allows creating custom `Short` argument matchers.
`static java.lang.String`	`startsWith(java.lang.String prefix)` `String` argument that starts with the given prefix.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Constructor Detail
  - Matchers
```
public Matchers()
```
- Method Detail
  - anyBoolean
```
public static boolean anyBoolean()
```
    Any boolean or non-null Boolean
    See examples in javadoc for Matchers class
    
    Returns:
    false.
  - anyByte
```
public static byte anyByte()
```
    Any byte or non-null Byte.
    See examples in javadoc for Matchers class
    
    Returns:
    0.
  - anyChar
```
public static char anyChar()
```
    Any char or non-null Character.
    See examples in javadoc for Matchers class
    
    Returns:
    0.
  - anyInt
```
public static int anyInt()
```
    Any int or non-null Integer.
    See examples in javadoc for Matchers class
    
    Returns:
    0.
  - anyLong
```
public static long anyLong()
```
    Any long or non-null Long.
    See examples in javadoc for Matchers class
    
    Returns:
    0.
  - anyFloat
```
public static float anyFloat()
```
    Any float or non-null Float.
    See examples in javadoc for Matchers class
    
    Returns:
    0.
  - anyDouble
```
public static double anyDouble()
```
    Any double or non-null Double.
    See examples in javadoc for Matchers class
    
    Returns:
    0.
  - anyShort
```
public static short anyShort()
```
    Any short or non-null Short.
    See examples in javadoc for Matchers class
    
    Returns:
    0.
  - anyObject
```
public static <T> T anyObject()
```
    Matches anything, including null.
    This is an alias of: any() and any(java.lang.Class)
    See examples in javadoc for Matchers class
    
    Returns:
    null.
  - anyVararg
```
public static <T> T anyVararg()
```
    Any vararg, meaning any number and values of arguments.
    Example:
```
   //verification:
   mock.foo(1, 2);
   mock.foo(1, 2, 3, 4);

   verify(mock, times(2)).foo(anyVararg());

   //stubbing:
   when(mock.foo(anyVararg()).thenReturn(100);

   //prints 100
   System.out.println(mock.foo(1, 2));
   //also prints 100
   System.out.println(mock.foo(1, 2, 3, 4));
 
```
    See examples in javadoc for Matchers class
    Returns:
    null.
  - any
```
public static <T> T any(java.lang.Class<T> clazz)
```
    Matches any object, including nulls
    This method doesn't do type checks with the given parameter, it is only there to avoid casting in your code. This might however change (type checks could be added) in a future major release.
    See examples in javadoc for Matchers class
    This is an alias of: any() and anyObject()
    
    Returns:
    null.
  - any
```
public static <T> T any()
```
    Matches anything, including nulls
    Shorter alias to anyObject()
    See examples in javadoc for Matchers class
    This is an alias of: anyObject() and any(java.lang.Class)
    
    Returns:
    null.
  - anyString
```
public static java.lang.String anyString()
```
    Any non-null String
    See examples in javadoc for Matchers class
    
    Returns:
    empty String ("")
  - anyList
```
public static java.util.List anyList()
```
    Any non-null List.
    See examples in javadoc for Matchers class
    
    Returns:
    empty List.
  - anyListOf
```
public static <T> java.util.List<T> anyListOf(java.lang.Class<T> clazz)
```
    Generic friendly alias to anyList(). It's an alternative to @SuppressWarnings("unchecked") to keep code clean of compiler warnings.
    Any non-null List.
    This method doesn't do type checks with the given parameter, it is only there to avoid casting in your code. This might however change (type checks could be added) in a future major release.
    See examples in javadoc for Matchers class
    
    Parameters:
    clazz - Type owned by the list to avoid casting
    
    Returns:
    empty List.
  - anySet
```
public static java.util.Set anySet()
```
    Any non-null Set.
    See examples in javadoc for Matchers class
    
    Returns:
    empty Set
  - anySetOf
```
public static <T> java.util.Set<T> anySetOf(java.lang.Class<T> clazz)
```
    Generic friendly alias to anySet(). It's an alternative to @SuppressWarnings("unchecked") to keep code clean of compiler warnings.
    Any non-null Set.
    This method doesn't do type checks with the given parameter, it is only there to avoid casting in your code. This might however change (type checks could be added) in a future major release.
    See examples in javadoc for Matchers class
    
    Parameters:
    clazz - Type owned by the Set to avoid casting
    
    Returns:
    empty Set
  - anyMap
```
public static java.util.Map anyMap()
```
    Any non-null Map.
    See examples in javadoc for Matchers class
    
    Returns:
    empty Map.
  - anyMapOf
```
public static <K,V> java.util.Map<K,V> anyMapOf(java.lang.Class<K> keyClazz,
                                java.lang.Class<V> valueClazz)
```
    Generic friendly alias to anyMap(). It's an alternative to @SuppressWarnings("unchecked") to keep code clean of compiler warnings.
    Any non-null Map.
    This method doesn't do type checks with the given parameter, it is only there to avoid casting in your code. This might however change (type checks could be added) in a future major release.
    See examples in javadoc for Matchers class
    
    Parameters:
    keyClazz - Type of the map key to avoid casting
    valueClazz - Type of the value to avoid casting
    
    Returns:
    empty Map.
  - anyCollection
```
public static java.util.Collection anyCollection()
```
    Any non-null Collection.
    See examples in javadoc for Matchers class
    
    Returns:
    empty Collection.
  - anyCollectionOf
```
public static <T> java.util.Collection<T> anyCollectionOf(java.lang.Class<T> clazz)
```
    Generic friendly alias to anyCollection(). It's an alternative to @SuppressWarnings("unchecked") to keep code clean of compiler warnings.
    Any non-null Collection.
    This method doesn't do type checks with the given parameter, it is only there to avoid casting in your code. This might however change (type checks could be added) in a future major release.
    See examples in javadoc for Matchers class
    
    Parameters:
    clazz - Type owned by the collection to avoid casting
    
    Returns:
    empty Collection.
  - isA
```
public static <T> T isA(java.lang.Class<T> clazz)
```
    Object argument that implements the given class.
    See examples in javadoc for Matchers class
    
    Type Parameters:
    T - the accepted type.
    Parameters:
    clazz - the class of the accepted type.
    
    Returns:
    null.
  - eq
```
public static boolean eq(boolean value)
```
    boolean argument that is equal to the given value.
    See examples in javadoc for Matchers 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 Matchers 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 Matchers 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 Matchers 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 Matchers 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 Matchers 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 Matchers 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 Matchers 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 Matchers class
    
    Parameters:
    value - the given value.
    
    Returns:
    null.
  - refEq
```
public static <T> T refEq(T value,
          java.lang.String... excludeFields)
```
    Object argument that is reflection-equal to the given value with support for excluding selected fields from a class.
    This matcher can be used when equals() is not implemented on compared objects. Matcher uses java reflection API to compare fields of wanted and actual object.
    Works similarly to EqualsBuilder.reflectionEquals(this, other, exlucdeFields) from apache commons library.
    Warning The equality check is shallow!
    See examples in javadoc for Matchers class
    
    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 Matchers 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 java.lang.Object isNull()
```
    null argument.
    See examples in javadoc for Matchers class
    
    Returns:
    null.
  - isNull
```
public static <T> T isNull(java.lang.Class<T> clazz)
```
    null argument. The class argument is provided to avoid casting.
    See examples in javadoc for Matchers class
    
    Parameters:
    clazz - Type to avoid casting
    
    Returns:
    null.
  - notNull
```
public static java.lang.Object notNull()
```
    Not null argument.
    alias to isNotNull()
    See examples in javadoc for Matchers class
    
    Returns:
    null.
  - notNull
```
public static <T> T notNull(java.lang.Class<T> clazz)
```
    Not null argument, not necessary of the given class. The class argument is provided to avoid casting.
    alias to isNotNull(Class)
    See examples in javadoc for Matchers class
    
    Parameters:
    clazz - Type to avoid casting
    
    Returns:
    null.
  - isNotNull
```
public static java.lang.Object isNotNull()
```
    Not null argument.
    alias to notNull()
    See examples in javadoc for Matchers class
    
    Returns:
    null.
  - isNotNull
```
public static <T> T isNotNull(java.lang.Class<T> clazz)
```
    Not null argument, not necessary of the given class. The class argument is provided to avoid casting.
    alias to notNull(Class)
    See examples in javadoc for Matchers class
    
    Parameters:
    clazz - Type to avoid casting
    
    Returns:
    null.
  - contains
```
public static java.lang.String contains(java.lang.String substring)
```
    String argument that contains the given substring.
    See examples in javadoc for Matchers class
    
    Parameters:
    substring - the substring.
    
    Returns:
    empty String ("").
  - matches
```
public static java.lang.String matches(java.lang.String regex)
```
    String argument that matches the given regular expression.
    See examples in javadoc for Matchers class
    
    Parameters:
    regex - the regular expression.
    
    Returns:
    empty String ("").
  - endsWith
```
public static java.lang.String endsWith(java.lang.String suffix)
```
    String argument that ends with the given suffix.
    See examples in javadoc for Matchers class
    
    Parameters:
    suffix - the suffix.
    
    Returns:
    empty String ("").
  - startsWith
```
public static java.lang.String startsWith(java.lang.String prefix)
```
    String argument that starts with the given prefix.
    See examples in javadoc for Matchers class
    
    Parameters:
    prefix - the prefix.
    
    Returns:
    empty String ("").
  - argThat
```
public static <T> T argThat(org.hamcrest.Matcher<T> matcher)
```
    Allows creating custom argument matchers.
    In rare cases when the parameter is a primitive then you *must* use relevant intThat(), floatThat(), etc. method. This way you will avoid NullPointerException during auto-unboxing.
    See examples in javadoc for ArgumentMatcher class
    
    Parameters:
    matcher - decides whether argument matches
    
    Returns:
    null.
  - charThat
```
public static char charThat(org.hamcrest.Matcher<java.lang.Character> matcher)
```
    Allows creating custom Character argument matchers.
    See examples in javadoc for Matchers class
    
    Parameters:
    matcher - decides whether argument matches
    
    Returns:
    0.
  - booleanThat
```
public static boolean booleanThat(org.hamcrest.Matcher<java.lang.Boolean> matcher)
```
    Allows creating custom Boolean argument matchers.
    See examples in javadoc for Matchers class
    
    Parameters:
    matcher - decides whether argument matches
    
    Returns:
    false.
  - byteThat
```
public static byte byteThat(org.hamcrest.Matcher<java.lang.Byte> matcher)
```
    Allows creating custom Byte argument matchers.
    See examples in javadoc for Matchers class
    
    Parameters:
    matcher - decides whether argument matches
    
    Returns:
    0.
  - shortThat
```
public static short shortThat(org.hamcrest.Matcher<java.lang.Short> matcher)
```
    Allows creating custom Short argument matchers.
    See examples in javadoc for Matchers class
    
    Parameters:
    matcher - decides whether argument matches
    
    Returns:
    0.
  - intThat
```
public static int intThat(org.hamcrest.Matcher<java.lang.Integer> matcher)
```
    Allows creating custom Integer argument matchers.
    See examples in javadoc for Matchers class
    
    Parameters:
    matcher - decides whether argument matches
    
    Returns:
    0.
  - longThat
```
public static long longThat(org.hamcrest.Matcher<java.lang.Long> matcher)
```
    Allows creating custom Long argument matchers.
    See examples in javadoc for Matchers class
    
    Parameters:
    matcher - decides whether argument matches
    
    Returns:
    0.
  - floatThat
```
public static float floatThat(org.hamcrest.Matcher<java.lang.Float> matcher)
```
    Allows creating custom Float argument matchers.
    See examples in javadoc for Matchers class
    
    Parameters:
    matcher - decides whether argument matches
    
    Returns:
    0.
  - doubleThat
```
public static double doubleThat(org.hamcrest.Matcher<java.lang.Double> matcher)
```
    Allows creating custom Double argument matchers.
    See examples in javadoc for Matchers class
    
    Parameters:
    matcher - decides whether argument matches
    
    Returns:
    0.

Class Matchers

Custom Argument Matchers

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

Matchers

Method Detail

anyBoolean

anyByte

anyChar

anyInt

anyLong

anyFloat

anyDouble

anyShort

anyObject

anyVararg

any

any

anyString

anyList

anyListOf

anySet

anySetOf

anyMap

anyMapOf

anyCollection

anyCollectionOf

isA

eq

eq

eq

eq

eq

eq

eq

eq

eq

refEq

same

isNull

isNull

notNull

notNull

isNotNull

isNotNull

contains

matches

endsWith

startsWith

argThat

charThat

booleanThat

byteThat

shortThat

intThat

longThat

floatThat

doubleThat