How to use ArgumentCaptor for stubbing?

java

mockito

testing

best-practices

byNikita Barsukov·Feb 22, 2025

ArgumentCaptor is initialized via ArgumentCaptor.forClass(YourClass.class). Apply captor.capture() within Mockito.when() or doReturn(), which hooks to the argument. Following the method call, acquire the value utilizing captor.getValue().

Example:

// Our captor is ready for action 🎬
ArgumentCaptor<YourClass> captor = ArgumentCaptor.forClass(YourClass.class);
// Prepare the stage, the performance is about to start 🎭
when(yourMock.methodToStub(captor.capture())).thenReturn(mockedResult);

// Roll camera! 🎥
yourMock.methodToStub(actualArgument);

// Time for a post-mortem, let's dissect the actor!
YourClass captured = captor.getValue();
// Captured, cornered, and grilled for truth! 👩‍⚖️

Remember, ArgumentCaptor is not a magician's tool for illusion but a detective's gadget for investigation and verification. It unleashes its true potential in method call verifications.

The heart of ArgumentCaptor

Underneath its simple interface, ArgumentCaptor is a powerful entity. Positioned for capturing and verifying method arguments, its use for stubbing is not recommended per Mockito's official guide.

Strategy: Stubbing vs Verification

To differentiate: stubbing sets up a mock's behavior, while verification handles the post-analysis. Thing Stubbing as the setup for a crime scene, with Verification as the investigation after.

The Matcher's game in Stubbing

Stubbing where you expect specific arguments? Use Matchers like eq() rather than relying on ArgumentCaptor. For a much readable and broader match, go for Matchers.any().

Incorporating eq() Example:

// The masterplan is set, let's match the password for the heist 🦹‍♂️
when(yourMock.methodToStub(eq(expectedArgument))).thenReturn(mockedResult);

Implement equals for effective matching

Multitude of tests with Matchers? Operationalize the equals method for better comparison and fulfilling the contract that eq() works upon.

Stubbing with reasoning

Stubbing with advanced arguments and conditional logic requires running with doReturn() in conjunction with argThat() to manage complex argument problems.

// Let's add a secret door in the mock's method maze 🚪
doReturn(mockedResult).when(yourMock).methodToStub(argThat(new MyCustomMatcher()));

Non-null returns: A Mock's Reality

Avoid the illusion of null returns from Mock objects. Null could lead us to a path of delusion in tests. Opting for Optional or alternative constructs offer better clarity.

Beef up your tests

Building Test Strength

Boost the power of your tests using ArgumentCaptor by applying those specific Matchers. Leveling up here enhances the meaningfulness and quality of your tests.

Your Verification Hall of Fame

Climb the ladder to assert dominance using verify with a capture to assert that the method was called with the right arguments.

// Firing up the verification machine! 🎛️
verify(yourMock).methodToStub(captor.capture());
// Trapped! You can't escape now!
YourClass capturedParam = captor.getValue();
assertEquals(expectedParam, capturedParam); // Busted! 🕵️‍♂️