Package org.mockito

Class Matchers

java.lang.Object
org.mockito.Matchers
Direct Known Subclasses:
Mockito

public class Matchers extends 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 *doesn'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<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
    Description
     
  • Method Summary

    Modifier and Type
    Method
    Description
    static <T> T
    any()
    Any object or null.
    static <T> T
    any(Class<T> clazz)
    Any kind object, not necessary of the given class.
    static boolean
    Any boolean, Boolean or null.
    static byte
    Any byte, Byte or null.
    static char
    Any char, Character or null.
    static Collection
    Any Collection or null.
    static <T> Collection<T>
    Generic friendly alias to anyCollection().
    static double
    Any double, Double or null.
    static float
    Any float, Float or null.
    static int
    Any int, Integer or null.
    static List
    Any List or null.
    static <T> List<T>
    anyListOf(Class<T> clazz)
    Generic friendly alias to anyList().
    static long
    Any long, Long or null.
    static Map
    Any Map or null.
    static <K, V> Map<K,V>
    anyMapOf(Class<K> keyClazz, Class<V> valueClazz)
    Generic friendly alias to anyMap().
    static <T> T
    Any Object or null.
    static Set
    Any Set or null.
    static <T> Set<T>
    anySetOf(Class<T> clazz)
    Generic friendly alias to anySet().
    static short
    Any short, Short or null.
    static String
    Any String or null.
    static <T> T
    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<Boolean> matcher)
    Allows creating custom Boolean argument matchers.
    static byte
    byteThat(org.hamcrest.Matcher<Byte> matcher)
    Allows creating custom Byte argument matchers.
    static char
    charThat(org.hamcrest.Matcher<Character> matcher)
    Allows creating custom Character argument matchers.
    static String
    contains(String substring)
    String argument that contains the given substring.
    static double
    doubleThat(org.hamcrest.Matcher<Double> matcher)
    Allows creating custom Double argument matchers.
    static String
    endsWith(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<Float> matcher)
    Allows creating custom Float argument matchers.
    static int
    intThat(org.hamcrest.Matcher<Integer> matcher)
    Allows creating custom Integer argument matchers.
    static <T> T
    isA(Class<T> clazz)
    Object argument that implements the given class.
    static Object
    Not null argument.
    static <T> T
    isNotNull(Class<T> clazz)
    Not null argument, not necessary of the given class.
    static Object
    null argument.
    static <T> T
    isNull(Class<T> clazz)
    null argument.
    static long
    longThat(org.hamcrest.Matcher<Long> matcher)
    Allows creating custom Long argument matchers.
    static String
    matches(String regex)
    String argument that matches the given regular expression.
    static Object
    Not null argument.
    static <T> T
    notNull(Class<T> clazz)
    Not null argument, not necessary of the given class.
    static <T> T
    refEq(T value, 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<Short> matcher)
    Allows creating custom Short argument matchers.
    static String
    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 Details

    • Matchers

      public Matchers()
  • Method Details

    • anyBoolean

      public static boolean anyBoolean()
      Any boolean, Boolean or null.

      This method *doesn'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 *doesn'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 *doesn'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 *doesn'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 *doesn'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 *doesn'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 *doesn'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 *doesn'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 *doesn'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(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 *doesn'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 *doesn'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 String anyString()
      Any String or null.

      This method *doesn'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 List anyList()
      Any List or null.

      This method *doesn'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> List<T> anyListOf(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 *doesn'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 Set anySet()
      Any Set or null.

      This method *doesn'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> Set<T> anySetOf(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 *dones'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 Map anyMap()
      Any Map or null.

      This method *doesn'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> Map<K,V> anyMapOf(Class<K> keyClazz, 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 *doesn'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 Collection anyCollection()
      Any Collection or null.

      This method *dones'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> Collection<T> anyCollectionOf(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 *doesn'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(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, 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 Object isNull()
      null argument.

      See examples in javadoc for Matchers class

      Returns:
      null.
    • isNull

      public static <T> T isNull(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 Object notNull()
      Not null argument.

      alias to isNotNull()

      See examples in javadoc for Matchers class

      Returns:
      null.
    • notNull

      public static <T> T notNull(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 Object isNotNull()
      Not null argument.

      alias to notNull()

      See examples in javadoc for Matchers class

      Returns:
      null.
    • isNotNull

      public static <T> T isNotNull(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 String contains(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 String matches(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 String endsWith(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 String startsWith(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<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<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<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<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<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<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<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<Double> matcher)
      Allows creating custom Double argument matchers.

      See examples in javadoc for Matchers class

      Parameters:
      matcher - decides whether argument matches
      Returns:
      0.