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.
 

Custom Argument Matchers

Use argThat(org.hamcrest.Matcher) method and pass an instance of hamcrest Matcher.

You can use ArgumentMatcher which is an hamcrest matcher with predefined describeTo() method. In case of failure ArgumentMatcher generates description based on 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());
 

Custom argument matchers 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.

Constructor Summary

Matchers()

Method Summary

static <T> T	any(java.lang.Class<T> clazz) any object of specified 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 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 long	anyLong() any long, Long or null.
static java.util.Map	anyMap() any Map or null.
static <T> T	anyObject() any Object or null.
static short	anyShort() any short, Short or null.
static java.lang.String	anyString() any String or null.
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 argument matchers.
static byte	byteThat(org.hamcrest.Matcher<java.lang.Byte> matcher) Allows creating custom argument matchers.
static char	charThat(org.hamcrest.Matcher<java.lang.Character> matcher) Allows creating custom 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 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 argument matchers.
static int	intThat(org.hamcrest.Matcher<java.lang.Integer> matcher) Allows creating custom 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 java.lang.Object	isNull() null argument.
static long	longThat(org.hamcrest.Matcher<java.lang.Long> matcher) Allows creating custom 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	refEq(T value) Object argument that is reflection-equal to the given value.
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 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.

See examples in javadoc for Matchers class

Returns:

false.

anyByte

public static byte anyByte()

any byte, Byte or null

See examples in javadoc for Matchers class

Returns:

0.

anyChar

public static char anyChar()

any char, Character or null.

See examples in javadoc for Matchers class

Returns:

0.

anyInt

public static int anyInt()

any int, Integer or null.

See examples in javadoc for Matchers class

Returns:

0.

anyLong

public static long anyLong()

any long, Long or null.

See examples in javadoc for Matchers class

Returns:

0.

anyFloat

public static float anyFloat()

any float, Float or null.

See examples in javadoc for Matchers class

Returns:

0.

anyDouble

public static double anyDouble()

any double, Double or null.

See examples in javadoc for Matchers class

Returns:

0.

anyShort

public static short anyShort()

any short, Short or null.

See examples in javadoc for Matchers class

Returns:

0.

anyObject

public static <T> T anyObject()

any Object or null.

See examples in javadoc for Matchers class

Returns:

null.

any

public static <T> T any(java.lang.Class<T> clazz)

any object of specified class. Sometimes looks better than anyObject()

Alias to anyObject()

See examples in javadoc for Matchers class

Returns:

null.

anyString

public static java.lang.String anyString()

any String or null.

See examples in javadoc for Matchers class

Returns:

empty String ("")

anyList

public static java.util.List anyList()

any List or null.

See examples in javadoc for Matchers class

Returns:

empty List.

anyMap

public static java.util.Map anyMap()

any Map or null.

See examples in javadoc for Matchers class

Returns:

empty Map.

anyCollection

public static java.util.Collection anyCollection()

any Collection or null.

See examples in javadoc for Matchers class

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)

Object argument that is reflection-equal to the given value.

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) from apache commons library.

See examples in javadoc for Matchers class

Parameters:

value - the given value.

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.

notNull

public static java.lang.Object notNull()

not null argument.

alias to isNotNull()

See examples in javadoc for Matchers class

Returns:

null.

isNotNull

public static java.lang.Object isNotNull()

not null argument.

alias to notNull()

See examples in javadoc for Matchers class

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.

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 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 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 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 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 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 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 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 argument matchers.

See examples in javadoc for Matchers class

Parameters:

matcher - decides whether argument matches

Returns:

0.