A coding agent finds a test that passes alone but fails beside another test. It adds a cleanup hook, reruns the file and reports success. Before accepting the patch, ask which state the hook was supposed to remove.

Call history, configured behavior and the original method on a spied object are different things. Choosing a cleanup operation by how reassuring its name sounds can erase a fixture the next test needs or preserve behavior the next test should never inherit.

This guide is for maintainers reviewing agent-written Vitest tests. The desired result is a small, explainable state boundary rather than a blanket cleanup call added until the suite turns green.

Methodology and version boundary

We reviewed Vitest's mock API, vi utility reference and clearMocks configuration documentation on September 27, 2026. These are documentation-based recommendations. We did not execute a repository's tests or demonstrate a measured reduction in flaky failures.

Check the version installed in your project before adopting current documentation literally. Also inspect configuration and setup files: a local hook may interact with cleanup that already runs elsewhere. Ask the agent to identify the actual policy before proposing another one.

The comparison below concerns mock lifecycle. It is not a complete reset strategy for databases, module state, timers or external services.

Start with three state questions

For each shared mock or spy, write down:

Should the next test see calls made by the previous test?
Should the next test inherit the current replacement behavior?
Should the object still expose a spy, or its original method?

These questions make the intended boundary reviewable. For example, a shared harmless formatter stub may need fresh call history while retaining its baseline behavior. A test-specific simulated failure should not silently become the next test's default. A temporarily observed object method may need to be restored after the observation ends.

Do not infer those intentions from the test name. Inspect where the mock is constructed, where behavior is changed, and which code holds a reference to it.

What clear, reset and restore actually change

The current individual-mock API distinguishes the operations. mockClear clears recorded calls without resetting implementation. mockReset also resets behavior and queued one-time implementations; the reset baseline differs between vi.fn() and vi.fn(impl). mockRestore additionally restores the original descriptors for an object spied on with vi.spyOn; on a vi.fn mock it acts like mockReset. Vitest mock API.

Our practical rule is to choose the smallest operation that matches the three state questions, then explicitly establish the next test's required fixture. Do not use an implementation reset when the only unwanted state is a previous assertion's call history.

For a spy, separately inspect the method currently installed on the object and any retained spy variable. A reference held by the test is not itself proof that later application calls still pass through that spy.

Do not treat the global helpers as synonyms

Vitest documents clearAllMocks as clearing history without changing implementations, and resetAllMocks as also resetting implementations. Its current restoreAllMocks documentation specifically says it restores vi.spyOn originals, does not affect automocked mocks, and does not clear mock history or reset the retained mock implementation like an individual mockRestore does. Vitest vi utilities.

That distinction matters when an agent mechanically replaces one helper with another across a repository. Require an explanation of which objects are affected and which references survive. A stronger-sounding name is not evidence of a more complete cleanup.

Avoid sweeping changes as the first diagnostic experiment. Start with the smallest pair of tests that exhibits the suspected dependency, and preserve the original failure before changing the lifecycle.

A concrete order-dependence investigation

Consider an illustrative notification client. One test configures the client to reject a request and checks the error message. The next test expects the normal success response.

Ask the agent to produce a state note before changing code: who creates the client double, where the rejection is configured, whether it is one-time or persistent, and who establishes the success baseline. This is an investigation plan, not a claim that your suite has this defect.

Then propose three bounded observations: run each test alone, run the pair in the original order, and run the pair in the reverse order where the test setup permits it. Keep those outcomes distinct. A different outcome can support an order-dependence hypothesis, but it does not uniquely identify mock state as the cause.

After the proposed patch, repeat the same observations without weakening the meaningful assertions. Include a neighboring test that relies on the original object method if restoration is part of the change. Record unavailable checks honestly.

Configuration is part of the fixture

The clearMocks option controls automatic history clearing before tests. Its documentation also warns about shared mocks in asynchronous concurrent tests. Vitest clearMocks configuration.

Our recommendation is to avoid sharing a mutable mock between overlapping scenarios when independent test-local doubles can satisfy the same requirement. A cleanup hook cannot establish a clean boundary if another test is actively using the same state.

Record whether the tests run sequentially or concurrently and whether setup happens per test or once for a group. Do not change the whole suite's concurrency policy merely to conceal a localized fixture problem without discussing the trade-off.

Limitations and the review handoff

A correct mock cleanup choice does not reset a service, empty a queue or undo an application side effect. Nor does passing an isolated test prove the suite is independent of execution order.

The useful handoff contains the original failure, the identified shared object, the state intended to survive, the scoped change, actual executed checks and remaining uncertainty. If the agent only reviewed documentation, it should say so.

Our flaky-test evidence guide explains how to retain contradictory attempts. Use the skill directory to find coding workflows, but evaluate their explanations as well as their patches. The best cleanup is the one whose effect you can predict before rerunning.