Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## org.mockito
Class Matchers

    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.

Warning 2:

The any family methods *don't do any type checks*, those are only here to avoid casting in your code. If you want to perform type checks use the `isA(Class)` method. This might however change (type checks could be added) in a future major release.

# Custom Argument Matchers

Use `argThat(org.hamcrest.Matcher)` 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
`Matchers()`

Method Summary
`static
`<T> T`
` | `any()` Any object or `null`.
`static
`<T> T`
` | `any(java.lang.Class<T> clazz)` Any kind object, not necessary of the given class.
`static boolean` | `anyBoolean()` Any `boolean`, `Boolean` or `null`.
`static byte` | `anyByte()` Any `byte`, `Byte` or `null`.
`static char` | `anyChar()` Any `char`, `Character` or `null`.
`static java.util.Collection` | `anyCollection()` Any `Collection` or `null`.
`static
`<T> java.util.Collection<T>`
` | `anyCollectionOf(java.lang.Class<T> clazz)` Generic friendly alias to `anyCollection()`.
`static double` | `anyDouble()` Any `double`, `Double` or `null`.
`static float` | `anyFloat()` Any `float`, `Float` or `null`.
`static int` | `anyInt()` Any int, Integer or `null`.
`static java.util.List` | `anyList()` Any `List` or `null`.
`static
`<T> java.util.List<T>`
` | `anyListOf(java.lang.Class<T> clazz)` Generic friendly alias to `anyList()`.
`static long` | `anyLong()` Any `long`, `Long` or `null`.
`static java.util.Map` | `anyMap()` Any `Map` or `null`.
`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()` Any `Object` or `null`.
`static java.util.Set` | `anySet()` Any `Set` or `null`.
`static
`<T> java.util.Set<T>`
` | `anySetOf(java.lang.Class<T> clazz)` Generic friendly alias to `anySet()`.
`static short` | `anyShort()` Any `short`, `Short` or `null`.
`static java.lang.String` | `anyString()` Any `String` or `null`.
`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`, `Boolean` or `null`.

  This method *don't do any type checks*, 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

  Returns:
    `false`.

### anyByte

    public static byte anyByte()

  Any `byte`, `Byte` or `null`.

  This method *don't do any type checks*, 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

  Returns:
    `0`.

### anyChar

    public static char anyChar()

  Any `char`, `Character` or `null`.

  This method *don't do any type checks*, 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

  Returns:
    `0`.

### anyInt

    public static int anyInt()

  Any int, Integer or `null`.

  This method *don't do any type checks*, 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

  Returns:
    `0`.

### anyLong

    public static long anyLong()

  Any `long`, `Long` or `null`.

  This method *don't do any type checks*, 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

  Returns:
    `0`.

### anyFloat

    public static float anyFloat()

  Any `float`, `Float` or `null`.

  This method *don't do any type checks*, 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

  Returns:
    `0`.

### anyDouble

    public static double anyDouble()

  Any `double`, `Double` or `null`.

  This method *don't do any type checks*, 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

  Returns:
    `0`.

### anyShort

    public static short anyShort()

  Any `short`, `Short` or `null`.

  This method *don't do any type checks*, 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

  Returns:
    `0`.

### anyObject

    public static <T> T anyObject()

  Any `Object` or `null`.

  This method *don't do any type checks*, it is only there to avoid casting in your code. This might however change (type checks could be added) in a future major release.

  Has aliases: `any()` and `any(Class clazz)`

  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)

  Any kind object, not necessary of the given class. The class argument is provided only to avoid casting.

  Sometimes looks better than `anyObject()` - especially when explicit casting is required

  Alias to `anyObject()`

  This method *don't do any type checks*, 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` - The type to avoid casting
  Returns:
    `null`.

### any

    public static <T> T any()

  Any object or `null`.

  Shorter alias to `anyObject()`

  This method *don't do any type checks*, 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

  Returns:
    `null`.

### anyString

    public static java.lang.String anyString()

  Any `String` or `null`.

  This method *don't do any type checks*, 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

  Returns:
    empty String ("")

### anyList

    public static java.util.List anyList()

  Any `List` or `null`.

  This method *don't do any type checks*, 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

  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 `List` or `null`.

  This method *don't do any type checks*, 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 `Set` or `null`.

  This method *don't do any type checks*, 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

  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 `Set` or `null`

  This method *don't do any type checks*, 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 `Map` or `null`.

  This method *don't do any type checks*, 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

  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 `Map` or `null`

  This method *don't do any type checks*, 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 `Collection` or `null`.

  This method *don't do any type checks*, 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

  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 `Collection` or `null`.

  This method *don't do any type checks*, 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`.

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD