Playwright テストの API 呼び出しを、サーバーサイドのリクエストも含めて記録・再生

一度記録する。
ずっと再生する。

ローカルでの Playwright 実行中にアプリが受け取る API レスポンスを WebSocket も含めて記録し、CI ではバックエンドをオフにしたまま再生します。

npm i -D test-proxy-recorder GitHub でスター

v2.1.0 · MIT · TypeScript · Node ≥ 20 · Next.js と TanStack Start の SSR、SPA、Chrome 拡張、WebSocket

REC · MODE=record · local run

saved todos__adds-a-todo.mock.json

REPLAY · MODE=replay · CI

200 OK · 3 ms · from disk

記録、そして再生の様子を見る

1 回の Playwright 実行で実際のレスポンスをディスクに記録し、再生に切り替えれば同じスイートがバックエンドをオフにしたまま通過します。

2 つの記録方法

リクエストは 2 つの場所から発生するため、記録の方法も 2 つあり、どちらの方法でもプロキシのプロセスが動きます。プロキシに送られたもの(サーバーサイドフェッチ、サーバーと共通の API ベース URL を経由するブラウザからの呼び出し、WebSocket)は、そのテストの .mock.json から再生されます。フィクスチャの url パターンに一致する、他のホストへのブラウザからの呼び出しは、そのテストの .har から再生されます。

プロキシ

.mock.json

Next.js / TanStack Start SSR → プロキシ → 実際の API

サーバーが API を呼び出すフルスタックアプリ向け。

サーバーと API の間に位置し、サーバーサイドのリクエストを記録します。Server Component と SSR のフェッチ、ルートハンドラー、バックエンド・フォー・フロントエンドが呼び出すあらゆるものが対象です。

各テストのサーバーサイドのリクエストにはそのテストの id が付くため、並列に実行されるテストが記録を共有することはありません。

HAR

.har

ブラウザ → HAR 傍受 → 実際の API

SPA、拡張、ブラウザのみのアプリ向け。

ブラウザ自体の中で傍受し、HTTP Archive(HAR)ファイルに保存します。クライアントサイドの fetch 呼び出し、Chrome 拡張の API トラフィック、アナリティクス、サードパーティ API のうち、フィクスチャの url パターンに一致するものを記録します。

routeFromHAR を単体で使う場合に比べ、テストごとに HAR を 1 つずつ分け、認証ヘッダーをマスキングする機能が加わります。

記録ファイルの中身

テストごとに 1 ファイル
各テストはテスト名に基づいた名前の専用ファイルに書き込むため、 npx playwright test -g "adds a todo" でそのテストだけを記録し直せます。テストが 1 つのデータベースやアカウントを共有しない限り、記録も再生と同じく並列のワーカーで実行できます。
テストの id
Playwright はテストが行うすべてのリクエストに x-test-rcrd-id を付けて送り、 registerProxyFetch() がそれをサーバー自身のフェッチにコピーします。プロキシはこれを読み取り、テストを並列に実行しているときでも、各テストをそのテスト専用のファイルに記録し、そこから再生します。
シークレット
Authorization、Cookie、Set-Cookie ヘッダーの値は、.mock.json ファイルでは書き込まれる前に、.har ファイルでは実行の終了時に [REDACTED] に置き換えられます。レスポンスボディ内のシークレットには独自のパターンが必要です。 シークレットのマスキング →
e2e/recordings/todos__adds-a-todo.mock.json
{
"id": "todos__adds-a-todo",
"recordings": [
{
"request": {
"method": "POST",
"url": "/todos",
"headers": {
"authorization": "[REDACTED]",
"x-test-rcrd-id": "todos__adds-a-todo"
},
"body": "{\"title\":\"Buy groceries\"}"
},
"response": {
"statusCode": 201,
"body": "{\"id\":7,\"title\":\"Buy groceries\",\"done\":false}"
},
"key": "POST_todos.json",
"sequence": 0
}
]
}
実際の記録の一部です(全体は 2.6 KB)。1 つのテストの POST で、Authorization ヘッダーはマスキングされています。ファイル全体には、その後に続いた GET、すべてのヘッダー、各リクエストのタイムスタンプも含まれます。

適している場面

モックツールはそれぞれ得意分野が異なります。以下の組み合わせ — SSR、ブラウザ、WebSocket にまたがって実際のトラフィックを記録し、手書きモックを必要としないこと — こそが、他のツールが埋められていない空白です。

test-proxy-recorder と Playwright の routeFromHAR、MSW、Polly.js、playwright-network-cache、Mocky Balboa との機能比較。
機能test-proxy-recorderPlaywright routeFromHARMSWPolly.jsplaywright-network-cacheMocky Balboa
実際のトラフィックを記録対応対応非対応対応対応非対応
サーバーサイド (SSR)対応非対応対応部分的非対応対応
ブラウザサイド対応対応対応対応対応対応
WebSocket対応非対応対応非対応非対応非対応
Playwright ネイティブ対応対応対応非対応対応対応
メンテナンス状況対応対応対応非対応対応対応

Polly.js は自身が動いているプロセスの中で記録するため、サーバーサイドのリクエストに使うにはアプリのサーバー内で動かす必要があります。MSW と Mocky Balboa もサーバーサイドのリクエストをモックできますが、レスポンスは自分で書きます。出典と、他のツールを選ぶべき場面を含む完全な比較は ドキュメントにあります。

トレードオフとして、ブラウザのみを対象とするツールよりも最初のセットアップに手間がかかります。テストと並行してプロキシのプロセスが動き、サーバーサイドのリクエストについては、テスト実行中はアプリの API ベース URL をプロキシに向けます。

実際の認証プロバイダーと連携

Cognito、Auth0、Clerk、WorkOS を通じて、毎回の実行で本物のログインを行います。記録されるのはアプリの API だけで、認証はライブのまま、データはオフラインで再生されます。

// e2e/auth.setup.ts — log in for real, once. Never recorded.
import { test as setup } from '@playwright/test';
import { setProxyMode } from 'test-proxy-recorder';
setup('authenticate', async ({ page }) => {
await setProxyMode('transparent'); // login bypasses the recorder
await page.goto('/login');
await page.getByTestId('email').fill(process.env.TEST_EMAIL!);
await page.getByTestId('password').fill(process.env.TEST_PASSWORD!);
await page.getByTestId('signinButton').click();
await page.waitForURL('/dashboard');
// Reused by every test — they start already signed in.
await page.context().storageState({ path: 'e2e/.auth/state.json' });
});

クイックスタート

1 つのコマンドですべてをスキャフォールドし、API をプロキシに向け、記録してコミットします。ブラウザのみのアプリですか? init は SSR の手順をスキップしてくれます。

リポジトリで変わること

  • テストスイート: Playwright フィクスチャ、プロキシのプロセス(テスト中にのみ動作します)、git にコミットされる記録。
  • アプリ(サーバーサイドのリクエストについてのみ): テスト実行中は API ベース URL をプロキシに向け、Next.js では app/layout.tsx、TanStack Start では src/router.tsx で registerProxyFetch() を 1 回呼び出します。これはテストの id を各サーバーサイドフェッチにコピーし、TEST_PROXY_RECORDER_ENABLED が設定されていない限り、本番では何もしません。
  • エージェント用プロンプトを使う場合: @tanstack/intent が、このライブラリのスキルを読み込むためのガイダンスをエージェントの設定ファイル(CLAUDE.md など)に追加します。
  • デプロイ済みの環境をテストしますか? HAR はアプリを変更せずに、その環境のブラウザからの呼び出しを記録しますが、ページ自体は引き続きそのサーバーから読み込まれます。サーバーサイドの呼び出しも再生するには、CI でプロキシと並べてアプリを実行してください。

これを Claude Code、Cursor などのコーディングエージェントに貼り付けてください。エージェントはまず @tanstack/intent を実行します。これはエージェントの設定ファイル(CLAUDE.md など)にガイダンスを追加し、エージェントがこのライブラリのセットアップ用スキルを読み込むようにします。続いてパッケージをインストールし、アプリの設定からバックエンドの URL を見つけ、 init を実行し、その出力に従って配線を完了させます。

Set up test-proxy-recorder for end-to-end tests in this project, then follow the instructions that `init` prints. Run these commands:
npx @tanstack/intent@latest install
npm install --save-dev test-proxy-recorder
Then run init, passing this project's backend API base URL as the target — find it yourself from the app's env/config (the URL the app calls in dev); don't assume the default:
npx test-proxy-recorder init <your-backend-api-url> --port 8100 --dir ./e2e/recordings
Then complete the app-specific steps init prints: point the app's API base URL at the proxy in dev/test only, tag server-side fetches (Next.js), add a smoke test, and verify record → replay.

詳しいセットアップガイド →

再生についての質問

リクエストはどう照合されますか?
プロキシはサーバーサイドの呼び出しを、メソッド、パス、クエリ文字列の完全一致、ボディで照合するため、並列に送られた呼び出しもそれぞれ自分のレスポンスを受け取ります。繰り返された呼び出しには、記録された順にレスポンスを返します。ブラウザからの呼び出しも、メソッド、URL、ボディで照合されます。タイムスタンプのように実行のたびに変わるクエリ文字列やボディは一致することがなく、値を無視するオプションもないため、そうした値はテスト中は固定してください。 再生時のリクエストの照合 →
記録がない場合はどうなりますか?
プロキシは 404 を返し、該当するリクエストとテストを示します。記録された回数より多く行われた呼び出しには最後のレスポンスがもう一度返され、プロキシのログに警告が出ます。ブラウザでは、Playwright は url パターン(フィクスチャが before() に渡すもの)に一致し、かつ HAR にない呼び出しを中断します。それ以外の呼び出しはネットワークに到達します。
再生が実際の API に到達するのはどんなときですか?
再生が実際の API に到達するのは、プロキシが再生モードを抜けた後だけです。プロキシは実行中のすべてのテストに対して 1 つのモードを保持します。再生モードを抜けるのは、最後のテストが開始してから 120 秒後か、テストごとのフックが teardown() を呼んだときです。CI でバックエンドが動いていなければ、そうした呼び出しは通らずに失敗します。 セッションのタイムアウトと teardown →
API が変わったらどうなりますか?
型付きの API クライアントを使っている場合、変更されたフィールドに合わせてクライアントを更新すると、そのフィールドを使う再生テストが失敗します。記録には古いフィールドが残っているためです。これで変更箇所がわかり、記録し直せば、手書きのモックを編集するより少ない手間でテストが直ります。
エラーやエッジケースはどうテストしますか?
ブラウザでは、 page.route() を before() の後に登録すると、そのハンドラーが記録より優先されます。サーバーサイドのレスポンスは .mock.json ファイルで編集します。 レスポンスを強制する →

手書きモックをやめる

API はすでに正しい答えを返しています。それを記録しましょう。

npm i -D test-proxy-recorder GitHub でスター

午後の時間が節約できたなら、スターは 1 秒で済みます — 次の人が見つける手段であり、1 人で保守を続ける者への「作り続けて」という合図です。つまずいたりアイデアがあれば、 issue を開く か Discord に参加してください。