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, 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, 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 fakes, or call order. Prefer making an invalid state unrepresentable to testing
SQL semantics at the interceptor or domain level with fakes. One table-driven test per behaviour; extend the table that it is rejected.
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. 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 ## Invariants