Mock Lifecycle and Hygiene

## What clearing is, and what it is not A MockK mock carries several independent pieces of state. `clearMocks` resets chosen pieces **in place**: you keep the same object reference, so anything already holding that reference keeps working. It is not re-creation — properties fixed when the mock was built (its type, its `name`, whether it is relaxed, whether it records private calls) are not touched by clearing. ## The pieces of state ```kotlin clearMocks( mock, answers = true, recordedCalls = true, childMocks = true, verificationMarks = true, exclusionRules = true, ) ``` **answers** — the stub table built by `every`/`coEvery`. Each entry maps a call pattern to an answer. Clearing empties the table. On a strict (non-relaxed) mock the next unstubbed call then fails with a MockK exception along the lines of "no answer found for". On a relaxed mock it quietly falls back to relaxed defaults again, because relaxation is a creation property, not a stub. **recordedCalls** — the append-only log of invocations that actually happened. `verify` matches patterns against this log. Clearing it sets every count back to zero; `verify { mock.foo() }` immediately afterwards fails as though the call never happened. **childMocks** — when you stub a chain, MockK invents intermediate mocks to stand in for the intermediate results. Those children hang off the parent. Clearing them means the next chained stubbing creates fresh children; any reference you held to an old child is now detached from the parent's graph. **verificationMarks** — MockK notes which recorded calls have already been matched by a verification, which is what lets an exhaustive check know whether anything is left over. Clearing resets that bookkeeping. **exclusionRules** — rules registered to keep certain calls out of the record. Clearing removes them, so those calls start being recorded again. ## Why selective clearing exists The flags are not decoration; two patterns use them regularly. **Reset counts, keep stubs.** A test drives the system through phase one, verifies, then drives phase two and wants counts starting from zero — without re-declaring a dozen stubs: ```kotlin clearMocks(repository, answers = false) ``` **Reset stubs, keep history.** Rarer, but occasionally you want to re-stub a collaborator differently while still asserting on everything it received so far: ```kotlin clearMocks(repository, recordedCalls = false) ``` ## The trap: clearing after you stubbed Because clearing is a plain function call, it obeys ordering. A blanket clear placed in shared setup that runs *after* per-test stubbing wipes those stubs, and the test then fails with "no answer found" pointing at a method you can plainly see being stubbed two lines up. Decide deliberately whether clearing belongs before setup or after the test, and keep it in exactly one place. ## Clearing versus recreating Creating a fresh mock per test is usually simpler and always safer: no state can survive because the object does not. Reach for `clearMocks` when the mock is genuinely shared — held by an expensive fixture, injected into a long-lived component, or created once for a class — or when you need a mid-test reset. If you find yourself clearing at the start of every test on mocks you also create per test, delete the clear; it is doing nothing. ## Relationship to the bulk functions `clearAllMocks(...)` applies the same reset to every mock MockK knows about, with additional flags selecting *which kinds* to touch — regular mocks, object mocks, static mocks and constructor mocks. It is still a **clear**: it wipes state, it does not undo instrumentation. Removing the instrumentation installed by `mockkObject`/`mockkStatic`/`mockkConstructor` is the job of the `unmockk*` family, which is a different operation entirely. ## Summary sentence to have ready "Clearing resets a mock's stubs, its call log, its child mocks and its verification bookkeeping, selectively via flags; it keeps the same object and its creation-time properties, and it never un-patches anything."