Back to Details

contract-testing

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese
<objective> A provider renames a response field. Both services pass their own unit tests, and the mismatch only surfaces in production when the consumer's frontend breaks. Contract testing catches that in CI: the consumer declares exactly what it needs, the provider verifies it can deliver, and `can-i-deploy` blocks the deploy until the broker confirms both sides are compatible. This skill produces Pact consumer tests, broker-driven provider verification, and the deployment gate that ties them together — so services can be deployed independently without a shared integration environment. </objective>
<objective> 某提供者重命名了一个响应字段。两个服务各自通过了单元测试，但这种不匹配仅在生产环境中导致消费者前端崩溃时才暴露出来。契约测试可在CI阶段捕获此类问题：消费者明确声明其需求，提供者验证自身能否满足该需求，而`can-i-deploy`会在Broker确认双方兼容前阻止部署。本技能可生成Pact消费者测试、基于Broker的提供者验证，以及将两者关联的部署网关——让服务无需共享集成环境即可独立部署。 </objective>

Discovery Questions

探索性问题

Check 
.agents/qa-project-context.md
first — if it exists, use it and skip anything already answered there. Then:
  1. Architecture: Microservices, monolith with separate consumers (mobile/SPA), or BFF pattern? Contract testing matters most when teams deploy independently.
  2. Who owns the contract? Consumer-driven (consumers define what they need) or provider-driven (provider publishes a spec)? Most teams benefit from consumer-driven.
  3. API versioning strategy: URL-based (
    /v1/
    , 
    /v2/
    ), header-based, or none? Contracts must account for version negotiation.
  4. How many consumer-provider pairs? Start with the highest-traffic or most-fragile integration. Do not try to contract-test everything at once.
  5. Existing API specs: Is there an OpenAPI/Swagger spec? If yes, consider schema-first contracts (or Schemathesis) as a starting point.
  6. 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).
首先查看
.agents/qa-project-context.md
——如果该文件存在，则使用其中内容并跳过已回答的问题。然后：
  1. 架构类型：微服务、带有独立消费者（移动端/单页应用）的单体应用，还是BFF模式？当团队独立部署服务时，契约测试的价值最大。
  2. 契约归属：消费者驱动型（消费者定义自身需求）还是提供者驱动型（提供者发布规范）？大多数团队会从消费者驱动型中获益。
  3. API版本策略：基于URL（
    /v1/
    、
    /v2/
    ）、基于请求头，还是无版本策略？契约必须考虑版本协商机制。
  4. 消费者-提供者对数量：从流量最高或最脆弱的集成点开始。不要试图一次性为所有接口做契约测试。
  5. 现有API规范：是否存在OpenAPI/Swagger规范？如果有，可以考虑将优先Schema的契约（或Schemathesis）作为起点。
  6. HTTP还是异步通信：请求/响应式API使用本文中的HTTP示例；队列/主题集成（Kafka、SNS/SQS）使用Pact消息契约（参见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.
1. 消费者定义需求，提供者验证交付能力。消费者编写测试声明「我将调用
GET /users/123
，并期望返回
{ id, name, email }
」。提供者针对真实实现运行该测试。如果提供者无法满足契约要求，构建会在部署前失败。
2. Broker是唯一可信数据源。而非文档、Slack线程或「先部署再观察」的方式。契约文件和验证结果存储在Pact Broker中；提供者验证从Broker拉取契约（通过
pactBrokerUrl
+ 
consumerVersionSelectors
），而非本地文件，因为Broker知晓哪些消费者版本正在实际运行。
3. 契约测试替代集成环境，而非集成测试。你仍需要针对复杂多步骤工作流的集成测试。契约测试消除了为验证接口而必须同时部署消费者和提供者的需求。
4. 契约违规时终止构建。仅记录警告但允许部署的契约测试毫无价值。契约必须作为部署的强制关卡。
5. 测试契约而非业务逻辑。消费者测试验证响应结构和状态码。提供者验证确保契约可被满足。业务规则应放在单元测试和集成测试中。

Pact-JS Setup

Pact-JS 搭建

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. Use 
    Matchers
    (
    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 
    stateHandlers
    to set up the data each 
    given(...)
    state expects, and publishes the verification result back to the broker.
Pact-JS v16 (current as of June 2026) renamed 
PactV4
→ 
Pact
and 
MatchersV3
→ 
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-foundation/pact
作为开发依赖。工作流分为两部分：
  • 消费者测试：消费者声明其从提供者处需要的内容（请求结构 + 预期响应）。运行测试会生成
    pacts/<consumer>-<provider>.json
    ——即契约文件。使用
    Matchers
    （
    Matchers.like
    、
    Matchers.eachLike
    、
    Matchers.integer
    、
    Matchers.string
    、
    Matchers.regex
    ）让契约断言类型和格式，而非脆弱的精确值。
  • 提供者验证：提供者针对其真实实现（而非模拟服务）运行消费者的契约，使用
    stateHandlers
    为每个
    given(...)
    状态设置所需数据，并将验证结果发布回Broker。
**截至2026年6月的当前版本Pact-JS v16已将
PactV4
重命名为
Pact
，
MatchersV3
重命名为
Matchers
。**旧名称在v16中已被移除。如果从旧博客/示例中复制代码，请更新导入语句。API行为未发生变化。
对于事件驱动系统，同一个
Pact
类支持消息契约（Kafka、SNS/SQS、RabbitMQ）——消费者断言其期望的消息结构，提供者验证其生产者发送的消息是否符合该结构。
有关安装命令、消费者测试（单个用户、404场景、分页列表）、带有状态处理和待处理契约的Broker驱动型提供者验证规范、Pact Broker Docker Compose配置，以及消息契约指引，请查看
references/pact-js-setup.md
。

Pact Broker

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.
Pact Broker是集中式注册中心，用于存储契约文件和记录提供者验证结果。它支持
can-i-deploy
工作流。可使用Docker Compose结合Postgres在本地运行；消费者CI将契约发布到Broker，并使用提交SHA和分支作为标签。
所有凭证均从环境变量注入——包括Postgres密码、Broker数据库URL和基础认证密码。在compose文件中硬编码任何凭证都会导致秘密泄露到版本控制系统中。将Broker镜像固定到已发布的标签，而非
:latest
。
有关
docker-compose.pact-broker.yml
配置和
pact-broker publish
命令，请查看
references/pact-js-setup.md
。

Consumer-Driven Workflow

消费者驱动工作流

The full cycle:
1. Consumer writes contract test
   └── Generates pact JSON file

2. Consumer CI publishes pact to broker
   └── Broker stores pact tagged with consumer version + branch

3. Broker webhook triggers provider verification
   └── Provider CI pulls latest pact, runs verification

4. Provider publishes verification result to broker
   └── Broker records: "provider v2.3.1 satisfies consumer v1.5.0"

5. Before deploy: can-i-deploy check
   └── "Can consumer v1.5.0 be deployed? Yes, provider v2.3.1 is in production and verified."
Both pipelines run contract tests, publish results to the broker, and gate deployment on 
can-i-deploy
. The provider pipeline also listens for a 
repository_dispatch
event so a new pact triggers verification automatically.
See 
references/ci-pipelines.md
for the consumer CI workflow, the provider CI workflow (with Postgres service + migrations), and the standalone 
can-i-deploy
/ 
record-deployment
commands.
完整流程：
1. 消费者编写契约测试
   └── 生成契约JSON文件

2. 消费者CI将契约发布到Broker
   └── Broker存储带有消费者版本 + 分支标签的契约

3. Broker Webhook触发提供者验证
   └── 提供者CI拉取最新契约，运行验证

4. 提供者将验证结果发布到Broker
   └── Broker记录：「提供者v2.3.1兼容消费者v1.5.0」

5. 部署前：执行can-i-deploy检查
   └── 「能否部署消费者v1.5.0？可以，生产环境中已运行经过验证的提供者v2.3.1。」
两条流水线均运行契约测试，将结果发布到Broker，并以
can-i-deploy
作为部署关卡。提供者流水线还监听
repository_dispatch
事件，以便新契约发布时自动触发验证。
有关消费者CI工作流、提供者CI工作流（含Postgres服务 + 迁移），以及独立的
can-i-deploy
/ 
record-deployment
命令，请查看
references/ci-pipelines.md
。

Pact Broker Webhooks

Pact Broker Webhooks

Configure webhooks in the Pact Broker to trigger provider verification via 
repository_dispatch
when a new pact is published. The webhook sends a 
POST
to 
https://api.github.com/repos/myorg/user-service/dispatches
with event type 
pact-changed
, which the provider pipeline listens for (see the 
repository_dispatch
trigger in 
references/ci-pipelines.md
).
在Pact Broker中配置Webhook，以便发布新契约时通过
repository_dispatch
触发提供者验证。Webhook向
https://api.github.com/repos/myorg/user-service/dispatches
发送
POST
请求，事件类型为
pact-changed
，提供者流水线会监听该事件（参见
references/ci-pipelines.md
中的
repository_dispatch
触发器）。

Pending Pacts (Incremental Adoption)

待处理契约（增量适配）

Set 
enablePending: true
(plus 
includeWipPactsSince
) on the provider 
Verifier
so a brand-new consumer interaction can land without breaking the provider build — it is reported but does not fail until the consumer marks it expected. This is the standard safety net when adding contracts incrementally.
在提供者
Verifier
上设置
enablePending: true
（加上
includeWipPactsSince
），这样全新的消费者交互可以在不破坏提供者构建的情况下落地——它会被报告但不会导致失败，直到消费者将其标记为预期交互。这是增量添加契约时的标准安全机制。

Schema-First vs Consumer-First

优先Schema vs 优先消费者

Consumer-First (Pact)

优先消费者（Pact）

Consumers define what they need; contracts emerge from real usage patterns.
Best for: Teams where consumers have specific needs that differ across clients (mobile needs fewer fields than web), APIs that evolve organically, microservice ecosystems.
消费者定义自身需求；契约源于实际使用模式。
最适合：消费者需求因客户端而异（移动端所需字段少于Web端）的团队、有机演进的API、微服务生态系统。

Schema-First (OpenAPI + Validation)

优先Schema（OpenAPI + 验证）

Provider publishes an OpenAPI spec; consumers validate their usage against the spec.
Best for: Public APIs with many consumers, APIs designed upfront before implementation, teams with strong API design governance.
OpenAPI 3.0 is not plain JSON Schema (
nullable: true
etc.) — vanilla Ajv defaults to draft 2020-12 and mis-validates real 3.0 specs. Configure Ajv for the OpenAPI dialect with 
ajv-formats
, or use an OpenAPI-aware validator. See the caveat in 
references/schema-first.md
for the Ajv config and the OpenAPI-against-spec validation helper.
提供者发布OpenAPI规范；消费者验证其使用是否符合该规范。
最适合：拥有大量消费者的公共API、在实现前预先设计的API、具有严格API设计治理的团队。
OpenAPI 3.0并非纯JSON Schema（如
nullable: true
等）——默认的Ajv采用draft 2020-12标准，会错误验证真实的3.0规范。请为Ajv配置OpenAPI方言并使用
ajv-formats
，或使用支持OpenAPI的验证器。有关Ajv配置和OpenAPI规范验证助手的注意事项，请查看
references/schema-first.md
。

Hybrid Approach

混合方案

Use OpenAPI as the design artifact and Pact as the enforcement mechanism.
  1. Design API with OpenAPI spec (provider team leads design).
  2. Generate Pact consumer tests from the OpenAPI spec as a baseline.
  3. Consumers add specific interactions beyond the baseline.
  4. Provider verifies against Pact contracts (a subset of the OpenAPI spec).
将OpenAPI作为设计工件，Pact作为执行机制。
  1. 使用OpenAPI规范设计API（由提供者团队主导设计）。
  2. 从OpenAPI规范生成Pact消费者测试作为基线。
  3. 消费者添加基线之外的特定交互。
  4. 提供者针对Pact契约（OpenAPI规范的子集）进行验证。

Bi-Directional Contracts (PactFlow / SmartBear)

双向契约（PactFlow / SmartBear）

PactFlow (by SmartBear) offers bi-directional contract testing that decouples consumer pacts from provider verification — the provider supplies an OpenAPI spec, the consumer supplies a pact, and PactFlow checks compatibility without requiring the provider to run pact verification. It is a paid PactFlow/SmartBear feature, not part of Pact OSS. Useful when:
  • The provider team can't or won't run a Pact verifier in their CI.
  • The provider already publishes an OpenAPI spec as the source of truth.
  • You want contract coverage without tight coupling between consumer and provider repos.
Trade-off: bi-directional checks are coarser than full pact verification — they validate spec/contract overlap, not exact runtime behaviour. Use it as the on-ramp; promote to full verification once both teams are bought in.
PactFlow（由SmartBear提供）支持双向契约测试，将消费者契约与提供者验证解耦——提供者提供OpenAPI规范，消费者提供契约，PactFlow无需提供者运行Pact验证器即可检查兼容性。这是PactFlow/SmartBear的付费功能，不属于Pact开源项目。适用于以下场景：
  • 提供者团队无法或不愿在其CI中运行Pact验证器。
  • 提供者已将OpenAPI规范作为可信数据源发布。
  • 你希望获得契约覆盖，同时避免消费者与提供者仓库之间的紧密耦合。
权衡：双向检查的粒度比完整的Pact验证更粗——它们验证规范/契约的重叠部分，而非精确的运行时行为。可将其作为入门方案；当双方团队都认可后，再升级为完整验证。

Schemathesis (Property-Based, Spec-Driven)

Schemathesis（基于属性、规范驱动）

For OpenAPI-first projects, Schemathesis (v4.x) runs property-based tests against a live API directly from the spec — generating thousands of valid+invalid requests and checking response conformance. Catches a different class of bugs than Pact (encoding, edge-case payloads, status-code drift). Pair them: Pact for consumer-driven interactions, Schemathesis for spec-driven coverage. In CI, prefer the 
schemathesis/action@v3
Action over a raw shell line.
Avoid: 
schemathesis run --base-url ... --hypothesis-deadline=2000
(Schemathesis ≤ v3, dead as of v4.0, 2025-06). v4 removed 
--hypothesis-deadline
and renamed 
--base-url
to 
--url
; the schema is now the positional arg. Current form: 
schemathesis run ./openapi.yaml --url <base> --checks all
. See 
references/schema-first.md
.
对于优先OpenAPI的项目，Schemathesis（v4.x）直接从规范出发，对实时API运行基于属性的测试——生成数千个有效/无效请求并检查响应一致性。它能捕获Pact无法发现的一类Bug（编码问题、边缘情况 payload、状态码漂移）。可将两者结合使用：Pact用于消费者驱动的交互，Schemathesis用于规范驱动的覆盖。在CI中，优先使用
schemathesis/action@v3
Action，而非原始shell命令。
**注意：避免使用
schemathesis run --base-url ... --hypothesis-deadline=2000
（Schemathesis ≤ v3，2025-06起已废弃）。**v4移除了
--hypothesis-deadline
，并将
--base-url
重命名为
--url
；现在规范是位置参数。当前格式：
schemathesis run ./openapi.yaml --url <base> --checks all
。请查看
references/schema-first.md
。

can-i-deploy

can-i-deploy

The 
can-i-deploy
command is the deployment gate. It checks the Pact Broker matrix to answer "given everything the broker knows, is this exact version compatible with what is already in the target environment?" After a successful deploy, record it with 
record-deployment
so the matrix stays accurate.
Always pass 
--retry-while-unknown <n> --retry-interval <s>
. This fixes the single most common real-world failure: the consumer just published a pact and the provider hasn't finished verifying it yet, so without retries the gate hard-fails on a race instead of waiting for the result to land.
Never deploy without a passing 
can-i-deploy
check, and never skip it on 
main
. 
main
is what reaches production — a skipped gate there ships a version the broker has not confirmed compatible, which is the exact break contract testing exists to prevent.
See 
references/ci-pipelines.md
for the 
can-i-deploy
and 
record-deployment
commands with annotated output and the retry flags.
can-i-deploy
命令是部署关卡。它检查Pact Broker的兼容性矩阵，回答「根据Broker掌握的所有信息，此特定版本是否与目标环境中已运行的版本兼容？」部署成功后，使用
record-deployment
记录部署信息，以保持矩阵的准确性。
始终传递
--retry-while-unknown <n> --retry-interval <s>
参数。这可以解决现实中最常见的故障：消费者刚发布契约，提供者尚未完成验证，若无重试机制，关卡会因竞态条件直接失败，而非等待验证结果生成。
永远不要在未通过
can-i-deploy
检查的情况下部署，也不要在
main
分支上跳过该检查。
main
分支的代码会进入生产环境——跳过关卡会部署Broker未确认兼容的版本，这正是契约测试要防止的故障场景。
有关带注释输出和重试参数的
can-i-deploy
与
record-deployment
命令，请查看
references/ci-pipelines.md
。

Anti-Patterns

反模式

Testing business logic in contracts. Keep contracts thin: status codes, field presence, field types, field format. Business logic belongs in unit and integration tests.
Provider-driven contracts without consumer input. If the provider team defines contracts alone, they test what they think consumers need, not what consumers actually use. Consumer-driven contracts catch real integration failures.
Skipping provider states. If the consumer expects 
given("user 123 exists")
but provider verification runs against an empty database, the verification is meaningless. Provider state handlers must set up the exact scenario.
Verifying from local pact files in production CI. Local 
pactUrls
verification only sees the pacts on disk, not what is deployed. Pull from the broker with 
pactBrokerUrl
+ 
consumerVersionSelectors
so verification reflects live consumer versions.
Publishing pacts from local machines. Pacts must be published from CI with a known commit SHA and branch. Local publishes produce untraceable versions that pollute the broker.
Ignoring 
can-i-deploy
failures. If 
can-i-deploy
says no, fix the contract violation or negotiate the change with the consumer team. Deploying anyway breaks production.
One massive pact covering every endpoint. Start with critical integration points. Add contracts incrementally (use pending pacts) as failures justify them. A 500-interaction pact is unmaintainable.
Not cleaning up old pacts. Configure the Pact Broker to delete pact versions older than 90 days that are not deployed to any environment. Stale pacts slow verification and confuse the matrix.
在契约中测试业务逻辑。保持契约简洁：仅测试状态码、字段存在性、字段类型、字段格式。业务逻辑应放在单元测试和集成测试中。
无消费者参与的提供者驱动契约。如果仅由提供者团队定义契约，他们测试的是自己认为消费者需要的内容，而非消费者实际使用的内容。消费者驱动契约才能捕获真实的集成故障。
跳过提供者状态设置。如果消费者期望
given("user 123 exists")
，但提供者验证针对空数据库运行，那么验证毫无意义。提供者状态处理程序必须设置精确的场景。
在生产CI中从本地契约文件进行验证。本地
pactUrls
验证只能看到磁盘上的契约，无法了解已部署的版本。请通过
pactBrokerUrl
+ 
consumerVersionSelectors
从Broker拉取契约，确保验证反映当前运行的消费者版本。
从本地机器发布契约。契约必须从CI发布，并附带已知的提交SHA和分支。本地发布会产生无法追踪的版本，污染Broker。
忽略
can-i-deploy
失败。如果
can-i-deploy
返回不允许部署，请修复契约违规问题，或与消费者团队协商变更。强行部署会导致生产环境故障。
单个大型契约覆盖所有端点。从关键集成点开始。随着故障出现，增量添加契约（使用待处理契约）。包含500个交互的契约难以维护。
不清理旧契约。配置Pact Broker删除90天以上且未部署到任何环境的契约版本。过时契约会减慢验证速度并混淆兼容性矩阵。

Verification

验证步骤

Prove the artifacts work, smallest check first:
  1. Consumer test emits a pact. Run 
    npm run test:contract
    and confirm 
    pacts/<consumer>-<provider>.json
    is written and contains the interactions you declared. No file = no contract.
  2. Provider verification passes against the real service. Run 
    npm run test:contract:provider
    with the test database up; every consumer interaction should verify green against the running provider, not a mock.
  3. Broker round-trip. Publish with 
    pact-broker publish ./pacts --consumer-app-version=$GIT_COMMIT --branch=$GIT_BRANCH
    and confirm the pact appears in the broker UI with the verification result recorded.
  4. Deployment gate. Run 
    pact-broker can-i-deploy --pacticipant=<name> --version=<sha> --to-environment=production --dry-run
    and confirm it returns a definite yes/no (not "unknown") for a known-good version.
验证工件是否可用，从最小检查开始：
  1. 消费者测试生成契约。运行
    npm run test:contract
    ，确认
    pacts/<consumer>-<provider>.json
    已生成且包含你声明的交互。无文件则无契约。
  2. 提供者针对真实服务验证通过。启动测试数据库后运行
    npm run test:contract:provider
    ；每个消费者交互都应针对运行中的提供者验证通过，而非模拟服务。
  3. Broker往返验证。运行
    pact-broker publish ./pacts --consumer-app-version=$GIT_COMMIT --branch=$GIT_BRANCH
    发布契约，确认契约出现在Broker UI中且已记录验证结果。
  4. 部署关卡验证。运行
    pact-broker can-i-deploy --pacticipant=<name> --version=<sha> --to-environment=production --dry-run
    ，确认已知良好版本返回明确的是/否结果（而非「未知」）。

Done When

完成标准

  • Consumer pact tests run in CI and a 
    pacts/*.json
    file is generated and published to the broker on every run, tagged with the commit SHA and branch.
  • Provider verification job runs in CI on every provider change and on every new pact published (via the Pact Broker 
    repository_dispatch
    webhook), pulling pacts from the broker — not local files.
  • can-i-deploy
    (with 
    --retry-while-unknown
    ) gates deployment in both consumer and provider pipelines on 
    main
    and fails the job when a contract is broken.
  • A 
    CONTRACTS.md
    (or 
    CODEOWNERS
    entry) exists naming the owner/reviewer for each consumer-provider interaction.
  • At least one breaking-change scenario has been run end-to-end and confirmed caught by the 
    can-i-deploy
    check before reaching production.
  • 消费者契约测试在CI中运行，每次运行都会生成
    pacts/*.json
    文件并发布到Broker，附带提交SHA和分支标签。
  • 提供者验证任务在CI中运行，每次提供者变更或发布新契约时（通过Pact Broker的
    repository_dispatch
    Webhook）触发，从Broker拉取契约——而非本地文件。
  • can-i-deploy
    （带
    --retry-while-unknown
    参数）作为消费者和提供者流水线中
    main
    分支的部署关卡，契约违规时终止任务。
  • 存在
    CONTRACTS.md
    （或
    CODEOWNERS
    条目），指定每个消费者-提供者交互的负责人/审核人。
  • 至少运行过一次端到端的变更故障场景，并确认
    can-i-deploy
    检查在故障到达生产环境前将其拦截。

Reference Files (in 
references/
)

参考文件（位于
references/
目录）

  • pact-js-setup.md — Install commands, consumer pact test (user/404/pagination), broker-driven provider verification with state handlers and pending pacts, message-contract pointer, and Pact Broker Docker Compose + publish command.
  • ci-pipelines.md — Consumer and provider GitHub Actions workflows plus the standalone 
    can-i-deploy
    (with retry flags) / 
    record-deployment
    commands.
  • schema-first.md — OpenAPI-against-Ajv response validation helper (with the 3.0 dialect caveat) and the Schemathesis v4 command + Action.
  • pact-js-setup.md —— 安装命令、消费者契约测试（用户/404/分页）、带有状态处理和待处理契约的Broker驱动型提供者验证、消息契约指引，以及Pact Broker Docker Compose配置 + 发布命令。
  • ci-pipelines.md —— 消费者和提供者GitHub Actions工作流，以及独立的
    can-i-deploy
    （带重试参数）/ 
    record-deployment
    命令。
  • schema-first.md —— OpenAPI与Ajv的响应验证助手（含3.0方言注意事项），以及Schemathesis v4命令 + Action。

Related Skills

相关技能

  • api-testing — Asserting your own REST/GraphQL endpoints (shape, status, auth, headers). Go there for general endpoint testing; come here when a separate team consumes your API and you need guaranteed compatibility, not just a shared schema.
  • service-virtualization — Stubbing or mocking a dependency to isolate a test. Go there to replace a service with a fake; come here to prove two real services agree on the interface — contracts verify compatibility, virtualization fakes it.
  • ci-cd-integration — Pipeline mechanics: running these contract jobs as CI gates, secrets, and parallelization. Go there for the pipeline plumbing this skill's deployment gate plugs into.
  • test-environments — Environment strategy. Go there to decide where contract verification runs and how the broker is provisioned across staging/production.
  • api-testing —— 断言自有REST/GraphQL端点（结构、状态、认证、请求头）。如需常规端点测试，请使用该技能；当其他团队消费你的API且需要保证兼容性（而非仅共享规范）时，请使用本技能。
  • service-virtualization —— 为隔离测试而存根或模拟依赖。如需用假服务替代真实服务，请使用该技能；如需证明两个真实服务在接口上达成一致，请使用本技能——契约测试验证兼容性，虚拟化则模拟依赖。
  • ci-cd-integration —— 流水线机制：将这些契约任务作为CI关卡运行、管理密钥、并行化处理。如需本技能部署关卡所需的流水线基础配置，请使用该技能。
  • test-environments —— 环境策略。如需确定契约验证运行位置，以及如何在 staging/生产环境中部署Broker，请使用该技能。",