# ADR 0012: Testing Strategy and Quality Gates

- Status: Accepted
- Date: 2026-03-11
- Owners: QA/Quality Engineering Team, Platform Team, Architecture Group
- Related:
  - `docs/adr/0003-financial-ledger-invariants.md`
  - `docs/adr/0004-idempotency-and-locking-strategy.md`
  - `docs/adr/0005-api-error-and-idempotency-response-contract.md`
  - `docs/adr/0007-observability-and-audit-traceability-standard.md`
  - `docs/non-functional-slo.md`
  - `docs/phase-tracker.md`

## Context
The wallet platform spans multiple OTP apps and high-risk financial workflows. Without a formal test strategy and quality gates, regressions in ledger correctness, idempotency, security, and integration behavior may reach production.

This ADR defines test layers, mandatory coverage, and release-blocking quality gates.

## Decision
Adopt a risk-based, multi-layer validation model with hard gates for critical domains.

Core decisions:
1. Critical financial paths require stronger testing than non-critical features.
2. Test types are mapped to architecture layers and failure modes.
3. CI quality gates block promotion when critical checks fail.
4. Release readiness requires functional, non-functional, and operational test evidence.

## Test Pyramid for Wallet Platform
1. Unit tests (highest volume):
- Domain rules, command handlers, validations, pure functions.

2. Component/service tests:
- OTP app public interfaces and boundary behavior.

3. Contract tests:
- API envelopes, event schemas, adapter ports, error code contracts.

4. Integration tests:
- Cross-app workflows (auth -> transfer -> ledger -> events -> notifications).

5. End-to-end scenario tests:
- User/business critical journeys in staging-like environment.

6. Non-functional tests:
- performance, resilience, concurrency, recovery, security.

## Mandatory Test Suites by Risk Area
Financial correctness:
- Ledger invariant property tests.
- Transfer state-machine transition tests.
- Idempotency replay and conflict tests.

Security:
- Auth token and refresh rotation tests.
- OTP/MFA enforcement tests.
- Secret redaction and access-control tests.

Integration:
- Adapter contract tests per provider.
- Webhook signature/replay tests.
- Reconciliation mismatch handling tests.

Observability and audit:
- Trace propagation tests.
- Mandatory audit event coverage tests.
- Alert trigger simulation tests for critical failures.

## Environment Strategy
- Local/dev: fast unit and component tests.
- CI ephemeral: contract + integration subsets.
- Staging: full integration and non-functional suites.
- Pre-prod (or prod-like): canary rehearsal and rollback drills.

Test data policy:
- Synthetic and masked datasets only.
- Deterministic fixture generation for reproducibility.

## Quality Gates (Blocking)
Gate A: Pull Request Gate
- Unit tests pass.
- Static analysis/lint checks pass.
- Required contract tests pass for changed interfaces.

Gate B: Merge-to-Main Gate
- Component and integration tests pass.
- No critical security scan findings unresolved.
- Migration checks pass for schema-impacting changes.

Gate C: Release Candidate Gate
- Full critical-path integration suite pass.
- Performance baseline check within thresholds.
- Observability/audit checks pass.
- Rollback plan validated.

Gate D: Production Promotion Gate
- Canary metrics within SLO guardrails.
- No new critical incident indicators.
- Release approval from required owners.

## Coverage and Evidence Policy
Coverage principles:
- Focus on critical path and risk coverage, not line coverage alone.
- Maintain minimum thresholds for domain-critical apps.

Evidence requirements:
- CI artifacts for all gate runs.
- Test report traceable to release version.
- Failed-test triage and disposition records.

## Flaky Test and Defect Policy
- Flaky tests tracked in dedicated backlog with owner and SLA.
- Repeated flaky tests become release blockers in critical paths.
- Critical defects require root-cause and regression test addition.

## Performance and Resilience Baselines
Mandatory recurring tests:
- Concurrent transfer load tests.
- Queue backlog and worker saturation tests.
- Provider outage/latency chaos scenarios.
- Recovery and replay correctness tests.

Baseline comparison:
- Each release candidate compared to prior stable baseline.
- Significant regression requires explicit waiver approval.

## Security Test Baseline
- SAST/dependency checks in CI.
- DAST/penetration validation before major releases.
- Auth abuse scenarios (bruteforce, replay, token misuse).

## Roles and Responsibilities
- Domain teams: own unit/component tests and domain regressions.
- QA/Quality Engineering: own integration/E2E strategy and release test orchestration.
- Platform/SRE: own non-functional and rollback rehearsal validation.
- Security: own security test sign-offs and vulnerability policy enforcement.

## Consequences
Positive:
- Lower production risk for financial and compliance-critical flows.
- Faster root-cause isolation through layered tests.
- Clear release governance and accountability.

Trade-offs:
- Increased CI/runtime cost and maintenance effort.
- Requires disciplined test ownership across teams.

## Acceptance Criteria
1. Mandatory test suites are implemented for critical domains.
2. CI gates enforce blocking policy across PR, merge, and release stages.
3. Non-functional and security test evidence is included in release artifacts.
4. Flaky-test and defect triage process is active with ownership.
5. Phase 8 readiness includes successful quality-gate drill evidence.