Should a team standardize on Mockito's do-family stubbing form everywhere for consistency, or keep when(...).thenReturn(...) as the default and use the do-family only where required? Argue your position.

## Framing the decision This is a test-suite policy question, and the honest answer starts by naming what a convention is supposed to buy: fewer decisions per line, uniform review expectations, and code that reads the same everywhere. Those are real benefits — but they are bought with whatever the chosen uniform style gives up. Here the currency is compile-time type checking, and that makes the trade lopsided. ## The case for standardizing on the do-family Take it seriously before rejecting it: - **One form to learn.** Newcomers hit the spy trap (`when(spy.call())` executing the real method) exactly once and then never again if the codebase never uses `when(...)`. - **No form-switching mid-test.** Mixed syntax within a class can look arbitrary to a reader who does not know why. - **The do-family is universal.** It works for mocks, spies, void methods and generics; `when(...).thenReturn(...)` does not. A single universal form means no line ever has to be rewritten when a mock becomes a spy. - **Lint-ability.** A blanket "never use `Mockito.when`" rule is trivially enforceable; "use `when` unless the target is a spy" is not, because static analysis rarely knows which is which. That last point is the strongest one, and it is why some teams do adopt the blanket rule. It should be acknowledged rather than dismissed. ## Why the default should still be when(...) **Type safety is the decisive asymmetry.** `when(T methodCall)` infers the stubbed method's return type, so `thenReturn` is checked at compile time. Change a method from `long` to `UUID` and every such stub fails the build, immediately, with the method name in the error. `doReturn(Object)` has nothing to check against; the same refactor leaves stubs that compile, and Mockito only reports `WrongTypeOfReturnValue` if and when that test line executes. In a large suite, "fails at build" versus "fails when that test happens to run" is a meaningful difference in feedback latency, and some mismatches (widening, supertypes, erased generics) never fail at all. **Reading order.** `when(mock.findById(1)).thenReturn(order)` follows the sentence people speak. The inverted form leads with the answer and ends with the question, which is measurably harder to skim in a long arrange block. **Signal value.** If `doReturn` appears only where it is necessary, its presence carries information: this collaborator is a spy, or the method is void, or the generics are awkward. Standardizing destroys that signal and, with it, a cheap review heuristic — "why is there a spy here?" is a question worth prompting. **Ecosystem alignment.** `when(...).thenReturn(...)` is the form in Mockito's own documentation, in most examples and in most engineers' muscle memory. Deviating raises the onboarding cost for every new joiner in exchange for removing one gotcha they would learn anyway. ## The policy I would actually write 1. Default: `when(mock.call()).thenReturn(value)` for plain mocks with value-returning methods. 2. Required: the do-family for spies (always), void methods (no alternative), generics that will not compile otherwise, and `doCallRealMethod`. 3. Never stub a spy with `when(spy.call())`, even when the real method looks harmless — a future change to that method would turn a passing test into a mysterious one. 4. Where `doReturn` is used, bind the value to a typed local first so the intended type is stated on the page. 5. Review rule: two or more `doCallRealMethod`/spy stubbings in one test is a design discussion, not a style nit. Item 3 is the part worth being absolutist about, because it is the rule that prevents real damage; the rest is preference with a justification. ## What the metric should be Rather than policing syntax, watch the *ratio*. A codebase where the do-family appears in a handful of places is healthy. One where it dominates is telling you that spies are everywhere, which in turn says classes under test are mixing behaviour that must run with behaviour that must be suppressed. The response is extraction into collaborators, not a linter rule. Framed that way, the syntax question becomes a diagnostic instrument, which is more valuable than the uniformity it would otherwise buy. ## Where I would concede If a team is genuinely burned repeatedly by the spy trap — say a legacy suite that is spy-heavy and cannot be restructured soon — a temporary blanket do-family rule is a defensible stopgap, paired with a plan to reduce spy usage. Conventions are allowed to be time-boxed responses to a current weakness rather than permanent truths, and saying so is a stronger answer than defending the ideal position unconditionally.