Explain what Mockito's ArgumentCaptor is for, how you create one and wire it into a verification, and how you read the captured value afterwards.

## The problem it solves Verification normally answers "was this method called with something matching X?". When the argument is a rich object built inside the code under test - an event, a DTO, a request - encoding the whole expectation as a matcher is awkward and the failure message is poor. `ArgumentCaptor` inverts the flow: let the call match loosely, keep the actual object, and assert on it with your normal assertion library. ## Creating a captor Two ways: ```java // 1. explicit ArgumentCaptor<Email> captor = ArgumentCaptor.forClass(Email.class); // 2. annotation - needs MockitoExtension or MockitoAnnotations.openMocks(this) @Captor ArgumentCaptor<Email> captor; ``` The annotation form is preferred for generic types: `ArgumentCaptor.forClass(List.class)` cannot express `List<String>` and forces an unchecked assignment, while `@Captor ArgumentCaptor<List<String>> captor` reads the type from the field's generic signature. Recent Mockito versions also offer `ArgumentCaptor.captor()`, which infers the type from the assignment target. ## Using it `captor.capture()` is called *inside* the mocked invocation, in the position of the argument you want: ```java verify(mailer).send(captor.capture()); verify(repo).update(eq(42L), captor.capture()); // eq() required: capture() is a matcher ``` That is the key mental model: **`capture()` is an argument matcher** that matches any value and, as a side effect, records it. Because it participates in the matcher stack, mixing it with raw literals in the same call throws `InvalidUseOfMatchersException`; wrap the literals in `eq()`. Capture happens during verification, when Mockito replays the recorded invocations and evaluates matchers against them. So order matters: the captor is empty until the `verify` line executes, and if the verification fails (wrong number of calls, other argument mismatch), no assertions on the captured value will be meaningful - fix the verification first. ## Reading values - `getValue()` - the last captured argument. If the verification matched several invocations, this is the most recent one. - `getAllValues()` - a `List` of every value captured by this captor, in invocation order, across all verifications that used it. ```java verify(mailer, times(2)).send(captor.capture()); List<Email> sent = captor.getAllValues(); assertThat(sent).extracting(Email::to).containsExactly("a@x", "b@x"); ``` Calling `getValue()` when nothing was captured throws `MockitoException` ("No argument value was captured") - a common symptom of asserting before verifying, or of verifying a method that was never called. ## A worked example ```java @ExtendWith(MockitoExtension.class) class SignupServiceTest { @Mock Mailer mailer; @Captor ArgumentCaptor<Email> captor; @InjectMocks SignupService service; @Test void sendsWelcomeMail() { service.signUp("[email protected]"); verify(mailer).send(captor.capture()); Email sent = captor.getValue(); assertThat(sent.to()).isEqualTo("[email protected]"); assertThat(sent.subject()).isEqualTo("Welcome"); } } ``` The failure output here names the exact field that differed, whereas a matcher-based verification would report only that no matching invocation was found. ## Gotchas to mention **Mutable arguments.** The captor stores a reference, not a snapshot. If production code reuses or mutates the object after the call (a pooled builder, a cleared list), the captured value reflects the *final* state. Assert on a copy or capture a defensive projection when that bites. **Captor in stubbing.** `when(mock.f(captor.capture())).thenReturn(x)` is legal but captures on every matching call including ones you did not intend to inspect, and mixes concerns; capturing belongs in verification. **One captor, one argument position.** Reusing a captor for two different parameters in the same call accumulates both into `getAllValues()` in registration order, which is confusing - declare one captor per parameter. ## Interview framing A junior answer covers create-capture-assert. A stronger one adds that `capture()` is a matcher (hence `eq()` for siblings), that `getValue()` is the last value while `getAllValues()` covers repeated calls, and that `@Captor` exists mainly to carry generics.