api-contract-testing

SKILL.md

API Contract Testing

Table of Contents

Overview

When to Use

Quick Start

Reference Guides

Best Practices

Overview

Contract testing verifies that APIs honor their contracts between consumers and providers. It ensures that service changes don't break dependent consumers without requiring full integration tests. Contract tests validate request/response formats, data types, and API behavior independently.

When to Use

Testing microservices communication

Preventing breaking API changes

Validating API versioning

Testing consumer-provider contracts

Ensuring backward compatibility

Validating OpenAPI/Swagger specifications

Testing third-party API integrations

Catching contract violations in CI

Quick Start

Minimal working example:

// tests/pact/user-service.pact.test.ts
import { PactV3, MatchersV3 } from "@pact-foundation/pact";
import { UserService } from "../../src/services/UserService";

const { like, eachLike, iso8601DateTimeWithMillis } = MatchersV3;

const provider = new PactV3({
  consumer: "OrderService",
  provider: "UserService",
  port: 1234,
  dir: "./pacts",
});

describe("User Service Contract", () => {
  const userService = new UserService("http://localhost:1234");

  describe("GET /users/:id", () => {
    test("returns user when found", async () => {
      await provider
        .given("user with ID 123 exists")
        .uponReceiving("a request for user 123")
        .withRequest({
          method: "GET",
          path: "/users/123",
          headers: {
// ... (see reference guides for full implementation)

Reference Guides

Detailed implementations in the references/ directory:

Guide
Contents

Pact for Consumer-Driven Contracts
Pact for Consumer-Driven Contracts

OpenAPI Schema Validation
OpenAPI Schema Validation

JSON Schema Validation
JSON Schema Validation

REST Assured for Java
REST Assured for Java

Contract Testing with Postman
Contract Testing with Postman

Pact Broker Integration
Pact Broker Integration

Best Practices

✅ DO

Test contracts from consumer perspective

Use matchers for flexible matching

Validate schema structure, not specific values

Version your contracts

Test error responses

Use Pact broker for contract sharing

Run contract tests in CI

Test backward compatibility

❌ DON'T

Test business logic in contract tests

Hard-code specific values in contracts

Skip error scenarios

Test UI in contract tests

Ignore contract versioning

Deploy without contract verification

Test implementation details

Mock contract tests

1d:[