Argument Matchers

Argument matchers are mainly used for performing flexible verification and stubbing in Mockito. It extends ArgumentMatchers class to access all the matcher functions. Mockito uses equal() as a legacy method for verification and matching of argument values. In some cases, we need more flexibility during the verification of argument values, so we should use argument matchers instead of equal() method. The ArgumentMatchers class is available in org.mockito package.

The ArgumentMatchers class contains a variety of methods; some of them are listed below:

Method type and method name	Description
<T> any()	It matches all values (anything), including null values and varargs.
boolean anyBoolean()	It matches to any boolean or not-null boolean values.
byte anyByte()	It matches to any byte or not-null byte values.
char anyChar()	It matches to any char or not-null character values.
Collection <T> anyCollection	It matches any not-null collection in the application.
double anyDouble()	It matches to any double or not-null double values.
float anyFloat()	It matches to any float or not-null float values.
int anyInt()	It matches to any int or not-null integer values.
Iterable<T> anyIterable()	It matches to any int or not-null integer values.
Iterable<T> anyIterable()	It matches to any not-null iterable values.
List<T> anyList()	It matches any not-null list.
long anyLong()	It matches to any long or not-null long values.
Set<T> anySet()	It matches any not-null set.
short anyShort()	It matches to any short or not-null short values.
String anyString()	It matches any not-null String.
<T> argThat(ArgumentMatcher<T> matcher)	It allows the creation of custom argument matchers.
boolean booleanThat(ArgumentMatcher<Boolean> matcher)	It allows the creation of the custom boolean argument matchers.
byte byteThat(ArgumentMatcher<Byte> matcher)	It allows the creation of custom byte argument matchers.
char charThat(ArgumentMatcher<Character> matcher)	It allows the creation of custom char argument matchers.
String contains(String substring)	It matches the String argument that contains the substring.
double doubleThat(ArgumentMatcher<Double> matcher)	It allows the creation of custom double argument matchers.
String endsWith(String suffix)	It matches the String argument that ends with the given suffix.
boolean eq(boolean value)	It matches with the boolean argument that is equal to the given value.
double eq(double value)	It matches with the double argument that is equal to the given value.
long eq(long value)	It matches the long argument that is equal to the given value.
<T> isNotNull()	It matches with the not null argument.
<T> is Null()	It matches the null argument.
<T> same(T value)	It checks whether the object argument is the same as the given value.

Note: All the arguments must be provided by the matchers while using argument matchers.

Example of Argument Matcher

Here, we are going to create an example of Argument matchers. We are using the anyInt() method in our test case, we can use any of the methods available in the ArgumentMatchers class.

TestList.java

import static org.junit.Assert.*;
import static org.mockito.Mockito.when;
import java.util.List;
import org.junit.Test;
import org.mockito.Mock;
import org.mockito.Mockito;
public class TestList { 
              @Test
	  public void testList_Argument_Matchers() {

		List<String> mocklist = mock(List.class);

		when(mocklist.get(Mockito.anyInt())).thenReturn("Mockito");
		
		assertEquals("Mockito", mocklist.get(0));
		assertEquals("Mockito", mocklist.get(1)); 
                        assertEquals("Mockito", mocklist.get(2));
	}
 }

Output

The following output shows that the test is successfully running using argument matchers.

Example of throwing an exception using Argument matcher

Here, we are going to create an example of throwing an exception using argument matchers. In this example, we will use JUnit feature @Test(expected = RuntimeException.class) to prevent the test failure. If we don't use it, the test fails and throws an exception.

TestList.java

import static org.junit.Assert.*;
import static org.mockito.Mockito.mock;
import static org.mockito.Mockito.when;

import java.util.List;
import org.junit.Test;
import org.mockito.Mockito;

public class TestList {

	@Test(expected = RuntimeException.class)
	  public void testList_ThrowsException() {
		  
	  List<String> mocklist = mock(List.class);
	  
	  when(mocklist.get(Mockito.anyInt())).thenThrow(new RuntimeException("Error.."));
	  mocklist.get(0);
	  }
 }

Output

The following output shows that the test is successfully running using the @Test(expected = RuntimeException.class).