---
name: canon-tdd
description: Implement features and fix bugs test-first, the Canon TDD way (test list → one test → make it pass → refactor → repeat). Use when implementing any new feature, endpoint, model, or method, fixing a bug, or executing a plan — write the test list and a failing test BEFORE production code.
---

# Canon TDD

Test-driven development the way Kent Beck describes as "Canon TDD", per
<https://adam-young.co.uk/blog/canon-tdd/>. CLAUDE.md mandates a TDD approach for
this package; this skill is the detailed how.

> **Red-Green-Refactor is the engine. The Test List is the steering wheel.**

## Agent behaviour contract

The point of this skill: do these by default, without being reminded.

1. **Start with a test list, and show it.** Before touching production code,
   enumerate the behaviours and edge cases as a checklist and confirm it with the
   user (or state it explicitly). This is the steering wheel — it defines "done".
2. **No production code before a failing test.** Write exactly **one** test,
   run it, and watch it fail for the right reason. Never write the implementation
   first and back-fill tests.
3. **One test at a time.** Do not convert the whole test list into code up front
   — the first passing test often forces a design change that affects the rest.
4. **Refactor only on green**, and keep refactoring out of the make-it-pass step.
5. **Repeat until the test list is empty**, adding newly-discovered cases to the
   list as you go.

## The five steps

1. **Write a test list** — every behavioural variant and edge case you can think
   of, as a plain checklist. Not code yet. It's a living list: add to it whenever
   implementation reveals a new case.
2. **Write a test** — pick the next item and write one real, automated test:
   setup, invocation, and **assertions**. Define *what* the system does and *how
   it's invoked* — not how it works inside. Run it; confirm it fails — and
   **state the failure**: quote the failing assertion/message and check it is
   the *expected* reason. (For brand-new API the first red is normally a
   compile error — the symbol doesn't exist yet; that is expected. Stub the
   minimal declaration and re-run so the red becomes the failing assertion.)
   A compile error in *existing* code, a missing import, or an unrelated
   crash is a red for the wrong reason — it proves nothing about the
   behaviour, so fix the test and re-run until it is red for the right reason.
3. **Make it pass** — change the system to satisfy that test with the simplest
   thing that works. Nothing more; resist solving items still on the list.
4. **Optionally refactor** — improve names, structure, and duplication while every
   test stays green. Skip if there's nothing to improve.
5. **Repeat** — next item, until the list is empty.

## Separate interface from implementation

A test fixes a *decision* about the interface (the call shape, inputs, outputs)
and should be silent about the internals. Tests that assert on private mechanics
break under refactoring and defeat step 4.

## Anti-patterns (don't)

- **Tests without assertions** — a test that invokes but asserts nothing proves
  nothing.
- **Pre-converting the whole list to code** — write one test, learn, then the
  next. Batching tests locks in design decisions before you've learned anything.
- **Mixing refactor into make-it-pass** — keep "make it work" and "make it clean"
  as separate steps on either side of green.
- **Premature abstraction from duplication** — a little duplication across two
  green tests is fine; abstract when the shape is clear, not at the first repeat.

## In this codebase (TMDb)

Apply the loop with the project's tooling and conventions:

- **Framework:** Swift Testing — `@Suite`, `@Test`, `#expect`, `#require`. Never
  force-unwrap in tests; unwrap optionals with `try #require(...)`.
- **Run tests via the delegated skills**, not `make` directly, so output stays
  out of context: `/test` (unit) and `/integration-test` (live API). Re-run after
  each red→green and after refactoring.
- **Both layers are required for new behaviour.** Unit tests with JSON fixtures
  AND integration tests against the live API — put both kinds of items on the
  test list from the start.
- **Models / new endpoints:** when the test list involves decoding, the fixture
  must exercise **every** decode branch (all N optional appended properties, plus
  a paired "without appended data" test that asserts they're `nil`). Use the TMDb
  MCP server (`mcp__tmdb__*`) to fetch **real** API responses for fixtures rather
  than inventing JSON — see `.claude/docs/tmdb-api.md` → "Workflow for New
  Endpoints".
- **Bug fixes:** the first item on the list is a test that **reproduces the bug**
  (red), then the fix (green) — never fix first.
- **New public API:** the test list should include the doc/DocC and README
  updates as completion items, even though they aren't tests (per the
  `document-swift` skill's consistency checklist).

## When NOT to use it

Pure refactors with existing coverage, formatting, config/CI edits, and docs-only
changes don't start from a new failing test — keep the existing tests green
instead. TDD is for *new behaviour* and *bug fixes*.