How to properly match varargs in Mockito

Unit testing plays a pivotal role in ensuring the robustness and reliability of software. When working with Java, developers frequently encounter methods that utilize variable arguments, commonly known as varargs. While incredibly flexible for method design, testing these methods with Mockito can sometimes present a unique challenge. Properly matching varargs in Mockito is crucial for writing effective and maintainable tests, ensuring your mocked dependencies behave exactly as expected. This guide will walk you through the nuances of handling varargs in your Mockito tests, from simple wildcard matching to creating highly specific custom argument matchers, equipping you with the knowledge to tackle any varargs scenario with confidence.

Understanding Varargs and Mockito’s Matching Challenge

In Java, varargs (variable arguments) allow a method to accept zero or more arguments of a specified type. Syntactically, this is represented by an ellipsis (...) after the type, such as String... names. Behind the scenes, the Java compiler treats these variable arguments as an array. This underlying array conversion is where the challenge for Mockito often arises. When you call a method with varargs, you’re effectively passing an array, and Mockito’s default argument matchers need to be aware of this.

Consider a scenario where you have a service method like myService.process(String... data). If you try to verify or stub this method using standard eq("value1", "value2"), Mockito won’t inherently understand that these are elements of a varargs array. It expects a single array object. Directly passing an array like eq(new String[]{"value1", "value2"}) might seem intuitive, but Mockito’s argument matching works by comparing the actual argument passed during the test execution with the argument matcher provided during stubbing or verification. This often requires specialized matchers for array-like structures.

The core issue stems from how Java handles varargs at runtime. A method call like myMethod("a", "b") with String... args actually compiles down to myMethod(new String[]{"a", "b"}). Therefore, when Mockito intercepts the call, it sees an array object. Without the correct matcher, Mockito’s strict argument comparison will likely lead to UnfinishedStubbingException or unexpected test failures, making it essential to grasp the correct matching techniques for effective unit testing.

Leveraging Mockito’s Wildcard and Array Matchers

To properly match varargs in Mockito, developers primarily leverage anyVararg() for flexible matching or more specific Hamcrest matchers via argThat() for granular control over individual vararg elements. For scenarios requiring precise validation of each argument, a custom ArgumentMatcher provides the highest degree of specificity and clarity.

Mockito provides several powerful argument matchers that can simplify the process of dealing with varargs. The most straightforward approach for general matching is anyVararg(). This matcher will match any varargs argument, regardless of its content or length. It’s particularly useful when the exact content of the varargs isn’t critical to the test logic, and you simply need to confirm that a method was called with any variable arguments.

For situations where you know the type of the varargs but don’t care about the specific values, you can use any(Class<T> type) or its shorthand any(), specifically when Mockito can infer the type. While any() can work for arrays, anyVararg() is more explicit and often preferred for clarity when dealing directly with varargs. However, if your varargs method is overloaded and accepts a single argument of the array type (e.g., void process(String[] data) vs. void process(String... data)), using any(String[].class) might be necessary to differentiate. The key is to remember that varargs are arrays, so matchers designed for arrays are often applicable. For more details on various Mockito matchers, the official Mockito Javadoc is an excellent resource.

• anyVararg(): Matches any number of arguments of any type passed as varargs. Ideal for simple presence checks.
• any(Class<T> type): Can be used with array types (e.g., any(String[].class)) to match any array of that specific type, including varargs.
• eq(value): While not directly for varargs, it can be used for individual elements within a varargs if combined with other strategies like argThat().

Granular Matching with argThat() and Custom Matchers

When anyVararg() is too broad, and you need to specify conditions for the elements within the varargs, Mockito’s argThat() method comes into play. This method allows you to use Hamcrest matchers or define your own custom matching logic. Hamcrest provides a rich set of matchers for collections, arrays, and individual objects, which are incredibly useful for asserting properties of varargs. For instance, you might want to ensure the varargs array contains specific elements, has a certain size, or meets other criteria.

Consider a scenario where you need to verify that a method was called with at least three string arguments, and one of them must be “critical”. You could combine Hamcrest’s arrayWithSize and hasItemInArray matchers within argThat(). For more complex validation, such as checking specific patterns or relationships between elements, implementing a custom ArgumentMatcher provides the highest degree of control and readability. This approach involves creating a class that implements Mockito’s ArgumentMatcher interface and overriding its matches() method Question & Answer :

I’ve been trying to get to mock a method with vararg parameters using Mockito:

interface A { B b(int x, int y, C... c); } A a = mock(A.class); B b = mock(B.class); when(a.b(anyInt(), anyInt(), any(C[].class))).thenReturn(b); assertEquals(b, a.b(1, 2)); 

This doesn’t work, however if I do this instead:

when(a.b(anyInt(), anyInt())).thenReturn(b); assertEquals(b, a.b(1, 2)); 

This works, despite that I have completely omitted the varargs argument when stubbing the method.

Any clues?

Mockito 1.8.1 introduced anyVararg() matcher:

when(a.b(anyInt(), anyInt(), Matchers.<String>anyVararg())).thenReturn(b); 

Also see history for this: https://code.google.com/archive/p/mockito/issues/62

Edit new syntax after deprecation:

when(a.b(anyInt(), anyInt(), ArgumentMatchers.<String>any())).thenReturn(b);