ADR 0002: Mandatory API Testing Policy

Ratification

Adopted before ADR 0018. There was no separate ratification process. Git history for this file on main is the record.

• Discussion Issue: not recorded (before ADR 0018)
• Merge PR: see git history for this file
• Accepted: as merged to main

Context

Why this matters: Automated tests are the cheapest place to find bugs. A bug in CI costs minutes; in production it costs trust, on-call time, and data fixes. Manual “click through” does not scale as the API grows or more people touch the code.

API tests are part of the contract: if there is not at least one success test and one failure test, the change is not complete.

Decision

Endpoint-level automated tests are mandatory before release:

1. Any API change must include tests.
2. Endpoint coverage must include at least:
   • one success scenario (happy path),
   • one failure scenario (validation or business error).
3. Changes without tests are considered incomplete.
4. Quality gates must enforce test execution before deployment.

Implementation in this repository

• Test framework: pytest
• Test location: tests/
• API baseline tests:
  • tests/api/v1/test_user_create.py
• Make targets:
  • make test
  • make test-one path=...
  • make release-check (includes tests via make verify)
  • make release DEPLOY_CMD="..." (always runs release-check first)

Consequences

Positive

• Early regression detection.
• Higher confidence in API contract stability.
• Faster onboarding with executable behavior examples.

Trade-offs

• Additional implementation effort for each change.
• Slightly longer pipeline execution time.

Usage

Typical flow:

        make test
        make test-one path=tests/api/v1/test_user_create.py
        make release-check
      

Broader strategy (layers, contract vs load): ADR 0012: Testing strategy — automated, contract, and load.

Page history