コンテンツにスキップ

記録と再生の仕組み: SSR にはプロキシ、ブラウザには HAR

test-proxy-recorder は、リクエストの発生場所に応じて 2 つの記録メカニズムをサポートします。両方を併用することも、独立して使うこともできます。

メカニズム記録する対象ユースケース
プロキシ (.mock.json)サーバーサイドのリクエスト(Next.js などの SSR フェッチ)サーバーが API を呼ぶフルスタックアプリ
HAR (.har)ブラウザサイドのリクエスト(ブラウザの fetch、拡張、SPA)SPA、Chrome 拡張、サードパーティ API
Server-side (proxy) Browser-side (HAR)
Next.js SSR ──> Proxy ──> Real API Browser ──> HAR intercept ──> Real API
│ │
└──> .mock.json └──> .har

各テストは開始時に自分のセッションのモードを設定し、すべてのリクエストは x-test-rcrd-id ヘッダーでそのテストの id を運ぶため、同時に実行されるテストはそれぞれ自分のモードとファイルを保持します。record モードではプロキシは実際のバックエンドへ転送し、レスポンスをそのテストのファイルに保存します。replay モードでは保存済みのレスポンスを、そのテストの記録からディスク経由で提供します。transparent モードでは記録せずに転送します。バージョン 2.0.1 までは、すべてのリクエストに対して 1 つの記録セッションを保持していたため、それらのバージョンで記録を実行するにはワーカーを 1 つにする必要があります。プロキシは transparent モードで起動するため、テスト以外でプロキシ経由で実行したアプリは通常どおりバックエンドと通信します。モードの切り替え方法はコントロールエンドポイントを参照してください。

プロキシと HAR ファイルでは、記録済みのレスポンスを探す方法が異なります。

再生時プロキシ (.mock.json)HAR (.har)
照合に使うものメソッド、パス、クエリ文字列の MD5 ハッシュ、リクエストボディ(multipart の境界は無視)。GET と HEAD はボディなしで照合します。ヘッダーは比較しません。メソッド、URL、ボディ。続いて、共通するリクエストヘッダーが最も多いエントリを選びます。同じ URL とボディでも、ヘッダーで区別される別の操作であることがあるためです。どのエントリにもないボディはメソッドと URL での照合にフォールバックし、multipart の境界(boundary)は無視されます。
同じリクエストが再び来た場合同じボディを持つ次の記録を、記録された順で。記録された順で次の記録。書き込みには 1 つのルールがあります(後述)。
記録がない場合リクエストを示す JSON ボディ付きの 404。さらに playwrightProxy.before() がページを閉じるため、テストは即座に失敗します(failOnMissingRecording: false で無効にできます)。リクエストは中断され、[Client-Side Replay] No recorded response for <method> <url> がログに出力されます。
実際の API への到達transparent モードのときのみ。url に一致しないリクエストのみ。

サーバーサイドのリクエスト(プロキシ)

Section titled “サーバーサイドのリクエスト(プロキシ)”

キーは、メソッド、パス、そしてクエリ文字列の MD5 ハッシュの先頭 16 文字(16 進数)です。GET /todos?page=2 のキーは GET_todos_46589c7afd19c014.json です。そのため、クエリ文字列が少しでも異なれば、パラメーターの順序の違いだけでも別のキーになります。

同じキーの呼び出しは、次にリクエストボディで照合されます。そのため、並列に送られて実行ごとに異なる順序でプロキシに届く呼び出しも、それぞれ自分のレスポンスを受け取ります。比較の前に、プロキシは両方のボディにボディのマスキング(bodyPatterns)を適用し、multipart の境界を取り除きます。そのため、マスキングされたシークレットや、リクエストごとに変わる境界があっても照合は失敗しません。GET と HEAD の呼び出しはキーだけで照合されます。

どの記録にもないボディを持つ呼び出しは、後述の記録がないリクエストとして扱われ、その理由はボディに言及します: No recording for POST /embeddings with this request body in session <id> (2 recorded with other bodies)。プロキシは、別のボディに対して作られた記録でそれに応答することはありません。そうするとアプリが送った内容の変化が隠れてしまうためです。実行間でボディを同じに保ってください。ボディに現在の日付やランダムな id が含まれていると、再生は失敗します。

同じキーとボディの呼び出しには、記録された順にレスポンスが返されます。そのボディの最後の記録を超えた呼び出しにはその記録のレスポンスがもう一度返され、プロキシは [REPLAY WARNING] All N recordings matching this request already served for <key> (session: <id>), reusing last one とログに出力します。N はそのボディを持つ記録の数です。

記録のないリクエストは実際の API には到達しません。プロキシは [REPLAY ERROR] の行をログに出力し、404 で応答します:

{
"error": "No recording found",
"message": "No recording found for GET_todos_46589c7afd19c014.json at GET localhost:8100/todos?page=2",
"key": "GET_todos_46589c7afd19c014.json",
"sessionId": "todos__shows-the-list"
}

プロキシがリクエストを実際のバックエンドへ送るのは transparent モードのときだけです。再生中の実行がそこに行き着く経路は 2 つあります。テストがまだ実行中に playwrightProxy.teardown() が実行される場合と、次の playwrightProxy.before() の呼び出しより前にセッションのタイムアウト(デフォルトは 120000 ms)が切れる場合です。どちらも FAQ で説明しています。

url を渡すと、playwrightProxy.before() は一致するブラウザのリクエストを Playwright の HAR レコーダーで記録します:

await page.routeFromHAR(harPath, { url, update: true, updateContent: 'embed' });

再生には page.routeFromHAR() ではなく、このファイルを読むライブラリ独自の page.route() ハンドラーを使います。Playwright の再生は、同じリクエストが繰り返されるたびに最初に一致したエントリを返すため(microsoft/playwright#18288)、POST の後の GET には POST 前の一覧が表示されていました。このハンドラーは代わりに、各記録を記録された順に 1 回ずつ返し、ページが記録時より多くリクエストした場合にのみ記録を再利用します。書き込みに対する読み取りの順序は 1 つのルールで決まります。あるパスへの書き込み(GET、HEAD、OPTIONS 以外のメソッド。そのため GraphQL のクエリも該当します)が再生されると、そのパスまたはその配下のパスへの読み取りは、書き込みの後に記録されたコピーを優先します。次の同様の書き込みまでに残りのコピーがない読み取りは、その書き込みより前の最新のコピーを再利用します。このルールにより、React の Strict Mode で fetch が二重に実行される場合のように、アプリの読み取り回数が記録時と異なっても再生は正しく保たれます。記録されたリダイレクトは .har の中でたどります。ブラウザの後続リクエストは page.route() に届かないためです。fetch は最終的なレスポンスを受け取り、ナビゲーションはリダイレクト先へ送られます。

url に一致するが .har にないリクエストは中断されます。url に一致しないリクエストはインターセプトされず、transparent モードではどのリクエストもインターセプトされません。これらは実際のネットワークに送られます。

プロキシ自体(localhost:8100)へのリクエストは例外です。before() は HAR のハンドラーの後にそれら専用のハンドラーを登録し、Playwright は後から登録されたハンドラーを先に実行します。このハンドラーはリクエストをプロキシへ転送し、プロキシはサーバーサイドのリクエストと同じように .mock.json から再生します。