Mockito's spy(realObject) does not wrap the instance you hand it. Explain what it actually builds, and what that means for state changes made through the spy and for calls the real code makes on itself.

## What spy() actually constructs `Mockito.spy(realObject)` is shorthand for creating a mock with two settings: the spied instance, and a default answer of "call the real method". Under the hood Mockito generates an instrumented type for the class (a Byte Buddy subclass with the default mock maker, or an instrumented version of the class itself with the inline mock maker), instantiates it **without running a constructor**, and then copies the fields of `realObject` into the new instance one by one via reflection. So you end up with **two objects**: the original you passed in, and the spy. They start with equal field values and then diverge. ## Consequence 1 — the original goes stale ```java List<String> original = new ArrayList<>(); List<String> spied = spy(original); spied.add("a"); original.size(); // 0 — the mutation went into the copy spied.size(); // 1 ``` Anyone holding a reference to `original` — including production code that was handed it before the test wrapped it — sees the pre-spy snapshot. In a test this shows up as an assertion on the wrong object; in a Spring-style setup it shows up as production code and test code operating on different instances. The rule of thumb: after `spy(x)`, throw away your reference to `x` and work exclusively with the spy. The copy is **shallow**. If the original held a reference to a `Map`, the spy holds the same `Map` reference, so mutations *through that map* are visible from both. Only the fields themselves are independent, not the objects they point to. This half-shared state is worth knowing when a test seems to leak in one direction but not the other. The copy is also **best-effort**. Mockito copies leniently and swallows failures rather than aborting, so a field it cannot write — `final` instance fields on some JVM configurations, fields blocked by module access rules — may silently arrive with its default value. A spy whose object was constructed elsewhere and passed in is therefore riskier than one you build inline in the test. ## Consequence 2 — self-invocation is intercepted This is the property that makes partial mocking work and the one most candidates get wrong. Because the real method bodies execute **on the spy instance**, `this` inside them refers to the spy. Any call the real code makes to another of its own public/protected methods passes through Mockito's interceptor: ```java class Job { void run() { if (enabled()) doWork(); } boolean enabled() { return readConfigFromDisk(); } void doWork() { /* ... */ } } Job job = spy(new Job()); doReturn(false).when(job).enabled(); job.run(); // real run() executes; its internal enabled() hits the stub -> doWork() skipped ``` Contrast this with a **delegating** double. `mock(Job.class, AdditionalAnswers.delegatesTo(realJob))` forwards each call to a genuinely separate object, so `realJob.run()` calls `realJob.enabled()` directly and your stub is bypassed. Same superficial goal, completely different interception semantics. (Delegation is the right tool when the real object cannot be subclassed, or when you deliberately want internal calls left alone.) Two limits on interception: `private` methods are never intercepted — they are not overridable and are invoked directly — and `static` methods need `mockStatic`. With Mockito 5's default inline mock maker, `final` classes and `final` methods *can* be instrumented; with the older subclass mock maker they could not, and stubbing a final method silently had no effect, which produced some memorably confusing test failures. ## Why this couples tests to internals Self-call interception is powerful and, for the same reason, brittle. A test that stubs `enabled()` to control `run()` is asserting on the class's **internal call graph**, not only its behaviour. Inline `enabled()` into `run()`, rename it, or make it private, and the test breaks though nothing observable changed. That is the real argument against leaning on spies: not that they are slow or exotic, but that they turn refactorings into test failures. ## Practical guidance - Build the object inside the test and spy it immediately: `Foo foo = spy(new Foo(dep));` — never keep and assert on the pre-spy reference. - Prefer injecting the spy into whatever consumes it, so production code and the test share one instance. - Remember the copy is shallow: shared mutable fields are still shared. - Do not rely on spying an object with `final` fields wired externally; the copy may not carry them. - When you need real behaviour but explicitly do **not** want self-calls intercepted, use `delegatesTo` instead of `spy`. - Keep the number of self-methods you stub at one, and treat two as a signal to extract a collaborator.