ADR-0008: Define a layered testing strategy for critical flows
- Status: Accepted
- Date: 2026-03-25
- Deciders: avm
- Supersedes:
- Superseded by:
Related ADRs
Context
Integration, orchestration, and policy failures are expensive. Unit tests alone are not enough, while relying only on e2e tests makes feedback slow and expensive.
Decision
The repository uses a layered testing strategy:
- unit tests for domain logic and pure functions;
- integration tests for storage, message bus, and external adapters;
- contract tests for APIs and events;
- workflow tests for state transitions and orchestration;
- smoke or e2e tests for critical end-to-end scenarios;
- security regression tests for sensitive flows.
Tests live as close as possible to the owning code, while cross-app scenarios live in root-level tests/.
Consequences
Positive
- confidence in platform-critical flows increases;
- regressions are caught at the right level faster;
- the test strategy stays balanced in cost and signal quality.
Negative
- test infrastructure becomes more expensive;
- workflow and e2e tests can be slow and fragile.
Neutral
- high coverage alone does not guarantee correct architecture or policy behavior.
Alternatives considered
- relying only on unit tests;
- testing critical flows mostly by hand;
- relying only on e2e tests and skipping lower layers.
Follow-up work
- [ ] define the test pyramid
- [ ] define the golden scenarios
- [ ] document shared test fixtures