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,
|
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
|
||||||
|
|
||||||
|
|||||||
Reference in new issue
Block a user