Java Academy · Lesson

Mockito Advanced: Argument Captors and Spies

Capture method arguments with ArgumentCaptor and partially mock real objects with Mockito.spy.

Lesson 2 of 413 steps

Mockito Advanced: Argument Captors and Spies is a free Java Academy lesson on CoddyKit. This is lesson 2 of 4. You can read the complete lesson below for free — then practise it hands-on in the browser with a built-in code editor and a 24/7 AI tutor. It is part of the Java Academy learning path, and your progress syncs across the web and the CoddyKit app. The Java Academy course includes 4 lessons in total.

ArgumentCaptor: Capturing Method Arguments

ArgumentCaptor captures the arguments passed to a mocked method so you can assert on them. Useful when the argument is built inside the system under test and you cannot access it directly.

Creating and Using ArgumentCaptor

Create a captor for the argument type, pass captor.capture() as the argument matcher in verify(), then call captor.getValue() to get the captured argument.

@Test
void sends_correct_email() {
    ArgumentCaptor<EmailMessage> captor = ArgumentCaptor.forClass(EmailMessage.class);
    userService.register(new CreateUserRequest("alice@example.com"));
    verify(emailService).send(captor.capture());
    EmailMessage msg = captor.getValue();
    assertEquals("alice@example.com", msg.getTo());
    assertTrue(msg.getSubject().contains("Welcome"));
}

@Captor Annotation

Use @Captor with @ExtendWith(MockitoExtension.class) to avoid verbose ArgumentCaptor.forClass() calls.

@ExtendWith(MockitoExtension.class)
class UserServiceTest {
    @Mock EmailService emailService;
    @Captor ArgumentCaptor<EmailMessage> emailCaptor;
    @Test
    void captures_email() {
        // ...
        verify(emailService).send(emailCaptor.capture());
        assertEquals("Welcome!", emailCaptor.getValue().getSubject());
    }
}

Capturing Multiple Calls

Use captor.getAllValues() when the method is called multiple times. Returns a list of all captured values in call order.

verify(emailService, times(3)).send(emailCaptor.capture());
List<EmailMessage> messages = emailCaptor.getAllValues();
assertEquals(3, messages.size());
assertEquals("Confirmation", messages.get(0).getSubject());

Mockito Spies: Partial Mocking

Mockito.spy() wraps a real object. All methods behave normally unless you explicitly stub them. Use when you need to test a class that has some hard-to-test dependencies but mostly works.

List<String> realList = new ArrayList<>();
List<String> spy = Mockito.spy(realList);
spy.add("hello"); // calls real ArrayList.add()
System.out.println(spy.size()); // 1 — real method called
doReturn(42).when(spy).size(); // stub just size()
System.out.println(spy.size()); // 42 — stubbed

@Spy Annotation

Use @Spy with @ExtendWith(MockitoExtension.class) to create spies. The field must be initialized (either inline or via @Spy UserService svc = new UserService(repo);).

@ExtendWith(MockitoExtension.class)
class OrderServiceTest {
    @Spy
    OrderService orderService = new OrderService(mockRepo, mockEmail);
}

Spying on Spring Beans with @SpyBean

In Spring Boot tests, @SpyBean wraps an existing Spring bean in a Mockito spy — real behavior unless stubbed. Pairs with @SpringBootTest.

@SpringBootTest
class IntegrationTest {
    @SpyBean EmailService emailService;
    @Test
    void order_sends_email() {
        orderService.placeOrder(cart);
        verify(emailService).sendConfirmation(any());
    }
}

doReturn vs when().thenReturn() for Spies

For spies, use doReturn(value).when(spy).method() instead of when(spy.method()).thenReturn(value). The when(spy.method()) form actually calls the real method, which may cause side effects.

// Correct for spies:
doReturn(List.of()).when(spy).findAll();
// WRONG for spies — calls real findAll() first:
when(spy.findAll()).thenReturn(List.of()); // real method called!

Verifying No Interactions

Use verifyNoInteractions(mock) to assert a mock was never called, and verifyNoMoreInteractions(mock) after all expected calls to catch unexpected ones.

verifyNoInteractions(emailService); // never called
verify(repo).save(any());
verifyNoMoreInteractions(repo); // save() was the only interaction

InOrder Verification

Use InOrder to assert that mocked methods were called in a specific order.

InOrder inOrder = inOrder(repo, emailService);
inOrder.verify(repo).save(any());
inOrder.verify(emailService).send(any()); // save happened BEFORE send

Argument Matchers

Combine captors with matchers: any(), eq(), anyString(), argThat(predicate). If any argument uses a matcher, all must use matchers.

verify(repo).save(argThat(user ->
    user.getEmail().endsWith("@example.com") &&
    user.getStatus() == UserStatus.ACTIVE));

Quick Check

Why use doReturn instead of when().thenReturn() when stubbing a spy?

Answer it in the interactive lesson

Recap

ArgumentCaptor captures arguments for assertion after the call. Spies wrap real objects and delegate unless stubbed. Use doReturn for spies. @SpyBean for Spring integration tests. Verify call order with InOrder.

Free to start

Learn Java with an AI tutor — free

Write and run real code in your browser, get instant help from a 24/7 AI tutor, and pick up where you left off on the web or in the app.

Courses: 104
Lessons: 374

Start learning free View the full course

Frequently Asked Questions

Is the “Mockito Advanced: Argument Captors and Spies” lesson free?

Yes — the full text of “Mockito Advanced: Argument Captors and Spies” is free to read here on the web. To practise it interactively (a built-in code editor and a 24/7 AI tutor) and unlock the rest of the Java Academy course, upgrade to CoddyKit PRO. The Java Academy course includes 4 lessons in total.

What will I learn in “Mockito Advanced: Argument Captors and Spies”?

Capture method arguments with ArgumentCaptor and partially mock real objects with Mockito.spy. You practise Java Academy with hands-on code you run directly in the browser, and a 24/7 AI tutor answers your questions as you work through the lesson.

Do I need any experience to start Java Academy?

No prior experience is required. Java Academy on CoddyKit is structured for beginners through advanced learners, so you can start here or from the beginning and move at your own pace. This is lesson 2 of 4.

How long does the “Mockito Advanced: Argument Captors and Spies” lesson take?

Most CoddyKit lessons take about 5–10 minutes. Each one is bite-sized and interactive, so you make steady progress and pick up exactly where you left off across the web and the app.

Can I write and run code in this Java Academy lesson?

Yes. Every Java Academy lesson includes a built-in code editor, so you write and run real code right in your browser and get instant AI feedback — no local setup required.

All lessons in this course

Parameterized Tests with @CsvSource and @MethodSource
Mockito Advanced: Argument Captors and Spies
Spring Boot Test Slices: @WebMvcTest and @DataJpaTest
Testcontainers: Real Database Integration Tests

← Back to Java Academy