📝 Require labeled AAA blocks in tests

Rule in CONTRIBUTING.md; decision, why and rejected unlabeled
ordering in development/testing.md.
This commit is contained in:
tmu committed 2026-09-16 16:00:43 +00:00
1 parent 34567856a5
commit 62a5599ab3
2 files changed
+33

No files matched your search

+27
View File
@@ -36,6 +36,33 @@ The runner is `node --test --strip-types "src/**/*.test.ts"` and the tiers are i
build step, and the runner relies on the `.ts` import-extension convention (see
[tooling.md](./tooling.md#source-imports-use-ts-extensions)).
## AAA ordering
The rule is in
[CONTRIBUTING.md § Testing discipline (type-driven)](../CONTRIBUTING.md#testing-discipline-type-driven).
#### Decision (2026-09)
Test bodies read arrange → act → assert: inputs (the factory) set up first, the
subject exercised once from them, all checks last — types then runtime. The
blocks are labeled with `// Arrange` / `// Act` / `// Assert` comments and
separated by a blank line; an empty block drops its label.
#### Why
- Interleaved setup/checks hide what runs vs. what is observed; the eye
re-reads the block to find the seams.
- A factory built mid-test invites a second throwaway call of the subject;
arranging it once makes the positive construction and the negative
`Parameters<…>` check share one source of truth.
- Labels make the seams explicit, not inferred — grep-able and reviewable
without reading the statements.
#### Rejected
- Unlabeled ordering (bare blank lines): the seams still have to be found by
reading; the labels cost nothing.
## Known issues
- The type-aware linter misidentifies `expectTypeOf()` as a floating promise, so