WireMock スタンドアロン Docker スキル

概要

WireMock をスタンドアロン Docker コンテナとして実行し、統合テストおよびエンドツーエンドテスト中に外部 API をモック化するためのパターンを提供します。WireMock を独立したサービスとして実行し、HTTP クライアント、リトライロジック、エラーハンドリングをテストするための実際の API 動作をシミュレートします。

使用場面

以下の場合に使用します:

• 統合テストまたはエンドツーエンドテスト中に外部 API をモック化する必要がある
• 実際のサービスを使わずにエラー条件（タイムアウト、5xx、レート制限）をシミュレートする
• HTTP クライアント設定、リトライロジック、エラーハンドリングをテストする
• ポータブルで再現可能なテスト環境を作成する
• 実際のサービスを実装する前に API コントラクトを検証する

手順

ステップ 1: Docker Compose のセットアップ

WireMock 3.5.2、ポートマッピング、マッピングおよびファイルのボリュームマウントを含む docker-compose.yml を作成します:

version: "3.8"
services:
  wiremock:
    image: wiremock/wiremock:3.5.2
    ports:
      - "8080:8080"
    volumes:
      - ./wiremock:/home/wiremock
    command: ["--global-response-templating"]

ステップ 2: ディレクトリ構造の作成

WireMock の設定ディレクトリを作成します:

wiremock/
├── mappings/   # JSON スタブ定義
└── __files/   # レスポンスボディファイル

ステップ 3: API マッピングの定義

各シナリオ用に wiremock/mappings/ に JSON スタブファイルを作成します:

• 成功: 200 と JSON ボディを返す
• 未検出: 404 を返す
• サーバーエラー: 500 を返す
• タイムアウト: fixedDelayMilliseconds を使用
• レート制限: 429 と Retry-After ヘッダーを返す

ステップ 4: WireMock の起動

docker compose up -d

ステップ 5: WireMock が動作していることを確認

curl http://localhost:8080/__admin/mappings

期待結果: スタブが読み込まれていない場合は空の配列 {"mappings":[]} を返し、またはあなたのスタブ定義を返します。接続拒否エラーが表示される場合は、コンテナが実行されているか確認してください: docker compose ps

ステップ 6: HTTP クライアントの設定

アプリケーションが実際の API ではなく http://localhost:8080 (または Docker ネットワーク内では http://wiremock:8080) を指すようにしてください。

ステップ 7: エッジケースのテスト

常に以下をテストしてください: 200、400、401、403、404、429、500、タイムアウト、不正な形式のレスポンス。

例

例 1: 成功した GET リクエストをモック化

{
  "request": { "method": "GET", "url": "/api/users/123" },
  "response": {
    "status": 200,
    "jsonBody": { "id": 123, "name": "Mario Rossi" }
  }
}

例 2: サーバーエラーをモック化

{
  "request": { "method": "GET", "url": "/api/error" },
  "response": { "status": 500, "body": "Internal Server Error" }
}

例 3: タイムアウトをモック化

{
  "request": { "method": "GET", "url": "/api/slow" },
  "response": {
    "status": 200,
    "fixedDelayMilliseconds": 5000,
    "jsonBody": { "message": "delayed" }
  }
}

例 4: アプリケーション付き Docker Compose

services:
  wiremock:
    image: wiremock/wiremock:3.5.2
    ports:
      - "8080:8080"
    volumes:
      - ./wiremock:/home/wiremock

  app:
    build: .
    environment:
      - API_BASE_URL=http://wiremock:8080
    depends_on:
      - wiremock

ベストプラクティス

1. 機能ごとにマッピングを整理する: users/、products/ のようなサブディレクトリを使用
2. マッピングをバージョン管理に含める: 再現可能なテストのためにマッピングを git に保持する
3. すべてのエラーシナリオをテストする: 401、403、404、429、500、タイムアウト
4. テスト実行間でリセットする: curl -X POST http://localhost:8080/__admin/reset
5. わかりやすいファイル名を使用する: get-user-success.json、post-user-error.json

制約と警告

• ポート 8080 が利用可能であることを確認するか、別のポートにマップします
• 複数のコンテナを実行する場合は Docker ネットワークを設定してください
• 動的レスポンスのために --global-response-templating を有効にしてください
• コンテナ再起動時に WireMock はマッピングをリセットします

トラブルシューティング

リクエストがスタブにマッチしない? WireMock が受け取ったものを確認してください: curl http://localhost:8080/__admin/requests — マッチしないリクエストと実際に送信された内容の詳細を表示します。

スタブファイルが読み込まれない? ファイルの場所を確認してください: JSON スタブを wiremock/mappings/ に、レスポンスファイルを wiremock/__files/ に配置します。ファイルのパーミッションを確認してください。

接続拒否エラー? docker compose ps を実行してコンテナが実行されていることを確認します。lsof -i :8080 でポート競合を確認します。

参考資料

references/ で完全な例を参照してください:

• docker-compose.yml - 完全な Docker Compose 設定
• wiremock/mappings/ - すべてのシナリオの完全なスタブ例