contract-testing

契约测试

<default_to_action> 测试 API 契约或微服务时：

1. 明确消费者的预期（消费者实际需要什么）
2. 验证提供方是否满足契约（Pact 验证）
3. 在部署前检测破坏性变更（CI/CD 集成）
4. 对 API 进行语义化版本控制（破坏性变更 = 主版本号递增）
5. 为受支持的版本维护向后兼容性

契约测试快速步骤：

• 消费者：定义预期的请求/响应对
• 提供方：根据所有消费者契约进行验证
• CI/CD：阻止会破坏契约的部署
• 版本控制：记录受支持的版本和弃用信息

成功的关键因素：

• 消费者拥有契约（由他们定义所需内容）
• 提供方必须在部署前通过所有消费者契约
• 破坏性变更需要协调，不能让人措手不及 </default_to_action>

快速参考卡

适用场景

• 微服务通信
• 第三方 API 集成
• 分布式团队协作
• 防止破坏性变更

消费者驱动的契约流程

Consumer → Defines Expectations → Contract
                    ↓
Provider → Verifies Contract → Pass/Fail
                    ↓
CI/CD → Blocks Breaking Changes

破坏性变更与非破坏性变更

变更类型	是否有破坏性？	Semver
删除字段	✅ 是	主版本
重命名字段	✅ 是	主版本
更改类型	✅ 是	主版本
添加可选字段	❌ 否	次版本
添加新端点	❌ 否	次版本
修复错误	❌ 否	补丁版本

工具

工具	最适用场景
Pact	消费者驱动的契约
OpenAPI/Swagger	API 优先设计
JSON Schema	模式验证
GraphQL	模式优先契约

---

消费者契约（Pact）

// Consumer defines what it needs
const { Pact } = require('@pact-foundation/pact');

describe('Order API Consumer', () => {
  const provider = new Pact({
    consumer: 'CheckoutUI',
    provider: 'OrderService'
  });

  beforeAll(() => provider.setup());
  afterAll(() => provider.finalize());

  it('creates an order', async () => {
    await provider.addInteraction({
      state: 'products exist',
      uponReceiving: 'a create order request',
      withRequest: {
        method: 'POST',
        path: '/orders',
        body: { productId: 'abc', quantity: 2 }
      },
      willRespondWith: {
        status: 201,
        body: {
          orderId: like('order-123'),  // Any string matching pattern
          total: like(19.99)           // Any number
        }
      }
    });

    const response = await orderClient.create({ productId: 'abc', quantity: 2 });
    expect(response.orderId).toBeDefined();
  });
});

---

提供方验证

// Provider verifies it fulfills all consumer contracts
const { Verifier } = require('@pact-foundation/pact');

describe('Order Service Provider', () => {
  it('fulfills all consumer contracts', async () => {
    await new Verifier({
      provider: 'OrderService',
      providerBaseUrl: 'http://localhost:3000',
      pactUrls: ['./pacts/checkoutui-orderservice.json'],
      stateHandlers: {
        'products exist': async () => {
          await db.products.create({ id: 'abc', price: 9.99 });
        }
      }
    }).verifyProvider();
  });
});

---

破坏性变更检测

// Agent detects breaking changes
await Task("Contract Validation", {
  currentContract: 'openapi-v2.yaml',
  previousContract: 'openapi-v1.yaml',
  detectBreaking: true,
  calculateSemver: true,
  generateMigrationGuide: true
}, "qe-api-contract-validator");

// Output:
// Breaking changes found: 2
// - Removed field: order.discount
// - Type change: order.total (number → string)
// Recommended version: 3.0.0 (major bump)

---

CI/CD 集成

name: Contract Tests
on: [push]

jobs:
  consumer-tests:
    steps:
      - run: npm run test:contract
      - name: Publish Pacts
        run: npx pact-broker publish ./pacts --broker-base-url $PACT_BROKER

  provider-verification:
    needs: consumer-tests
    steps:
      - name: Verify Provider
        run: npm run verify:contracts
      - name: Can I Deploy?
        run: npx pact-broker can-i-deploy --pacticipant OrderService --version $VERSION

---

Agent 协作提示

记忆命名空间

aqe/contract-testing/
├── contracts/*           - Current contracts
├── breaking-changes/*    - Detected breaking changes
├── versioning/*          - Version compatibility matrix
└── verification-results/* - Provider verification history

Fleet 协作

const contractFleet = await FleetManager.coordinate({
  strategy: 'contract-testing',
  agents: [
    'qe-api-contract-validator',  // Validation, breaking detection
    'qe-test-generator',          // Generate contract tests
    'qe-security-scanner'         // API security
  ],
  topology: 'sequential'
});

---

Agent CLI 与高级模式

有关 v3 Agent 专用命令（aqe contract ...）、GraphQL 契约、事件契约和 Pact Broker 集成，请参阅 references/agent-commands.md。

相关技能

• api-testing-patterns - API 测试策略
• shift-left-testing - 提前验证契约
• cicd-pipeline-qe-orchestrator - 流水线集成

---

请牢记

消费者拥有契约。 他们定义所需内容；提供方必须满足这些需求。破坏性变更需要递增主版本号并进行协调。CI/CD 会阻止破坏契约的部署。消费者驱动的契约使用 Pact，API 优先设计使用 OpenAPI。

使用 Agent： Agent 会验证契约、检测破坏性变更并提供语义化版本建议，还会生成迁移指南。使用 Agent 可大规模维护契约合规性。

注意事项

• 运行前必须配置 Pact broker URL；否则 Agent 会生成测试，但会静默跳过验证
• 消费者测试在本地通过，却在 CI 中失败，通常是因为未设置提供方状态；务必验证双方
• 在响应中添加必需字段属于破坏性变更，即使提供方测试通过也不例外，因为消费者并未预期该字段
• Agent 可能会根据 API 文档而不是实际消费者的使用情况生成契约；契约必须反映消费者的真实需求
• GraphQL 契约测试需要考虑模式拼接；片段可能引用其他服务中的类型