api-contract-testing

API コントラクトテスト

目次

• 概要
• 使用する場面
• クイックスタート
• リファレンスガイド
• ベストプラクティス

概要

コントラクトテストでは、API がコンシューマーとプロバイダー間のコントラクトを遵守しているかを検証します。完全な統合テストを実施しなくても、サービスの変更によって依存するコンシューマーが破損しないことを確認できます。コントラクトテストでは、リクエスト／レスポンスの形式、データ型、API の動作を個別に検証します。

使用する場面

• マイクロサービス間の通信をテストする
• API の互換性を損なう変更を防ぐ
• API のバージョン管理を検証する
• コンシューマーとプロバイダー間のコントラクトをテストする
• 後方互換性を確保する
• OpenAPI／Swagger 仕様を検証する
• サードパーティ API との統合をテストする
• CI でコントラクト違反を検出する

クイックスタート

最小限の実行例：

// 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)

リファレンスガイド

詳細な実装は references/ ディレクトリにあります：

ガイド	内容
コンシューマー主導のコントラクトに対応する Pact	コンシューマー主導のコントラクトに対応する Pact
OpenAPI スキーマの検証	OpenAPI スキーマの検証
JSON Schema の検証	JSON Schema の検証
Java 向け REST Assured	Java 向け REST Assured
Postman を使ったコントラクトテスト	Postman を使ったコントラクトテスト
Pact Broker の統合	Pact Broker の統合

ベストプラクティス

✅ 推奨事項

• コンシューマーの視点からコントラクトをテストする
• 柔軟に照合するためにマッチャーを使用する
• 特定の値ではなく、スキーマ構造を検証する
• コントラクトをバージョン管理する
• エラーレスポンスをテストする
• コントラクトの共有に Pact broker を使用する
• CI でコントラクトテストを実行する
• 後方互換性をテストする

❌ 禁止事項

• コントラクトテストでビジネスロジックをテストする
• コントラクトに特定の値をハードコードする
• エラーシナリオを省略する
• コントラクトテストで UI をテストする
• コントラクトのバージョン管理を無視する
• コントラクトを検証せずにデプロイする
• 実装の詳細をテストする
• コントラクトテストをモックする