VPSでWireMockとHurlをセルフホストする方法
WireMockはGitで管理するスタブ、HurlはCIで実行するAPIテストです。VPS上でDocker Composeにまとめ、再構築後もレポートを残す構成を紹介します。
1 つのリポジトリを共有する 2 つのジョブ
セルフホスト型の API モックとテストは別のジョブです。これらを 1 つとして扱うと、1 週間を無駄にします。モックサーバーは、CI から呼び出せない依存サービスの代わりになります。決済プロバイダー、パートナー API、レート制限のある上流サービス、別チームがまだリリースしていないサービスなどです。API テストランナーは、自分たちのエンドポイントを決められた順序で呼び出し、レスポンスを検証します。あるレスポンスの値を次のリクエストに引き継ぐこともできます。
両方の役割を担えるツールもあります。モックサーバーの主な役割は、リクエストに応答することです。テストランナーは、カードが拒否されたときに決済プロバイダーが何を返すかについて関知しません。すでにサーバーを借りているチームの多くは、同じ Docker Compose ファイルで起動し、同じ pull request でレビューするモックサーバーとテストランナーを 1 つずつ運用します。
セルフホストで API のモックとテストを行う理由
テスト用フィクスチャは、本番環境に近い形のデータです。API テストのリクエスト本文には、名前だけを変更した実際の顧客レコードが入ることがあります。誰も確認しなければ、名前すら変更されていない場合もあります。記録したスタブはさらに危険です。プロキシによる記録では、アップストリームが実際に返した内容が保存されます。そのため、記録して作成したスタブ用ディレクトリには、誰かが全ファイルを確認するまで、実際のトークンや顧客のメールアドレスが残ります。ホステッドサービスでこのデータを扱うと、他者のインシデントとなり、情報漏えいにつながります。
2 つ目の理由は、到達性です。プライベートアドレスにバインドしたサービスへ、ホステッドランナーからアクセスするには、事前にプライベートネットワーク接続が必要です。どの回避策にもコストがかかります。テストのために API をインターネットへ公開すると、非公開にしていた理由が失われます。トンネルや公開ステージング環境のコピーは、別途保守するシステムです。また、ステージング環境のコピーはリリースの間に本番環境から乖離します。GitHub-hosted runners では、WireGuard オーバーレイまたは Azure Virtual Network を使ったプライベートアクセスも利用できます。同じプライベートネットワーク上のランナーなら、サービスを直接呼び出せるため、これらは不要です。これが、self-hosted GitHub Actions runner を使う実務上の理由です。
セルフホスト型モックサーバーはどれを運用すべきか
これらはすべて、所有するサーバー上でコンテナとして実行できます。重要なのは、それぞれが何を正本として扱うかです。それによって、コンテナを再構築しても何も失わずに済むのか、それとも半日かかるのかが決まります。
- WireMock は、すべてのスタブを
mappings/ディレクトリ内の JSON ファイルとして保持し、大きなレスポンス本文を__files/に保存します。イメージはwiremock/wiremock、コンテナ内のルートディレクトリは/home/wiremockです。また、記録プロキシとしても動作します。ディスク上のファイルを使うため、他のコードと同じようにモックを git で管理できます。 - Mockoon CLI は、モック API 全体を 1 つの JSON データファイルに保持します。
npm install -g @mockoon/cliでインストールしてmockoon-cli start --data ./data-file.jsonで起動するか、そのファイルを bind mount してmockoon/cliイメージを実行します。デスクトップアプリも同じファイルを編集するため、UI で設計して結果をコミットする運用と互換性があります。 - MockServer は
mockserver/mockserverイメージから実行し、ポート 1080 で待ち受けます。期待値は独自の REST API 経由で登録するため、テストコードからの操作には便利ですが、デプロイ方法としては注意が必要です。デフォルトでは、HTTP 呼び出しで作成した期待値はコンテナの再起動時に消えます。恒久的に使うスタブには、JSON 初期化ファイルを使用してください。実行時の変更を保持するにはpersistExpectationsを有効にし、出力ファイルをコンテナ外に永続化して、起動時にinitializationJsonPathから読み込みます。 - Prism は、個別のスタブファイルではなく OpenAPI ドキュメントからモックを生成します。
npm install -g @stoplight/prism-cliでインストールし、その後prism mock openapi.yamlを実行します。コンテナ内では-h 0.0.0.0を追加してください。Prism はデフォルトで localhost に bind するため、指定しないとコンテナ外部から到達できません。 - Microcks は大規模な選択肢です。OpenAPI ドキュメントと Postman コレクションをインポートする Web UI を備え、モックとして提供し、コントラクトテストも実行します。完全なインストールには MongoDB と Keycloak が必要で、非同期機能には Kafka も必要です。オールインワンの
microcks-uberイメージにはインメモリ MongoDB が含まれています。プロジェクトのドキュメントでは一時的な用途に適すると説明されているため、UI で作成したものは破棄される前提で扱い、元の成果物は git に保存してください。
実行すべきセルフホスト型 API テストランナーはどれか
ここで行う処理は、認証、注文の作成、注文の再取得、状態が変化したことのアサートという一連の手順です。1 つのレスポンスから取得した値を、次のリクエストで使用する必要があります。呼び出し間で状態を引き継げないツールは、API テストではなくヘルスチェックです。
- Hurl は、単一のバイナリで HTTP リクエストのプレーンテキストファイルを実行します。
[Captures]セクションでレスポンスから値を取り出し、[Asserts]セクションで値を検証し、--testでサマリーと終了コードを備えたテストランナーにできます。2026 年 8 月時点の最新バージョンは 8.0.1 です。 - Bruno CLI は
.bruファイルのディレクトリを実行します。npm install -g @usebruno/cliでインストールし、bru run folder --env Local --reporter-junit results.xmlで実行します。コレクション形式は設計上ディレクトリ内のテキストファイルであるため、レビュー時に差分を読みやすく確認できます。 - Newman は Postman の外部で Postman コレクションを実行します。
npm install -g newmanの後にnewman run collection.json -r cli,junit --reporter-junit-export results.xmlを実行します。注意すべき点は形式です。Newman は v2.1 JSON 形式でエクスポートされたコレクションを実行します。一方、Postman は現在、v3 コレクション形式と Postman CLI による Native Git ワークフローもサポートしています。Postman のドキュメントによると、Newman に対する今後の更新や修正は予定されておらず、スクリプトと CI パイプラインを Postman CLI に移行するよう推奨されています。 - Schemathesis は異なる種類のチェックを行います。OpenAPI スキーマを読み込み、スキーマ上では発生しないはずのレスポンスを生成しようとするケースを作成します。
uvx schemathesis run https://your.api/openapi.json。クラッシュやコントラクト違反を検出できますが、ビジネスルールは認識しません。そのため、スクリプト化したテストスイートの代替ではなく、併用するツールです。 - Hoppscotch のセルフホスト版は Web UI を利用する選択肢で、Postgres インスタンスが必要です。インストールする前に、このトレードオフを理解してください。コレクションはリポジトリではなくデータベースに保存されます。
避けるべきものもあります。Step CI は現在もツールの比較記事に登場し、YAML ワークフロー形式も読みやすいものの、リポジトリへの最後のコミットは 2024 年 8 月です。CI と API の間に置くプログラムに、メンテナンスされていないコードを選ぶのは適切ではありません。
ファイアウォールの背後にモックサーバーを配置する
以下の構成では、決済プロバイダーの代替として WireMock を実行します。compose ファイル形式に慣れていない場合は、VPS 上の Docker Composeで、このセクションで使用するライフサイクルコマンドを説明しています。
services:
mock-payments:
image: wiremock/wiremock:3.13.2
command: ["--verbose"]
volumes:
- ./mocks/payments:/home/wiremock
ports:
- "127.0.0.1:8080:8080"
restart: unless-stoppedポート指定の 127.0.0.1: プレフィックスが重要です。単独の 8080:8080 では、パブリック IP を含むすべてのインターフェースでモックが公開されます。また、ufw でそのポートを拒否していても到達可能なままです。これは、Docker が公開トラフィックを ufw の INPUT ルールに到達する前に nat テーブル経由でルーティングするためです。ループバックアドレスにバインドすると、Engine 28.0.0 以降の Docker のデフォルトブリッジネットワークでは、公開ポートにホストからのみアクセスできるようになります。古いリリースでは、同じ layer 2 ネットワーク上のホストから localhost に公開されたポートへ到達できます。プライベートインターフェースのアドレスにバインドすると、そのアドレスへルーティングできるネットワークからのアクセスは許可されます。
テスト対象のサービスは、次にモックを参照します。サービスが同じ compose プロジェクトで実行される場合、compose が独自のネットワーク上でサービス名を解決するため、モックのベース URL は http://mock-payments:8080 です。サービスがホスト上で実行される場合は http://127.0.0.1:8080 です。これは環境変数で設定し、コードには記述しないでください。そうしないと、テスト用 URL が本番環境へ持ち込まれます。
スタブは ./mocks/payments/mappings/ に、1 ファイルにつき 1 つの JSON ファイルとして配置します。
{
"request": {
"method": "POST",
"urlPath": "/v1/charges",
"bodyPatterns": [{ "matchesJsonPath": "$.amount" }]
},
"response": {
"status": 201,
"headers": { "Content-Type": "application/json" },
"jsonBody": { "id": "ch_test_001", "status": "succeeded", "amount": 4200 }
}
}起動したら、実際に読み込まれた内容を確認します。
docker compose up -d --wait mock-payments
curl -fsS http://127.0.0.1:8080/__admin/mappings--wait は、コンテナが healthy を報告するまで待機します。WireMock イメージには /__admin/health エンドポイントに対する HEALTHCHECK が含まれているため、この処理が機能します。mappings の呼び出しでは、サーバーが読み込んだすべてのスタブを一覧表示します。作成したスタブがその一覧にない場合、読み込まれていません。ファイルがマウント先のルートではなく mappings/ 配下にあることと、JSON の構文が正しいことを確認してください。
リクエストが到着して一致するスタブがない場合、WireMock は 404 を返します。近い一致が見つかった場合、本文は Request was not matched で始まり、その後に最も近いスタブとの差分が続きます。スタブマッピングがない場合、本文は No response could be served as there are no stub mappings in this WireMock instance. です。内容を変更する前に、差分があれば確認してください。差分には異なる正確なフィールドが示されます。通常は、スタブで /v1/charges と指定している箇所に /v1/charge が含まれます。
テストを呼び出し間で状態を引き継ぐシーケンスとして記述する
Hurl ファイルはプレーンテキストです。プロジェクトの releases から deb パッケージをインストールします。
VERSION=8.0.1
curl --location --remote-name https://github.com/Orange-OpenSource/hurl/releases/download/$VERSION/hurl_${VERSION}_amd64.deb
sudo apt update && sudo apt install ./hurl_${VERSION}_amd64.debモックに対して独自の API をテストするスイートは tests/checkout.hurl にあります。
POST {{base_url}}/orders
Content-Type: application/json
{
"sku": "ssd-1tb",
"amount": 4200
}
HTTP 201
[Captures]
order_id: jsonpath "$['id']"
GET {{base_url}}/orders/{{order_id}}
HTTP 200
[Asserts]
jsonpath "$.status" == "paid"
jsonpath "$.charge_id" == "ch_test_001"[Captures] ブロックにより、これは無関係な2つのリクエストではなく API テストになります。order_id は最初のレスポンスから読み取られ、2つ目の URL に埋め込まれます。charge_id に対するアサーションが、このテストの目的です。これにより、サービスが決済プロバイダーを呼び出し、返された値を保存したことを検証できます。比較対象の値は、WireMock のスタブに記述した値です。これで、フローの両方の処理を1つのファイルで検証できます。
hurl --test --variable base_url=http://127.0.0.1:3000 \
--report-junit reports/junit.xml \
--report-json reports/json \
tests/テストに成功すると、ファイルごとに1行とサマリーが出力されます。
tests/checkout.hurl: Success (2 request(s) in 61 ms)
Executed files: 1
Executed requests: 2 (30.1/s)
Succeeded files: 1 (100.0%)
Failed files: 0 (0.0%)
Duration: 64 ms失敗すると、ファイル名と行番号を含む error: Assert failure が出力され、取得した値と期待した値が示されます。その後、hurl はゼロ以外の終了コードで終了するため、CI が停止します。status が、期待した paid ではなく pending を読み取る場合、サービスはモックのレスポンスを処理できていません。次に確認するのは /__admin/requests の WireMock リクエストジャーナルです。ここで、呼び出しがモックに到達したかどうかを確認できます。
自分の CI runner から suite を実行する
同じホストに runner を登録している場合、workflow は短くなります。runner はホスト上で動作する通常のプロセスであるため、docker と hurl をそのホストにインストールする必要があります。hosted image の内容は引き継がれません。
name: api-tests
on: [push]
jobs:
hurl:
runs-on: self-hosted
steps:
- uses: actions/checkout@v4
- name: Start the mock
run: docker compose up -d --wait mock-payments
- name: Run the suite
run: hurl --test --variable base_url=http://127.0.0.1:3000 --report-junit reports/junit.xml tests/
- name: Archive the reports
if: always()
run: install -d /srv/api-tests/reports/$GITHUB_SHA && cp -r reports/. /srv/api-tests/reports/$GITHUB_SHA/
- name: Stop the mock
if: always()
run: docker compose downarchive step の if: always() が重要です。これがないと、テスト実行が失敗した場合に copy がスキップされ、確認したかった report を失います。copy 先は workspace の外側にする必要もあります。actions/checkout@v4 は fetch の前にデフォルトで git clean -ffdx を実行するため、次回の checkout 時に repository directory 内の untracked report が削除されるからです。
結果を直近の実行だけに限定しない
コミットごとに JUnit XML ファイルを保存すれば、成功したかどうかは確認できます。ただし、ファイルを開かなくなると、その内容を読み取るものがないため、エンドポイントの応答がいつ遅くなり始めたかは分かりません。傾向を把握するには、同じホスト上の小さなデータベースに、実行ごとに 1 行を追加します。コミット SHA、ファイル名、成功数、失敗数、実行時間を保持する単一のテーブルで十分です。保存先としては VPS 上の本番環境での SQLite が適しています。1 つのファイルで済み、サーバープロセスも不要です。既存のバックアップに履歴全体を含めることもできます。詳細な実行データは Hurl の --report-json 出力を解析します。JSON と JUnit XML はどちらも機械可読です。
コンテナの再ビルド後も保持すべきもの
モックの定義とテストスイートはソースコードです。対象のサービスと同じリポジトリで管理し、エンドポイントを変更するプルリクエストで同時に変更します。Web UI で編集したスタブや、実行時に REST API 経由で MockServer へ登録した期待値を再ビルド後も保持するには、エクスポートまたは永続化の設定が必要です。docker compose downを実行すると、コンテナのメモリと書き込み可能レイヤーは失われます。bind mount または名前付きボリュームに保存したデータは保持されます。リポジトリも自社のハードウェアで運用している場合は、自ホスト型の git サーバーを使うことで、フィクスチャとサービスを同じ信頼境界内に置けます。
次に、実際のルールを示します。イメージタグは固定してください。latestによって、リポジトリを変更していなくてもモックがリクエストに一致する方法が変わる可能性があり、その失敗原因をたどるのは非常に困難だからです。ツールが書き込む必要のないスタブディレクトリは、読み取り専用でマウントします。モックのスタブを名前付き Docker ボリュームに置いてはいけません。そうするとボリュームが正本になり、git にあるコピーが気付かないうちに不正確になるためです。
もう 1 つ注意点があります。プロキシを通過する実際のトラフィックを記録してスタブを作成する場合は、生成されたファイルをすべて確認してからコミットしてください。記録には、上流サーバーが返した内容がそのまま含まれます。bearer token や顧客のメールアドレスも例外ではありません。コミットすると、それらはリポジトリに永続的に残ります。git は削除した内容も履歴に保持するためです。
FAQ
API mock server と API test runner の違いは何ですか?
Mock server はリクエストに応答します。CI から呼び出せない依存先の代わりになります。一部のツールは contract test も実行し、その結果を報告します。API test runner は自分のサービスにリクエストを送り、レスポンスを検証し、ある呼び出しの値を次の呼び出しへ引き継ぎ、検証に失敗すると non zero で終了します。両者は異なる問題を解決します。一般的な構成では、両方を同時に実行します。runner が自分のサービスを呼び出し、そのサービスが mock を呼び出します。
ホスト型 CI runner から内部 API をテストできますか?
はい。プライベートネットワークを使用します。GitHub-hosted runner では、WireGuard overlay または Azure Virtual Network を使用して、API を公開せずにプライベートリソースへ接続できます。API を公開する方法、tunnel を実行する方法、公開された staging copy を維持する方法もありますが、それぞれ障害や情報漏えいの原因となるシステムが増えます。同じプライベートネットワーク上の runner ならサービスを直接呼び出せます。これが、この作業を self-host する主な実務上の理由です。
mock stub と API test suite はどこに置くべきですか?
git に置き、対象サービスの隣で管理します。WireMock の mappings/ directory、Mockoon の data file、Hurl file、Bruno の .bru folder など、定義を file として保存するツールなら、code review を行えます。また、追加コストなしで container を再構築できます。定義を database または web UI に保存するツールでは、backup plan と export step が必要です。container がすでに失われるまで、多くの人は export を忘れます。
stub が正しいように見えるのに、mock が 404 を返すのはなぜですか?
WireMock は、リクエストが設定済みの matcher を満たす場合にだけ stub を提供します。matcher に一致しないリクエストには 404 が返ります。近い一致がある場合、body は Request was not matched で始まり、その後に最も近い stub との差分が続きます。この差分には、異なる field が示されます。stub mapping がない場合、body には instance に mapping がないことが示されます。よくある原因は、path の末尾に slash があること、stub が要求する Content-Type header を client が送信していないこと、variable segment に必要な urlPathPattern の代わりに urlPath を使用していること、payload に合わない body matcher です。まず /__admin/requests を確認し、リクエストが mock に到達したかを確認します。
staging environment がある場合でも mock は必要ですか?
はい。理由は2つあります。管理していない upstream の staging copy は停止することがあり、rate limit も適用されます。そのため、code と関係のない理由で suite が失敗します。また、declined card や gateway timeout など、テストで特に必要なレスポンスを生成できない場合もあります。mock なら、それらを要求時に local network speed で返せます。sandbox に対して数分かかる suite を、数秒で完了する suite にできます。release 前の最終確認には staging を使用し、CI では mock を使用します。