docs(agents): say how tests are written

This commit is contained in:
sam committed 2026-11-13 03:16:15 +11:00
1 parent db346b159d
commit 7c7129eefb
1 file changed
+23 -4
+23 -4
View File
@@ -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