wiremock-standalone-docker

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 stub definitions
└── __files/   # Response body files

ステップ 3：API マッピングを定義する

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

• 成功：JSON ボディを含む 200 を返します
• 見つからない場合：404 を返します
• サーバーエラー：500 を返します
• タイムアウト：fixedDelayMilliseconds を使用します
• レート制限：Retry-After ヘッダーを含む 429 を返します

ステップ 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/ - すべてのシナリオを網羅したスタブの例