In Mockito, what is the difference between chaining two answers in a single stubbing — thenReturn(1).thenReturn(2) — and writing two separate when(...) statements for the same call?

## Two mechanisms that look alike Mockito stores stubbings per *invocation matcher* — the method plus its argument matchers on a given mock. Both of the snippets below touch the same invocation matcher, `repo.count()`, but they mean different things. **Chaining** attaches an ordered queue of answers to one stubbing: ```java when(repo.count()).thenReturn(1).thenReturn(2); ``` `when(...)` returns an `OngoingStubbing`, and each `thenReturn`/`thenThrow`/`thenAnswer` on it appends another answer to that same stubbing. Calls pop answers in order and then stick on the last one: 1, 2, 2, 2, ... **Re-stubbing** creates a new stubbing that shadows the old one: ```java when(repo.count()).thenReturn(1); when(repo.count()).thenReturn(2); ``` The second statement does not append to the first. Mockito resolves an invocation against the most recently registered matching stubbing, so from the moment the second line runs, every call returns 2 — the value 1 is never observed by the code under test. ## Why this trips people up The two forms are visually close, and the failure is silent: no exception, no warning, just a test asserting on a first value that the mock never produced. The symptom is usually reported as "consecutive stubbing doesn't work". A closely related trap is loop-built stubbing: ```java for (String page : pages) { when(client.nextPage()).thenReturn(page); // each iteration overrides the previous } ``` This leaves only the final page stubbed. The correct form collects the values and hands them to the varargs overload: ```java when(client.nextPage()).thenReturn(pages.get(0), pages.subList(1, pages.size()).toArray(new String[0])); ``` or, more readably, builds one chain explicitly. ## When overriding is the right tool Overriding is a deliberate and useful feature, not just a hazard. The standard pattern is a shared setup that installs sane defaults for a collaborator so that every test does not repeat five lines of stubbing, and then an individual test that re-stubs the one call it cares about: ```java @BeforeEach void defaults() { when(featureFlags.enabled("beta")).thenReturn(false); } @Test void usesBetaPathWhenFlagOn() { when(featureFlags.enabled("beta")).thenReturn(true); // intentional override ... } ``` This reads well precisely because the override is expressing "this test differs in exactly one way". The rule of thumb: override to change a *constant*, chain to express a *sequence*. Never mix the two ideas in one test. ## Interaction with argument matchers Stubbings are keyed by arguments, so what looks like an override may not be one: ```java when(repo.find(1L)).thenReturn(a); when(repo.find(2L)).thenReturn(b); // different matcher — both stubbings coexist ``` But a broad matcher registered later shadows a narrow one for the calls it matches: ```java when(repo.find(1L)).thenReturn(a); when(repo.find(anyLong())).thenReturn(b); // now find(1L) returns b as well ``` So ordering matters when matchers overlap: register the general default first and the specific case afterwards, not the other way round. ## What the varargs form does `thenReturn(1, 2, 3)` is a single stubbing with three queued answers — exactly equivalent to chaining three `thenReturn` calls. The signature is `thenReturn(T value, T... values)`; the varargs overload only applies when you pass at least two arguments, so there is no ambiguity for the single-value case. ## Diagnosing it in a real test When a mock returns an unexpected value, three checks resolve almost every case. First, search the test class *and* its base classes and setup methods for other `when(...)` statements naming the same method — an override may live in an inherited `@BeforeEach`. Second, check for a broader matcher registered later. Third, remember that consecutive answers are consumed globally across the test, not per assertion block: if setup code or an earlier arrange step invokes the mock, it silently consumes the first answer and shifts everything by one — which is another reason to keep chains short and to verify call counts explicitly. ## Guidance Express sequences in exactly one statement, keep them to the shortest run that names a scenario, and treat any second `when(...)` on the same call as an override you must justify. If you find yourself needing many overrides for a single collaborator, that collaborator is usually doing too much and a hand-written fake will read better than the stub pile.