QE Contract Testing

Purpose

Guide the use of v3's contract testing capabilities including consumer-driven contracts, schema validation, backward compatibility checking, and API versioning verification.

Activation

• When testing API contracts
• When validating schema changes
• When checking backward compatibility
• When testing GraphQL APIs
• When verifying event schemas

Quick Start

bash
1# Generate contract from API
2aqe contract generate --api openapi.yaml --output contracts/
3
4# Verify provider against contracts
5aqe contract verify --provider http://localhost:3000 --contracts contracts/
6
7# Check breaking changes
8aqe contract breaking --old api-v1.yaml --new api-v2.yaml
9
10# Test GraphQL schema
11aqe contract graphql --schema schema.graphql --operations queries/

Agent Workflow

typescript
1// Contract generation
2Task("Generate API contracts", `
3  Analyze the REST API and generate consumer contracts:
4  - Parse OpenAPI specification
5  - Identify critical endpoints
6  - Generate Pact contracts
7  - Include example requests/responses
8  Output to contracts/ directory.
9`, "qe-api-contract")
10
11// Breaking change detection
12Task("Check API compatibility", `
13  Compare API v2.0 against v1.0:
14  - Detect removed endpoints
15  - Check parameter changes
16  - Verify response schema changes
17  - Identify deprecations
18  Report breaking vs non-breaking changes.
19`, "qe-api-compatibility")

Contract Testing Types

1. Consumer-Driven Contracts (Pact)

typescript
1await contractTester.consumerDriven({
2  consumer: 'web-app',
3  provider: 'user-service',
4  contracts: 'contracts/web-app-user-service.json',
5  verification: {
6    providerBaseUrl: 'http://localhost:3000',
7    providerStates: providerStateHandlers,
8    publishResults: true
9  }
10});

2. Schema Validation

typescript
1await contractTester.validateSchema({
2  type: 'openapi',
3  schema: 'api/openapi.yaml',
4  requests: actualRequests,
5  validation: {
6    requestBody: true,
7    responseBody: true,
8    headers: true,
9    statusCodes: true
10  }
11});

3. GraphQL Contract Testing

typescript
1await graphqlTester.testContracts({
2  schema: 'schema.graphql',
3  operations: 'queries/**/*.graphql',
4  validation: {
5    queryValidity: true,
6    responseShapes: true,
7    nullability: true,
8    deprecations: true
9  }
10});

4. Event Contract Testing

typescript
1await contractTester.eventContracts({
2  schema: 'events/schemas/',
3  events: {
4    'user.created': {
5      schema: 'UserCreatedEvent.json',
6      examples: ['examples/user-created.json']
7    },
8    'order.completed': {
9      schema: 'OrderCompletedEvent.json',
10      examples: ['examples/order-completed.json']
11    }
12  },
13  compatibility: 'backward'
14});

Breaking Change Detection

yaml
1breaking_changes:
2  always_breaking:
3    - endpoint_removed
4    - required_param_added
5    - response_field_removed
6    - type_changed
7
8  potentially_breaking:
9    - optional_param_removed
10    - response_field_added
11    - enum_value_removed
12
13  non_breaking:
14    - endpoint_added
15    - optional_param_added
16    - response_field_made_optional
17    - documentation_changed

Contract Report

typescript
1interface ContractReport {
2  summary: {
3    contracts: number;
4    passed: number;
5    failed: number;
6    warnings: number;
7  };
8  consumers: {
9    name: string;
10    contracts: ContractResult[];
11    compatibility: 'compatible' | 'breaking' | 'unknown';
12  }[];
13  breakingChanges: {
14    type: string;
15    location: string;
16    description: string;
17    impact: 'high' | 'medium' | 'low';
18    migration: string;
19  }[];
20  deprecations: {
21    item: string;
22    deprecatedIn: string;
23    removeIn: string;
24    replacement: string;
25  }[];
26}

CI/CD Integration

yaml
1contract_verification:
2  consumer_side:
3    - generate_contracts
4    - publish_to_broker
5    - can_i_deploy_check
6
7  provider_side:
8    - fetch_contracts_from_broker
9    - verify_against_provider
10    - publish_results
11
12  pre_release:
13    - check_breaking_changes
14    - verify_all_consumers
15    - update_compatibility_matrix

Pact Broker Integration

typescript
1await contractTester.withBroker({
2  brokerUrl: 'https://pact-broker.example.com',
3  auth: { token: process.env.PACT_TOKEN },
4  operations: {
5    publish: true,
6    canIDeploy: true,
7    webhooks: true
8  }
9});

Coordination

Primary Agents: qe-api-contract, qe-api-compatibility, qe-graphql-tester Coordinator: qe-contract-coordinator Related Skills: qe-test-generation, qe-security-compliance