Playwrightのpage.routeで、API応答を書き換える方法
Playwright の page.route を使うと、ページが出す API の通信をテストの中で受け止めて、応答を差し替えられます。E2E テストで API をモックするときの基本の道具です。応答を丸ごと作るだけでなく、本物のサーバーの応答を取ってきて一部だけ書き換えたり、リクエストにヘッダーを足してからサーバーに送ったりもできます。
私は検証環境で、猫の一覧を表示する小さなページとサーバーを作り、page.route の使い方を変えたテストを9つ書いて通しました。サーバー側では届いた通信を記録し、どの書き方で通信がサーバーまで届くのかを数えています。
検証環境は Ubuntu 24.04.5 LTS、Node.js 22.23.4、@playwright/test 1.63.0 です。ブラウザは Playwright 用の Chromium だけで、ページと API は Node.js の http モジュールで書いたサーバーから配信しました。Firefox・WebKit、CI サービス上での実行、HAR ファイルを使った差し替え、Service Worker を使うページは試していません。React の画面で、500 エラー・通信の失敗・読み込み中の表示を差し替える例は、別の記事「ReactとPlaywrightで、APIをモックしてテストする方法」で扱っています。
試したページとサーバー
ページは、開いたときに /api/plan と /api/cats を fetch で読みます。/api/plan の応答から「プラン:free」のような表示を作り、/api/cats の応答から猫の一覧と「3匹」のような件数を出します。読み込みに失敗したときは、件数の場所に「読み込みに失敗しました(500)」と出します。「もう一度読み込む」ボタンを押すと、一覧をもう一度読み込みます。
サーバーは /api/cats に3匹分の JSON を返し、X-Total-Count: 3 というヘッダーを付けます。/api/plan は、リクエストに x-plan ヘッダーがあればその値を、なければ free を返します。
// server.mjs(API の部分)
if (url.pathname.startsWith('/api/')) {
hits.push(`${req.method} ${req.url} x-plan=${req.headers['x-plan'] ?? '-'}`);
}
if (url.pathname === '/api/cats') {
res.writeHead(200, { 'Content-Type': 'application/json', 'X-Total-Count': String(cats.length) });
return res.end(JSON.stringify(cats));
}
if (url.pathname === '/api/plan') {
const plan = req.headers['x-plan'] ?? 'free';
res.writeHead(200, { 'Content-Type': 'application/json' });
return res.end(JSON.stringify({ plan }));
}
hits は、サーバーまで届いた API の通信の記録です。テストからは /__hits で読み出し、テストごとに /__reset で空にしています。この2つは検証のために足したもので、page.route の使い方とは関係ありません。playwright.config.ts では、webServer で node server.mjs を起動し、baseURL を http://localhost:4173 にしました。
本物の応答を取ってきて、一部だけ書き換える
一覧の中に、とても長い名前の猫が混ざったときの表示を確かめたいとします。応答を丸ごと作ってもよいのですが、ほかの項目は本物のサーバーが返すままにしたいときは、route.fetch を使います。route.fetch は、リクエストをサーバーに送って応答を受け取りますが、まだページには返しません。受け取った応答を書き換えてから、route.fulfill でページに返します。公式ドキュメントの、API の応答を書き換える例も、この形です。
test('本物の応答を取ってきて、1匹だけ書き換える', async ({ page }) => {
await page.route('**/api/cats', async (route) => {
const response = await route.fetch();
const cats = await response.json();
console.log('サーバーの応答:', response.status(), JSON.stringify(cats));
cats[0].name = 'とても長い名前の猫'.repeat(3);
await route.fulfill({ response, json: cats });
});
await page.goto('/');
await expect(page.locator('#status')).toHaveText('3匹');
await expect(page.getByRole('listitem').first()).toHaveText(
'とても長い名前の猫とても長い名前の猫とても長い名前の猫(3歳)',
);
await expect(page.getByRole('listitem').nth(1)).toHaveText('みけ(5歳)');
console.log('サーバーに届いた通信:', await serverHits(page));
});
実行すると、テストは通りました。route.fetch で受け取ったのはサーバーの本物の3匹で、サーバーには /api/cats の通信が1回届いています(helpers.ts の test と serverHits は、記録を空にする処理と読み出す処理です)。
サーバーの応答: 200 [{"id":1,"name":"たま","age":3},{"id":2,"name":"みけ","age":5},{"id":3,"name":"くろ","age":1}]
サーバーに届いた通信: [ 'GET /api/plan x-plan=-', 'GET /api/cats x-plan=-' ]
✓ 4 [chromium] › tests/fetch.spec.ts:3:5 › 本物の応答を取ってきて、1匹だけ書き換える (81ms)
ページには、1匹目だけ名前が変わった一覧が出ます。同じハンドラーで書き換えたページを撮ったのが、次の画像です。

fulfill に渡した response は、取ってきた応答そのものです。json などのほかの指定は、その応答の一部を上書きします(route.fulfill の response オプションの説明)。本文を空の配列に差し替えたとき、ヘッダーがどうなるかも見ました。
test('fulfill に response を渡すと、ヘッダーも本物のまま返る', async ({ page }) => {
await page.route('**/api/cats', async (route) => {
const response = await route.fetch();
await route.fulfill({ response, json: [] });
});
const resPromise = page.waitForResponse('**/api/cats');
await page.goto('/');
const res = await resPromise;
console.log('status:', res.status());
console.log('x-total-count:', await res.headerValue('x-total-count'));
console.log('content-type:', await res.headerValue('content-type'));
await expect(page.locator('#status')).toHaveText('0匹');
});
status: 200
x-total-count: 3
content-type: application/json
✓ 3 [chromium] › tests/fetch-headers.spec.ts:3:5 › fulfill に response を渡すと、ヘッダーも本物のまま返る (76ms)
ページは「0匹」と表示しましたが、X-Total-Count ヘッダーはサーバーが付けた 3 のまま残りました。本文だけを書き換えると、ヘッダーと中身が食い違うことがあります。ページがヘッダーの値を使うなら、fulfill の headers も合わせて書き換えます。
リクエストにヘッダーを足して、サーバーに送る
応答ではなく、リクエストのほうを変えたいときは route.continue を使います。headers を渡すと、そのヘッダーでサーバーに送ります。元のヘッダーを残すには、公式の例と同じく、元のリクエストのヘッダーをスプレッド構文で展開してから足します。
test('continue でリクエストのヘッダーを足してサーバーに送る', async ({ page }) => {
await page.route('**/api/plan', async (route) => {
const headers = { ...route.request().headers(), 'x-plan': 'pro' };
await route.continue({ headers });
});
await page.goto('/');
await expect(page.locator('#plan')).toHaveText('プラン:pro');
console.log('サーバーに届いた通信:', await serverHits(page));
});
サーバーに届いた通信: [ 'GET /api/cats x-plan=-', 'GET /api/plan x-plan=pro' ]
✓ 2 [chromium] › tests/continue.spec.ts:3:5 › continue でリクエストのヘッダーを足してサーバーに送る (80ms)
サーバーには x-plan=pro の付いた /api/plan が届き、ページは「プラン:pro」になりました。ただし、Cookie や Host のように、書き換えられないヘッダーもあります。continue で指定しても無視され、元の値のまま送られます(route.continue の説明)。
ハンドラーが2つ合うときは、あとで登録したほうが先に動く
テストの共通の準備で API 全体にハンドラーを付け、個々のテストで一部の API だけを差し替えると、1つの通信に複数のハンドラーが合います。そのときの順番を確かめました。
test('あとで登録したハンドラーが先に動き、fallback で前のハンドラーに回す', async ({ page }) => {
const calls: string[] = [];
// 1つ目:API 全体に合う、共通のハンドラー
await page.route('**/api/**', async (route) => {
calls.push(`共通 ${new URL(route.request().url()).pathname}`);
await route.continue();
});
// 2つ目:一覧だけを差し替えるハンドラー
await page.route('**/api/cats', async (route) => {
calls.push('一覧');
await route.fallback();
});
await page.goto('/');
await expect(page.locator('#status')).toHaveText('3匹');
console.log('ハンドラーが動いた順:', calls);
console.log('サーバーに届いた通信:', await serverHits(page));
});
ハンドラーが動いた順: [ '共通 /api/plan', '一覧', '共通 /api/cats' ]
サーバーに届いた通信: [ 'GET /api/plan x-plan=-', 'GET /api/cats x-plan=-' ]
/api/cats の通信は、あとで登録した「一覧」のハンドラーに先に届きました。そこで route.fallback を呼ぶと、前に登録した「共通」のハンドラーに回り、その continue でサーバーに届いています。/api/plan は「一覧」のパターンに合わないので、「共通」のハンドラーだけが動きました。

「一覧」のハンドラーの fallback を continue に変えると、結果は次のようになりました。
ハンドラーが動いた順: [ '共通 /api/plan', '一覧' ]
continue はその場でサーバーに送るので、前に登録したハンドラーは動きません。公式リファレンスにも、複数のハンドラーが合うときは登録と逆の順に動くこと、continue を呼ぶとほかのハンドラーは呼ばれないことが書かれています(route.fallback の説明)。共通のハンドラーで通信を記録したり、ヘッダーを足したりしているなら、個々のハンドラーでは continue ではなく fallback で回します。
fallback には continue と同じく headers を渡せて、変えた値は前のハンドラーにも見えます。「共通」のハンドラーでヘッダーの値を表示させると、/api/plan では pro になっていました。
await page.route('**/api/plan', async (route) => {
await route.fallback({ headers: { ...route.request().headers(), 'x-plan': 'pro' } });
});
共通のハンドラーが見た x-plan: pro
共通のハンドラーが見た x-plan: -
サーバーに届いた通信: [ 'GET /api/plan x-plan=pro', 'GET /api/cats x-plan=-' ]
最初の1回だけ差し替える・途中で差し替えをやめる
page.route の3つ目の引数に { times: 1 } を渡すと、そのハンドラーは1回だけ使われます。最初の読み込みだけ 500 を返し、再読み込みでは本物の応答に戻るテストを書きました。
test('times: 1 で、最初の1回だけ 500 を返す', async ({ page }) => {
await page.route('**/api/cats', (route) => route.fulfill({ status: 500, body: 'error' }), {
times: 1,
});
await page.goto('/');
await expect(page.locator('#status')).toHaveText('読み込みに失敗しました(500)');
await page.getByRole('button', { name: 'もう一度読み込む' }).click();
await expect(page.locator('#status')).toHaveText('3匹');
console.log('サーバーに届いた通信:', await serverHits(page));
});
サーバーに届いた通信: [ 'GET /api/plan x-plan=-', 'GET /api/cats x-plan=-' ]
✓ 8 [chromium] › tests/times.spec.ts:3:5 › times: 1 で、最初の1回だけ 500 を返す (146ms)
/api/cats はページから2回読まれましたが、サーバーに届いたのは1回だけです。1回目は fulfill で 500 を返したのでサーバーまで行かず、2回目はハンドラーが外れてサーバーに届きました。
テストの途中で差し替えをやめたいときは、page.unroute に、登録したときと同じパターンと関数を渡します。
test('unroute で差し替えをやめる', async ({ page }) => {
const handler = (route: import('@playwright/test').Route) => route.fulfill({ json: [] });
await page.route('**/api/cats', handler);
await page.goto('/');
await expect(page.locator('#status')).toHaveText('0匹');
await page.unroute('**/api/cats', handler);
await page.getByRole('button', { name: 'もう一度読み込む' }).click();
await expect(page.locator('#status')).toHaveText('3匹');
console.log('サーバーに届いた通信:', await serverHits(page));
});
このテストも通り、サーバーに届いた /api/cats は、unroute のあとの1回だけでした。関数を省くと、そのパターンのハンドラーがすべて外れます(page.unroute の説明)。
page.route と context.route の両方に合うとき
context.route は、同じブラウザコンテキストで開いたすべてのページの通信に効きます。同じ URL に両方を登録して、どちらが使われるかを見ました。
test('context.route と page.route の両方に合うと、page.route が使われる', async ({ page, context }) => {
await context.route('**/api/cats', (route) => route.fulfill({ json: [{ id: 9, name: 'context', age: 0 }] }));
await page.route('**/api/cats', (route) => route.fulfill({ json: [{ id: 8, name: 'page', age: 0 }] }));
await page.goto('/');
await expect(page.getByRole('listitem')).toHaveText(['page(0歳)']);
// 同じ context で開いた別のタブには、context.route だけが効く
const other = await context.newPage();
await other.goto('/');
await expect(other.getByRole('listitem')).toHaveText(['context(0歳)']);
});
テストは通りました。page.route を登録したページでは page.route の応答が、同じコンテキストで新しく開いたページでは context.route の応答が使われています。公式リファレンスにも、両方に合うときは page.route が優先されると書かれています(page.route の説明)。テストの中で新しいタブを開くなら、そのページの通信も差し替えるために context.route のほうを使います。
公式リファレンスによると、Service Worker が受け止めた通信には page.route が効きません。Service Worker を使うページで差し替えるときは、browser.newContext() の serviceWorkers を 'block' にするよう勧められています(page.route の説明)。
ここまでの9つのテストをまとめて実行した結果です(console.log の出力の行は省きました)。
$ npx playwright test --reporter=list; echo "exit=$?"
Running 9 tests using 1 worker
✓ 1 [chromium] › tests/context.spec.ts:3:5 › context.route と page.route の両方に合うと、page.route が使われる (189ms)
✓ 2 [chromium] › tests/continue.spec.ts:3:5 › continue でリクエストのヘッダーを足してサーバーに送る (80ms)
✓ 3 [chromium] › tests/fetch-headers.spec.ts:3:5 › fulfill に response を渡すと、ヘッダーも本物のまま返る (76ms)
✓ 4 [chromium] › tests/fetch.spec.ts:3:5 › 本物の応答を取ってきて、1匹だけ書き換える (81ms)
✓ 5 [chromium] › tests/order.spec.ts:3:5 › あとで登録したハンドラーが先に動き、fallback で前のハンドラーに回す (70ms)
✓ 6 [chromium] › tests/order.spec.ts:21:5 › continue を呼ぶと、前に登録したハンドラーは動かない (75ms)
✓ 7 [chromium] › tests/order.spec.ts:36:5 › fallback に headers を渡すと、前のハンドラーにも届く (79ms)
✓ 8 [chromium] › tests/times.spec.ts:3:5 › times: 1 で、最初の1回だけ 500 を返す (146ms)
✓ 9 [chromium] › tests/times.spec.ts:15:5 › unroute で差し替えをやめる (136ms)
9 passed (1.7s)
exit=0





