Capturing Variable Arguments (Varargs) in Mockito: A Complete Guide

When unit testing Java applications, Mockito has become the go-to framework for creating and managing mock objects. One common challenge developers face is capturing and verifying variable arguments (varargs) passed to methods. This comprehensive guide will walk you through everything you need to know about capturing varargs with Mockito.

The Challenge with Varargs

Java’s varargs feature allows methods to accept an arbitrary number of arguments. For example:

public void setNames(String... names) {
    // Process multiple names
}

This method can be called with any number of String arguments:

• setNames("Jeff")
• setNames("Jeff", "Mike")
• setNames("Jeff", "Mike", "John")

When testing such methods with Mockito, capturing these variable arguments requires a specific approach.

The Solution: Capturing Varargs in Mockito

Starting with Mockito 1.10.5, capturing varargs became much simpler. Here’s the correct approach:

// Create an ArgumentCaptor for the type of your varargs
ArgumentCaptor<String> namesCaptor = ArgumentCaptor.forClass(String.class);

// Create your mock
A mock = Mockito.mock(A.class);

// Execute the method with varargs
mock.setNames("Jeff", "Mike", "John");

// Verify and capture all arguments
Mockito.verify(mock).setNames(namesCaptor.capture());

// Get all values at once
List<String> capturedNames = namesCaptor.getAllValues();

// Assert the captured values
assertEquals(Arrays.asList("Jeff", "Mike", "John"), capturedNames);

Key Points to Remember

1. Use a single ArgumentCaptor: Unlike your initial approach with multiple captors, you only need one captor for all varargs.
2. Call capture() once: In the verification step, you only call capture() once – Mockito handles collecting all the arguments.
3. Use getAllValues(): This returns all captured values as a List.
4. Works with any number of arguments: This approach works regardless of how many arguments are passed to the method.

Common Mistakes to Avoid

Mistake 1: Using Multiple Captors

// Incorrect approach
ArgumentCaptor<String> captor1 = ArgumentCaptor.forClass(String.class);
ArgumentCaptor<String> captor2 = ArgumentCaptor.forClass(String.class);

mock.setNames("Jeff", "Mike");
verify(mock).setNames(captor1.capture(), captor2.capture()); // Only works for exactly 2 arguments

This approach is inflexible because it requires knowing the exact number of arguments in advance.

Mistake 2: Using getValue() Instead of getAllValues()

// Incorrect usage
String firstArg = namesCaptor.getValue(); // Only returns the last captured value

When capturing varargs, always use getAllValues() to get all the arguments as a list.

Advanced Usage: Matching Specific Arguments

Sometimes you might want to mix exact matching with argument capturing:

// Match the first argument exactly, capture the rest as varargs
verify(mock).someMethod(eq("firstArg"), namesCaptor.capture());

// For methods that take multiple parameters and the last one is varargs
verify(mock).complexMethod(eq(1), any(String.class), namesCaptor.capture());

Compatibility Note

The varargs capturing feature was introduced in Mockito 1.10.5. If you’re using an older version, consider upgrading to take advantage of this functionality.

Testing Examples

Example 1: Basic Varargs Capturing

@Test
public void testVarargsCapture() {
    A mock = Mockito.mock(A.class);
    
    // Call the method with varargs
    mock.setNames("Jeff", "Mike", "John");
    
    // Create a captor
    ArgumentCaptor<String> namesCaptor = ArgumentCaptor.forClass(String.class);
    
    // Verify and capture
    verify(mock).setNames(namesCaptor.capture());
    
    // Get all values
    List<String> capturedNames = namesCaptor.getAllValues();
    
    // Assert
    assertEquals(3, capturedNames.size());
    assertEquals("Jeff", capturedNames.get(0));
    assertEquals("Mike", capturedNames.get(1));
    assertEquals("John", capturedNames.get(2));
}

Example 2: Capturing Zero Arguments

@Test
public void testEmptyVarargs() {
    A mock = Mockito.mock(A.class);
    
    // Call with no arguments
    mock.setNames();
    
    ArgumentCaptor<String> namesCaptor = ArgumentCaptor.forClass(String.class);
    verify(mock).setNames(namesCaptor.capture());
    
    // Expect an empty list
    assertTrue(namesCaptor.getAllValues().isEmpty());
}

Conclusion

Capturing varargs in Mockito is straightforward once you understand the correct approach. Use a single ArgumentCaptor, capture all arguments at once, and retrieve them using getAllValues(). This method works with any number of arguments, making your tests more flexible and robust.

By following the practices outlined in this guide, you can effectively test methods with variable arguments, ensuring your code behaves as expected under all conditions.

Related Resources

• Mockito Official Documentation
• Java Varargs Tutorial