docs(agents): say how tests are written
This commit is contained in:
1 file changed
+23
-4
@@ -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
|
||||
|
||||
|
||||
Reference in new issue
Block a user