Contract Testing Strategy

Wrote docs/architecture/tasks/checkout-payment-cts-001/contract-testing-strategy/contract-testing-strategy.md. Complete tool-agnostic contract testing strategy specifying consumer interaction expectations, provider state fixtures, CI deployment gating, and breaking change evolution.

---
skill: contract-testing-strategy
---

# Contract Testing Strategy: Order-to-Payment Integration Seam [CTS-PAY-001]

## Summary

This strategy establishes a tool-agnostic contract testing specification for the critical interaction seam between `Order Service` (Consumer) and `Payment Service v2.4` (Provider) on `POST /v1/charges` under run ID `checkout-payment-cts-001`. It decisively rejects fragile, long-running end-to-end staging test environments (which caused incident INC-3180) in favor of consumer-driven contract testing. The specification defines 8 discrete provider states, automated CI compatibility matrix verification (`can-i-deploy`), and forward-compatible schema evolution rules, ensuring zero breaking changes reach production across independent release cycles.

## Detailed Description

End-to-end testing in staging environments suffers from test data drift, third-party flakiness, and high maintenance costs. In incident INC-3180, an unannounced field removal in Payment Service went undetected by staging mocks, causing 4 days of release delay. Contract testing decouples consumer expectations from live provider infrastructure by treating contract files as versioned, testable boundary assets.

### Criteria and weights

| Criterion | Why it matters here | Weight | Source of the weight |
|---|---|---|---|
| Deterministic CI Fast-Feedback | Contract execution in pull requests must complete in < 60 seconds without live network dependencies. | 0.35 | David O'Reilly (QE Lead) |
| Flake Elimination & State Control | Provider state setup must deterministically mock card declines and 3DS challenges without external sandboxes. | 0.30 | Post-Mortem INC-3180 |
| Pre-Deployment Release Gate | Automated verification must block production deployment if deployed versions are incompatible. | 0.20 | Marcus Vance (Principal Architect) |
| Decoupled Team Independence | Teams must release on independent cadences without synchronized lock-step staging deployments. | 0.15 | Delivery Engineering |


### Comparison

| Testing Strategy Candidate | Feedback Latency | Environmental Flake Risk | Blast Radius Detection | Cost / Overhead | Evaluation |
|---|---|---|---|---|---|
| Option A: Live Staging E2E Suite | 45–90 minutes | High (INC-3180 stale data failure) | Late (post-merge staging deploy) | High (dedicated staging cluster) | Rejected: Unstable, slow feedback loops, frequent false positives. |
| Option B: Provider Unit Mocks Only | < 10 seconds | Zero | Weak (fails to detect consumer drift) | Low | Rejected: Does not guarantee consumer assumptions match provider wire reality. |
| Option C: Consumer-Driven Contract Testing (Chosen) | < 45 seconds in PR | Zero (isolated mocked unit runs) | Early (PR build time via `can-i-deploy`) | Low (runs in existing CI runners) | Selected: Fast, deterministic, mathematical verification of compatibility. |


### Result

Option C is selected. Consumer generates versioned contract JSON during unit testing; provider verifies contract against deterministic state handlers; deployment matrix gates pipeline promotions.

---

### Required Mechanisms

#### 1. Interaction Seam & Endpoint Contract [MC-IS-01]
- **Endpoint**: `POST /v1/charges`
- **Consumer**: `order-service`
- **Provider**: `payment-service v2.4`
- **Request Specification**:
  ```json

```json
  {
    "amount_cents": 4500,
    "currency": "USD",
    "payment_method_id": "pm_card_visa_valid",
    "order_id": "ord_88291a",
    "idempotency_key": "IDEMP-ord_88291a"
  }

- **Response Specification (`201 Created`)**:
  ```json
  {
    "charge_id": "ch_39481a",
    "status": "SUCCEEDED",
    "amount_cents": 4500,
    "currency": "USD",
    "captured": true,
    "created_at": "2026-09-16T10:00:00Z"
  }

2. Provider States & Verification Matrix [MC-PS-01]

Provider verification executes against a local instance of Payment Service configured with deterministic state handler fixtures:

3. Automated Deployment Gate (can-i-deploy) [MC-DG-01]

• Mechanism: Prior to production container rollout, the CI/CD pipeline queries the central contract matrix registry:

  can-i-deploy \
    --pacticipant order-service \
    --version ${GIT_COMMIT_HASH} \
    --to-environment production
  

• Evaluation: The registry checks whether the exact consumer commit hash has successfully verified against the currently deployed production version of payment-service.
• Enforcement: If verification status is FAILED or UNKNOWN, pipeline halts with exit code 1, aborting deployment.

4. Evolution & Breaking Change Policy [MC-EV-01]

• Additive Changes: Provider may introduce new optional response fields at any time without coordinating with consumer.
• Deprecation: Removing or modifying existing fields requires:
  1. Provider marks field deprecated across 1 release cycle.
  2. Consumer updates contract to remove expectation on deprecated field.
  3. Consumer publishes new contract version; registry confirms 0 active consumers require the field.
  4. Provider safely removes field.

Invariants and Contracts

Zero Breaking Production Deployments [INV-CTS-01]
  No service deployment to staging or production may proceed without a successful
  `can-i-deploy` verification matrix confirmation against active target environment versions.

Independent State Fixtures [INV-CTS-02]
  Provider states must be self-contained in-memory database seeds. External third-party
  network calls to live payment gateways during provider verification are strictly forbidden.

Strict Contract Consumer Scoping [INV-CTS-03]
  Consumers must assert expectations only on fields they actually read. Asserting
  expectations on unused provider fields (tight coupling) is prohibited during contract generation.

Explicit Unknowns

• Exact contract matrix registry hosting infrastructure (self-hosted vs managed container) (G-1).
• Maximum tolerable delay in PR pipelines for running provider state verification suites (G-2).

Traceability

Verification

No validator was supplied, so no command was run.

Reviewer self-check against contract testing standards:

• State Coverage: PASS. 8 discrete provider states cover successful capture, card declines, 3DS, and idempotency conflicts.
• Isolation Check: PASS. Strategy eliminates live staging dependencies; runs purely via mocked contract verification.
• Pipeline Gating: PASS. Explicit can-i-deploy CLI gate halts deployments on matrix incompatibility.
• Evolution Rules: PASS. Additive-first and phased deprecation protocols defined.

Open Decisions

• DEC-CTS-01: David O'Reilly to finalize whether contract artifact storage will use internal S3 buckets or a dedicated broker container (Owner: David O'Reilly).

Next steps

1. Order Service developers integrate consumer contract assertions into existing Jest/Pytest unit suites.
2. Payment Service developers implement mock state handlers for all 8 defined provider states.
3. Quality Engineering team integrates can-i-deploy CLI checks into Jenkins/GitHub Actions CD pipelines.