In Mockito, doReturn(x).when(mock).getValue() and when(mock.getValue()).thenReturn(x) stub the same call. What do you give up by choosing the doReturn form, and when is that trade worth making?

## Where the type safety comes from ```java when(mock.getValue()).thenReturn(42); ``` `Mockito.when` is declared `static <T> OngoingStubbing<T> when(T methodCall)`. The compiler infers `T` from the return type of `getValue()`, so the returned `OngoingStubbing<Integer>` exposes `thenReturn(Integer)`. Handing it a `String` does not compile. That is a genuine, free safety net: if someone changes `getValue()` to return a `UUID`, every stub written this way fails the build immediately with a clear message. ```java doReturn(42).when(mock).getValue(); ``` `Mockito.doReturn` is declared `static Stubber doReturn(Object toBeReturned)`. It has to be `Object`, because at the moment you call it the method being stubbed has not been named yet — it appears two calls later. So there is nothing for the compiler to check against. ## When the mismatch surfaces Mockito validates the answer against the invocation when the stubbing is completed, throwing `WrongTypeOfReturnValue` with a message naming both types ("String cannot be returned by getValue(); getValue() should return Integer"). So it does fail fast at runtime — on the stubbing line, not deep inside the code under test — which softens the loss, but it is still a test-run failure rather than a compile failure, and it only fires for tests that actually execute that line. The more insidious case is a *silent* survivor: when the new and old return types are compatible enough (widening, a supertype, an unchecked generic), a stale stub can keep compiling and running while no longer meaning what it did. ## Where doReturn is not a choice but a necessity **Spies.** `when(spy.loadAll())` evaluates `spy.loadAll()` first, and an unstubbed call on a spy runs the real method — real database hits, real exceptions, extra invocations counted by `verify`. `doReturn(list).when(spy).loadAll()` records the invocation without executing it. This alone justifies the family's existence. **Void methods.** A void call cannot be an argument in Java, so `when(mock.delete(id))` does not compile. `doNothing()`, `doThrow(...)` and `doAnswer(...)` are the only route. **Generics the compiler cannot reconcile.** Two recurring shapes: ```java // 1. method returns List<? extends Number>: thenReturn cannot accept List<Integer> cleanly doReturn(List.of(1, 2)).when(mock).numbers(); // 2. a <T> T signature where inference picks Object at the call site doReturn(customer).when(mapper).convert(row, Customer.class); ``` In both cases `thenReturn` forces an ugly cast or an `@SuppressWarnings`, and the do-family reads better precisely because it does no checking. **Partial mocking.** `doCallRealMethod().when(mock).template()` has no `then...` equivalent that avoids invoking the method. **Consecutive answers on void methods.** `doThrow(...).doNothing().when(mock).send(msg)` — the only way to express a sequence for a void call. ## Reading the two forms The `when(...).thenReturn(...)` order matches how people describe behaviour ("when this is called, return that"), which is why it is the documented default. The do-family reverses it ("return this, when this is called"), which reads less naturally and puts the interesting part — the method being stubbed — at the end of the line. That readability difference is a real, if minor, argument for keeping `when` as the default rather than standardising on the do-family for uniformity. ## A practical policy - Default to `when(mock.call()).thenReturn(value)` for plain mocks with value-returning methods. You get compile-time checking and the natural reading order for free. - Switch to the do-family whenever the target is a spy, the method is void, generics fight you, or you need `doCallRealMethod`. - Do not mix the two arbitrarily inside one test class; pick the required form per collaborator kind so a reader can infer the reason from the syntax alone. Seeing `doReturn` should signal "this is a spy or a special case", which is useful information. - When you must use `doReturn`, keep the stubbed value strongly typed in a local variable (`List<Order> orders = ...; doReturn(orders).when(spy).loadAll();`) so at least the value's own type is stated near the stub. ## Summary The do-family trades compile-time checking of the stubbed value for control over *when* the target method is invoked. On a plain mock there is nothing to control, so the trade is a pure loss; on a spy, a void method or an awkward generic signature, the control is the only thing that makes the stubbing possible at all.