Generate Contract

Creates comprehensive API contracts for consumer-driven contract testing, enabling safe evolution of microservices by validating interactions between service consumers and providers. Supports Pact, Spring Cloud Contract, and OpenAPI specifications with automated verification and CI/CD integration.

When to Use

Use this command when:

• Building microservices that need to evolve independently
• Implementing consumer-driven contract testing (CDCT)
• Preventing breaking changes between API versions
• Setting up automated compatibility testing in CI/CD
• Documenting API expectations between teams
• Migrating from monolithic to microservice architecture
• Establishing service boundaries and contracts

Do NOT use this command for:

• Internal function testing (use unit tests instead)
• UI testing (use end-to-end tests)
• Performance testing (use load testing tools)
• Security testing (use security scanning tools)

Prerequisites

Before running this command, ensure:

• API endpoints are defined (at least conceptually)
• Consumer and provider services are identified
• Testing framework is chosen (Pact, Spring Cloud Contract, etc.)
• API documentation exists or requirements are clear
• Version control is set up for contract storage

Process

Step 1: Analyze API Requirements

The command examines your API specifications to generate appropriate contracts:

• Identifies HTTP methods and endpoints
• Extracts request/response schemas
• Determines required headers and parameters
• Captures validation rules and constraints
• Notes authentication requirements

Step 2: Generate Contract Definitions

Based on the analysis, creates contract files that include:

• Consumer expectations (what the consumer needs)
• Provider capabilities (what the provider offers)
• Interaction definitions (request/response pairs)
• State management (preconditions for tests)
• Metadata for versioning and identification

Step 3: Create Verification Tests

Generates test code to verify contracts:

• Consumer-side tests to ensure correct API usage
• Provider-side tests to verify implementation
• Mock server configurations for isolated testing
• Integration points for CI/CD pipelines
• Breaking change detection logic

Step 4: Configure Contract Management

Sets up infrastructure for contract lifecycle:

• Contract versioning strategies
• Pact Broker or contract repository configuration
• CI/CD pipeline integration scripts
• Webhook configurations for automated testing
• Documentation generation from contracts

Output Format

The command generates multiple files based on your chosen framework:

api-contracts/
├── consumers/
│   ├── [consumer-name]/
│   │   ├── pacts/
│   │   │   └── [consumer]-[provider].json
│   │   └── tests/
│   │       └── contract.test.js
├── providers/
│   ├── [provider-name]/
│   │   ├── contracts/
│   │   │   └── [provider]-contract.groovy
│   │   └── tests/
│   │       └── contract-verification.test.js
├── shared/
│   ├── schemas/
│   │   └── api-schema.json
│   └── states/
│       └── provider-states.js
…

Output Files Explained:

• pacts/: Pact contract files in JSON format
• contracts/: Spring Cloud Contract definitions in Groovy/YAML
• tests/: Generated test files for contract verification
• schemas/: Shared schema definitions (JSON Schema, OpenAPI)
• states/: Provider state setup for test scenarios
• docs/: Human-readable contract documentation

Examples

Example 1: REST API User Service Contract

Scenario: Generate contract for a user service with CRUD operations

User Input:

/generate-contract --service user-api --consumer mobile-app --framework pact

Generated Pact Contract:

{
  "consumer": {
    "name": "mobile-app"
  },
  "provider": {
    "name": "user-api"
  },
  "interactions": [
    {
      "description": "a request to get a user",
      "providerState": "user with ID 123 exists",
      "request": {
        "method": "GET",
        "path": "/api/users/123",
        "headers": {
          "Accept": "application/json",
          "Authorization": "Bearer [token]"
        }
…

Generated Consumer Test:

// consumer-tests/user-api.test.js
const { Pact } = require('@pact-foundation/pact');
const { getUserById, createUser } = require('../src/api-client');

describe('User API Consumer Tests', () => {
  const provider = new Pact({
    consumer: 'mobile-app',
    provider: 'user-api',
    port: 8080,
    log: path.resolve(process.cwd(), 'logs', 'pact.log'),
    dir: path.resolve(process.cwd(), 'pacts'),
    logLevel: 'warn'
  });

  beforeAll(() => provider.setup());
  afterEach(() => provider.verify());
  afterAll(() => provider.finalize());
…