In MockK, when you write spyk(existingInstance), what relationship does the resulting spy have with the instance you passed in — and what breaks if you assume it is a wrapper that delegates to that object?

## What a spy is, mechanically A spy is a test double that keeps the real implementation: any member you have not stubbed runs the class's actual code, and every call is recorded so you can verify it later. MockK creates one with `spyk`. To intercept calls, MockK needs an *instrumented* instance — an instance of a class whose bytecode MockK controls. It cannot instrument an arbitrary object you already constructed after the fact and hand it back to you as the same reference. So `spyk(obj)` does something subtly different from what the name suggests. ## What spyk(obj) actually does 1. MockK produces a new instance of `obj`'s class that it controls (created without running your constructor). 2. It then copies the field values out of the object you passed and writes them into the new instance, field by field. 3. It returns that new instance. From that point on, **there is no link at all** between the object you passed and the spy you got. Nothing is forwarded, nothing is delegated. The phrase to remember is "copy, not wrapper". ## The four consequences that bite people **1. Assertions on the original fail.** A test creates `val cart = Cart()`, spies it, drives the spy through `addItem(...)`, then asserts `cart.total == 10`. The spy's `total` moved; `cart.total` is still whatever it was at copy time. Always assert on the value `spyk` returned. **2. Late wiring is lost.** If a field is assigned after construction — a setter, a manual dependency injection step, a builder finishing up — and you created the spy before that assignment, the spy holds the old value. Create the spy *after* the object is fully initialized, and re-create it (rather than mutating the original) if setup changes. **3. The copy is shallow.** Field values are copied as-is. A `var count: Int` diverges immediately, because copying an `Int` copies the value. A `val items: MutableList<String>` does not diverge, because both objects hold the *same list reference*: mutating through the spy is visible through the original and vice versa. This mixed behaviour is exactly what makes the bug confusing — half the state seems shared and half does not. **4. Identity changes.** `spy === original` is false. Any code that looked the original up in an identity-based structure, or that was already given the original as a collaborator, keeps talking to the original — so the calls you expect the spy to record simply never reach it. Whatever consumes the collaborator must be constructed with, or told about, the spy. ## Why MockK is built this way MockK must be in the call path for *every* member of the class, including final ones (Kotlin classes and members are final by default). It achieves that by producing an instance whose class it has instrumented. A delegating wrapper would only be able to intercept calls that arrive from outside through the wrapper reference, and would need the class to be open to be substitutable. Copying state into an instrumented instance sidesteps both problems, at the price of the copy semantics above. ## Verifying against a spy Because the spy is a full MockK mock underneath, every real call through it is recorded: `verify { spy.addItem(any()) }` works exactly as it does for a plain mock, even though the method actually executed real code and produced real results. That combination — real behaviour plus a recorded interaction log — is the whole point of a spy. ## The checklist - Construct and wire the object completely; spy it last. - Pass the spy, not the original, to the system under test. - Assert and verify on the spy. - Remember the copy is shallow when state includes mutable collections or shared services. - If the class is expensive or awkward to construct, that is a signal to reconsider the spy, not a reason to spy the half-built object.