contract-testing

Original：🇺🇸 English

Translated

Contract testing for API consumers and providers. Pact framework, Spring Cloud Contract, consumer-driven contracts, provider verification, and contract broker setup. USE WHEN: user mentions "contract testing", "Pact", "consumer-driven contract", "Spring Cloud Contract", "API contract", "provider verification" DO NOT USE FOR: OpenAPI validation - use `openapi-contract`; integration testing - use integration test skills

2installs

Sourceclaude-dev-suite/claude-dev-suite

Added on2026-03-12

NPX Install

npx skill4agent add claude-dev-suite/claude-dev-suite contract-testing

SKILL.md Content

View Translation Comparison →

Contract Testing

Pact (Consumer-Driven Contracts)

Consumer Test (Node.js)

typescript

import { PactV3, MatchersV3 } from '@pact-foundation/pact';

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

const provider = new PactV3({
  consumer: 'OrderService',
  provider: 'ProductService',
});

describe('Product API contract', () => {
  it('returns a product by ID', async () => {
    await provider
      .given('product 123 exists')
      .uponReceiving('a request for product 123')
      .withRequest({
        method: 'GET',
        path: '/api/products/123',
        headers: { Accept: 'application/json' },
      })
      .willRespondWith({
        status: 200,
        headers: { 'Content-Type': 'application/json' },
        body: like({
          id: string('123'),
          name: string('Widget'),
          price: integer(1999),
        }),
      })
      .executeTest(async (mockserver) => {
        const client = new ProductClient(mockserver.url);
        const product = await client.getProduct('123');
        expect(product.id).toBe('123');
        expect(product.name).toBeDefined();
      });
  });
});

Provider Verification

typescript

import { Verifier } from '@pact-foundation/pact';

describe('Product provider verification', () => {
  it('validates contracts', async () => {
    await new Verifier({
      providerBaseUrl: 'http://localhost:3000',
      pactUrls: ['./pacts/OrderService-ProductService.json'],
      // Or from broker:
      // pactBrokerUrl: 'https://pact-broker.example.com',
      // publishVerificationResult: true,
      // providerVersion: process.env.GIT_SHA,
      stateHandlers: {
        'product 123 exists': async () => {
          await db.product.create({ data: { id: '123', name: 'Widget', price: 1999 } });
        },
      },
    }).verifyProvider();
  });
});

Spring Cloud Contract

Contract Definition (Groovy DSL)

groovy

// contracts/shouldReturnProduct.groovy
Contract.make {
    description "should return product by ID"
    request {
        method GET()
        url "/api/products/123"
        headers { contentType applicationJson() }
    }
    response {
        status OK()
        headers { contentType applicationJson() }
        body([
            id: "123",
            name: $(regex('[A-Za-z ]+')),
            price: $(regex('[0-9]+')),
        ])
    }
}

Provider Base Test

java

@SpringBootTest(webEnvironment = WebEnvironment.MOCK)
@AutoConfigureMockMvc
public abstract class ContractBaseTest {
    @Autowired MockMvc mockMvc;
    @MockBean ProductRepository productRepo;

    @BeforeEach
    void setup() {
        when(productRepo.findById("123"))
            .thenReturn(Optional.of(new Product("123", "Widget", 1999)));
        RestAssuredMockMvc.mockMvc(mockMvc);
    }
}

Workflow

1. Consumer writes contract test → generates pact file
2. Pact file published to broker (or shared via file)
3. Provider runs verification against pact
4. Both sides deploy only when contracts pass

Pact Broker

bash

# Publish pact
npx pact-broker publish ./pacts \
  --consumer-app-version=$(git rev-parse HEAD) \
  --broker-base-url=https://pact-broker.example.com

# Can I Deploy?
npx pact-broker can-i-deploy \
  --pacticipant=OrderService \
  --version=$(git rev-parse HEAD) \
  --to-environment=production

Anti-Patterns

Anti-Pattern	Fix
Testing implementation details	Test contract shape, not business logic
Over-specifying response fields	Use matchers (like, regex), not exact values
No state management	Define provider states for test data setup
Contracts not in CI	Run contract tests in CI/CD pipeline
Skipping provider verification	Both sides must run their tests

Production Checklist

Consumer-driven contracts for all API dependencies
Pact Broker (or equivalent) for contract sharing
Provider verification in CI pipeline
```
can-i-deploy
```
check before deployment
Provider states for test data setup
Contract versioned with git SHA