contract-testing
Implement consumer-driven contract testing with Pact-JS (v16). Covers consumer test writing, broker-driven provider verification, Pact Broker setup, can-i-deploy as a deployment gate, webhook-triggered verification, pending pacts, and schema-first vs consumer-first approaches (OpenAPI/Ajv, Schemathesis). Use when: "contract test," "Pact," "consumer-driven," "API contract," "provider verification," "can-i-deploy." Not for: stubbing or mocking a dependency to isolate a test — use service-virtualization; general REST/GraphQL endpoint assertions against your own API — use api-testing. Related: api-testing, service-virtualization, ci-cd-integration, test-environments.
petrkindlmann · 已有 AI 审核记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add petrkindlmann/qa-skills --skill contract-testing技能说明
name: contract-testing description: >- Implement consumer-driven contract testing with Pact-JS (v16). Covers consumer test writing, broker-driven provider verification, Pact Broker setup, can-i-deploy as a deployment gate, webhook-triggered verification, pending pacts, and schema-first vs consumer-first approaches (OpenAPI/Ajv, Schemathesis). Use when: "contract test," "Pact," "consumer-driven," "API contract," "provider verification," "can-i-deploy." Not for: stubbing or mocking a dependency to isolate a test — use service-virtualization; general REST/GraphQL endpoint assertions against your own API — use api-testing. Related: api-testing, service-virtualization, ci-cd-integration, test-environments. license: MIT metadata: author: kindlmann version: "2.0" category: infrastructure
Discovery Questions
Check .agents/qa-project-context.md first — if it exists, use it and skip anything already answered there. Then:
- Architecture: Microservices, monolith with separate consumers (mobile/SPA), or BFF pattern? Contract testing matters most when teams deploy independently.
- Who owns the contract? Consumer-driven (consumers define what they need) or provider-driven (provider publishes a spec)? Most teams benefit from consumer-driven.
- API versioning strategy: URL-based (
/v1/,/v2/), header-based, or none? Contracts must account for version negotiation. - How many consumer-provider pairs? Start with the highest-traffic or most-fragile integration. Do not try to contract-test everything at once.
- Existing API specs: Is there an OpenAPI/Swagger spec? If yes, consider schema-first contracts (or Schemathesis) as a starting point.
- HTTP or async? Request/response APIs use the HTTP examples here; queue/topic integrations (Kafka, SNS/SQS) use Pact message contracts (see Pact-JS Setup).
Core Principles
1. Consumers define what they need, providers verify they can deliver. The consumer writes a test declaring "I will call GET /users/123 and expect { id, name, email }." The provider runs this test against its real implementation. If the provider cannot satisfy the contract, the build breaks before deployment.
2. The broker is the shared source of truth. Not documentation, not Slack threads, not "just deploy and see." Pacts and verification results live in the Pact Broker; provider verification pulls pacts from the broker (pactBrokerUrl + consumerVersionSelectors), not from local files, because the broker knows which consumer versions are actually live.
3. Contract tests replace integration environments, not integration tests. You still need integration tests for complex multi-step workflows. Contract tests eliminate the need to deploy consumer and provider together just to verify the interface.
4. Break the build on contract violation. A contract test that logs a warning but allows deployment provides zero value. Contracts must be deployment gates.
5. Test the contract, not the business logic. Consumer tests verify response shape and status codes. Provider verification ensures the contract is satisfiable. Business rules belong in unit and integration tests.
Pact-JS Setup
Install @pact-foundation/pact as a dev dependency on both the consumer and provider sides. The workflow has two halves:
- Consumer test: the consumer declares what it needs from the provider (request shape + expected response). Running the test generates
pacts/<consumer>-<provider>.json— the contract file. UseMatchers(Matchers.like,Matchers.eachLike,Matchers.integer,Matchers.string,Matchers.regex) so contracts assert types and formats, not brittle exact values. - Provider verification: the provider runs the consumer's pact against its real implementation (not mocks), using
stateHandlersto set up the data eachgiven(...)state expects, and publishes the verification result back to the broker.
Pact-JS v16 (current as of June 2026) renamed
PactV4→PactandMatchersV3→Matchers. The old names were removed in v16. If you copy from older blog posts/examples, update the imports. The API behavior is unchanged.
For event-driven systems, the same Pact class supports message pacts (Kafka, SNS/SQS, RabbitMQ) — the consumer asserts the shape of a message it expects and the provider verifies what its producer emits.
See references/pact-js-setup.md for the install commands, the consumer test (single user, 404, paginated list), the broker-driven provider verification spec with state handlers and pending pacts, the Pact Broker Docker Compose, and the message-contract pointer.
Pact Broker
The Pact Broker is the central registry where pact files are published and provider verification results are recorded. It enables the can-i-deploy workflow. Run it locally with Docker Compose backed by Postgres; consumer CI publishes pacts to it tagged with a commit SHA and branch.
Inject every credential from the environment — Postgres password, broker DB URL, and basic-auth password. Hardcoding any of them in the compose file leaks secrets into version control. Pin the broker image to a released tag, not :latest.
See references/pact-js-setup.md for the docker-compose.pact-broker.yml and the pact-broker publish command.
Consumer-Driven Workflow
The full cycle:
1
阅读完整来源 ↗