コンテンツにスキップ

手動セットアップ

ほとんどの人は init を実行すべきです — 以下のファイルをすべて書き出してくれます。このページは init が生成する内容のリファレンスで、手で組み込んだり、コード生成を省いたり、各ピースを理解したりするために使います。

フルスタック(SSR + ブラウザ)

Section titled “フルスタック(SSR + ブラウザ)”

Next.js や類似フレームワーク向けで、サーバーとブラウザの両方が API 呼び出しを行う場合。両方の記録メカニズムを併用します — 仕組みを参照。

プロキシはテスト実行のためにアプリと並べて起動する(以下のスクリプトや Playwright の webServer で)軽量なプロセスであり、デプロイや保守するインフラではありません。セットアップ全体は、アプリの隣で起動し、アプリの API ベース URL をそこに向け、SSR からセッションヘッダーを伝播し、フィクスチャを 1 つ書くだけです。

1. package.json にスクリプトを追加する

Section titled “1. package.json にスクリプトを追加する”
{
"scripts": {
"proxy": "test-proxy-recorder http://localhost:8000 --port 8100 --dir ./e2e/recordings",
"dev:proxy": "concurrently \"npm run proxy\" \"TEST_PROXY_RECORDER_ENABLED=1 npm run dev\"",
"serve:proxy": "concurrently \"npm run proxy\" \"TEST_PROXY_RECORDER_ENABLED=1 npm run serve\""
}
}

アプリのコードでは、recorder が有効な場合はプロキシへ、そうでない場合は実際のバックエンドへ API のベース URL を向けてください — プロキシは本番では実行されません:

// TEST_PROXY_RECORDER_ENABLED is 'true' or '1' for the e2e run only.
const recorderEnv = process.env.TEST_PROXY_RECORDER_ENABLED ?? '';
const API_BASE = ['true', '1'].includes(recorderEnv)
? 'http://localhost:8100' // proxy address
: 'https://api.example.com';

TEST_PROXY_RECORDER_ENABLED は上記の dev:proxy / serve:proxy スクリプト、および init が生成したスクリプトによって設定されます。アプリが API のベース URL に既に使用している環境変数を使ってください(例えば API_URL、NEXT_PUBLIC_API_URL) — 同じ条件分岐が適用されます。

2. サーバーサイドフェッチにタグ付けする(Next.js)

Section titled “2. サーバーサイドフェッチにタグ付けする(Next.js)”

サーバーサイドの fetch 呼び出しには記録セッションヘッダーが必要で、これによりプロキシはそのリクエストがどのテストに属するかを知ります。Playwright がすでにブラウザのナビゲーションにそれを設定しているため、id は next/headers にあります — あとは送信する SSR リクエストにそれを付与するだけです。ルートレイアウトに 1 行追加してください(init がこれを行います):

app/layout.tsx
import { registerProxyFetch } from 'test-proxy-recorder/nextjs';
registerProxyFetch(); // no-op in production unless TEST_PROXY_RECORDER_ENABLED=true
export default function RootLayout({ children }: { children: React.ReactNode }) {
return (
<html lang="en">
<body>{children}</body>
</html>
);
}

これは Node と Edge の両方のランタイムで動作します。axios アプリの場合は、代わりに各サーバーサイドインスタンスで registerProxyAxios(instance) を呼んでください。単一の fetch には createHeadersWithRecordingId(await headers()) がパッチ不要の代替です。setNextProxyHeaders を使う proxy.ts/middleware.ts は任意です — id を公開するだけで、フェッチにはタグ付けしません。本番ビルド(next build && next start)に対して記録し、next dev では行わないでください。詳しくは Next.js インテグレーションを参照。ブラウザのみのアプリはこのステップを省略できます。

import { test, expect } from '@playwright/test';
import { playwrightProxy } from 'test-proxy-recorder';
// SSR requests (server → proxy) are recorded to .mock.json.
// Browser requests to the proxy URL are also covered.
const CLIENT_SIDE_URL = /localhost:8100/;
// RECORD_MODE=1 updates the recordings; otherwise tests replay.
const MODE = process.env.RECORD_MODE ? 'record' : 'replay';
test.beforeEach(async ({ page }, testInfo) => {
await playwrightProxy.before(page, testInfo, MODE, { url: CLIENT_SIDE_URL });
});
test('homepage loads', async ({ page }) => {
await page.goto('/');
await expect(page.getByText('Welcome')).toBeVisible();
});

記録する前に、自前のシードスクリプトでバックエンドのデータベースをテストが想定する状態にしてください。

Terminal window
# Terminal 1
npm run serve:proxy
# Terminal 2 — .mock.json and .har files are written automatically
RECORD_MODE=1 npx playwright test

各テストは自分のセッションに記録するため、記録は再生と同じ数のワーカーで実行できます。テストがバックエンドの状態を共有する場合、たとえばリセットする 1 つのデータベースやサインインする 1 つのアカウントを共有する場合は、--workers 1 を追加してください。バージョン 2.0.1 までは、すべてのリクエストに対して 1 つの記録セッションを保持するため、それらのバージョンでは記録の実行に毎回 --workers 1 が必要です。

5. 再生に切り替えてコミットする

Section titled “5. 再生に切り替えてコミットする”
Terminal window
git add e2e/recordings/
git commit -m "add e2e recordings"

すべての API 呼び出しがブラウザから来る場合(SSR なし)、必要なのは HAR メカニズムだけです。記録そのものにプロキシのバックエンドは不要です — プロキシのプロセスはセッション管理を提供するだけです。

Terminal window
npm install --save-dev test-proxy-recorder

2. playwright.config.ts にプロキシを追加する

Section titled “2. playwright.config.ts にプロキシを追加する”
import { defineConfig } from '@playwright/test';
export default defineConfig({
webServer: {
command: 'test-proxy-recorder https://api.example.com --port 8100 --dir ./e2e/recordings',
url: 'http://localhost:8100/__control',
reuseExistingServer: true,
},
});

ブラウザのみの記録では、プロキシのターゲット(https://api.example.com)は重要ではありません — サーバーサイド(SSR)リクエストもプロキシ経由にする必要がある場合にのみ使われます。プロキシのプロセスは、セッション管理のために /__control エンドポイントが利用可能になるよう実行されている必要があります。

e2e/fixtures.ts
import { test as base, type Page, type BrowserContext } from '@playwright/test';
import { playwrightProxy } from 'test-proxy-recorder';
// Match the external API domain your browser makes requests to.
// In record mode these requests go to the real API and are saved.
// In replay mode they are served from disk — no network needed.
const CLIENT_SIDE_URL = /api\.example\.com/;
// RECORD_MODE=1 hits the real API and updates the recordings; otherwise tests replay.
const MODE = process.env.RECORD_MODE ? 'record' : 'replay';
export const test = base.extend<{ page: Page }>({
page: async ({ context }, use, testInfo) => {
const page = await context.newPage();
await playwrightProxy.before(page, testInfo, MODE, { url: CLIENT_SIDE_URL });
await use(page);
},
});
e2e/my.test.ts
import { test, expect } from './fixtures';
test('homepage loads', async ({ page }) => {
await page.goto('https://myapp.com/');
await expect(page.getByText('Welcome')).toBeVisible();
});

5. 記録する — 実際の API に対して一度実行する

Section titled “5. 記録する — 実際の API に対して一度実行する”
Terminal window
RECORD_MODE=1 npx playwright test
# .har files are written to e2e/recordings/ automatically

テストが実際の API の状態を共有する場合(たとえば全テストが同じ 1 つのアカウントでサインインする場合)や、バージョン 2.0.1 以前を使う場合は、--workers 1 を追加してください。

RECORD_MODE を設定しなければ、npx playwright test はこれらの記録から再生します。

Terminal window
git add e2e/recordings/
git commit -m "add e2e recordings"

CI はネットワークアクセスなしで実行できるようになります。

PR の差分で大きな記録ファイルを折りたたむには、.gitattributes に次を追加してください。GitHub ではクリック 1 回で表示できるため、変更されたレスポンスも引き続きレビューできます:

/e2e/recordings/** linguist-generated=true