From 7c7129eefbbca40a28eb4b28b99f86fecc3a463b Mon Sep 17 00:00:00 2001 From: Sam Catlow Date: Fri, 13 Nov 2026 03:16:15 +1100 Subject: [PATCH] docs(agents): say how tests are written --- CLAUDE.md | 27 +++++++++++++++++++++++---- 1 file changed, 23 insertions(+), 4 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 8fa3e66eb..93d9799c4 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -125,10 +125,29 @@ The default for a change is no new test. Write one only when: A test that exists must catch a real regression, survive refactoring, run fast, and be cheap to keep. Never test wiring, constants, defaults, struct shapes, -fakes, or call order. No test opens a real database or needs Docker; test -SQL semantics at the interceptor or domain level with fakes. One table-driven test per behaviour; extend the table -instead of adding a second test. Prefer making an invalid state unrepresentable -to testing that it is rejected. Test helpers live in `_test.go` files only. +fakes, or call order. Prefer making an invalid state unrepresentable to testing +that it is rejected. + +How to write one: + +- **Prove it.** Run the new test against the code before the fix and see it + fail. A test that passes either way proves nothing: delete it. When a bug + can't be reproduced deterministically (a race, say), fix it with an API that + rules it out and don't add a test. +- **One table per behaviour.** Extend the table instead of adding a second test. + Name the test after the behaviour, and say in its comment what regression it + guards. +- **Same gate as production.** Tests pass golangci-lint, gosec included, with no + exclusions for test files. Fix what the linter finds. A fixture that has to + look like a secret (a key the redaction must catch, a URL with a password the + parser must reject) uses a plainly fake value and a `//nolint:gosec` saying + what it tests. +- **Isolated.** Use `t.TempDir()` and `t.Setenv`, never host state. A test that + commits with git sets `GIT_CONFIG_GLOBAL` to `os.DevNull`. No test opens a + real database or needs Docker: test SQL semantics at the interceptor or domain + level with fakes. Files are written `0o600`, or `0o700` for a script. +- **Shared setup in helpers.** When several tests repeat the same setup, put it + in a helper in a `_test.go` file, never in production code. ## Invariants