qe-contract-testing

QE 合约测试

目的

介绍如何使用 v3 的合约测试功能，包括消费者驱动合约、架构验证、向后兼容性检查和 API 版本验证。

激活条件

• 测试 API 合约时
• 验证架构变更时
• 检查向后兼容性时
• 测试 GraphQL API 时
• 验证事件架构时

快速入门

# Generate contract from API
aqe contract generate --api openapi.yaml --output contracts/

# Verify provider against contracts
aqe contract verify --provider http://localhost:3000 --contracts contracts/

# Check breaking changes
aqe contract breaking --old api-v1.yaml --new api-v2.yaml

# Test GraphQL schema
aqe contract graphql --schema schema.graphql --operations queries/

Agent 工作流

// Contract generation
Task("Generate API contracts", `
  Analyze the REST API and generate consumer contracts:
  - Parse OpenAPI specification
  - Identify critical endpoints
  - Generate Pact contracts
  - Include example requests/responses
  Output to contracts/ directory.
`, "qe-api-contract")

// Breaking change detection
Task("Check API compatibility", `
  Compare API v2.0 against v1.0:
  - Detect removed endpoints
  - Check parameter changes
  - Verify response schema changes
  - Identify deprecations
  Report breaking vs non-breaking changes.
`, "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
  }
});

协调

主要 Agent：qe-api-contract、qe-api-compatibility、qe-graphql-tester 协调器：qe-contract-coordinator 相关技能：qe-test-generation、qe-security-compliance