Contract Test Generator

# Contract Test Generator

Contract testing bridges the gap between unit tests and full integration tests by verifying that services can communicate correctly without requiring all services to be running simultaneously. Consumer-driven contract testing, pioneered by the Pact framework, inverts the traditional approach: consumers define what they expect from providers, and providers verify they can satisfy those expectations. This skill guides AI coding agents through generating robust contract tests that catch integration breaking changes before they reach production.

## Core Principles

1. **Consumer-Driven Design**: Consumers define the contract based on what they actually use, not what the provider offers. This ensures contracts are minimal, focused, and reflect real usage patterns rather than hypothetical API surfaces.

2. **Provider Verification Independence**: Provider tests verify contracts independently without needing the consumer running. This decouples deployment schedules and enables teams to work autonomously while maintaining integration guarantees.

3. **Contract as Shared Artifact**: The contract (pact file) serves as a living specification between consumer and provider. It is versioned, stored centrally, and referenced by both sides during their respective CI pipelines.

4. **Minimal Assertion Surface**: Contracts should assert only what the consumer needs, not the full provider response. Testing for specific fields rather than entire response bodies prevents brittle contracts that break on harmless provider changes.

5. **Versioning Alignment with Deployability**: Every contract must be associated with a specific consumer version and verified against a specific provider version. The combination of these versions determines whether a deployment is safe.

6. **Fail-Fast in CI**: Contract verification failures must block deployments. The can-i-deploy tool provides a definitive answer about deployment safety based on the latest verification matrix.

7. **Incremental Adoption**: Contract tests can be introduced for the most critical interactions first, then expanded. There is no requirement to cover every endpoint immediately; focus on high-risk integration points.

## Project Structure

```
project-root/
├── consumer/
│   ├── src/
│   │   ├── api-client.ts
│   │   └── types.ts
│   ├── tests/
│   │   └── contract/
│   │       ├── user-service.consumer.pact.ts
│   │       ├── order-service.consumer.pact.ts
│   │       └── helpers/
│   │           ├── pact-setup.ts
│   │           └── matchers.ts
│   ├── pacts/                          # Generated pact files (JSON)
│   │   └── consumer-user_service.json
│   └── pact-config.ts
├── provider/
│   ├── src/
│   │   └── controllers/
│   ├── tests/
│   │   └── contract/
│   │       ├── provider-verification.pact.ts
│   │       └── state-handlers/
│   │           ├── user-states.ts
│   │           └── order-states.ts
│   └── pact-config.ts
├── pact-broker/
│   └── docker-compose.yml
└── ci/
    ├── publish-pacts.sh
    ├── verify-provider.sh
    └── can-i-deploy.sh
```

## Consumer Test Generation

### Basic Consumer Test in TypeScript

Consumer tests define the expectations a consumer has of a provider API. The Pact mock server simulates the provider during consumer tests.

```typescript
// consumer/tests/contract/user-service.consumer.pact.ts
import { PactV4, MatchersV3 } from '@pact-foundation/pact';
import { resolve } from 'path';
import { UserApiClient } from '../../src/api-client';

const { like, eachLike, regex, integer, string, timestamp } = MatchersV3;

const provider = new PactV4({
  consumer: 'frontend-app',
  provider: 'user-service',
  dir: resolve(__dirname, '../../pacts'),
  logLevel: 'warn',
});

describe('User Service Contract', () => {
  describe('GET /api/users/:id', () => {
    it('returns a user when one exists', async () => {
      await provider
        .addInteraction()
        .given('a user with ID 42 exists')
        .uponReceiving('a request for user 42')
        .withRequest('GET', '/api/users/42', (builder) => {
          builder.headers({
            Accept: 'application/json',
            Authorization: regex(/^Bearer\s[\w-]+\.[\w-]+\.[\w-]+$/, 'Bearer eyJ.test.token'),
          });
        })
        .willRespondWith(200, (builder) => {
          builder.headers({ 'Content-Type': 'application/json' });
          builder.jsonBody({
            id: integer(42),
            name: string('Jane Doe'),
            email: regex(/^[\w.]+@[\w.]+\.\w+$/, 'jane@example.com'),
            role: regex(/^(admin|user|moderator)$/, 'user'),
            createdAt: timestamp("yyyy-MM-dd'T'HH:mm:ss.SSSX", '2024-01-15T10:30:00.000Z'),
            preferences: like({
              theme: string('dark'),
              notifications: like(true),
            }),
          });
        })
        .executeTest(async (mockServer) => {
          const client = new UserApiClient(mockServer.url);
          const user = await client.getUser(42);

          expect(user.id).toBe(42);
          expect(user.name).toBeDefined();
          expect(user.email).toContain('@');
        });
    });

    it('returns 404 when user does not exist', async () => {
      await provider
        .addInteraction()
        .given('no user with ID 999 exists')
        .uponReceiving('a request for non-existent user 999')
        .withRequest('GET', '/api/users/999', (builder) => {
          builder.headers({
            Accept: 'application/json',
            Authorization: regex(/^Bearer\s[\w-]+\.[\w-]+\.[\w-]+$/, 'Bearer eyJ.test.token'),
          });
        })
        .willRespondWith(404, (builder) => {
          builder.headers({ 'Content-Type': 'application/json' });
          builder.jsonBody({
            error: string('Not Found'),
            message: string('User with ID 999 not found'),
          });
        })
        .executeTest(async (mockServer) => {
          const client = new UserApiClient(mockServer.url);
          await expect(c