mh-cto-sdlc-contract-test-design

Contract Test Design

Mode: synthesize-first (D34). Read the integration contracts and system diagram. Derive consumer/provider relationships. Ask only where the contract boundary or failure behavior is ambiguous.

Elite character: Contract tests protect the assumption that "if my service sends this, the other service handles it correctly." Without contract tests, integration failures appear in staging or production — not in CI. The cost of a late integration failure is 100× the cost of a contract test. Every external boundary is a contract. Every contract is a potential break point.

Step 1 — Load Artifacts

Confirm present:

• Integration contracts (integration-contracts.md) ✓ / ✗ — REQUIRED
• System diagram (system-diagram.md) ✓ / ✗ — REQUIRED
• Test strategy (test-strategy.md) ✓ / ✗

Missing integration contracts: "Cannot design contract tests without integration-contracts.md. Run /mh-cto-sdlc-integration-design first."

Step 2 — Map Consumer/Provider Relationships

For each integration identified in integration-contracts.md, establish the contract relationship:

For each integration:

• Consumer: [service or client that initiates or depends on the integration]
• Provider: [service that fulfills the request or produces the event]
• Boundary type: REST API | gRPC | Message/Event | Webhook | SDK call
• Owned by: [internal — we control both sides] / [external — we control only the consumer]

Consumer-driven contract principle: The consumer defines what it needs from the provider — not what the provider offers. This is the inverse of schema-first API design. If the provider changes a field the consumer depends on, the contract test fails.

For external providers (third-party APIs, SaaS), note: we cannot run provider-side contract tests. We design consumer-side pact tests with recorded responses and provider replay.

Step 3 — Design Contract Per Integration

For each integration, produce the contract specification:

Contract: {Consumer} → {Provider}

Consumer: {service name}
Provider: {service name or external service}
Boundary: {REST / gRPC / Event / Webhook}

Interactions:
  1. {Interaction name}
     Given: {provider state required for this interaction}
     When: {what the consumer sends — request or event shape}
     Then: {what the consumer expects in return — response or side effect}
     On failure: {circuit breaker / retry / fallback behavior — from integration-contracts.md}

  2. {Interaction name — happy path}
     ...

  3. {Error interaction}
     Given: {provider is degraded or returns error status}
     When: {consumer request}
     Then: {expected graceful degradation behavior}

Idempotency verification: For async integrations, include:

• Interaction sending duplicate events (same idempotency key)
• Expected: provider deduplicates, consumer does not double-process

Dead letter scenario: For queue-backed integrations, include:

• Interaction where provider rejects the message
• Expected: message goes to dead letter queue, alert is triggered

Step 4 — Identify Missing Contracts

Scan the system diagram for integration boundaries not covered in integration-contracts.md. Flag them:

"The system diagram shows {service A} calling {service B} via {mechanism}, but no integration contract exists. Either add the contract in integration-contracts.md or document why this integration does not need a contract test."

Step 5 — Define Contract Test Infrastructure

Specify what infrastructure is needed to run these contract tests:

Provider mocks: For each external provider — what mock/stub approach?

• Record-replay (Pact, WireMock): suitable for stable external APIs
• Hand-crafted mocks: suitable for simple, infrequently-changing contracts
• Real sandbox: when the provider offers a test environment

Contract verification:

• For internal services (we control both): bi-directional pact verification in CI
• For external services: consumer-side only, with periodic replay against real sandbox

Test isolation: Contract tests must run without real network calls. All provider interactions are intercepted.

Step 6 — Write Output

Save to _mh-output/cto/sdlc/contract-test-design/{YYYY-MM-DD}_{r###}_contract-test-spec.md:

# Contract Test Specification

**Product:** {name}
**Date:** {date}

---

## Consumer/Provider Map

| Consumer  | Provider       | Boundary | Control  | Contract Count |
| --------- | -------------- | -------- | -------- | -------------- |
| {service} | {service}      | REST     | Internal | {N}            |
| {service} | {external API} | REST     | External | {N}            |

## Contracts

### {Consumer} → {Provider}

{Full contract spec from Step 3}

---

## Missing Contract Flags

{Any uncontracted boundaries from Step 4}

## Test Infrastructure

| Provider   | Mock Strategy      | Verification Mode    |
| ---------- | ------------------ | -------------------- |
| {service}  | Pact record-replay | Bi-directional in CI |
| {external} | WireMock stub      | Consumer-side only   |

## Contract Test Counts

Total contracts: {N}
Interactions per contract (avg): {N}
External provider contracts: {N}

Step 7 — Present Summary

Contract Test Design complete.

Integrations covered: {N} integrations, {N} contracts, {N} total interactions.

External provider contracts: {N} — consumer-side only (no provider verification).

Infrastructure required: {mock/stub approach summary}.

Gaps flagged: {N} uncontracted boundaries (if any).

Next step: Run /mh-cto-sdlc-test-data-arch to design the test data strategy.