Test Doubles & Mockito

Notebook Summary

Copy this by hand. Everything here is derived from the detailed notes below.

Detailed Study Notes

Google Maps shows Uber price estimates. To get them, it calls Uber's live pricing API and hands the numbers to users. One afternoon Uber's service starts returning null and negative prices for a handful of routes, and Google Maps crashes for those users. The team patches the code to handle the bad values — but now comes the hard part. How do you test that fix when the buggy responses are rare, live, and owned by a company that has no interest in helping you reproduce them?

You cannot call the real Uber API in a test: it is slow, it costs money, it needs the network, and you cannot force it to return the exact broken data you are guarding against. This single problem — a class you want to test depends on something you do not control — is what the entire idea of test doubles exists to solve.

1.1Why unit test at all

A unit test checks one small piece of code — usually a single class or method — in isolation from everything else. The common objection is that writing them is a tax on an already-packed schedule, and that solid code does not need them. In practice the opposite holds: tests increase development speed. They catch regressions the moment you introduce them, and they let you refactor aggressively because a green test suite tells you nothing broke.

The word "unit" is the whole tension. A unit is one class. But almost no useful class lives alone — it calls a database, a payment gateway, another team's service. If your test of GMapService secretly reaches across the internet to Uber, you are no longer unit testing; you are testing Uber, the network, and your code all at once, and any of the three can make the test fail.

1.2Fakes — a real thing, just smaller

A fake is a genuine working implementation of the dependency, but a lightweight one that lives inside your test instead of out in the world. It really does the job — it just does it locally and simply. The classic example is swapping a production database for an in-memory collection: same behavior (store, fetch), none of the network, disk, or setup cost.

For the Uber problem, a fake means building a small fakeuberapi.com that returns hand-crafted responses, including the null and negative prices you want to test against. It works, and it lets you rehearse corner cases on demand. But two problems surface immediately.

@Test
public void testGetPriceEstimates() {
    double startLat = 37.775231, startLng = -122.418075;
    double endLat   = 37.775241, endLng   = -122.518075;

    // A Fake: a real handler pointed at a lightweight fake endpoint
    UberRESTHandler externalUberService = new RealUberRESTHandler("https://fakeuberapi.com");

    GMapService gMapService = new GMapService(externalUberService);

    PriceEstimate[] actual = gMapService.getPriceEstimates(startLat, startLng, endLat, endLng);

    assertEquals(5, actual.length);
}

1.3Stubs — canned answers, no logic

A stub is an object that returns pre-configured answers when its methods are called, and does nothing else. There is no working implementation behind it — no in-memory database, no parsing, no logic. When the code under test asks the stub for price estimates, the stub simply hands back a canned list you decided on in advance (often read from a JSON file in the test's resources folder).

Stubs shine in the scenario fakes struggle with. Suppose Uber announces a new response format that ships in a month. You implement your side against the proposed format now — but there is no live service returning it yet, and editing your elaborate fake to match is costly. A stub sidesteps all of that: you just declare "when asked, return a response in the new shape," scoped to this one test.

@Test
public void testGetPriceEstimates() {
    double startLat = 37.775231, startLng = -122.418075;
    double endLat   = 37.775241, endLng   = -122.518075;

    // A Stub: no real logic, just pre-configured responses
    UberRESTHandler externalUberService = new StubUberRESTHandler();

    GMapService gMapService = new GMapService(externalUberService);

    // When getPriceEstimates() calls the stub, it returns the
    // canned response (e.g. read from a JSON file in resources).
    PriceEstimate[] actual = gMapService.getPriceEstimates(startLat, startLng, endLat, endLng);

    assertEquals(5, actual.length);
}

A stub is lighter than a fake, but you still have to hand-write a class — StubUberRESTHandler — and often a new one per test scenario. That is a lot of boilerplate for "just return this list." Which is where mocks, and Mockito, come in.

1.4Mocks — a stub that also watches

A mock is a more sophisticated stub: it still returns pre-fabricated values, but it also records every call it receives, so you can afterward verify how it was used. Was the dependency called? How many times? In what order? With what arguments? A stub answers "what did my code get back"; a mock also answers "what did my code do."

The canonical reason you need this: a method whose whole job is a side effect. Think of code that sends a confirmation email. There is no return value to assert on — success means "the email service was called exactly once with the right address." Only a mock can check that, because only a mock records the call.

Writing a mock class by hand would be even more work than a stub — it has to record calls too. So nobody does. You use a mocking framework: EasyMock, PowerMock, and most commonly Mockito. The framework generates the double, the stubbed answers, and the recording machinery for you, at runtime, in a few lines.

1.5Mockito in three verbs

Mockito's entire everyday surface is three static methods. Learn these and you can read and write the majority of mock-based tests.

@Test
public void testGetPriceEstimates() {
    double startLat = 37.775231, startLng = -122.418075;
    double endLat   = 37.775241, endLng   = -122.518075;

    List<PriceEstimate> estimateList = someListOfPriceEstimates(); // canned data

    // 1. create the mock
    UberRESTHandler externalUberServiceMock = mock(RealUberRESTHandler.class);

    GMapService gMapService = new GMapService(externalUberServiceMock);

    // 2. stub its response
    when(externalUberServiceMock.fetchEstimates(startLat, startLng, endLat, endLng)).thenReturn(estimateList);

    // 3. exercise the code under test
    PriceEstimate[] actual = gMapService.getPriceEstimates(startLat, startLng, endLat, endLng);

    // check the returned value
    assertEquals(5, actual.length);

    // 4. verify the dependency was actually called
    verify(externalUberServiceMock).fetchEstimates(startLat, startLng, endLat, endLng);
}

1.6A template for reading any mock test

Mock tests get dense fast. A reliable way to decode one — or to plan your own before writing it — is to name six things explicitly. Fill this in for any test and the structure falls out on its own.

1.7Fake vs. Stub vs. Mock, side by side

All three replace a real dependency. They differ in how much they actually do, and in whether they let you inspect how they were used.

1.8The annotation style — how Mockito is really written

The mock(Class.class) factory call is the honest, explicit way to see what is happening — but in a real Spring project you almost never write it. Mockito ships three annotations that do the same work declaratively, wired up once at the top of the test class. This is the form the take-home exercise actually uses, and the form an interviewer expects you to recognize.

@ExtendWith(MockitoExtension.class)
class ExternalUberServiceTest {

    @Mock
    private GoogleMapsHelper googleMapsHelperMock;

    @Mock
    private RestTemplate restTemplateMock;

    // built by Mockito; the two mocks above are injected into it
    @InjectMocks
    private ExternalUberService externalUberService;

    @Test
    void getPriceEstimatesValidLocationReturnsPriceEstimatesTest() {
        when(googleMapsHelperMock.isValidLocations(anyDouble(), anyDouble(), anyDouble(), anyDouble())).thenReturn(true);
        // ... exercise externalUberService.getPriceEstimates(...) and assert
    }
}

Before @InjectMocks, every test had to build the object and hand it each mock through setters — new ExternalUberService(), then setGoogleMapsHelper(mock), then setRestTemplate(mock). The annotation collapses all of that into one field declaration and does the injection before every test, through those same setters.

1.9Argument matchers & returns that depend on the input

So far every stub returned the same value no matter what. Two refinements from the exercise make stubs far more precise: argument matchers loosen or tighten which calls a stub responds to, and doAnswer lets the return value be computed from the actual arguments.

Argument matchers

Instead of hard-coding isValidLocations(37.77, ...) you can match by shape: any() matches any object, anyDouble() any double, and eq(x) pins one argument to an exact value while the others stay loose. This is also the go-to debugging move when a stub silently never fires (see §1.10).

// matches ANY four arguments
when(googleMapsHelperMock.isValidLocations(any(), any(), any(), any()))
    .thenReturn(false);

// matches any four doubles (type-aware)
when(googleMapsHelperMock.isValidLocations(anyDouble(), anyDouble(), anyDouble(), anyDouble())).thenReturn(false);

// pin the first arg exactly, leave the rest loose
when(googleMapsHelperMock.isValidLocations(eq(37.775231), anyDouble(), anyDouble(), anyDouble())).thenReturn(true);

doAnswer — compute the return from the arguments

doAnswer() lets a mock decide its answer at call time, based on the exact arguments it received. Where thenReturn(x) is a fixed sign, doAnswer is a tiny function: it hands you an InvocationOnMock, you pull the arguments off it with getArgument(i), and you return whatever those arguments imply. In the exercise this validates a latitude — return true only when it falls within −90 to +90.

Answer<Boolean> validity = new Answer<Boolean>() {
    public Boolean answer(InvocationOnMock invocation) throws Throwable {
        Double startLatitude = invocation.getArgument(0); // first arg
        return Math.abs(startLatitude) <= 90;             // valid latitude range
    }
};

// use validity when the mock's method is invoked with these arg shapes
doAnswer(validity).when(googleMapsHelperMock)
    .isValidLocations(eq(37.775231), anyDouble(), anyDouble(), anyDouble());

1.10Common Mockito pitfalls & how to debug them

Mockito is fiddly to get right, but its error messages are unusually informative — the fastest debugging habit is to actually read the exception rather than re-scan your code. Three failures come up constantly in this exercise.

1.11The Mock Design template

The exercise gives one reusable planning template — fill it in before writing a mock test and the code writes itself. It expands the six-part reading frame from §1.6 to handle multiple mocked dependencies, which real tests usually have.

Code Under Test:
Test case:

Dependency Layer/Function:
  1.
  2.

Mock Setup:
  - Function to mock:
    - Input to mock:
    - Pre-set output from mock:
  - Function to mock:
    - Input to mock:
    - Pre-set output from mock:

Test Input:
Expected Test Output:

Worked for the exercise's own test, getPriceEstimatesValidLocationReturnsPriceEstimatesTest(), it fills in like this:

Code Under Test:  ExternalUberService.getPriceEstimates()
Test case:        valid coordinates return a populated PriceEstimate[]

Dependency Layer/Function:
  1. GoogleMapsHelper.isValidLocations()  -> validates the coordinates
  2. RestTemplate.getForObject()          -> fetches the price-estimate response

Mock Setup:
  - Function to mock: googleMapsHelperMock.isValidLocations
    - Input to mock: the start/end lat & lng coordinates
    - Pre-set output from mock: true
  - Function to mock: restTemplateMock.getForObject
    - Input to mock: the built request URL
    - Pre-set output from mock: JSON read from price_estimate.json

Test Input:          valid start/end coordinates
Expected Test Output: PriceEstimate[] of length 3 with the expected fare strings

Microexercises — Build the Muscle

Reading a mock and writing one are different muscles. Do each of these before you open the walkthrough — sketch the test in an editor or on paper first. Struggling for a minute is what turns "I recognise verify()" into "I can reach for it without thinking."

Exercise 1 · Stub a slow API, verify the call

public interface WeatherApi {
    double tempCelsius(String city);   // the real impl hits the network
}

public class WeatherReporter {
    private final WeatherApi api;
    public WeatherReporter(WeatherApi api) { this.api = api; }

    public String report(String city) {
        double t = api.tempCelsius(city);
        return city + ": " + (t >= 30 ? "hot" : "mild");
    }
}

import static org.junit.jupiter.api.Assertions.assertEquals;
import static org.mockito.Mockito.*;
import org.junit.jupiter.api.Test;

class WeatherReporterTest {

    @Test
    void reportsHotWhenApiSaysHot() {
        // 1 · create the double
        WeatherApi api = mock(WeatherApi.class);

        // 2 · stub — the argument must match the real call
        when(api.tempCelsius("Dubai")).thenReturn(41.0);

        // 3 · exercise the REAL class under test
        WeatherReporter reporter = new WeatherReporter(api);
        String result = reporter.report("Dubai");

        // 4 · assert state + verify behavior
        assertEquals("Dubai: hot", result);
        verify(api).tempCelsius("Dubai");
        verifyNoMoreInteractions(api);   // optional: nothing else was touched
    }
}

Exercise 2 · The test that passes-but-proves-nothing (diagnose & fix)

public class Greeter {
    private final UserRepo repo;
    public Greeter(UserRepo repo) { this.repo = repo; }
    public String greet(long id) {
        return "Hi, " + repo.findById(id).name();
    }
}

@Test
void greetsUser() {
    UserRepo repo = mock(UserRepo.class);
    when(repo.findById(1L)).thenReturn(new User("Trinity"));

    Greeter greeter = new Greeter(repo);
    String msg = greeter.greet(2L);          // ← asks for id 2

    assertEquals("Hi, Trinity", msg);
}

@Test
void greetsUser() {
    UserRepo repo = mock(UserRepo.class);
    when(repo.findById(1L)).thenReturn(new User("Trinity"));

    Greeter greeter = new Greeter(repo);
    String msg = greeter.greet(1L);          // ← now matches the stub

    assertEquals("Hi, Trinity", msg);
    verify(repo).findById(1L);
}