0
0

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?

@tonbi_attack

WireMockのAdmin APIを使って「なぜモックに当たらないのか」を調査する

0
Posted at

はじめに

この記事では、WireMockで「mappingはあるのに期待したモックに当たらない」問題を、Admin APIで切り分ける方法を整理します。

重要なのは、設定を見るAPIと、実際に届いたリクエストを見るAPIを分けて使うことです。mappingファイルだけを確認しても、実際にどのスタブが選ばれたかまでは分かりません。

対象読者は、DockerやCI/CDでWireMockを動かしており、次のような状態に困っている人です。

  • mappingファイルは配置されている
  • GET /__admin/mappings では対象のmappingが見つかる
  • それでも実リクエストでは期待と違うレスポンスが返る

WireMockの基本的な起動方法とスタブ定義は、WireMock を Docker で動かして外部 API をスタブするで整理しています。

率直な結論

調査では、次の2つを突き合わせます。

  • GET /__admin/mappings: WireMockに登録されている設定
  • GET /__admin/requests: WireMockで実際に処理したリクエスト

この2つは同じことを確認するAPIではありません。

mappingsは「どの条件なら、どのレスポンスを返す設定か」を示します。requestsは「実際には、どのリクエストを受け、どのスタブを選んだか」を示します。

期待したmappingが存在することと、そのmappingが選ばれたことは別です。この違いを最初に意識すると、調査の方向を誤りにくくなります。

GET /__admin/mappingsで設定を確認する

次のリクエストで、現在のWireMockに登録されているmapping一覧を取得できます。

curl -s http://localhost:8080/__admin/mappings | jq

例えば、次のmappingが登録されているとします。

{
  "request": {
    "method": "GET",
    "url": "/users/1"
  },
  "response": {
    "status": 200,
    "jsonBody": {
      "id": 1,
      "name": "Taro"
    }
  }
}

確認する項目は次のとおりです。

  • HTTPメソッド
  • URL、URLパターン、クエリパラメータ
  • ヘッダーとリクエストボディの条件
  • priority
  • bodyFileNameを含むレスポンス定義

このAPIは、期待したWireMockプロセスに接続できているか、必要なmappingがロード済みかを確認する最初の手段になります。公式ドキュメントでも、登録済みスタブの取得とWireMockの稼働確認に使えるとされています。

UUIDの404だけでmapping不在と判断しない

一覧レスポンスにはmappingのUUIDが含まれます。個別取得は次のAPIです。

curl -s \
  http://localhost:8080/__admin/mappings/89f60f38-9fd9-4be8-a880-4fea74879fdc \
  | jq

ただし、過去に控えたUUIDが404だったとしても、mappingそのものが存在しないとは限りません。再起動や再読込、mappingの再登録によってUUIDが変わる運用もあるためです。

まず一覧を取り、URL、メソッド、bodyFileName、metadataなどから対象のmappingを探します。UUIDはその時点で稼働中のスタブを追跡するための識別子として扱うと安全です。

GET /__admin/requestsで実際の通信を確認する

アプリケーションから問題のAPIを1回呼んだ直後に、次を実行します。

curl -s http://localhost:8080/__admin/requests | jq

Request Journalには、WireMockが受け取ったリクエストと、スタブに一致したかどうかが記録されます。レスポンスにはリクエストのURL、メソッド、ヘッダー、ボディに加え、wasMatchedやレスポンス定義が含まれます。

確認する順番は次のとおりです。

  1. 対象リクエストが記録されているか
  2. URL、メソッド、ヘッダー、ボディは想定どおりか
  3. wasMatchedがtrueか
  4. 一致したスタブは期待したものか

Request Journalはメモリ上の受信履歴です。負荷試験向けの設定などで無効化されている場合は使えません。WireMock公式のVerificationガイドも、受信リクエストの調査にはRequest Journalを使うと説明しています。

「mappingはあるが、通信が来ていない」を分ける

mappingsに対象があり、requestsに対象リクエストがない場合、問題はrequest matchingより手前にあります。

  • アプリケーションの接続先が別のホストやポートを向いている
  • Docker Compose内でlocalhostを指定している
  • プロキシやサービスディスカバリが別の宛先へ送っている
  • アプリケーション側でリクエスト送信前に失敗している

特にComposeでは、アプリケーションコンテナのlocalhostはWireMockコンテナではなく、アプリケーション自身を指します。Compose内からは、通常はサービス名を使ってhttp://wiremock:8080へ接続します。

この状態でスタブの条件を書き換えても解決しません。まずWireMockに届いていない原因を調べます。

unmatched requestで条件不一致を確認する

WireMockまでは届いているが、どのスタブにも一致しない場合は次を実行します。

curl -s \
  http://localhost:8080/__admin/requests/unmatched \
  | jq

ここに対象リクエストがあれば、通信経路は問題ありません。疑うべき対象はmappingの条件です。

よくある違いは次のとおりです。

  • GETとPOSTが異なる
  • /reportと/report/が異なる
  • query parameterが足りない、または余分に付いている
  • Content-Typeや認証ヘッダーが異なる
  • JSONやXMLのボディ条件が一致しない
  • XPathやJSONPathが実際のデータを取得できていない

unmatched requestは「WireMockが受信したが、設定済みのスタブには一致しなかったリクエスト」を返します。HTTP APIではGET /__admin/requests/unmatchedで取得できます。公式ドキュメントも参照してください。

Near Missで近いmappingを探す

条件の差分が細かい場合は、Near Missが役立ちます。Near Missは完全には一致しなかったリクエストに対して、近いmappingを距離順に返します。

例えば、設定がPOST /reportかつXML中のMSNが123で、実際にはMSNが456だったとします。URLとメソッドは正しくても、ボディ条件だけが違う状況です。

Request Journalから対象リクエストの内容を取得し、次のAPIへ渡します。

curl -s -X POST \
  http://localhost:8080/__admin/near-misses/request \
  -H 'Content-Type: application/json' \
  -d @actual-request.json \
  | jq

レスポンスのstubMappingとmatchResultを確認すると、どの条件が近かったかを追えます。Near Missは、URLのわずかな違いやボディ条件の不一致を調べるときに有効です。詳細な形式は公式ドキュメントを参照してください。

別のmappingに当たっていないかを確認する

wasMatchedがtrueでも安心はできません。汎用的なスタブに一致し、期待した個別スタブが選ばれていないことがあります。

例えば、次の2つが登録されているとします。

{
  "priority": 1,
  "request": {
    "method": "POST",
    "url": "/report"
  },
  "response": {
    "status": 200,
    "bodyFileName": "report/success.xml"
  }
}

{
  "priority": 10,
  "request": {
    "urlPattern": ".*"
  },
  "response": {
    "status": 200,
    "bodyFileName": "default.xml"
  }
}

WireMockでは、小さいpriorityが優先されます。個別スタブの条件が1つでも外れると、後者のようなフォールバックスタブが選ばれることがあります。

Request Journalで実際に選ばれたスタブを特定し、そのUUIDでmappingを取得します。そこから、期待と異なるurlPattern、priority、レスポンスファイルを確認します。

期待したスタブに一致しているのにレスポンスが違う場合

この場合はrequest matchingではなく、レスポンス定義を調べます。

特にbodyFileNameを使う場合、mappingとレスポンスファイルは別の責務です。

  • mapping: どのリクエストに反応するか
  • bodyFileName: どのファイルをレスポンスとして返すか

次のようなmappingでは、report/success.xmlが__files配下に存在し、期待した内容である必要があります。

{
  "response": {
    "status": 200,
    "bodyFileName": "report/success.xml"
  }
}

期待したスタブに一致していても、別のファイルを指していたり、ファイルの反映が遅れていたりすれば、期待とは違うレスポンスになります。

Request Journalを安全に使う

履歴が多い環境では、古いリクエストが混ざると判断を誤りやすくなります。個人用のローカル環境なら、次の手順が分かりやすいです。

  1. DELETE /__admin/requestsでJournalを空にする
  2. 問題の操作を1回だけ実行する
  3. GET /__admin/requestsで結果を確認する
curl -X DELETE http://localhost:8080/__admin/requests

共有環境でJournalを消すと、他の利用者の調査履歴にも影響します。その場合は削除せず、sinceやlimitのクエリパラメータで対象を絞る方が安全です。

curl -s \
  'http://localhost:8080/__admin/requests?since=2026-08-11T10:00:00&limit=10' \
  | jq

sinceとlimitは、Request Journalの取得結果を時刻と件数で絞り込むためのパラメータです。利用できるエンドポイントやパラメータはWireMockのバージョンによって差があり得るため、実行環境のAdmin API Referenceも確認します。

Admin APIからの直接登録は切り分けに限定する

Admin APIでmappingを直接登録すれば、ファイル配置や再読込を待たずに、実行中のWireMockで条件を試せます。

curl -X POST \
  http://localhost:8080/__admin/mappings \
  -H 'Content-Type: application/json' \
  -d @mapping.json

同じmappingを直接登録すると動くのに、CI/CD経由の反映では動かない場合、mappingの内容よりも次の経路を疑えます。

ただし、Admin APIで登録した状態は再起動後も残るとは限りません。Gitで管理しているmappingファイルを正とし、直接登録は原因確認や一時的な検証に留めます。

また、共有環境ではresetやmapping削除など、ほかの利用者へ影響するAPIを不用意に実行しないことが大切です。

CI/CDではreadinessを3段階で確認する

CI/CDが成功しても、WireMockが必要なスタブを読み込み終え、実リクエストを処理できるとは限りません。固定時間のsleepより、確認する状態を分けたreadiness checkの方が状況を正しく判断できます。

Level 1: /__admin/mappings がHTTP 200を返す
    ↓
WireMockのAdmin APIが応答できる

Level 2: 必要なmappingが一覧に存在する
    ↓
必要な設定のロードを確認できる

Level 3: probe requestが期待するレスポンスを返す
    ↓
実際に利用可能であることを確認できる

次のコマンドで確認できるのはLevel 1だけです。WireMockプロセスが起動し、Admin APIに応答できることは分かりますが、必要なmappingがロード済みであることまでは保証しません。

for i in $(seq 1 30); do
  if curl -sf http://wiremock:8080/__admin/mappings >/dev/null; then
    exit 0
  fi

  sleep 2
done

exit 1

Level 2では、取得したmapping一覧に必要なURLやmetadataが含まれることを確認します。Level 3では、実運用に近いprobe requestを送り、期待するstubに一致し、期待するレスポンスが返ることまで検証します。

CI/CDの成功条件を「ファイルを配置できた」ではなく「必要なモックが実リクエストを処理できる」と置くと、反映不整合を早く検出できます。重要な試験環境では、少なくともLevel 2、可能ならLevel 3までを完了条件にします。

障害調査の手順

実務では、次の順番で確認すると切り分けやすくなります。

この順番なら、原因を次のどこにあるかまで絞れます。

  • mappingの未反映
  • WireMockまでの通信不達
  • リクエスト条件の不一致
  • 汎用mappingの誤選択
  • レスポンス定義や外部ファイルの不備

まとめ

WireMockの調査では、mappingファイルだけを見て判断しないことが重要です。

まずGET /__admin/mappingsで、稼働中のWireMockに期待した設定があるかを確認します。次にGET /__admin/requestsで、実際に届いたリクエストと選ばれたスタブを確認します。

一致しなければ/requests/unmatchedとNear Missで条件差分を追い、一致しているのに結果が違えば、priorityやbodyFileNameを調べます。

WireMockはレスポンスを返すだけのモックではありません。Admin APIとRequest Journalを使うことで、実行中の状態を観測できるデバッグ対象になります。

0
0
0

Register as a new user and use Qiita more conveniently

  1. You get articles that match your needs
  2. You can efficiently read back useful information
  3. You can use dark theme
What you can do with signing up
Sign upLogin
0
0

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?