Runbook: Tests Failing

Trigger

• make test fails.
• make verify fails on test stage.
• CI pipeline reports failing tests.

Fast triage

1. Run full suite: make test.
2. Run failing file/node only: make test-one path=tests/....
3. Check static checks: make lint-check, make type-check.

Most common causes

• API shape changed; tests still expect old fields or payloads.
• Fixtures are out of date after schema or model changes.
• Local DB was not migrated before tests.
• Flaky order or shared state between tests.

Recovery steps

1. Ensure DB state is up to date: make migrate.
2. Re-run targeted test: make test-one path=....
3. Fix fixture/data setup in tests/conftest.py if schema changed.
4. Align assertions with current error contract (code, key, source).
5. Re-run full suite: make test.

Exit criteria

• make test passes locally.
• make verify passes.
• Any changed behavior is reflected in docs/examples.

Follow-up

• If the fix changes policy (contracts, versioning, test rules), add or update an ADR.
• If it is a new failure pattern, add a short note to this runbook.

Page history