A mailer collaborator's send(...) method has return type void. Using Mockito, how do you stub it so the first invocation throws an IOException and every later invocation succeeds silently?

## Why void needs a different shape Mockito's familiar stubbing form, `when(mock.call()).thenReturn(x)`, is an ordinary Java method call: the argument to `when(...)` is the *value* of `mock.call()`. A method declared `void` produces no value, so `when(mailer.send(msg))` is not even legal Java. Mockito therefore offers a mirrored syntax where the behaviour comes first and the call being stubbed comes last: ```java doThrow(new IOException()).when(mailer).send(msg); ``` Read it as "do this ... when this call happens". Mechanically, `when(mailer)` puts that mock into stubbing mode and returns it; the very next invocation on it is *recorded* as the stubbed call rather than executed. ## Building the sequence `doThrow(...)` returns a `Stubber`, and `Stubber` exposes `doThrow`, `doNothing`, `doAnswer`, `doReturn` and `doCallRealMethod` again — so behaviours chain exactly like `thenReturn` chains: ```java doThrow(new IOException("smtp down")) .doNothing() .when(mailer).send(any(Message.class)); ``` Invocation 1 throws. Invocation 2 does nothing. Invocation 3, 4, 5 also do nothing: the last entry in a consecutive chain is repeated forever once earlier entries are consumed. That persistence rule is what makes "fail once, then always succeed" expressible in two links rather than one per expected call. To model a stubborn outage — fails twice then recovers — just add a link: ```java doThrow(new IOException()).doThrow(new IOException()).doNothing() .when(mailer).send(any(Message.class)); ``` ## Ordering is the whole trick Because the tail is sticky, the *order* of the chain encodes the story. `doThrow(...).doNothing()` means transient failure. `doNothing().doThrow(...)` means "works once, then breaks permanently" — a very different scenario, and a common accidental inversion when someone writes the happy path first out of habit. ## Constraints Mockito enforces at stub time Two validations fire when the stubbing is recorded, not when the mock is called, so failures point at the stubbing line: - **Checked exceptions must be declared.** If `send(...)` does not declare `IOException`, Mockito raises a `MockitoException` reading "Checked exception is invalid for this method". Unchecked exceptions and `Error`s are always allowed. If the real signature throws a wrapped `MailException` instead, stub that. - **`doNothing()` is void-only.** Applying it to a method with a return type raises "Only void methods can doNothing()". The value-returning analogue is `doReturn(...)`. You can also stub by exception *type* — `doThrow(IOException.class)` — which lets Mockito instantiate it; use the instance form when the test asserts on the message or cause. ## What doNothing() actually adds On a plain mock, void methods already do nothing: Mockito's default answer for `void` is a no-op, so a bare `doNothing().when(mailer).send(msg)` is documentation, not behaviour. It earns its place in exactly two situations. First, as a link in a consecutive chain like the one above, where it is the only way to say "stop throwing from here on". Second, on a spy, where an unstubbed void call would otherwise run the real body and hit the network, the database or the file system — `doNothing()` is what suppresses that. ## Pairing the stub with a verification The stub alone proves nothing about the retry policy: because the tail answer repeats, a component that gives up after one attempt and a component that retries a hundred times both produce a green test. Add the interaction assertion: ```java assertThat(service.dispatch(message)).isTrue(); verify(mailer, times(2)).send(any(Message.class)); ``` If the retry count is a policy value, assert exactly that count rather than `atLeastOnce()`, so an accidental change to the policy fails the test. ## Capturing arguments across the sequence When the retry is supposed to resend the *same* message (rather than rebuild it), an `ArgumentCaptor` with `times(2)` gives you both invocations' arguments and lets you assert they are equal — a cheap way to catch a retry that accidentally mutates or re-serializes its payload between attempts. ## Practical guidance Keep these chains to the shortest sequence that expresses a named scenario, give the test a name that says the scenario out loud (`resendsAfterTransientSmtpFailure`), and prefer a single well-chosen exception instance over generic `RuntimeException` so the test also documents which failures the policy treats as retryable.