Test Design Reviewer
Review tests as executable specifications and safety evidence. Read the tests
before the implementation so their public story can stand on its own, then
inspect the production boundary and repository constraints needed to judge the
claims accurately.
Properties
| Property |
Inspect |
Strong evidence |
| Understandable |
Names, arrange/act/assert flow, domain vocabulary |
The behavior and failure are clear without reconstructing internals |
| Maintainable |
Coupling, duplication, fixtures, public boundaries |
Behavior-preserving refactors do not require unrelated test rewrites |
| Repeatable |
Time, randomness, concurrency, network, shared resources |
Repeated and parallel runs have controlled inputs and cleanup |
| Atomic |
Shared state, ordering, cleanup, failure isolation |
A test can run alone and its failure identifies one behavior |
| Necessary |
Distinct risk or contract protected |
Removing the test would remove meaningful evidence |
| Granular |
Scope of behavior and diagnostic quality |
Assertions describe one coherent outcome; related assertions may stay together |
| Fast |
Measured feedback time at the appropriate layer |
The suite is fast enough for its intended feedback loop |
| First |
Evidence of test-first development |
A captured RED run, development trace, or history demonstrates the test failed for the expected reason before production behavior changed |
Rating
Rate each property Strong, Mixed, Weak, or Not assessed.
- Use exact file locations and observed evidence.
- Do not calculate an aggregate score; unequal risks and repository contexts make a weighted number falsely precise.
- Mark First
Not assessed when only the final tree is available. Static test shape cannot prove chronology.
- Mark Fast
Not assessed unless execution evidence or trustworthy timing is available.
- Prefer the smallest change that strengthens observable behavior. Do not demand one assertion per test, one test per file, or unit tests where a higher-level contract is the honest evidence boundary.
Review Process
- Establish the claimed behavior, test layer, repository policy, and relevant risk.
- Read the tests without implementation and record what a failure would mean.
- Inspect the public production boundary, fixtures, and configured runner.
- Run focused tests or timing only when authorized and useful; report exactly what ran.
- Rate every property with evidence, including
Not assessed where evidence is absent.
- Rank only actionable findings by severity and impact. Include the smallest credible fix.
- Separate test defects from production-design seams and local policy preferences.
Output
## Test design review: [scope]
| Property | Rating | Evidence |
|---|---|---|
| Understandable | Strong/Mixed/Weak/Not assessed | [file:line and reason] |
| Maintainable | ... | ... |
| Repeatable | ... | ... |
| Atomic | ... | ... |
| Necessary | ... | ... |
| Granular | ... | ... |
| Fast | ... | ... |
| First | ... | ... |
### Findings
1. **[severity] — [problem]** (`path:line`)
Impact: [observable risk].
Smallest fix: [action].
### Validation gaps
- [Anything not assessed and the evidence needed]
No findings is a valid result; do not invent work to populate the section.
Source And Attribution
The eight properties are drawn from Dave Farley's
Properties of Good Tests.
This version is a fresh, evidence-based implementation rather than a textual
adaptation of an external skill. Read
references/source-notes.md for the exact
historical provenance and unresolved permission issue in older releases.
1---2name: test-design-reviewer3description: Review test quality using Dave Farley's eight properties of good tests. Use when assessing a test file or suite for understandability, maintainability, repeatability, atomicity, necessity, granularity, speed, and evidence of test-first development.4---56# Test Design Reviewer78Review tests as executable specifications and safety evidence. Read the tests9before the implementation so their public story can stand on its own, then10inspect the production boundary and repository constraints needed to judge the11claims accurately.1213## Properties1415| Property | Inspect | Strong evidence |16|---|---|---|17| Understandable | Names, arrange/act/assert flow, domain vocabulary | The behavior and failure are clear without reconstructing internals |18| Maintainable | Coupling, duplication, fixtures, public boundaries | Behavior-preserving refactors do not require unrelated test rewrites |19| Repeatable | Time, randomness, concurrency, network, shared resources | Repeated and parallel runs have controlled inputs and cleanup |20| Atomic | Shared state, ordering, cleanup, failure isolation | A test can run alone and its failure identifies one behavior |21| Necessary | Distinct risk or contract protected | Removing the test would remove meaningful evidence |22| Granular | Scope of behavior and diagnostic quality | Assertions describe one coherent outcome; related assertions may stay together |23| Fast | Measured feedback time at the appropriate layer | The suite is fast enough for its intended feedback loop |24| First | Evidence of test-first development | A captured RED run, development trace, or history demonstrates the test failed for the expected reason before production behavior changed |2526## Rating2728Rate each property `Strong`, `Mixed`, `Weak`, or `Not assessed`.2930- Use exact file locations and observed evidence.31- Do not calculate an aggregate score; unequal risks and repository contexts make a weighted number falsely precise.32- Mark **First** `Not assessed` when only the final tree is available. Static test shape cannot prove chronology.33- Mark **Fast** `Not assessed` unless execution evidence or trustworthy timing is available.34- Prefer the smallest change that strengthens observable behavior. Do not demand one assertion per test, one test per file, or unit tests where a higher-level contract is the honest evidence boundary.3536## Review Process37381. Establish the claimed behavior, test layer, repository policy, and relevant risk.392. Read the tests without implementation and record what a failure would mean.403. Inspect the public production boundary, fixtures, and configured runner.414. Run focused tests or timing only when authorized and useful; report exactly what ran.425. Rate every property with evidence, including `Not assessed` where evidence is absent.436. Rank only actionable findings by severity and impact. Include the smallest credible fix.447. Separate test defects from production-design seams and local policy preferences.4546## Output4748```markdown49## Test design review: [scope]5051| Property | Rating | Evidence |52|---|---|---|53| Understandable | Strong/Mixed/Weak/Not assessed | [file:line and reason] |54| Maintainable | ... | ... |55| Repeatable | ... | ... |56| Atomic | ... | ... |57| Necessary | ... | ... |58| Granular | ... | ... |59| Fast | ... | ... |60| First | ... | ... |6162### Findings63641. **[severity] — [problem]** (`path:line`)65 Impact: [observable risk].66 Smallest fix: [action].6768### Validation gaps6970- [Anything not assessed and the evidence needed]71```7273No findings is a valid result; do not invent work to populate the section.7475## Source And Attribution7677The eight properties are drawn from Dave Farley's78[Properties of Good Tests](https://www.linkedin.com/pulse/tdd-properties-good-tests-dave-farley-iexge/).79This version is a fresh, evidence-based implementation rather than a textual80adaptation of an external skill. Read81[`references/source-notes.md`](references/source-notes.md) for the exact82historical provenance and unresolved permission issue in older releases.
citypaul