documenting-test-suites

Start with a quickstart that gets a stranger from fresh clone to green run: prerequisites with versions, install, environment setup, run command, and expected results. Validate it by following it yourself on a clean clone in a fresh shell, then add conventions, a tag glossary, and decision records.

A quickstart with copy-pasteable commands, expected run results with rough counts and duration, conventions a reader would otherwise get wrong, CI workflow and artifact details, known coverage gaps, and links to architecture decision records. Leave out anything the environment or package.json already states.

Create a glossary with one row per tag covering its meaning, where it runs, and who may add it, plus a CI filter mapping table showing what each --grep filter actually selects. Require every E2E test to carry exactly one priority tag and audit tag counts quarterly.

A short numbered document capturing one test architecture decision: the context that forced it, the decision, alternatives considered with rejection reasons, consequences, and conditions for revisiting. Records are immutable; a changed decision gets a new record that supersedes the old one.

Skip anything the environment already states, such as npm script lists, framework tutorials, and config values, because those drift and mislead. Document only what a reader cannot find by looking: unwritten conventions, decision rationale, and gotchas no config file reveals.