The following steps describe how Mockito JAR files can be added as project dependency:

The following code snippet will add the Mockito dependency to a Maven project and download the JAR files from the central Maven repository (http://mvnrepository.com/artifact/org.mockito/mockito-core):

<dependency>
  <groupId>org.mockito</groupId>
  <artifactId>mockito-core</artifactId>
  <version>1.9.5</version>
  <scope>test</scope>
</dependency>

The following Gradle script snippet will add the Mockito dependency to a Gradle project:

  testCompile 'org.mockito:mockito-core:1.9.5'

This section demonstrates the mock objects with an example. The following jQuery table displays a list of countries:

This special table has numerous controls; you can sort by a column, either in descending or ascending order. The table displays selectable rows per page as a dropdown; you can change the number of records per page — you can choose 10, 15, 20, 30, or 50. The table has a next page, previous page, first page, and last page widget. It has a refresh icon to load the latest dataset.

We need to create a controller class to accept the Ajax call from the jQuery table and return a country list. The Ajax request contains the requested page number, rows per page, sort order, sort column name, and search query. The controller needs to retrieve the country details from a database table and return only filtered countries as an Ajax response.

The following is the Ajax controller class:

@Controller
@Scope("session")
public class AjaxController {
  private final CountryDao countryDao;

  public AjaxController(CountryDao countryDao) {
    this.countryDao = countryDao;
  }

  @RequestMapping(value = "retrieveCountries", method = RequestMethod.POST)
  public @ResponseBody
  JsonDataWrapper<Country> retrieve(HttpServletRequest webRequest) {
    List<Country> countries = new ArrayList<Country  >();
    RetrieveCountryRequest request = RequestBuilder.build(webRequest);
    countries = countryDao.retrieve(request);
    Long startIndex = (request.getPage() - 1) * (request.getRowPerPage());
    int size = countries.size();
    Long endIndex = (startIndex + request.getRowPerPage()) > size ? size: (startIndex + request.getRowPerPage());
    if (startIndex < endIndex) {
      countries = countries.subList(startIndex.intValue(),
      endIndex.intValue());
   }

    JsonDataWrapper<Country> wrapper = new JsonDataWrapper<Country>(request.getPage(), size, countries);

    return wrapper;
  }

}

The retrieve method accepts an HttpServletRequest object and builds a database access request from this object. The following is the request's builder code:

public class RequestBuilder {

  public static RetrieveCountryRequest build(HttpServletRequestwebReq) {
    RetrieveCountryRequest request = new RetrieveCountryRequest();
    request.setPage(getLong(webReq.getParameter("page")));
    request.setRowPerPage(getInt(webReq.getParameter("rp")));
    request.setSortOrder(SortOrder.find(webReq.getParameter("sortorder")));
    request.setSortname(SortColumn.find(webReq.getParameter("sortname")));
    request.setSerachQuery(webReq.getParameter("qtype"));

    return request;
  }

  private static Integer getInt(String val) {
    Integer retVal = null;
    try {
      retVal = Integer.parseInt(val);
    } catch (Exception e) {
    }

  return retVal;
  }

  private static Long getLong(String val) {
    Long retVal = null;
    try {
      retVal = Long.parseLong(val);
    } catch (Exception e) {
    }
    return retVal;
  }
}

Finally, the retrieve method builds a JsonDataWrapper object from the country list and hands it over to the Ajax request as JSON data. The @ResponseBody annotation instructs the JSON response.

To unit test this class, we need to create an HttpServletRequest object, populate it with testable data, and then isolate the countryDao/database access call.

We'll use the Mockito framework to create a mock HttpServletRequest object and isolate the countryDao access call by stubbing the database call.

A mock object can be created with the help of a static method mock(). You need to invoke the Mockito.mock() method or static import Mockito's mock() method. The following is the syntax:

import org.mockito.Mockito;
public class AjaxControllerTest {

  HttpServletRequest request;
  CountryDao countryDao;

  @Before
  public void setUp(){
    request = Mockito.mock(HttpServletRequest.class);
    countryDao = Mockito.mock(CountryDao.class);
  }
}

The following code snippet uses Java's static import construct:

import static org.mockito.Mockito.mock;
public class AjaxControllerTest {

  HttpServletRequest request;
  CountryDao countryDao;

  @Before
  public void setUp(){
    request = mock(HttpServletRequest.class);
    countryDao = mock(CountryDao.class);
  }
}

There's another way of mocking objects — using the @Mock annotation. But to work with the @Mock annotation, it is necessary to call MockitoAnnotations.initMocks(this) before using the mocks; or use MockitoJUnitRunner as a JUnit runner. We'll cover the annotation in depth in the next chapter. The following example is the syntax of mocking using the @Mock annotation:

import org.junit.Before;
import org.mockito.Mock;
import org.mockito.MockitoAnnotations;
public class AjaxControllerTest {

  private @Mock HttpServletRequest request;
  private @Mock CountryDao countryDao;

  @Before
  public void setUp(){
    MockitoAnnotations.initMocks(this);
  }
}

The following is the syntax of the @Mock annotation using MockitoJUnitRunner:

import org.junit.Before;
import org.junit.runner.RunWith;
import org.mockito.Mock;
import org.mockito.runners.MockitoJUnitRunner;

@RunWith(MockitoJUnitRunner.class)
public class AjaxControllerTest {

  private @Mock HttpServletRequest request;
  private @Mock CountryDao countryDao;

  @Before
  public void setUp() {
  }
}

We read about stubs in Chapter 1, Exploring Test Doubles. The stubbing process defines the behavior of a mock method, such as what value should be returned or whether any exception should be thrown when the method is invoked.

The Mockito framework supports stubbing and allows us to return a given value when a specific method is called. It can be done using Mockito.when() along with thenReturn().

The following is the syntax for importing when:

import static org.mockito.Mockito.when;

The following test code stubs the retrieve method for CountryDao and returns an empty list. Finally, the stubbing is verified using the assertTrue method:

@Test
public void retrieves_empty_country_list() throws Exception {
  List<Country> list = new ArrayList<Country>();
  list.add(new Country());
  when(countryDao.retrieve(isA(RetrieveCountryRequest.class))).thenReturn(emptyList);

  assertTrue(countryDao.retrieve(new RetrieveCountryRequest()).size() == 1);
}

The when() method represents the trigger—when to stub it. The following methods are used to represent a trigger action or what to do when the trigger is triggered.

The thenReturn() method has a variant; it can either return a hardcoded value or can accept variable arguments of hardcoded values. What follows are the three ensuing variants:

The thenReturn(value) variant returns the same hardcoded value for each method call, whereas when(mock.someMethod()).thenReturn(10,5,100) returns the following values:

We'll use this style of mocking for HttpServletRequest. The following is the modified test:

@Test
public void retrieves_empty_country_list() throws Exception {
  when(request.getParameter(anyString())).thenReturn("1", "10",SortOrder.ASC.name(), SortColumn.iso.name());

  List<Country> countryList = new ArrayList<Country>();
  countryList.add(new Country());

  when(countryDao.retrieve(isA(RetrieveCountryRequest.class))).thenReturn(countryList);
  JsonDataWrapper<Country> response = ajaxController.retrieve(request);

  assertEquals(1, response.getPage());
  assertEquals(1, response.getTotal());
  assertEquals(1, response.getRows().size());

}

The RequestBuilder class calls the getParameter() method of HttpServletRequest to fetch the request parameters. Sequentially, it calls webReq.getParameter("page"), webReq.getParameter("rp"), webReq.getParameter("sortorder"), and webReq.getParameter("sortname").

In the test method, we stubbed the getParameter call with a variable argument thenReturn style.

We used two Mockito matchers, namely, anyString and isA. The anyString() matcher is used to stub the getParameter method. The getParameter method accepts a string argument, such as webReq.getParameter("page"). The anyString matcher is used as a generic argument matcher. This means, no matter what value is passed to the getParameter method, it will return a hardcoded value.

The isA matcher is used to stub the retrieve method of CountryDao to get the following:

In the next section, we'll discuss argument matchers.

Unit tests are not meant only for happy path testing. We should test our code for failure conditions as well. Mockito provides an API to raise errors during testing. Suppose we are testing a flow where we compute some value and then send it to a printer; if the printer is not configured or a network error occurs or a page is not loaded, the system throws an exception. We can test this using Mockito's exception APIs.

How do we test exceptional conditions such as database access failure?

For this, Mockito provides a thenThrow(Throwable)method. This method tells the Mockito framework to throw a throwable (could be exception or error) when the stubbed method is invoked.

JUnit 4.0 provides a way to test exceptions using @Test(expected=<exception>).

We'll stub the countryDao access call to throw an exception and assert the exception using @Test(execpted=). If the test doesn't throw any exception, it will fail:

@Test(expected=RuntimeException.class)
public void when_system_throws_exception() {
  when(request.getParameter(anyString())).thenReturn("1", "10", SortOrder.DESC.name(), SortColumn.iso.name());

  when(countryDao.retrieve(isA(RetrieveCountryRequest.class))).    thenThrow(new RuntimeException("Database failure"));

  JsonDataWrapper<Country> response = ajaxController.retrieve(request);
}

To throw an exception from a void method, use the following code syntax:

doThrow(exception).when(mock).voidmethod(arguments);

Checking and throwing RuntimeException is not recommended. Instead, we can use a specific exception in production code. In JUint 4, there exists an ExpectedException rule API for exception handling.

The argument matcher plays a key role in mocking. Mock objects return expected values, but when they need to return different values for different arguments, the argument matcher comes into play.

Suppose we have a method that takes a cricket player's name as an input and returns the number of runs as an output. We want to stub it and return 100 for the player Sachin and 10 for xyz. We have to use the argument matcher to stub this.

Mockito returns expected values when a method is stubbed. If the method takes arguments, the argument must match during the execution. For example, the getValue(int someValue) method is stubbed in the following way:

when(mockObject.getValue(1)).thenReturn(expected value);

Here, the getValue method is called with mockObject.getValue(100). The parameter doesn't match (it is expected that the method will be called with 1, but at runtime it encounters 100), so the mock object fails to return the expected value. It will return the default value of the return type. If the return type is int or short or long, it returns 0 for wrapper types such as integer and long. If it returns NULL for Boolean, it'll return false if the object is null and so on.

Mockito verifies argument values in natural Java style by using an object's equals() method. Sometimes, we use argument matchers when extra flexibility is required. Mockito provides built-in matchers, such as anyInt(), anyDouble(), anyString(), anyList(), and anyCollection(). More built-in matchers and examples of custom argument matchers / hamcrest matchers can be found at the following link:

https://github.com/mockito/mockito/blob/master/src/org/mockito/Matchers.java

The isA matcher checks whether the passed object is an instance of the class type passed in the isA argument. The any(T) matcher also works in the same way.

public void someMethod(Object obj){
  Request req = new Request();
  Req.setValue(obj);
  Response resp = service.callMethod(req);
}

verify(mock).someMethod(anyInt(), anyString(), eq("third argument"));

verify(mock).someMethod(1, anyString(), "third argument");

import static org.hamcrest.CoreMatchers.*;
import static org.junit.Assert.*;

import org.junit.Test;

public class AssertThatTest {

  @Test
  public void verify_Matcher() throws Exception {
    int age = 30;
    assertThat(age, equalTo(30));
    assertThat(age, is(30));

    assertThat(age, not(equalTo(33)));
    assertThat(age, is(not(33)));
  }
}

java.lang.AssertionError: 
Expected: <30>
     but: was <29>
  at org.hamcrest.MatcherAssert.assertThat(MatcherAssert.java:20)
  at org.junit.Assert.assertThat(Assert.java:865)

@Test
public void verify_multiple_values() throws Exception {

  double marks = 100.00;
  assertThat(marks, either(is(100.00)).or(is(90.9)));

  assertThat(marks, both(not(99.99)).and(not(60.00)));
  assertThat(marks, anyOf(is(100.00),is(1.00),is(55.00),is(88.00),is(67.8)));

  assertThat(marks, not(anyOf(is(0.00),is(200.00))));

  assertThat(marks, not(allOf(is(1.00),is(100.00), is(30.00))));
}

or(Matcher other) is translated as 
return (new CombinableMatcher(first)).or(other);-> finally to 
new CombinableMatcher(new AnyOf(templatedListWith(other)));

class SortByISOInAscendingOrderMatcher extends
ArgumentMatcher<RetrieveCountryRequest> {
  @Override
  public boolean matches(Object request) {
    if (request instanceof RetrieveCountryRequest) {
      SortOrder sortOrder = ((RetrieveCountryRequest) request).getSortOrder();
      SortColumn col = ((RetrieveCountryRequest) request).getSortname();

      return SortOrder.ASC.equals(sortOrder) && SortColumn.iso.equals(col);
    }
    return false;
  }
}

@Test
public void countryList_sortedBy_ISO_In_asc_order() {
  when(request.getParameter(anyString())).thenReturn("1", "10",     SortOrder.ASC.name(), SortColumn.iso.name());

  Country argentina = new Country();
  argentina.setIso("AR");
  Country india = new Country();
  india.setIso("IN");
  Country usa = new Country();
  usa.setIso("US");

  List<Country> ascCountryList = new ArrayList<Country>();
  ascCountryList.add(argentina);
  ascCountryList.add(india);
  ascCountryList.add(usa);

  when(countryDao.retrieve(argThat(new SortByISOInAscendingOrderMatcher()))).thenReturn(ascCountryList);

  JsonDataWrapper<Country> response = ajaxController.retrieve(request);
  assertEquals(ascCountryList, response.getRows());
}

To verify a redundant method invocation or if a stubbed method was not called but was important from the test perspective, we should manually verify the invocation. We need to use the static verify method.

Mock objects are used to stub external dependencies. We set an expectation and a mock object returns an expected value. In some conditions, a behavior/method of a mock object should not be invoked, or sometimes we may need to call the method N (a number) times. The verify method verifies the invocation of mock objects. Mockito does not automatically verify all stubbed calls; JMock does this automatically.

If a stubbed behavior should not be called, but is called due to bug in a code, the verify method flags the error (but we have to verify that manually). The void methods don't return a value; verify is very handy to test a void method's behavior (explained later).

The verify() method has an overloaded version, which takes VerificationMode (AtLeast, AtMost, Times, and so on) as an argument. The Times mode is a Mockito framework class of package, org.mockito.internal.verification, and it takes the integer argument, wantedNumberOfInvocations.

If 0 is passed to Times, it infers that the method will not be invoked in the testing path. We can pass 0 to Times(0) to make sure that the sell or buy methods are not invoked. If a negative number is passed to the Times constructor, Mockito throws MockitoException - org.mockito.exceptions.base.MockitoException and shows the Negative value is not allowed here error. The following methods are used in conjunction with verify:

Verifying zero and no-more interactions

The verifyZeroInteractions (object, mocks) method verifies that no interactions happened on the given mocks. The following test code directly calls the verifyZeroInteractions and passes the two mock objects. Since no methods are invoked on the mock objects, the test passes.

@Test public void verify_zero_interaction() {
  verifyZeroInteractions(request,countryDao);
}

This is useful if your code depends on two or more collaborators. For a given input, only one collaborator should handle the request while others should just ignore the request.

The verifyNoMoreInteractions (Object, mocks) method checks if any of the given mocks have any unverified interaction. We can use this method after verifying a mock method to make sure that nothing else was invoked on the mock.

This is generally not a good practice as it makes your tests overly brittle and you end up testing more than just what you care about. The following test code demonstrates the verifyNoMoreInteractions method:

@Test public void verify_nomore_interaction() {
  request.getParameter("page");
  request.getContextPath();

  verify(request).getParameter(anyString());
  //this will fail getContextPath() is not verified
  verifyNoMoreInteractions(request);
}

The following is the JUnit output. The test fails as the getContextPath() method was not verified even though the getParameter() method was verified. So the test considered the getContextPath() method invocation as a coding bug and verifyNoMoreInteractions raised the error.

Stubbed methods return a hardcoded value but cannot return a dynamic on-the-fly result. Mockito framework offers callbacks to compute on-the-fly results.

Mockito allows stubbing with the generic Answer interface; this is a callback. When a stubbed method on a mock object is invoked, the answer(InvocationOnMock invocation) method of the Answer object is called. This Answer object's answer() method returns the actual object. The syntax is similar to thenReturn() and thenThrow():

when(mock.someMethod()).thenAnswer(new Answer() {…});

Alternatively, we can also use the following syntax:

when(mock.someMethod()).then(answer);

The Answer interface is defined as follows:

public interface Answer<T> {
  T answer(InvocationOnMock invocation) throws Throwable;
}

The InvocationOnMock argument is an important part of a callback. It gives you the arguments passed to the method and the mock object as well. The following methods of InvocationOnMock are used to get the arguments and the mock object:

Object[] args = invocation.getArguments();
Object mock = invocation.getMock();

The retrieve method of CountryDao is stubbed. We'll create an answer object to dynamically sort the country list based on the input sort order.

In test class, create a list for storing countries, and in the setUp method, populate the list with countries. The following is the changed test code:

  List<Country> countries;

  @Before
  public void setUp() {
    ajaxController = new AjaxController(countryDao);
    countries = new ArrayList<Country>();
    countries.add(create("Argentina", "AR", "32"));
    countries.add(create("USA", "US", "01"));
    countries.add(create("Brazil", "BR", "05"));
    countries.add(create("India", "IN", "91"));
  }

Write a new Answer class to sort the countries list based on the user input. The following example is the custom Answer class:

class SortAnswer implements Answer<Object> {
  @Override
  public Object answer(InvocationOnMock invocation) throws Throwable {
    RetrieveCountryRequest request = (RetrieveCountryRequest) invocation.getArguments()[0];
    final int order = request.getSortOrder().equals(SortOrder.ASC) ? 1: -1;
    final SortColumn col = request.getSortname();
    Collections.sort(countries, new Comparator<Country>() {
      public int compare(Country arg0, Country arg1) {
        if (SortColumn.countryCode.equals(col))
        return order * arg0.getCountryCode().compareTo(arg1.getCountryCode());

        if (SortColumn.iso.equals(col))
        return order * arg0.getIso().compareTo(arg1.getIso());
        return order * arg0.getName().compareTo(arg1.getName());
      }
    });

    return countries;
  }
}

The answer method gets the request object and sorts the countries list based on the SortOrder and SortColumn attributes. The following test verifies the ascending and descending sorting:

  @Test
  public void sorting_asc_on_iso() {
    when(request.getParameter(anyString())).thenReturn("1", "10", SortOrder.ASC.name(),   SortColumn.iso.name());


    when(countryDao.retrieve(isA(RetrieveCountryRequest.class))).thenAnswer(new SortAnswer());

    JsonDataWrapper<Country> response = ajaxController.retrieve(request);
    assertEquals("AR", response.getRows().get(0).getIso());
    assertEquals("BR", response.getRows().get(1).getIso());
    assertEquals("IN", response.getRows().get(2).getIso());
    assertEquals("US", response.getRows().get(3).getIso());
  }

  @Test
  public void sorting_desc_on_iso() {
    when(request.getParameter(anyString())).thenReturn("1",       "10",SortOrder.DESC.name(), SortColumn.iso.name());

    when(countryDao.retrieve(isA(RetrieveCountryRequest.class))).thenAnswer(new SortAnswer());

    JsonDataWrapper<Country> response = ajaxController.retrieve(request);
    assertEquals("AR", response.getRows().get(3).getIso());
    assertEquals("BR", response.getRows().get(2).getIso());
    assertEquals("IN", response.getRows().get(1).getIso());
    assertEquals("US", response.getRows().get(0).getIso());

  }