Testing

Pact with Node.js and Express: API Contract Testing Step by Step

Contract testing with Pact shines brightest in Node.js microservice environments.

15 May 2026 — 6 min read

Contract testing with Pact shines brightest in Node.js microservice environments. Most Node.js APIs are Express or Fastify apps — they're relatively thin, the test setup is familiar, and pact-js integrates cleanly with Jest. This guide walks through a complete, realistic example from consumer test to provider verification to CI pipeline.

We'll build contract tests for a User Service that a Frontend consumer depends on.

Project Structure

Suppose you have two services:

frontend/          # React/Next.js app — the consumer
  src/
    clients/
      UserClient.js
  pacts/           # generated pact files go here

user-service/      # Express API — the provider
  src/
    app.js
    routes/users.js
  tests/
    pact/
      provider.pact.test.js

The Consumer: Frontend App

The frontend makes these calls to the User Service:

// frontend/src/clients/UserClient.js
import axios from 'axios';

export class UserClient {
  constructor(baseUrl) {
    this.baseUrl = baseUrl;
    this.http = axios.create({ baseURL: baseUrl });
  }

  async getUser(userId) {
    const { data } = await this.http.get(`/users/${userId}`);
    return data;
  }

  async createUser(userData) {
    const { data } = await this.http.post('/users', userData);
    return data;
  }

  async updateUser(userId, updates) {
    const { data } = await this.http.patch(`/users/${userId}`, updates);
    return data;
  }

  async deleteUser(userId) {
    await this.http.delete(`/users/${userId}`);
  }
}

Consumer Tests

// frontend/src/clients/UserClient.pact.test.js
import { PactV3, MatchersV3 } from '@pact-foundation/pact';
import path from 'path';
import { UserClient } from './UserClient';

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

// Define the mock provider
const provider = new PactV3({
  consumer: 'frontend',
  provider: 'user-service',
  dir: path.resolve(process.cwd(), 'pacts'),
  logLevel: 'error',
});

describe('UserClient Pact Tests', () => {
  // GET /users/:id
  describe('getUser', () => {
    it('returns a user when user exists', () => {
      provider
        .given('user with id 1 exists')
        .uponReceiving('GET /users/1')
        .withRequest({ method: 'GET', path: '/users/1' })
        .willRespondWith({
          status: 200,
          headers: { 'Content-Type': 'application/json' },
          body: {
            id: integer(1),
            email: regex('.+@.+\\..+', 'alice@example.com'),
            name: string('Alice'),
            role: string('user'),
            active: boolean(true),
            createdAt: string('2024-01-15T10:00:00.000Z'),
          },
        });

      return provider.executeTest(async (mockProvider) => {
        const client = new UserClient(mockProvider.url);
        const user = await client.getUser(1);

        // Consumer assertions — what the frontend actually uses
        expect(user.id).toBe(1);
        expect(user.email).toMatch(/.+@.+\..+/);
        expect(typeof user.name).toBe('string');
        expect(typeof user.active).toBe('boolean');
      });
    });

    it('returns 404 when user does not exist', () => {
      provider
        .given('user with id 999 does not exist')
        .uponReceiving('GET /users/999')
        .withRequest({ method: 'GET', path: '/users/999' })
        .willRespondWith({
          status: 404,
          body: {
            error: string('User not found'),
            code: string('USER_NOT_FOUND'),
          },
        });

      return provider.executeTest(async (mockProvider) => {
        const client = new UserClient(mockProvider.url);
        await expect(client.getUser(999)).rejects.toMatchObject({
          response: { status: 404 },
        });
      });
    });
  });

  // POST /users
  describe('createUser', () => {
    it('creates a new user and returns it with an id', () => {
      provider
        .given('no existing user with email bob@example.com')
        .uponReceiving('POST /users with valid data')
        .withRequest({
          method: 'POST',
          path: '/users',
          headers: { 'Content-Type': 'application/json' },
          body: {
            email: 'bob@example.com',
            name: 'Bob',
            role: 'user',
          },
        })
        .willRespondWith({
          status: 201,
          headers: { 'Content-Type': 'application/json' },
          body: {
            id: integer(2),
            email: string('bob@example.com'),
            name: string('Bob'),
            role: string('user'),
            active: boolean(true),
          },
        });

      return provider.executeTest(async (mockProvider) => {
        const client = new UserClient(mockProvider.url);
        const user = await client.createUser({
          email: 'bob@example.com',
          name: 'Bob',
          role: 'user',
        });

        expect(user.id).toBeGreaterThan(0);
        expect(user.email).toBe('bob@example.com');
      });
    });

    it('returns 409 when email already exists', () => {
      provider
        .given('user with email alice@example.com exists')
        .uponReceiving('POST /users with duplicate email')
        .withRequest({
          method: 'POST',
          path: '/users',
          body: { email: 'alice@example.com', name: 'Alice 2', role: 'user' },
        })
        .willRespondWith({
          status: 409,
          body: { error: like('Email already in use') },
        });

      return provider.executeTest(async (mockProvider) => {
        const client = new UserClient(mockProvider.url);
        await expect(
          client.createUser({ email: 'alice@example.com', name: 'Alice 2', role: 'user' })
        ).rejects.toMatchObject({ response: { status: 409 } });
      });
    });
  });

  // PATCH /users/:id
  describe('updateUser', () => {
    it('updates user fields and returns the updated user', () => {
      provider
        .given('user with id 1 exists')
        .uponReceiving('PATCH /users/1 with name update')
        .withRequest({
          method: 'PATCH',
          path: '/users/1',
          body: { name: 'Alice Updated' },
        })
        .willRespondWith({
          status: 200,
          body: {
            id: integer(1),
            name: string('Alice Updated'),
            email: string('alice@example.com'),
            role: string('user'),
            active: boolean(true),
          },
        });

      return provider.executeTest(async (mockProvider) => {
        const client = new UserClient(mockProvider.url);
        const updated = await client.updateUser(1, { name: 'Alice Updated' });
        expect(updated.name).toBe('Alice Updated');
        expect(updated.id).toBe(1);
      });
    });
  });

  // DELETE /users/:id
  describe('deleteUser', () => {
    it('returns 204 on successful delete', () => {
      provider
        .given('user with id 1 exists')
        .uponReceiving('DELETE /users/1')
        .withRequest({ method: 'DELETE', path: '/users/1' })
        .willRespondWith({ status: 204 });

      return provider.executeTest(async (mockProvider) => {
        const client = new UserClient(mockProvider.url);
        await expect(client.deleteUser(1)).resolves.toBeUndefined();
      });
    });
  });
});

Run consumer tests:

npx jest UserClient.pact.test.js

Output: pacts/frontend-user-service.json is generated.

The Provider: Express App

// user-service/src/app.js
import express from 'express';
import { db } from './db';

const app = express();
app.use(express.json());

// GET /users/:id
app.get('/users/:id', async (req, res) => {
  const user = await db.users.findById(parseInt(req.params.id));
  if (!user) {
    return res.status(404).json({ error: 'User not found', code: 'USER_NOT_FOUND' });
  }
  res.json(user);
});

// POST /users
app.post('/users', async (req, res) => {
  const { email, name, role } = req.body;
  const existing = await db.users.findByEmail(email);
  if (existing) {
    return res.status(409).json({ error: 'Email already in use' });
  }
  const user = await db.users.create({ email, name, role, active: true });
  res.status(201).json(user);
});

// PATCH /users/:id
app.patch('/users/:id', async (req, res) => {
  const user = await db.users.update(parseInt(req.params.id), req.body);
  if (!user) return res.status(404).json({ error: 'User not found' });
  res.json(user);
});

// DELETE /users/:id
app.delete('/users/:id', async (req, res) => {
  await db.users.delete(parseInt(req.params.id));
  res.status(204).send();
});

export { app };

Provider Verification Test

// user-service/tests/pact/provider.pact.test.js
import { Verifier } from '@pact-foundation/pact';
import path from 'path';
import { app } from '../../src/app';
import { db } from '../../src/db';

describe('Pact Provider Verification — user-service', () => {
  let server;

  beforeAll(async () => {
    await db.connect();
    server = app.listen(4001);
  });

  afterAll(async () => {
    server.close();
    await db.disconnect();
  });

  it('validates pact with frontend consumer', () => {
    const verifier = new Verifier({
      provider: 'user-service',
      providerBaseUrl: 'http://localhost:4001',

      // Read pact from file (for local dev; use broker URL in CI)
      pactUrls: [
        path.resolve(process.cwd(), '../frontend/pacts/frontend-user-service.json'),
      ],

      // State handlers — set up the database before each interaction
      stateHandlers: {
        'user with id 1 exists': async () => {
          await db.users.deleteAll();
          await db.users.insert({
            id: 1,
            email: 'alice@example.com',
            name: 'Alice',
            role: 'user',
            active: true,
            createdAt: new Date('2024-01-15T10:00:00.000Z'),
          });
        },
        'user with id 999 does not exist': async () => {
          await db.users.deleteById(999);
        },
        'no existing user with email bob@example.com': async () => {
          await db.users.deleteByEmail('bob@example.com');
        },
        'user with email alice@example.com exists': async () => {
          await db.users.deleteAll();
          await db.users.insert({
            id: 1,
            email: 'alice@example.com',
            name: 'Alice',
            role: 'user',
            active: true,
          });
        },
      },

      logLevel: 'warn',
    });

    return verifier.verifyProvider();
  });
});

Run provider verification:

npx jest provider.pact.test.js

CI Integration with GitHub Actions

# .github/workflows/contract-tests.yml
name: Contract Tests

on:
  push:
    branches: ['*']

jobs:
  consumer-tests:
    name: Frontend Consumer Tests
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: '20', cache: 'npm' }
      - name: Install dependencies
        run: cd frontend && npm ci
      - name: Run consumer pact tests
        run: cd frontend && npx jest --testPathPattern=pact
      - name: Publish pact to broker
        env:
          PACT_BROKER_URL: ${{ secrets.PACT_BROKER_URL }}
          PACT_BROKER_TOKEN: ${{ secrets.PACT_BROKER_TOKEN }}
        run: |
          cd frontend
          npx pact-broker publish ./pacts \
            --consumer-app-version ${{ github.sha }} \
            --tag ${{ github.ref_name }}

  provider-verification:
    name: User Service Provider Verification
    needs: consumer-tests
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: '20', cache: 'npm' }
      - name: Install dependencies
        run: cd user-service && npm ci
      - name: Run provider verification
        env:
          PACT_BROKER_URL: ${{ secrets.PACT_BROKER_URL }}
          PACT_BROKER_TOKEN: ${{ secrets.PACT_BROKER_TOKEN }}
          PROVIDER_VERSION: ${{ github.sha }}
        run: cd user-service && npx jest --testPathPattern=provider.pact

State Handler Best Practices

State handlers are the most error-prone part of provider verification. Key rules:

1. Always reset state completely:

'user with id 1 exists': async () => {
  // Don't assume previous state — reset completely
  await db.users.deleteAll();
  await db.users.insert({ id: 1, ... });
},

2. State handlers run synchronously before each interaction: If your handler is async (most database operations are), return the promise:

'user exists': async () => {
  await db.users.insert({ id: 1 }); // must be awaited
},

3. Don't share state between handlers: Each provider state is independent. Don't design your pacts so that one interaction depends on state set by a previous one.

4. Mirror your test database setup: State handlers are essentially test fixtures. Use the same factories or builders you use in unit tests.

Common Issues

"Body does not match": Usually a matcher issue. Check whether you're using like() vs an exact value. Provider returns 42 but consumer expects integer(42) — these are compatible. Provider returns "42" but consumer expects integer(42) — type mismatch.

"Unexpected request": The provider received a request not in the pact. Often means the consumer is sending requests the pact doesn't define. Add the missing interaction to the consumer test.

State handler not found: The provider state string in the consumer test must exactly match the state handler key on the provider. Case-sensitive, character-for-character match.

JSON Content-Type header: Include 'Content-Type': 'application/json' in request headers for POST/PATCH interactions. Without it, some Express setups won't parse the body.