Argument Captors in Mockito in Java

Table of Contents

Overview

ArgumentCaptor is a Mockito feature that allows you to capture argument values passed to mocked methods for further verification and analysis. It's particularly useful when you need to verify complex objects or perform multiple assertions on method arguments.

Basic Usage

1. Simple Argument Captor

import org.mockito.ArgumentCaptor;
import org.mockito.Mock;
import org.mockito.MockitoAnnotations;
import org.junit.jupiter.api.BeforeEach;
import org.junit.jupiter.api.Test;
import java.util.List;
import static org.mockito.Mockito.*;
import static org.junit.jupiter.api.Assertions.*;
public class BasicArgumentCaptorTest {
@Mock
private List<String> mockedList;
@BeforeEach
void setUp() {
MockitoAnnotations.openMocks(this);
}
@Test
void testBasicArgumentCaptor() {
// Create ArgumentCaptor for String
ArgumentCaptor<String> argumentCaptor = ArgumentCaptor.forClass(String.class);
// Perform some operations on the mock
mockedList.add("hello");
mockedList.add("world");
// Verify and capture arguments
verify(mockedList, times(2)).add(argumentCaptor.capture());
// Get all captured values
List<String> allValues = argumentCaptor.getAllValues();
assertEquals(2, allValues.size());
assertEquals("hello", allValues.get(0));
assertEquals("world", allValues.get(1));
}
@Test
void testSingleValueCapture() {
ArgumentCaptor<String> captor = ArgumentCaptor.forClass(String.class);
mockedList.add("single value");
verify(mockedList).add(captor.capture());
String capturedValue = captor.getValue();
assertEquals("single value", capturedValue);
}
}

2. Capturing Multiple Arguments

import java.util.Map;
public class MultipleArgumentsTest {
@Mock
private Map<String, Integer> mockedMap;
@Test
void testCapturingMultipleMethodCalls() {
ArgumentCaptor<String> keyCaptor = ArgumentCaptor.forClass(String.class);
ArgumentCaptor<Integer> valueCaptor = ArgumentCaptor.forClass(Integer.class);
// Perform operations
mockedMap.put("key1", 100);
mockedMap.put("key2", 200);
mockedMap.put("key3", 300);
// Verify and capture
verify(mockedMap, times(3)).put(keyCaptor.capture(), valueCaptor.capture());
// Get all captured values
List<String> keys = keyCaptor.getAllValues();
List<Integer> values = valueCaptor.getAllValues();
assertEquals(3, keys.size());
assertEquals(3, values.size());
assertEquals("key1", keys.get(0));
assertEquals(100, values.get(0));
assertEquals("key3", keys.get(2));
assertEquals(300, values.get(2));
}
}

Advanced Usage

1. Capturing Complex Objects

public class ComplexObjectCaptureTest {
// Complex domain objects
public static class User {
private String username;
private String email;
private int age;
public User(String username, String email, int age) {
this.username = username;
this.email = email;
this.age = age;
}
// Getters and setters
public String getUsername() { return username; }
public String getEmail() { return email; }
public int getAge() { return age; }
}
public static class UserService {
private final UserRepository userRepository;
public UserService(UserRepository userRepository) {
this.userRepository = userRepository;
}
public void createUser(String username, String email, int age) {
User user = new User(username, email, age);
userRepository.save(user);
}
public void updateUserEmail(String username, String newEmail) {
User user = userRepository.findByUsername(username);
if (user != null) {
User updatedUser = new User(user.getUsername(), newEmail, user.getAge());
userRepository.save(updatedUser);
}
}
}
public interface UserRepository {
void save(User user);
User findByUsername(String username);
}
@Mock
private UserRepository userRepository;
private UserService userService;
@BeforeEach
void setUp() {
MockitoAnnotations.openMocks(this);
userService = new UserService(userRepository);
}
@Test
void testCapturingComplexObject() {
ArgumentCaptor<User> userCaptor = ArgumentCaptor.forClass(User.class);
userService.createUser("john_doe", "[email protected]", 30);
verify(userRepository).save(userCaptor.capture());
User capturedUser = userCaptor.getValue();
assertEquals("john_doe", capturedUser.getUsername());
assertEquals("[email protected]", capturedUser.getEmail());
assertEquals(30, capturedUser.getAge());
}
@Test
void testCapturingMultipleComplexObjects() {
ArgumentCaptor<User> userCaptor = ArgumentCaptor.forClass(User.class);
// Setup mock behavior
when(userRepository.findByUsername("jane_doe"))
.thenReturn(new User("jane_doe", "[email protected]", 25));
userService.updateUserEmail("jane_doe", "[email protected]");
verify(userRepository).save(userCaptor.capture());
User capturedUser = userCaptor.getValue();
assertEquals("jane_doe", capturedUser.getUsername());
assertEquals("[email protected]", capturedUser.getEmail());
assertEquals(25, capturedUser.getAge());
}
}

2. Capturing with Custom Matchers

public class CaptorWithMatchersTest {
@Mock
private NotificationService notificationService;
@Test
void testCaptorWithAdditionalVerification() {
ArgumentCaptor<String> messageCaptor = ArgumentCaptor.forClass(String.class);
ArgumentCaptor<String> recipientCaptor = ArgumentCaptor.forClass(String.class);
notificationService.sendNotification("Hello, User!", "[email protected]");
notificationService.sendNotification("Important update!", "[email protected]");
// Verify with captor and additional conditions
verify(notificationService, times(2))
.sendNotification(messageCaptor.capture(), recipientCaptor.capture());
List<String> messages = messageCaptor.getAllValues();
List<String> recipients = recipientCaptor.getAllValues();
// Additional assertions
assertTrue(messages.get(0).contains("Hello"));
assertTrue(recipients.get(1).contains("admin"));
// Verify specific conditions
assertEquals("[email protected]", recipients.get(0));
assertEquals("Important update!", messages.get(1));
}
}
interface NotificationService {
void sendNotification(String message, String recipient);
}

Practical Examples

Example 1: Email Service Testing

public class EmailServiceTest {
public static class Email {
private final String to;
private final String subject;
private final String body;
private final List<String> cc;
public Email(String to, String subject, String body, List<String> cc) {
this.to = to;
this.subject = subject;
this.body = body;
this.cc = cc != null ? new ArrayList<>(cc) : new ArrayList<>();
}
// Getters
public String getTo() { return to; }
public String getSubject() { return subject; }
public String getBody() { return body; }
public List<String> getCc() { return Collections.unmodifiableList(cc); }
}
public interface EmailSender {
void sendEmail(Email email);
void sendBulkEmails(List<Email> emails);
}
public static class EmailService {
private final EmailSender emailSender;
private final List<Email> sentEmails = new ArrayList<>();
public EmailService(EmailSender emailSender) {
this.emailSender = emailSender;
}
public void sendWelcomeEmail(String to, String username) {
String subject = "Welcome to Our Service!";
String body = String.format("Hello %s, welcome to our service!", username);
Email email = new Email(to, subject, body, null);
emailSender.sendEmail(email);
sentEmails.add(email);
}
public void sendBulkNotification(List<String> recipients, String message) {
List<Email> emails = recipients.stream()
.map(recipient -> new Email(recipient, "Notification", message, null))
.collect(Collectors.toList());
emailSender.sendBulkEmails(emails);
sentEmails.addAll(emails);
}
}
@Mock
private EmailSender emailSender;
private EmailService emailService;
@BeforeEach
void setUp() {
MockitoAnnotations.openMocks(this);
emailService = new EmailService(emailSender);
}
@Test
void testWelcomeEmailContent() {
ArgumentCaptor<Email> emailCaptor = ArgumentCaptor.forClass(Email.class);
emailService.sendWelcomeEmail("[email protected]", "John Doe");
verify(emailSender).sendEmail(emailCaptor.capture());
Email capturedEmail = emailCaptor.getValue();
assertEquals("[email protected]", capturedEmail.getTo());
assertEquals("Welcome to Our Service!", capturedEmail.getSubject());
assertTrue(capturedEmail.getBody().contains("John Doe"));
assertTrue(capturedEmail.getBody().contains("welcome to our service"));
}
@Test
void testBulkEmailSending() {
ArgumentCaptor<List<Email>> emailsCaptor = ArgumentCaptor.forClass(List.class);
List<String> recipients = Arrays.asList(
"[email protected]",
"[email protected]",
"[email protected]"
);
String message = "System maintenance scheduled";
emailService.sendBulkNotification(recipients, message);
verify(emailSender).sendBulkEmails(emailsCaptor.capture());
List<Email> capturedEmails = emailsCaptor.getValue();
assertEquals(3, capturedEmails.size());
// Verify each email
for (int i = 0; i < recipients.size(); i++) {
Email email = capturedEmails.get(i);
assertEquals(recipients.get(i), email.getTo());
assertEquals("Notification", email.getSubject());
assertEquals(message, email.getBody());
}
}
}

Example 2: Order Processing System

public class OrderProcessingTest {
public static class Order {
private String orderId;
private String customerId;
private List<OrderItem> items;
private double totalAmount;
private OrderStatus status;
public Order(String orderId, String customerId, List<OrderItem> items) {
this.orderId = orderId;
this.customerId = customerId;
this.items = new ArrayList<>(items);
this.totalAmount = calculateTotalAmount();
this.status = OrderStatus.PENDING;
}
private double calculateTotalAmount() {
return items.stream()
.mapToDouble(item -> item.getPrice() * item.getQuantity())
.sum();
}
// Getters and setters
public String getOrderId() { return orderId; }
public String getCustomerId() { return customerId; }
public List<OrderItem> getItems() { return Collections.unmodifiableList(items); }
public double getTotalAmount() { return totalAmount; }
public OrderStatus getStatus() { return status; }
public void setStatus(OrderStatus status) { this.status = status; }
}
public static class OrderItem {
private String productId;
private String productName;
private int quantity;
private double price;
public OrderItem(String productId, String productName, int quantity, double price) {
this.productId = productId;
this.productName = productName;
this.quantity = quantity;
this.price = price;
}
// Getters
public String getProductId() { return productId; }
public String getProductName() { return productName; }
public int getQuantity() { return quantity; }
public double getPrice() { return price; }
}
public enum OrderStatus {
PENDING, PROCESSING, COMPLETED, CANCELLED
}
public interface OrderRepository {
void save(Order order);
Order findById(String orderId);
void updateStatus(String orderId, OrderStatus status);
}
public interface PaymentService {
boolean processPayment(String orderId, double amount, String customerId);
}
public interface InventoryService {
boolean reserveItems(String orderId, List<OrderItem> items);
void releaseItems(String orderId);
}
public static class OrderProcessor {
private final OrderRepository orderRepository;
private final PaymentService paymentService;
private final InventoryService inventoryService;
public OrderProcessor(OrderRepository orderRepository, 
PaymentService paymentService, 
InventoryService inventoryService) {
this.orderRepository = orderRepository;
this.paymentService = paymentService;
this.inventoryService = inventoryService;
}
public boolean processOrder(Order order) {
try {
// Save initial order
orderRepository.save(order);
// Process payment
boolean paymentSuccess = paymentService.processPayment(
order.getOrderId(), 
order.getTotalAmount(), 
order.getCustomerId()
);
if (!paymentSuccess) {
order.setStatus(OrderStatus.CANCELLED);
orderRepository.save(order);
return false;
}
// Reserve inventory
boolean inventoryReserved = inventoryService.reserveItems(
order.getOrderId(),
order.getItems()
);
if (!inventoryReserved) {
// Refund payment if inventory not available
// (simplified - in real scenario, you'd call payment service to refund)
order.setStatus(OrderStatus.CANCELLED);
orderRepository.save(order);
return false;
}
// Mark order as completed
order.setStatus(OrderStatus.COMPLETED);
orderRepository.save(order);
return true;
} catch (Exception e) {
order.setStatus(OrderStatus.CANCELLED);
orderRepository.save(order);
return false;
}
}
}
@Mock
private OrderRepository orderRepository;
@Mock
private PaymentService paymentService;
@Mock
private InventoryService inventoryService;
private OrderProcessor orderProcessor;
@BeforeEach
void setUp() {
MockitoAnnotations.openMocks(this);
orderProcessor = new OrderProcessor(orderRepository, paymentService, inventoryService);
}
@Test
void testSuccessfulOrderProcessing() {
// Setup test data
List<OrderItem> items = Arrays.asList(
new OrderItem("prod1", "Product 1", 2, 25.0),
new OrderItem("prod2", "Product 2", 1, 50.0)
);
Order order = new Order("order123", "customer456", items);
// Setup mock behavior
when(paymentService.processPayment(anyString(), anyDouble(), anyString()))
.thenReturn(true);
when(inventoryService.reserveItems(anyString(), anyList()))
.thenReturn(true);
// Execute
boolean result = orderProcessor.processOrder(order);
// Verify
assertTrue(result);
// Capture and verify order saves
ArgumentCaptor<Order> orderCaptor = ArgumentCaptor.forClass(Order.class);
verify(orderRepository, times(3)).save(orderCaptor.capture());
List<Order> savedOrders = orderCaptor.getAllValues();
// First save - initial order
assertEquals(OrderStatus.PENDING, savedOrders.get(0).getStatus());
// Last save - completed order
assertEquals(OrderStatus.COMPLETED, savedOrders.get(2).getStatus());
assertEquals("order123", savedOrders.get(2).getOrderId());
}
@Test
void testOrderProcessingWithPaymentFailure() {
List<OrderItem> items = Arrays.asList(
new OrderItem("prod1", "Product 1", 1, 100.0)
);
Order order = new Order("order456", "customer789", items);
// Payment fails
when(paymentService.processPayment(anyString(), anyDouble(), anyString()))
.thenReturn(false);
boolean result = orderProcessor.processOrder(order);
assertFalse(result);
// Capture order saves and verify cancellation
ArgumentCaptor<Order> orderCaptor = ArgumentCaptor.forClass(Order.class);
verify(orderRepository, times(2)).save(orderCaptor.capture());
List<Order> savedOrders = orderCaptor.getAllValues();
assertEquals(OrderStatus.CANCELLED, savedOrders.get(1).getStatus());
// Verify inventory service was NOT called
verify(inventoryService, never()).reserveItems(anyString(), anyList());
}
@Test
void testInventoryReservationParameters() {
List<OrderItem> items = Arrays.asList(
new OrderItem("prod1", "Product 1", 2, 25.0),
new OrderItem("prod2", "Product 2", 1, 50.0)
);
Order order = new Order("order789", "customer123", items);
when(paymentService.processPayment(anyString(), anyDouble(), anyString()))
.thenReturn(true);
when(inventoryService.reserveItems(anyString(), anyList()))
.thenReturn(true);
orderProcessor.processOrder(order);
// Capture inventory reservation call
ArgumentCaptor<String> orderIdCaptor = ArgumentCaptor.forClass(String.class);
ArgumentCaptor<List<OrderItem>> itemsCaptor = ArgumentCaptor.forClass(List.class);
verify(inventoryService).reserveItems(orderIdCaptor.capture(), itemsCaptor.capture());
assertEquals("order789", orderIdCaptor.getValue());
List<OrderItem> capturedItems = itemsCaptor.getValue();
assertEquals(2, capturedItems.size());
// Verify items are correctly passed
OrderItem firstItem = capturedItems.get(0);
assertEquals("prod1", firstItem.getProductId());
assertEquals(2, firstItem.getQuantity());
assertEquals(25.0, firstItem.getPrice(), 0.001);
}
}

Advanced Techniques

1. Captoring with Verification Mode

public class AdvancedCaptorTechniques {
@Mock
private DataService dataService;
@Test
void testCaptorWithVerificationMode() {
ArgumentCaptor<String> queryCaptor = ArgumentCaptor.forClass(String.class);
dataService.executeQuery("SELECT * FROM users");
dataService.executeQuery("SELECT * FROM orders");
dataService.executeQuery("SELECT * FROM products");
// Verify with specific verification mode
verify(dataService, atLeast(2)).executeQuery(queryCaptor.capture());
verify(dataService, atMost(5)).executeQuery(queryCaptor.capture());
List<String> allQueries = queryCaptor.getAllValues();
assertTrue(allQueries.size() >= 2);
}
@Test
void testCaptorWithTimeout() {
ArgumentCaptor<String> captor = ArgumentCaptor.forClass(String.class);
// Simulate async operation
new Thread(() -> {
try {
Thread.sleep(100);
dataService.executeQuery("async query");
} catch (InterruptedException e) {
Thread.currentThread().interrupt();
}
}).start();
// Verify with timeout
verify(dataService, timeout(500)).executeQuery(captor.capture());
assertEquals("async query", captor.getValue());
}
}
interface DataService {
void executeQuery(String query);
}

2. Generic Argument Captor

public class GenericCaptorTest {
public static class Response<T> {
private T data;
private boolean success;
public Response(T data, boolean success) {
this.data = data;
this.success = success;
}
public T getData() { return data; }
public boolean isSuccess() { return success; }
}
public interface ApiClient {
<T> Response<T> post(String endpoint, T data);
<T> Response<T> get(String endpoint, Class<T> responseType);
}
@Mock
private ApiClient apiClient;
@Test
void testGenericArgumentCaptor() {
// For generic types, use ArgumentCaptor with wildcard
@SuppressWarnings("unchecked")
ArgumentCaptor<Object> dataCaptor = ArgumentCaptor.forClass(Object.class);
ArgumentCaptor<String> endpointCaptor = ArgumentCaptor.forClass(String.class);
User user = new User("testuser", "[email protected]", 25);
apiClient.post("/users", user);
verify(apiClient).post(endpointCaptor.capture(), dataCaptor.capture());
assertEquals("/users", endpointCaptor.getValue());
User capturedUser = (User) dataCaptor.getValue();
assertEquals("testuser", capturedUser.getUsername());
assertEquals("[email protected]", capturedUser.getEmail());
}
@Test
void testSpecificGenericCaptor() {
// For specific generic types, use @Captor annotation with wildcard
@Captor
private ArgumentCaptor<User> userCaptor;
User user = new User("specific", "[email protected]", 30);
apiClient.post("/users", user);
verify(apiClient).post(anyString(), userCaptor.capture());
User captured = userCaptor.getValue();
assertEquals("specific", captured.getUsername());
}
}

3. Captoring in Ordered Verification

public class OrderedVerificationTest {
@Mock
private AuditService auditService;
@Test
void testCaptorWithInOrder() {
ArgumentCaptor<String> actionCaptor = ArgumentCaptor.forClass(String.class);
ArgumentCaptor<String> userCaptor = ArgumentCaptor.forClass(String.class);
auditService.logAction("LOGIN", "user1");
auditService.logAction("VIEW_PAGE", "user1");
auditService.logAction("LOGOUT", "user1");
// Create in-order verification
InOrder inOrder = inOrder(auditService);
inOrder.verify(auditService).logAction(actionCaptor.capture(), userCaptor.capture());
inOrder.verify(auditService).logAction(actionCaptor.capture(), userCaptor.capture());
inOrder.verify(auditService).logAction(actionCaptor.capture(), userCaptor.capture());
List<String> actions = actionCaptor.getAllValues();
List<String> users = userCaptor.getAllValues();
assertEquals("LOGIN", actions.get(0));
assertEquals("VIEW_PAGE", actions.get(1));
assertEquals("LOGOUT", actions.get(2));
assertEquals("user1", users.get(0));
}
}
interface AuditService {
void logAction(String action, String username);
}

Best Practices

1. Proper Captor Usage

public class ArgumentCaptorBestPractices {
@Mock
private Service service;
@Captor
private ArgumentCaptor<String> stringCaptor;
@Captor
private ArgumentCaptor<Integer> integerCaptor;
@BeforeEach
void setUp() {
MockitoAnnotations.openMocks(this);
}
@Test
void goodPractice_useCaptorAnnotation() {
// Good: Use @Captor annotation for cleaner code
service.process("data", 42);
verify(service).process(stringCaptor.capture(), integerCaptor.capture());
assertEquals("data", stringCaptor.getValue());
assertEquals(42, integerCaptor.getValue());
}
@Test
void goodPractice_captureAtVerificationTime() {
// Good: Capture at the time of verification
service.process("value1", 1);
service.process("value2", 2);
verify(service, times(2)).process(stringCaptor.capture(), integerCaptor.capture());
List<String> strings = stringCaptor.getAllValues();
List<Integer> integers = integerCaptor.getAllValues();
assertEquals(2, strings.size());
assertEquals(2, integers.size());
}
@Test
void badPractice_dontOveruseCaptors() {
// Bad: Don't use captors when simple verification suffices
service.process("simple", 123);
// Instead of using captor for simple equality check:
// verify(service).process(stringCaptor.capture(), integerCaptor.capture());
// assertEquals("simple", stringCaptor.getValue());
// Better: Use direct argument matchers
verify(service).process(eq("simple"), eq(123));
}
@Test
void goodPractice_combineWithOtherMatchers() {
// Good: Combine captors with other matchers when needed
service.process("important", 999);
service.process("other", 111);
// Capture only calls with specific first argument
verify(service).process(eq("important"), integerCaptor.capture());
assertEquals(999, integerCaptor.getValue());
}
}
interface Service {
void process(String data, int value);
}

Common Pitfalls and Solutions

public class CommonPitfalls {
@Mock
private Repository repository;
@Test
void pitfall_captorReuse() {
ArgumentCaptor<String> captor = ArgumentCaptor.forClass(String.class);
repository.save("first");
verify(repository).save(captor.capture());
assertEquals("first", captor.getValue());
// Pitfall: Reusing the same captor
repository.save("second");
verify(repository, times(2)).save(captor.capture());
// Solution: Be aware that getAllValues contains all captured values
List<String> allValues = captor.getAllValues();
assertEquals(2, allValues.size());
assertEquals("first", allValues.get(0));
assertEquals("second", allValues.get(1));
}
@Test
void pitfall_captorNotUsedInVerification() {
ArgumentCaptor<String> captor = ArgumentCaptor.forClass(String.class);
repository.save("data");
// Pitfall: Captor created but not used in verification
// verify(repository).save("data"); // This doesn't use the captor
// Solution: Use captor in verification
verify(repository).save(captor.capture());
assertEquals("data", captor.getValue());
}
@Test
void solution_resetCaptorBetweenTests() {
// Solution: Create new captor for each test or use @Captor annotation
ArgumentCaptor<String> captor = ArgumentCaptor.forClass(String.class);
repository.save("test");
verify(repository).save(captor.capture());
// Captor is local to test, so no need to reset
}
}
interface Repository {
void save(String data);
}

ArgumentCaptor is a powerful tool for testing complex interactions with mocks. Use it when you need to verify the state of arguments passed to mocked methods, especially when dealing with complex objects or when you need to perform multiple assertions on the same arguments.