Why does stubbing a Mockito spy with when(spy.loadAll()).thenReturn(list) still execute the real loadAll() body, and what form avoids that?

## What a spy is `Mockito.spy(realObject)` (or `@Spy`) creates a partial mock: an object that delegates every invocation to real behaviour *unless* that invocation has been stubbed. Mocks are the opposite default — every unstubbed method returns an empty value and does nothing. That single difference in default is what makes spy stubbing syntax-sensitive. ## The evaluation-order problem `Mockito.when` is a static method with signature `when(T methodCall)`. Java evaluates arguments before invoking the method, so in ```java when(spy.loadAll()).thenReturn(list); ``` the sequence is: 1. `spy.loadAll()` is invoked. It is not stubbed yet, so the spy delegates to the **real** implementation. The real method opens a connection, reads a file, throws, mutates a field — whatever it does in production, it does now, in your test setup. 2. Its return value is passed to `when(...)`. 3. Mockito, having also recorded the invocation internally, registers the stubbing. The stubbing does end up correct; the damage is the unwanted step 1. On a plain mock this is harmless, because step 1 just returns a default value. On a spy it is real work. ## Three ways it bites **An exception in the arrange block.** If the real method throws (uninitialised state, missing connection, guard clause), the test fails on the setup line with a stack trace from production code, and the message points nowhere near the actual mistake. This is the most common way developers discover the rule. **Silent side effects.** The real method writes a row, publishes an event, increments a counter, or populates a cache. The test then passes, but it did real work and may leave state that breaks the next test or makes an interaction assertion count one extra call. **Wrong verification counts.** The setup invocation is a real invocation on the spy, so `verify(spy, times(1)).loadAll()` can fail with "wanted 1 time but was 2" because the arrange block consumed one. ## The fix ```java doReturn(list).when(spy).loadAll(); ``` `doReturn(list)` yields a `Stubber`; `stubber.when(spy)` switches the spy into stubbing mode and returns it; the following `loadAll()` is captured as the invocation to stub and is never executed. Nothing real runs. The same applies to every member of the family — `doThrow`, `doAnswer`, `doNothing`, `doCallRealMethod` — and to argument matchers, which behave exactly as usual: ```java doReturn(list).when(spy).findBy(anyString()); doNothing().when(spy).flush(); // suppress a real side effect ``` ## Void methods on spies are the sharpest case A void method on a spy cannot be stubbed with `when(...)` at all (a void call is not a legal argument), so the do-family is the only option — and it is also the only way to stop a real `flush()`, `send()` or `close()` from actually happening. `doNothing().when(spy).flush()` is the canonical suppression. ## What spies do not do A spy created from an existing instance is a **copy**: Mockito instantiates a proxy and copies the real object's fields into it. The original object is not affected by stubbing, and — importantly — internal calls made by the real code do not go through the proxy. If `loadAll()` internally calls `this.fetchPage()`, stubbing `fetchPage()` on the spy has no effect on that internal call, because the real method's `this` is the spy copy only when the outer call entered through the proxy; self-invocation inside a real method body does dispatch on the spy in Mockito's implementation, but code that captured `this` earlier, or was invoked reflectively, will not. Treat internal-call stubbing as fragile either way. ## Why spies are a smell more often than not Needing to stub part of the very class under test usually means the class is doing two jobs: the part you want to test and the part you want to suppress. Extracting the suppressed part into a collaborator lets you use a plain mock and removes the whole syntax hazard. Spies are legitimate for third-party classes you cannot restructure, for legacy code you are pinning before refactoring, and occasionally for large value-holding objects, but a suite full of spies is design feedback. ## Version note Since Mockito 5, the inline mock maker is the default, which allows spying final classes and final methods that older subclass-based mock makers could not intercept. The evaluation-order rule discussed here is unchanged across versions. ## Guidance Adopt one rule and apply it mechanically: **plain mock → `when(...).thenReturn(...)`; spy → `doReturn(...).when(spy)...`**. It costs a little type safety on the spy path and saves an entire class of hard-to-read failures.