📝 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:
1 parent
34567856a5
commit
62a5599ab3
2 files changed
+33
No files matched your search
@@ -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
|
||||
|
||||
Reference in new issue
Block a user