契約テスト（Pact）入門｜コンシューマー駆動の流れとコード例

契約テストは、API を呼ぶ側（コンシューマー）と提供する側（プロバイダー）が「このリクエストには、この形のレスポンスを返す」という約束（契約）を守れているかを、別々に確かめるテストです。 両方のサービスを同時に起動せずに、つなぎ目の食い違いを見つけられます。

Pact は「コンシューマー駆動」の契約テストのツールです。 呼ぶ側のテストから契約（pact ファイル）を作り、提供する側はその契約どおりに応答できるかを検証します。

確認環境：@pact-foundation/pact 17.1.4（内部の pact-core 20.2.0、Pact 仕様 4.0）、Vitest 5.0.4、Express 5.3.0、Node.js 22.22.2（Linux x64）で、手順 1・2・4 を実行しました。Pact のネイティブライブラリ（libpact_ffi.so）は npm の @pact-foundation/pact-core-linux-x64-glibc に入っており、追加のダウンロードなしで動きました。Pact Broker と can-i-deploy は、Pact のドキュメントと @pact-foundation/pact-cli 18.1.2 のヘルプで確かめました（確認日 2026年10月13日）。

契約テストが解決すること

マイクロサービスや、フロントエンドとバックエンドを別のチームが作る構成では、API の項目名・型・ステータスコードのずれがよく起きます。

単体テストのモックは「自分が思っている API」を真似るだけなので、相手が変わっても通り続けます。契約テストは、そのモックの中身を契約として相手に渡し、相手の本物で確かめる、というしくみです。

準備

npm init -y
npm pkg set type=module
npm i -D @pact-foundation/pact vitest

インストールすると、OS に合ったネイティブライブラリのパッケージ（Linux x64 なら @pact-foundation/pact-core-linux-x64-glibc）も入ります。package.json の engines では、Pact JS 17 は Node.js 22 以上です。

@pact-foundation/pact@17.1.4
├── @pact-foundation/pact-core@20.2.0
└── @pact-foundation/pact-core-linux-x64-glibc
    └── prebuilds/linux-x64/libpact_ffi.so, node.napi.node

Express の基本は、関連記事「Node.js Express入門｜Express5対応の最小APIをコピペで作る」で扱っています。

手順1・2：コンシューマーテストを書いて pact ファイルを作る

テストする API クライアント

注文画面（OrderWeb）が、ユーザー API（UserService）からユーザーを取る関数です。

// src/userClient.js
export async function getUser(baseUrl, id) {
  const res = await fetch(`${baseUrl}/users/${id}`, {
    headers: { Accept: 'application/json' },
  });
  if (res.status === 404) return null;
  if (!res.ok) throw new Error(`unexpected status ${res.status}`);
  const body = await res.json();
  return { id: body.id, name: body.name, email: body.email };
}

接続先の URL を引数で受け取る形にしておくと、テストでは Pact のモックサーバーに向けられます。

コンシューマーテスト（Vitest）

// test/user.consumer.test.js
import path from 'node:path';
import { describe, it, expect } from 'vitest';
import { PactV4, MatchersV3 } from '@pact-foundation/pact';
import { getUser } from '../src/userClient.js';

const { like, integer, regex } = MatchersV3;

const provider = new PactV4({
  consumer: 'OrderWeb',
  provider: 'UserService',
  dir: path.resolve(process.cwd(), 'pacts'),
  logLevel: 'warn',
});

describe('UserService の契約', () => {
  it('ユーザーが存在するとき 200 と利用者情報を返す', async () => {
    await provider
      .addInteraction()
      .given('ユーザー 1 が存在する', { id: 1 })        // プロバイダーの状態
      .uponReceiving('ユーザー 1 の取得')                 // やり取りの名前
      .withRequest('GET', '/users/1', (b) => {
        b.headers({ Accept: 'application/json' });
      })
      .willRespondWith(200, (b) => {
        b.headers({ 'Content-Type': 'application/json' });
        b.jsonBody({
          id: integer(1),                                  // 整数なら何でもよい
          name: like('山田 太郎'),                          // 文字列なら何でもよい
          email: regex('^[^@]+@[^@]+$', 'taro@example.com'),
        });
      })
      .executeTest(async (mockServer) => {
        const user = await getUser(mockServer.url, 1);
        expect(user).toEqual({ id: 1, name: '山田 太郎', email: 'taro@example.com' });
      });
  });

  it('ユーザーが存在しないとき 404 を返す', async () => {
    await provider
      .addInteraction()
      .given('ユーザー 999 は存在しない')
      .uponReceiving('存在しないユーザーの取得')
      .withRequest('GET', '/users/999', (b) => {
        b.headers({ Accept: 'application/json' });
      })
      .willRespondWith(404)
      .executeTest(async (mockServer) => {
        const user = await getUser(mockServer.url, 999);
        expect(user).toBeNull();
      });
  });
});

npx vitest run test/user.consumer.test.js

 Test Files  1 passed (1)
      Tests  2 passed (2)
   Duration  777ms (import 86%, transform 7%, tests 6%, worker 1%)

README では PactV3 の例が載っています。書き方はほぼ同じで、PactV4 は addInteraction() から始めます。

コンシューマーのテストが失敗する例

API クライアントが誤って /user/1（s が無い）を呼ぶと、モックサーバーが次のように知らせました。

ERROR (14474): pact@17.1.4: Test failed for the following reasons:
  Mock server failed with the following mismatches:
    0) The following request was not expected:
        Method: GET
        Path: /user/1
        ...
    1) The following request was expected but not received:
        Method: GET
        Path: /users/1
        Headers:
          Accept: application/json

モックサーバーは、期待していないリクエストには 500 を返します。このときクライアント側は Error: unexpected status 500 で失敗しました。テストが失敗したときは、pact ファイルは書き出されません。

できあがった pact ファイル

pacts/OrderWeb-UserService.json が作られました（2,305 バイト）。1つ目のやり取りの部分です。

{
  "consumer": { "name": "OrderWeb" },
  "interactions": [
    {
      "description": "ユーザー 1 の取得",
      "pending": false,
      "providerStates": [
        { "name": "ユーザー 1 が存在する", "params": { "id": 1 } }
      ],
      "request": {
        "headers": { "Accept": ["application/json"] },
        "method": "GET",
        "path": "/users/1"
      },
      "response": {
        "body": {
          "content": { "email": "taro@example.com", "id": 1, "name": "山田 太郎" },
          "contentType": "application/json",
          "encoded": false
        },
        "headers": { "Content-Type": ["application/json"] },
        "matchingRules": {
          "body": {
            "$.email": { "combine": "AND", "matchers": [{ "match": "regex", "regex": "^[^@]+@[^@]+$" }] },
            "$.id":    { "combine": "AND", "matchers": [{ "match": "integer" }] },
            "$.name":  { "combine": "AND", "matchers": [{ "match": "type" }] }
          }
        },
        "status": 200
      },
      "type": "Synchronous/HTTP"
    }
  ],
  "metadata": {
    "pact-js": { "version": "17.1.4" },
    "pactRust": { "ffi": "0.5.8", "models": "1.3.16" },
    "pactSpecification": { "version": "4.0" }
  },
  "provider": { "name": "UserService" }
}

matchingRules に、マッチャーで書いた「どこまで同じならよいか」が入ります。 値そのもの（山田 太郎）は例で、検証では型や正規表現で比べられます。

よく使うマッチャー

MatchersV3 にある主なものです。

値をそのまま書く（マッチャーを使わない）と、検証では完全一致で比べます。 一致を厳しくしすぎると、プロバイダーの小さな変更でも検証が落ちるので、コンシューマーが本当に使う項目と型だけを書きます。

手順4：プロバイダーで検証する

プロバイダーの API

// src/provider.js
import express from 'express';

export const users = new Map();

export function createApp() {
  const app = express();
  app.get('/users/:id', (req, res) => {
    const user = users.get(Number(req.params.id));
    if (!user) return res.status(404).end();
    res.json(user);
  });
  return app;
}

検証テスト

// test/user.provider.test.js
import path from 'node:path';
import { describe, it, beforeAll, afterAll } from 'vitest';
import { Verifier } from '@pact-foundation/pact';
import { createApp, users } from '../src/provider.js';

let server;
let port;

beforeAll(async () => {
  server = createApp().listen(0);                 // 空いているポートで起動
  await new Promise((r) => server.once('listening', r));
  port = server.address().port;
});
afterAll(() => server.close());

describe('UserService の契約の検証', () => {
  it('OrderWeb の契約を満たす', () => {
    return new Verifier({
      provider: 'UserService',
      providerBaseUrl: `http://127.0.0.1:${port}`,
      pactUrls: [path.resolve(process.cwd(), 'pacts/OrderWeb-UserService.json')],
      // given(...) の名前ごとに、テストデータを用意する
      stateHandlers: {
        'ユーザー 1 が存在する': async (params) => {
          users.clear();
          users.set(params.id, { id: params.id, name: '佐藤 花子', email: 'hanako@example.com' });
        },
        'ユーザー 999 は存在しない': async () => {
          users.clear();
        },
      },
      logLevel: 'warn',
    }).verifyProvider();
  });
});

Verifying a pact between OrderWeb and UserService
  ユーザー 1 の取得 (0s loading, 36ms verification)
     Given ユーザー 1 が存在する
    returns a response which
      has status code 200 (OK)
      includes headers
        "Content-Type" with value "application/json" (OK)
      has a matching body (OK)
  存在しないユーザーの取得 (0s loading, 7ms verification)
     Given ユーザー 999 は存在しない
    returns a response which
      has status code 404 (OK)
      has a matching body (OK)

 Test Files  1 passed (1)
      Tests  1 passed (1)

確かめられたことです。

• プロバイダーは名前に 佐藤 花子 を返しましたが、通りました。 契約では like('山田 太郎')（文字列なら何でもよい）としたためです。
• Express は Content-Type: application/json; charset=utf-8 を返しますが、application/json との比較で OK になりました。
• レスポンスに契約に無い項目（phone）を足しても、検証は通りました。 コンシューマーが使わない項目を増やすことは、契約を壊しません。

stateHandlers のキーは、コンシューマーの given(...) の文字列と完全に同じにします。params には given の第2引数（{ id: 1 }）が渡されます。

契約を破ったとき

プロバイダーが、name を fullName に変え、id を文字列にし、email を不正な値にしたときの出力です。

  ユーザー 1 の取得 (0s loading, 30ms verification)
     Given ユーザー 1 が存在する
    returns a response which
      has status code 200 (OK)
      includes headers
        "Content-Type" with value "application/json" (OK)
      has a matching body (FAILED)

Failures:

1) Verifying a pact between OrderWeb and UserService Given ユーザー 1 が存在する - ユーザー 1 の取得
    1.1) has a matching body
           $ -> Actual map is missing the following keys: name
           $.email -> Expected 'hanako' to match '^[^@]+@[^@]+$'
           $.id -> Expected '1' (String) to be an integer

There were 1 pact failures

どのコンシューマーの、どのやり取りの、どの項目かが分かるので、プロバイダーの開発者は相手のコードを読まずに直す場所を決められます。

プロキシの環境変数に注意

HTTPS_PROXY が設定されたシェルで検証を実行すると、プロバイダーへのリクエストがプロキシに送られ、すべてのやり取りが expected 200 but was 403 で失敗しました。NO_PROXY に 127.0.0.1 があっても同じで、検証のときだけ HTTPS_PROXY を外すと通りました。

env -u HTTPS_PROXY -u https_proxy npx vitest run test/user.provider.test.js

手順3・5：Pact Broker と can-i-deploy

Pact Broker の役割

Pact Broker は、pact ファイルと検証の結果を、版（バージョン）ごとに保存して共有するサーバーです。 オープンソース版（Docker イメージ）と、SaaS の PactFlow があります。

pact ファイルの登録（コンシューマーの CI）

npm の @pact-foundation/pact-cli（18.1.2）を入れると、pact broker コマンドが使えます。

npm i -D @pact-foundation/pact-cli

npx pact broker publish ./pacts \
  --broker-base-url "$PACT_BROKER_BASE_URL" \
  --broker-token "$PACT_BROKER_TOKEN" \
  --consumer-app-version "$GIT_SHA" \
  --branch "$GIT_BRANCH"

Broker から取って検証する（プロバイダーの CI）

pactUrls の代わりに Broker の情報を渡します（オプション名は pact-core の型定義で確認）。

new Verifier({
  provider: 'UserService',
  providerBaseUrl: `http://127.0.0.1:${port}`,
  pactBrokerUrl: process.env.PACT_BROKER_BASE_URL,
  pactBrokerToken: process.env.PACT_BROKER_TOKEN,
  // どの版の契約を検証するか
  consumerVersionSelectors: [
    { mainBranch: true },          // コンシューマーの main ブランチの最新
    { matchingBranch: true },      // 同じ名前のブランチ
    { deployedOrReleased: true },  // どこかの環境に出ている版
  ],
  enablePending: true,             // 新しい契約で落ちてもビルドを止めない
  publishVerificationResult: process.env.CI === 'true',
  providerVersion: process.env.GIT_SHA,
  providerVersionBranch: process.env.GIT_BRANCH,
  stateHandlers: { /* 上と同じ */ },
}).verifyProvider();

can-i-deploy

pact broker can-i-deploy --help の説明では、指定した版が、その環境にすでに出ている相手の各版と、検証に成功しているかを確かめ、終了コード 0 か 1 を返します。

# デプロイ前：この版を production に出してよいか
npx pact broker can-i-deploy \
  --pacticipant OrderWeb --version "$GIT_SHA" \
  --to-environment production \
  --broker-base-url "$PACT_BROKER_BASE_URL" --broker-token "$PACT_BROKER_TOKEN"

# デプロイ後：production に出したことを記録する
npx pact broker record-deployment \
  --pacticipant OrderWeb --version "$GIT_SHA" \
  --environment production \
  --broker-base-url "$PACT_BROKER_BASE_URL" --broker-token "$PACT_BROKER_TOKEN"

ドキュメントの Pact Matrix の例です（Foo がコンシューマー、Bar がプロバイダー、production には Bar 56 が出ている）。

この表では、Foo 23 は production の Bar 56 と検証済みなので「出してよい」、Foo 24 は Bar 56 との検証が無いので「出してはいけない」と判定されます。

ヘルプにある使い方の注意です。

CI の流れ

GitHub Actions の基本は、関連記事「CI/CDとは｜GitHub Actionsで最初のパイプラインを作るまで」で扱っています。

OpenAPI との違い

OpenAPI は「API で何ができるか」、Pact は「相手が実際に何を使っているか」を表します。 両方を使う場合、OpenAPI で設計を合意し、Pact でつなぎ目を守る、という分け方ができます。PactFlow には、OpenAPI とコンシューマーの契約を突き合わせる「双方向契約テスト（Bi-Directional Contract Testing）」もあります。OpenAPI の書き方は、関連記事「API設計書の書き方｜Markdown・OpenAPIテンプレートと記入例」で扱っています。

E2E テストとの使い分け

契約テストは E2E テストを置き換えるものではありません。 サービス間のつなぎ目の確認を契約テストに移すと、E2E テストを「大事な業務の流れ」に絞れます。E2E テストの書き方は、関連記事「Playwright入門｜E2Eテストの書き方とCI実行まで実行結果つきで解説」で扱っています。API 単体の観点は、関連記事「APIテストの観点チェックリスト｜正常系・異常系・認可・境界値」で扱っています。

契約を書くときの注意

よくある質問

Q. pact ファイルはどこに置きますか。 A. 小さく試すときはリポジトリやファイル共有でも動きます（この記事では pactUrls でファイルを直接指定）。複数の版と環境を扱うなら、Pact Broker に置くと can-i-deploy が使えます。

Q. プロバイダーが Java（Spring Boot）でも使えますか。 A. 使えます。pact ファイルは言語に依存しない JSON で、Pact JVM などで検証できます。Spring Boot の API は、関連記事「Spring BootでREST APIを作る｜入力チェック・エラー処理・テストまで」で扱っています。

Q. メッセージ（キュー）のやり取りにも使えますか。 A. Pact JS には、非同期メッセージ用の addAsynchronousInteraction() や MessageConsumerPact があります。

Q. 検証で has status code 200 (FAILED) と 403 が出ます。 A. プロバイダーの認証やプロキシが原因のことがあります。認証が要る API は、requestFilter などでヘッダーを足す方法がドキュメントにあります。プロキシは上の「プロキシの環境変数に注意」を見てください。

まとめ

• 契約テストは、呼ぶ側と提供する側の約束を、両方を同時に起動せずに確かめる
• Pact はコンシューマーのテストから pact ファイルを作り、プロバイダーで再生して検証する
• マッチャー（like・integer・regex など）で、値ではなく型や形式で比べる
• 検証の失敗は、Actual map is missing the following keys: name のように項目単位で出る
• Pact Broker は契約と検証の結果を版ごとに保存し、can-i-deploy がデプロイしてよいかを終了コードで答える
• OpenAPI は API の全体、Pact は実際に使われる部分。E2E テストは業務の流れに絞る

参考・出典

確認日はいずれも 2026年10月13日です。

• Pact Docs「Introduction」：https://docs.pact.io/
• Pact Docs「Consumer Tests（JavaScript）」：https://docs.pact.io/implementation_guides/javascript/docs/consumer
• Pact Docs「Provider Verification（JavaScript）」：https://docs.pact.io/implementation_guides/javascript/docs/provider
• Pact Docs「Can I Deploy」：https://docs.pact.io/pact_broker/can_i_deploy
• Pact Docs「Pact Broker」：https://docs.pact.io/pact_broker
• pact-js（GitHub）：https://github.com/pact-foundation/pact-js
• @pact-foundation/pact（npm）：https://www.npmjs.com/package/@pact-foundation/pact
• PactFlow「Bi-Directional Contract Testing」：https://docs.pactflow.io/docs/bi-directional-contract-testing

株式会社RJC ― SI事業・SES事業・AI駆動開発。RJCは一緒に成長を楽しめる会社です。