Argument captors in JUnit

Introduction

Argument captors help you catch and check the values passed to methods during tests. This lets you make sure your code sends the right data to other parts.

You want to check what exact value a method received when called.

You need to verify that a method was called with correct arguments.

You want to test side effects by capturing arguments passed to mocks.

You want to assert on complex objects passed to methods.

You want to debug what data your code sends to collaborators.

Syntax

JUnit

ArgumentCaptor<Type> captor = ArgumentCaptor.forClass(Type.class);
verify(mockObject).methodName(captor.capture());
Type capturedValue = captor.getValue();

Replace Type with the class of the argument you want to capture.

Use captor.getValue() to get the single captured argument or captor.getAllValues() for multiple calls.

Examples

Capture a String argument passed to sendMessage and check it equals "Hello".

JUnit

ArgumentCaptor<String> captor = ArgumentCaptor.forClass(String.class);
verify(mock).sendMessage(captor.capture());
String message = captor.getValue();
assertEquals("Hello", message);

Capture a User object passed to addUser and check the user's name.

JUnit

ArgumentCaptor<User> captor = ArgumentCaptor.forClass(User.class);
verify(userService).addUser(captor.capture());
User user = captor.getValue();
assertEquals("Alice", user.getName());

Sample Program

This test checks that when welcomeUser is called with "Bob", the notifyUser method receives the message "Welcome, Bob!".

JUnit

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

class NotificationService {
    void notifyUser(String message) {
        // sends notification
    }
}

class UserController {
    private NotificationService notificationService;
    UserController(NotificationService notificationService) {
        this.notificationService = notificationService;
    }
    void welcomeUser(String username) {
        String message = "Welcome, " + username + "!";
        notificationService.notifyUser(message);
    }
}

public class ArgumentCaptorTest {
    @Test
    void testWelcomeUserSendsCorrectMessage() {
        NotificationService mockNotification = mock(NotificationService.class);
        UserController controller = new UserController(mockNotification);

        controller.welcomeUser("Bob");

        ArgumentCaptor<String> captor = ArgumentCaptor.forClass(String.class);
        verify(mockNotification).notifyUser(captor.capture());

        String capturedMessage = captor.getValue();
        assertEquals("Welcome, Bob!", capturedMessage);
    }
}

Important Notes

Argument captors work only with mocks created by Mockito.

Use captor.getAllValues() if the method is called multiple times and you want all arguments.

Always verify the method call before capturing arguments to avoid errors.

Summary

Argument captors let you catch and check method arguments in tests.

They help verify that your code sends the right data to other parts.

Use them with Mockito mocks and verify() calls.

Practice

1. What is the main purpose of using an ArgumentCaptor in JUnit tests with Mockito?

easy

A. To capture and inspect the arguments passed to a mocked method

B. To create a mock object for testing

C. To verify the number of times a method was called

D. To stub the return value of a method

Solution

1. Step 1: Understand ArgumentCaptor role

   An ArgumentCaptor is used to catch the actual arguments passed to a mock's method during test execution.

2. Step 2: Differentiate from other Mockito features

   Unlike mocks or verify count, ArgumentCaptor focuses on capturing and inspecting method arguments.

3. Final Answer:

   To capture and inspect the arguments passed to a mocked method -> Option A

4. Quick Check:

   ArgumentCaptor captures arguments [OK]

Hint: ArgumentCaptor catches method inputs for checking [OK]

Common Mistakes:

• Confusing ArgumentCaptor with mock creation
• Thinking it counts method calls
• Assuming it stubs return values

2. Which of the following is the correct way to declare an ArgumentCaptor for a String argument in JUnit with Mockito?

easy

A. ArgumentCaptor<String> captor = ArgumentCaptor.forClass(String.class);

B. ArgumentCaptor captor = new ArgumentCaptor<String>();

C. ArgumentCaptor<String> captor = new ArgumentCaptor<>();

D. ArgumentCaptor<String> captor = ArgumentCaptor.capture(String.class);

Solution

1. Step 1: Recall ArgumentCaptor creation syntax

   The correct way is to use the static method forClass() with the class type.

2. Step 2: Check each option for syntax correctness

   ArgumentCaptor<String> captor = ArgumentCaptor.forClass(String.class); uses ArgumentCaptor.forClass(String.class), which is correct. Options B and C incorrectly use constructors, which are not public. ArgumentCaptor<String> captor = ArgumentCaptor.capture(String.class); uses a non-existent method capture() for creation.

3. Final Answer:

   ArgumentCaptor<String> captor = ArgumentCaptor.forClass(String.class); -> Option A

4. Quick Check:

   Use forClass() to create captor [OK]

Hint: Use ArgumentCaptor.forClass(Type.class) to declare captor [OK]

Common Mistakes:

• Trying to instantiate ArgumentCaptor with new
• Using non-existent capture() method
• Omitting the class type in forClass()

3. Given the following code snippet, what will be the captured argument value?

List<String> list = mock(List.class);
ArgumentCaptor<String> captor = ArgumentCaptor.forClass(String.class);
list.add("hello");
verify(list).add(captor.capture());
String captured = captor.getValue();

medium

A. null

B. "hello"

C. "captor"

D. Throws an exception

Solution

1. Step 1: Understand the mock and method call

   The mock list has add("hello") called, so "hello" is passed as argument.

2. Step 2: Verify and capture argument

   The verify(list).add(captor.capture()) captures the argument passed to add(), which is "hello".

3. Final Answer:

   "hello" -> Option B

4. Quick Check:

   Captured argument matches method call input [OK]

Hint: Captured value equals argument passed to mock method [OK]

Common Mistakes:

• Assuming captor captures method name
• Expecting null if not stubbed
• Thinking it throws exception without stubbing

4. Identify the error in the following test code using ArgumentCaptor:

ArgumentCaptor<Integer> captor = ArgumentCaptor.forClass(Integer.class);
verify(mockedList).add(captor.capture());
mockedList.add(5);
Integer value = captor.getValue();

medium

A. ArgumentCaptor should be declared after method call

B. No error, code is correct

C. Captor must be reset before use

D. The verify call is before the actual method call

Solution

1. Step 1: Analyze order of method call and verify

   The verify() call must come after the actual method call to check interactions.

2. Step 2: Identify the mistake

   Here, verify() is called before mockedList.add(5), so no interaction is recorded yet.

3. Final Answer:

   The verify call is before the actual method call -> Option D

4. Quick Check:

   Verify after method call [OK]

Hint: Always call verify() after the method under test [OK]

Common Mistakes:

• Calling verify before method invocation
• Assuming captor resets automatically
• Declaring captor after verify

5. You want to verify that a mocked service method was called twice with different String arguments, and capture both arguments for assertions. Which approach correctly uses ArgumentCaptor to achieve this?

hard

A. Use ArgumentCaptor only once; it cannot capture multiple calls

B. Create two separate ArgumentCaptors and verify each call separately

C. Use a single ArgumentCaptor and call getAllValues() after verifying two calls

D. Capture arguments by stubbing the method instead of verify

Solution

1. Step 1: Understand multiple call verification with ArgumentCaptor

   A single ArgumentCaptor can capture all arguments from multiple calls using getAllValues().

2. Step 2: Evaluate options for capturing multiple arguments

   Use a single ArgumentCaptor and call getAllValues() after verifying two calls correctly uses one captor and retrieves all captured arguments. Create two separate ArgumentCaptors and verify each call separately is unnecessary and verbose. Use ArgumentCaptor only once; it cannot capture multiple calls is false; captor supports multiple captures. Capture arguments by stubbing the method instead of verify is incorrect because stubbing does not capture arguments.

3. Final Answer:

   Use a single ArgumentCaptor and call getAllValues() after verifying two calls -> Option C

4. Quick Check:

   Single captor + getAllValues() captures multiple calls [OK]

Hint: Use getAllValues() on one captor for multiple calls [OK]

Common Mistakes:

• Creating multiple captors unnecessarily
• Thinking captor captures only one call
• Trying to capture arguments via stubbing