contract-testing

Files (1)

• SKILL.md

SKILL.md (first lines)

<objective>
Verify that services can communicate correctly without deploying them together.
</objective>

---

## Discovery Questions

1. **Architecture:** Microservices, monolith with separate consumers (mobile/SPA), or BFF pattern? Contract testing matters most when teams deploy independently.
2. **Who owns the contract?** Consumer-driven (consumers define what they need) or provider-driven (provider publishes a spec)? Most teams benefit from consumer-driven.
3. **API versioning strategy:** URL-based (`/v1/`, `/v2/`), header-based, or none? Contracts must account for version negotiations.
4. **How many consumer-provider pairs?** Start with the highest-traffic or most-fragile integration. Do not try to contract-test everything at once.
5. **Existing API specs:** Is there an OpenAPI/Swagger spec? If yes, consider schema-first contracts as a starting point.
6. **Check `.agents/qa-project-context.md` first.** Respect existing API conventions and testing infrastructure.

---

## Core Principles

**1. Consumers define what they need, providers verify they can deliver.** The consumer writes a test declaring "I will call `GET /users/123` and expect `{ id, name, email }`." The provider runs this test against its real implementation. If the provider cannot satisfy the contract, the build breaks before deployment.

**2. Contracts are the shared source of truth.** Not documentation, not Slack threads, not "just deploy and see." Contracts are executable tests that live in CI and block deployments on violation.

**3. Contract tests replace integration environments, not integration tests.** You still need integration tests for complex multi-step workflows. Contract tests eliminate the need to deploy consumer and provider together just to verify the interface.

**4. Break the build on contract violation.** A contract test that logs a warning but allows deployment provides zero value. Contracts must be deployment gates.

**5. Test the contract, not the business logic.** Consumer tests verify response shape and status codes. Provider verification ensures the contract is satisfiable. Business rules belong in unit and integration tests.

---

## Pact.js Setup

### Install

```bash
# Consumer side
npm i -D @pact-foundation/pact

# Provider side
npm i -D @pact-foundation/pact
```

### Consumer Test

The consumer defines what it needs from the provider. This generates a pact file (JSON contract).

> **Pact-JS v16 (Oct 2025) renamed `PactV4` → `Pact` and `MatchersV3` → `Matchers`.** The old names were removed in v16. If you copy from older blog posts/examples, update the imports. The API behavior is unchanged.

```typescript
// consumer/tests/contract/userApi.pact.spec.ts
// Requires @pact-foundation/pact >= 16
import { Pact, Matchers } from "@pact-foundation/pact";
import path from "path";
import { UserApiClient } from "../../src/userApiClient";

const { like, eachLike, integer, string, regex } = Matchers;

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

describe("User API Contract", () => {
  it("should return a user by ID", async () => {
    await provider
      .addInteraction()
      .given("user 123 exists")
      .uponReceiving("a request for user 123")
      .withRequest("GET", "/api/users/123", (builder) => {
        builder.headers({ Accept: "application/json" });
      })
      .willRespondWith(200, (builder) => {
        builder
          .headers({ "Content-Type": "application/json" })
          .jsonBody({
            id: integer(123),
            name: string("Alice Johnson"),
            email: regex("alice@example.com", "^[\\w.+-]+@[\\w-]+\\.[\\w.]+$"),
            role: string("member"),
            createdAt: regex("2024-01-15T00:00:00Z", "^\\d{4}-\\d{2}-\\d{2}T.*Z$"),
          });
      })
      .executeTest(async (mockServer) => {
        const client = new UserApiClient(mockServer.url);
        const user = await client.getUser(123);

        expect(user.id).toBe(123);
        expect(user.name).toBeDefined();
        expect(user.email).toContain("@");
      });
  });

  it("should return 404 for non-existent user", async () => {
    await provider
      .addInteraction()
      .given("user 999 does not exist")
      .uponReceiving("a request for non-existent user")
      .withRequest("GET", "/api/users/999")
      .willRespondWith(404, (builder) => {
        builder.jsonBody({
          error: string("Not Found"),
          message: string("User 999 not found"),
        });
      })
      .executeTest(async (mockServer) => {
        const client = new UserApiClient(mockServer.url);
        await expect(client.getUser(999)).rejects.toThrow("User 999 not found");
      });
  });

  it("should return a paginated list of users", async () => {
    await provider
      .addInteraction()
      .given("users exist")
      .uponReceiving("a request for the user list")
      .withRequest("GET", "/api/users", (builder) => {

From JaiminVadadoriya/Distributed-Cloud-Storage---Sync-Platform, MIT.

More from JaiminVadadoriya/Distributed-Cloud-Storage---Sync-Platform