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
- Read API contract — From qa-api-contract-curator (OpenAPI) or existing endpoint specs
- Write consumer tests — Define interactions (given state, request, expected response); run tests to generate pact JSON
- Generate pact files — Pact JSON written to
pacts/ or published to broker
- Write provider verification — Verify pact against real provider; set up provider states
- 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:
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 statesreferences/config.md — Pact Broker setup, CI integration, can-i-deployreferences/best-practices.md — Consumer-driven workflow, versioning, broker management
1---2name: qa-pact-writer3description: Generate consumer-driven contract tests using Pact for JavaScript and Python to verify microservice API compatibility between consumer and provider.4---56# QA Pact Writer78## Purpose910Write 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.1112## Key Concepts1314| Concept | Description |15| ------- | ----------- |16| **Consumer** | Service that makes requests (e.g., frontend, API gateway, another microservice) |17| **Provider** | Service that serves requests (e.g., REST API, backend service) |18| **Pact** | Contract/agreement describing expected request/response between consumer and provider |19| **Pact Broker** | Central repository for publishing, versioning, and sharing pacts |20| **Consumer-driven** | Consumer defines expectations; provider verifies it meets them |2122## Languages & Libraries2324| Language | Library | Notes |25| -------- | ------- | ----- |26| **JavaScript/TypeScript** | `@pact-foundation/pact` | PactV4 (default), HTTP + async/sync messages |27| **Python** | `pact-python` | pytest integration, functional state handlers (v2.3+) |2829## Workflow30311. **Read API contract** — From qa-api-contract-curator (OpenAPI) or existing endpoint specs322. **Write consumer tests** — Define interactions (given state, request, expected response); run tests to generate pact JSON333. **Generate pact files** — Pact JSON written to `pacts/` or published to broker344. **Write provider verification** — Verify pact against real provider; set up provider states355. **Publish to broker** — Publish pacts; run can-i-deploy checks; configure webhooks3637## Consumer Side3839- **Define interactions** — `given` (provider state), `uponReceiving` (scenario name), request (method, path, headers, body), expected response (status, headers, body)40- **Run tests** — Consumer tests hit Pact mock server; generate pact JSON on success41- **Matchers** — `like`, `eachLike`, `term`, `regex` for flexible matching4243## Provider Side4445- **Verify pact** — Replay interactions from pact against real provider46- **Provider states** — Set up data/state before each interaction (e.g., "user exists", "order is pending")47- **State handlers** — Functions or endpoints that prepare provider for each `given` state4849## Pact Broker5051- **Publish pacts** — Consumer publishes after tests pass52- **can-i-deploy** — Check if consumer/provider versions are compatible before deployment53- **Webhooks** — Trigger provider verification when new pacts are published5455## Key Patterns5657| Pattern | JavaScript | Python |58| ------- | ---------- | ------ |59| **Consumer setup** | `new PactV4()` / `new Pact()` | `pact.Consumer(...).has_pact_with(...)` |60| **Provider verification** | `Verifier.verifyProvider()` | `Verifier(provider=...).verify_pacts()` |61| **Provider states** | `given()` in interaction | `state_handler` / `set_state` |62| **Matchers** | `like()`, `eachLike()`, `term()` | `Like`, `EachLike`, `Term` |63| **Pending pacts** | `pending: true` | `pending: True` |64| **WIP pacts** | `wip: true` | `wip: True` |6566See `references/patterns.md` for consumer tests, provider verification, matchers, provider states.6768## Output6970- **Consumer tests** — Jest/Vitest (JS) or pytest (Python) files that generate pacts71- **Provider verification tests** — Scripts or config that verify provider against pacts72- **Pact JSON contracts** — `{consumer}-{provider}.json` in `pacts/` or broker7374## Feeds Into / From7576- **qa-api-contract-curator** — Use OpenAPI as input for consumer expectations77- **qa-supertest-writer** — Consumer tests may use Supertest-like patterns for HTTP78- **qa-httpx-writer** — Python consumer tests may use httpx for HTTP calls7980## Scope8182**Can do (autonomous):**83- Generate consumer tests from API contract (OpenAPI or description)84- Generate provider verification setup from pact files85- Define provider states and state handlers86- Use matchers (like, eachLike, term, regex)87- Configure Pact Broker publish and verification88- Add pending/WIP pacts for in-progress work89- Call qa-api-contract-curator for contract when needed9091**Cannot do (requires confirmation):**92- Change production API implementation93- Add dependencies not in package.json / requirements.txt94- Override project test config without approval95- Deploy or modify Pact Broker infrastructure9697**Will not do (out of scope):**98- Execute tests (user runs `npm test` or `pytest`)99- Set up or host Pact Broker (use Pactflow, self-hosted broker)100- Write E2E browser tests (use qa-playwright-ts-writer)101102## Quality Checklist103104Before delivering Pact tests:105106- [ ] Consumer tests define all interactions from API contract107- [ ] Provider states match consumer `given` clauses108- [ ] Matchers used for dynamic fields (IDs, timestamps, etc.)109- [ ] No hardcoded secrets; use env vars for broker URL, tokens110- [ ] Pact file path or broker config is correct111- [ ] Provider verification runs against real provider (or documented stub)112- [ ] Pending/WIP pacts have clear comments on completion criteria113114## Troubleshooting115116| Symptom | Likely Cause | Fix |117| ------- | ------------ | --- |118| Pact mock server port conflict | Port already in use | Change `port` in Pact config; use random port |119| Provider verification fails | State handler not matching `given` | Ensure state handler name matches consumer `given` exactly |120| Pact not published to broker | Wrong URL, auth, or version | Verify `PACT_BROKER_BASE_URL`, `PACT_BROKER_TOKEN`; check version in publish |121| Matcher mismatch on provider | Provider returns different shape | Align consumer matchers with provider response; or fix provider |122| Consumer test passes, pact empty | Pact not written before teardown | Ensure `executeTest()` / `verify()` completes; check output path |123| Python state handler not called | Wrong state name or handler signature | Match `given` string; use `state_handler` with correct params (v2.3+) |124125## References126127- `references/patterns.md` — Consumer tests, provider verification, matchers, provider states128- `references/config.md` — Pact Broker setup, CI integration, can-i-deploy129- `references/best-practices.md` — Consumer-driven workflow, versioning, broker management
azanir