Write Tests for Existing Code

Before Writing, Ask Yourself

• Module type? Route handler, repository, plugin, utility, or service — each has a different mock strategy
• Blast radius? Does this module have side effects (DB writes, API calls) that need isolation?
• Nearest test file? Find the closest

  *.test.ts

  and match its structure exactly

Mock Strategy by Module Type

app.inject()

execute

Mock Setup (mockReset: true)

If your test runner uses

mockReset: true

const { mockFn } = vi.hoisted(() => ({
  mockFn: vi.fn(),
}));

vi.mock("./dependency", () => ({
  dependency: (...args: unknown[]) => mockFn(...args),
}));

beforeEach(() => {
  // MUST reconfigure here — mockReset clears return values between tests
  mockFn.mockResolvedValue(defaultResult);
});

For complex TDZ cases (multiple interdependent mocks), use the globalThis registry pattern.

NEVER

• NEVER chain

  mockResolvedValueOnce

  —

  mockReset

  clears the chain between tests. Use counter-based

  mockImplementation

  instead.
• NEVER define mock variables at module scope then reference in

  vi.mock()

  factories — hoisting creates a temporal dead zone. Use

  vi.hoisted()

  or globalThis.
• NEVER

  vi.importActual()

  for modules with side effects — use selective re-exports.
• NEVER test implementation details (private state, internal call order) — test behavior through the public API.
• NEVER copy mock patterns from other projects — check YOUR test runner config first.
• NEVER modify source code — this skill writes tests only.

Metacognitive Rule

If >3 tests fail on first run: STOP. The root cause is almost certainly a mock wiring issue affecting all tests, not individual test logic errors. Re-examine the mock setup strategy holistically before fixing tests one by one.

Run

npx vitest run <test-file> --reporter=verbose

Arguments

• $ARGUMENTS

  : Path to the source file or module to cover
  • Example:

    /write-tests src/routes/admin/settings.ts

  • If empty, ask the user which file needs test coverage