test-driven-development — red, green, refactor

The rule: no production code without a failing test first. A test written after the code passes immediately — and a test you never saw fail proves nothing: it may test the wrong thing, test the implementation instead of the behavior, or miss the exact case you got wrong.

Already wrote code before the test? Stash or delete it, write the test, watch it fail, then re-implement. Don't keep it open "as reference" — that is writing tests after, with extra steps.

The cycle

1. RED — write one failing test

One behavior per test, named for the behavior ("rejects a receipt line with zero quantity", not "test1"). Test real code; mock only what you cannot run (network, clock). Copy setup from a sibling test file in the same package.

Where tests live: packages/{pkg}/src/**/*.test.ts or apps/erp/app/modules/{module}/__tests__/ (match the neighbors). Runner is vitest via the @carbon/config preset.

2. Verify RED — watch it fail (mandatory, never skip)

pnpm --filter <pkg> exec vitest run <path/to/file.test.ts>
# Expected: FAIL — assertion failure for the missing behavior

• Fails with an assertion about the missing behavior → proceed.
• Passes → it tests existing behavior; rewrite the test.
• Errors (import/type/syntax) → fix the error, re-run until it fails correctly.
• Carbon gotcha: vitest runs with passWithNoTests: true — a green run that collected 0 tests proves nothing. Check the test count in the output.

3. GREEN — minimal code to pass

Write the simplest code that makes the test pass. No extra options, no speculative parameters, no refactoring of neighboring code, nothing the test doesn't demand.

pnpm --filter <pkg> exec vitest run <path/to/file.test.ts>   # your test passes
pnpm --filter <pkg> test                                     # the package still passes

Test fails → fix the code, not the test. Other tests fail → fix now, not later.

4. REFACTOR — only while green

Remove duplication, improve names, extract helpers. No new behavior. Re-run the package tests after. Then loop to the next failing test.

After editing tests, also typecheck the package — pnpm exec turbo run typecheck --filter=<pkg> (never whole-repo). The repo uses noUncheckedIndexedAccess: indexed access in assertions needs optional chaining (rows[0]?.id), and that only surfaces in typecheck, not in the test run.

Bug fixes

A bug fix is TDD with the test written from the bug report: the failing test reproduces the bug, the fix turns it green, and the test stays as the regression guard. Never fix a bug without one (see /fix, which enforces this).

Rationalizations — all of them mean "write the test first"

Done when

• Every new behavior has a test you watched fail, for the right reason
• pnpm --filter <pkg> test green, with a non-zero collected-test count
• pnpm exec turbo run typecheck --filter=<pkg> green
• Output pristine — no stray warnings/errors you introduced

When adding mocks or test utilities, read testing-anti-patterns.md first — it covers testing mock behavior instead of real behavior, test-only methods on production classes, and mocking without understanding the dependency.