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

# 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 Workflow

// 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")

Contract Testing Types

1. Consumer-Driven Contracts (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. Schema Validation

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

3. GraphQL Contract Testing

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

4. Event Contract Testing

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 Change Detection

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

Contract Report

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 Integration

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 Integration

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

Coordination

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