5.5Test Documentation in the Repo

Co-Locating Test Docs with Test Code

The most effective place for test documentation is next to the tests themselves.

Repository structure example:

project/
├── src/
│   ├── checkout/
│   │   ├── checkout.ts
│   │   └── checkout.test.ts
│   └── payment/
│       ├── payment.ts
│       └── payment.test.ts
├── tests/
│   ├── e2e/
│   │   ├── checkout.spec.ts
│   │   └── README.md          ← What these tests cover
│   ├── performance/
│   │   ├── load-test.js
│   │   └── README.md          ← How to run, thresholds, history
│   └── test-data/
│       ├── fixtures/
│       └── README.md          ← How test data works
├── docs/
│   ├── test-strategy.md       ← Overall test strategy
│   ├── test-environments.md   ← Environment setup guide
│   └── runbooks/
│       ├── deploy-verification.md
│       └── incident-response.md
└── README.md

Benefits of co-location:

• Developers see test documentation when they change test code
• Documentation changes are reviewed in the same PR as code changes
• Git blame shows who wrote the documentation and when
• Documentation is always version-matched with the code

What to Put in the Repo vs. External Wiki

In the Repo	In the Wiki/External
Test strategy and approach	Meeting notes and decisions
How to run tests	Team processes and ceremonies
Test data documentation	Onboarding guides
Environment setup	Architecture decision records
Runbooks for automated processes	Troubleshooting guides (evolving)
API test documentation	Cross-team documentation