name: “QE合同测试” description: “包括REST、GraphQL和事件驱动系统的API消费者驱动合同测试，具有模式验证。” trust_tier: 3 validation: schema_path: schemas/output.json validator_path: scripts/validate-config.json eval_path: evals/qe-contract-testing.yaml

QE合同测试

目的

指导使用v3的合同测试功能，包括消费者驱动合同、模式验证、向后兼容性检查和API版本验证。

激活

当测试API合同时
当验证模式更改时
当检查向后兼容性时
当测试GraphQL API时
当验证事件模式时

快速开始

# 从API生成合同
aqe contract generate --api openapi.yaml --output contracts/

# 验证提供者对抗合同
aqe contract verify --provider http://localhost:3000 --contracts contracts/

# 检查破坏性更改
aqe contract breaking --old api-v1.yaml --new api-v2.yaml

# 测试GraphQL模式
aqe contract graphql --schema schema.graphql --operations queries/

代理工作流

// 合同生成
Task("生成API合同", `
  分析REST API并生成消费者合同：
  - 解析OpenAPI规范
  - 识别关键端点
  - 生成Pact合同
  - 包括示例请求/响应
  输出到contracts/目录。
`, "qe-api-contract")

// 破坏性更改检测
Task("检查API兼容性", `
  比较API v2.0对抗v1.0：
  - 检测移除的端点
  - 检查参数更改
  - 验证响应模式更改
  - 识别弃用
  报告破坏性与非破坏性更改。
`, "qe-api-compatibility")

合同测试类型

1. 消费者驱动合同（Pact）

await contractTester.consumerDriven({
  consumer: 'web-app',
  provider: 'user-service',
  contracts: 'contracts/web-app-user-service.json',
  verification: {
    providerBaseUrl: 'http://localhost:3000',
    providerStates: providerStateHandlers,
    publishResults: true
  }
});

2. 模式验证

await contractTester.validateSchema({
  type: 'openapi',
  schema: 'api/openapi.yaml',
  requests: actualRequests,
  validation: {
    requestBody: true,
    responseBody: true,
    headers: true,
    statusCodes: true
  }
});

3. GraphQL合同测试

await graphqlTester.testContracts({
  schema: 'schema.graphql',
  operations: 'queries/**/*.graphql',
  validation: {
    queryValidity: true,
    responseShapes: true,
    nullability: true,
    deprecations: true
  }
});

4. 事件合同测试

await contractTester.eventContracts({
  schema: 'events/schemas/',
  events: {
    'user.created': {
      schema: 'UserCreatedEvent.json',
      examples: ['examples/user-created.json']
    },
    'order.completed': {
      schema: 'OrderCompletedEvent.json',
      examples: ['examples/order-completed.json']
    }
  },
  compatibility: 'backward'
});

破坏性更改检测

breaking_changes:
  always_breaking:
    - endpoint_removed
    - required_param_added
    - response_field_removed
    - type_changed

  potentially_breaking:
    - optional_param_removed
    - response_field_added
    - enum_value_removed

  non_breaking:
    - endpoint_added
    - optional_param_added
    - response_field_made_optional
    - documentation_changed

合同报告

interface ContractReport {
  summary: {
    contracts: number;
    passed: number;
    failed: number;
    warnings: number;
  };
  consumers: {
    name: string;
    contracts: ContractResult[];
    compatibility: 'compatible' | 'breaking' | 'unknown';
  }[];
  breakingChanges: {
    type: string;
    location: string;
    description: string;
    impact: 'high' | 'medium' | 'low';
    migration: string;
  }[];
  deprecations: {
    item: string;
    deprecatedIn: string;
    removeIn: string;
    replacement: string;
  }[];
}

CI/CD集成

contract_verification:
  consumer_side:
    - generate_contracts
    - publish_to_broker
    - can_i_deploy_check

  provider_side:
    - fetch_contracts_from_broker
    - verify_against_provider
    - publish_results

  pre_release:
    - check_breaking_changes
    - verify_all_consumers
    - update_compatibility_matrix

Pact Broker集成

await contractTester.withBroker({
  brokerUrl: 'https://pact-broker.example.com',
  auth: { token: process.env.PACT_TOKEN },
  operations: {
    publish: true,
    canIDeploy: true,
    webhooks: true
  }
});

协调

主要代理: qe-api-contract, qe-api-compatibility, qe-graphql-tester 协调器: qe-contract-coordinator 相关技能: qe-test-generation, qe-security-compliance