Testing

Write automated tests following TDD principles.

Philosophy

Based on Matt Pocock's TDD approach:

• Test behavior through public interfaces, not implementation details
• Good tests survive refactors — if the public API doesn't change, tests shouldn't break
• Mock only at system boundaries (external APIs, databases, time/randomness)
• Never mock your own modules or internal collaborators

Workflow

Vertical Slices (Not Horizontal)

Wrong approach (horizontal): write ALL tests first, then implement everything.
Correct approach (vertical): write ONE test → make it pass → repeat.

Each cycle:

1. Write a single test that describes expected behavior
2. Run it and confirm it fails (red)
3. Write the minimum code to make it pass (green)
4. Refactor if needed (refactor)
5. Move to next behavior

Planning Phase

Before writing tests:

1. List the behaviors to verify (what should happen, not how)
2. Order them from simplest to most complex
3. Start with the "tracer bullet" — the simplest end-to-end case

Convention

Co-locate tests next to source: foo.test.ts next to foo.ts.

Vitest API

import { describe, expect, test, vi } from "vitest";

• test("description", () => { ... }) — Define a test
• describe("group", () => { ... }) — Group related tests
• expect(value).toBe(expected) — Strict equality
• expect(value).toEqual(expected) — Deep equality
• expect(fn).toThrow() — Assert throws
• vi.fn() — Create a mock function
• vi.mock("module") — Mock a module

Checklist Per Cycle

Before moving to the next test, verify:

• Test describes behavior, not implementation
• Test uses the public interface
• Test would survive an internal refactor
• Implementation is the minimum needed to pass
• No speculative features added

For mocking guidelines, see references/mocking.md.
For good vs bad test examples, see references/examples.md.