When is stubbing a collaborator to return a different value on each successive call the wrong tool for a test, and what would you use instead?

## Two very different reasons to reach for a sequence When you write `thenReturn(a, b, c)`, you may be doing one of two things, and they have opposite consequences. **Specifying a temporal contract.** The collaborator legitimately behaves differently over time and that is precisely what the test exists to pin down: a call fails once and succeeds on retry; a status poll returns `PENDING` then `DONE`; an iterator yields elements then reports exhaustion. Here the sequence *is* the requirement. The test is not coupled to an accident of implementation — it is asserting the contract. **Papering over collaborator state.** The collaborator is really a store, a queue or a session, and rather than model that, the test enumerates the values it happens to hand back in the order the current implementation happens to ask for them. Now the queue is an implicit, unstated assertion about call ordering and call count. ## Why the second case hurts The damage shows up as refactor-hostility. Suppose production code changes from calling `config.get("timeout")` twice to caching it once. Nothing observable changed, but the second answer now surfaces where the third used to, and every downstream assertion drifts. The test fails, the failure message points at an assertion far from the cause, and the person debugging has to reconstruct a call-count model in their head. The reverse happens too: an added call — a new log line that reads the same value, a defensive re-read — consumes an extra answer and shifts everything. And because the last answer repeats forever, some of these mistakes do *not* fail; they silently feed the same value everywhere and the test goes green while proving less than you think. Legibility suffers as well. `thenReturn(3, 3, 7, 0, 0)` carries no meaning. Two months later nobody can say which call each number was for, so nobody dares change it, so the test ossifies. ## What to use instead **A hand-written fake.** Implement the collaborator's interface with an in-memory version holding real state — a `Map`-backed repository, a list-backed queue, an `InMemoryClock` you advance explicitly. Arrange by putting data in; assert by looking at outcomes or the fake's final state. Order and count stop mattering, so refactors that only change *how often* the code reads a value no longer break the test. The cost is a class to maintain; the payoff is real once three or four tests need the same collaborator, and it forces the interface to be small enough to fake — itself useful design feedback. **A stateful answer.** Where a fake is overkill, one `Answer` that computes from real state (a counter, a queue you drain, the invocation's own arguments) is more honest than a hardcoded list, because it expresses the *rule* rather than a transcript. **Redesign the collaborator.** Frequently the sequence is a symptom: the unit under test is orchestrating too much, or the collaborator interface leaks a stateful protocol (`open`, `next`, `hasNext`, `close`) where a single call returning a collection or a stream would do. Replacing the chatty protocol with one call removes the sequencing problem instead of testing around it. **State-based assertions.** If the sequence exists only so the test can verify "it kept going until done", assert the end state — records written, message published, status final — rather than the intermediate reads. ## When sequences remain the best tool Do not over-correct. Consecutive stubbing stays right for: - **Transient-failure and retry tests**, where the whole point is that attempt 1 fails and attempt 2 succeeds. - **Poll-until-condition loops**, where two entries (`PENDING`, `DONE`) express the contract exactly. - **Exhaustion**, where a single trailing entry that repeats forever models "stays broken" with one line. - **Boundary probes**, such as an ID generator returning two different IDs to prove they are not reused. In each case the chain is short, each entry is meaningful, and the test name states the scenario the sequence encodes. ## A usable heuristic Ask: *if a reviewer deleted one entry from this chain, would the test's stated behaviour change in a way the test name mentions?* If yes, the sequence is specification. If the entry exists only to satisfy an extra call the implementation happens to make, it is coupling. As a practical threshold, two or three meaningful entries in a scenario-named test are healthy; five or more anonymous values are a signal to build a fake or simplify the collaborator. ## Team-level framing Treat long stub sequences the way you treat long mock setups generally — as a measure of how much of the design leaked into the tests. Their growth over time is a useful metric: when a test file's arrange blocks are dominated by ordering, the module underneath usually wants decomposition, not a better mocking trick.