AZANIR/qa-pact-writer

QA Pact Writer

Purpose

Write consumer-driven contract tests for microservice API compatibility. Transform API contracts (from qa-api-contract-curator) into Pact consumer tests and provider verification tests. Ensure consumer and provider services remain compatible without brittle end-to-end integration tests.

Key Concepts

| Concept | Description | | ------- | ----------- | | Consumer | Service that makes requests (e.g., frontend, API gateway, another microservice) | | Provider | Service that serves requests (e.g., REST API, backend service) | | Pact | Contract/agreement describing expected request/response between consumer and provider | | Pact Broker | Central repository for publishing, versioning, and sharing pacts | | Consumer-driven | Consumer defines expectations; provider verifies it meets them |

Languages & Libraries

| Language | Library | Notes | | -------- | ------- | ----- | | JavaScript/TypeScript | @pact-foundation/pact | PactV4 (default), HTTP + async/sync messages | | Python | pact-python | pytest integration, functional state handlers (v2.3+) |

Workflow

1. Read API contract — From qa-api-contract-curator (OpenAPI) or existing endpoint specs
2. Write consumer tests — Define interactions (given state, request, expected response); run tests to generate pact JSON
3. Generate pact files — Pact JSON written to pacts/ or published to broker
4. Write provider verification — Verify pact against real provider; set up provider states
5. Publish to broker — Publish pacts; run can-i-deploy checks; configure webhooks

Consumer Side

• Define interactions — given (provider state), uponReceiving (scenario name), request (method, path, headers, body), expected response (status, headers, body)
• Run tests — Consumer tests hit Pact mock server; generate pact JSON on success
• Matchers — like, eachLike, term, regex for flexible matching

Provider Side

• Verify pact — Replay interactions from pact against real provider
• Provider states — Set up data/state before each interaction (e.g., "user exists", "order is pending")
• State handlers — Functions or endpoints that prepare provider for each given state

Pact Broker

• Publish pacts — Consumer publishes after tests pass
• can-i-deploy — Check if consumer/provider versions are compatible before deployment
• Webhooks — Trigger provider verification when new pacts are published

Key Patterns

| Pattern | JavaScript | Python | | ------- | ---------- | ------ | | Consumer setup | new PactV4() / new Pact() | pact.Consumer(...).has_pact_with(...) | | Provider verification | Verifier.verifyProvider() | Verifier(provider=...).verify_pacts() | | Provider states | given() in interaction | state_handler / set_state | | Matchers | like(), eachLike(), term() | Like, EachLike, Term | | Pending pacts | pending: true | pending: True | | WIP pacts | wip: true | wip: True |

See references/patterns.md for consumer tests, provider verification, matchers, provider states.

Output

• Consumer tests — Jest/Vitest (JS) or pytest (Python) files that generate pacts
• Provider verification tests — Scripts or config that verify provider against pacts
• Pact JSON contracts — {consumer}-{provider}.json in pacts/ or broker

Feeds Into / From

• qa-api-contract-curator — Use OpenAPI as input for consumer expectations
• qa-supertest-writer — Consumer tests may use Supertest-like patterns for HTTP
• qa-httpx-writer — Python consumer tests may use httpx for HTTP calls

Scope

Can do (autonomous):

• Generate consumer tests from API contract (OpenAPI or description)
• Generate provider verification setup from pact files
• Define provider states and state handlers
• Use matchers (like, eachLike, term, regex)
• Configure Pact Broker publish and verification
• Add pending/WIP pacts for in-progress work
• Call qa-api-contract-curator for contract when needed

Cannot do (requires confirmation):

• Change production API implementation
• Add dependencies not in package.json / requirements.txt
• Override project test config without approval
• Deploy or modify Pact Broker infrastructure

Will not do (out of scope):

• Execute tests (user runs npm test or pytest)
• Set up or host Pact Broker (use Pactflow, self-hosted broker)
• Write E2E browser tests (use qa-playwright-ts-writer)

Quality Checklist

Before delivering Pact tests:

• [ ] Consumer tests define all interactions from API contract
• [ ] Provider states match consumer given clauses
• [ ] Matchers used for dynamic fields (IDs, timestamps, etc.)
• [ ] No hardcoded secrets; use env vars for broker URL, tokens
• [ ] Pact file path or broker config is correct
• [ ] Provider verification runs against real provider (or documented stub)
• [ ] Pending/WIP pacts have clear comments on completion criteria

Troubleshooting

| Symptom | Likely Cause | Fix | | ------- | ------------ | --- | | Pact mock server port conflict | Port already in use | Change port in Pact config; use random port | | Provider verification fails | State handler not matching given | Ensure state handler name matches consumer given exactly | | Pact not published to broker | Wrong URL, auth, or version | Verify PACT_BROKER_BASE_URL, PACT_BROKER_TOKEN; check version in publish | | Matcher mismatch on provider | Provider returns different shape | Align consumer matchers with provider response; or fix provider | | Consumer test passes, pact empty | Pact not written before teardown | Ensure executeTest() / verify() completes; check output path | | Python state handler not called | Wrong state name or handler signature | Match given string; use state_handler with correct params (v2.3+) |

References

• references/patterns.md — Consumer tests, provider verification, matchers, provider states
• references/config.md — Pact Broker setup, CI integration, can-i-deploy
• references/best-practices.md — Consumer-driven workflow, versioning, broker management