ReactとPlaywrightで、APIをモックしてテストする方法
React の画面が受け取る API の応答は、Playwright Test の page.route で差し替えられます(API のモック)。バックエンドのサーバーを動かさずに、一覧の表示、サーバーのエラー(500)、通信の失敗、読み込み中の表示を1つずつテストできます。本物のサーバーでは起こしにくいエラーの画面も、テストの中で決めた応答を返すだけで再現できます。
私は検証環境で、Vite の React + TypeScript で作った「猫の一覧」の画面に対し、応答を差し替えるテストを5つ書いて通しました。あわせて試して分かった、React の StrictMode で通信が2回になる点と、クエリ文字列の付いた URL にパターンが合わない点も、実際の出力とともに紹介します。
検証環境は Ubuntu 24.04、Node.js 22.23.4、npm 10.9.9 です。使ったのは react / react-dom 19.3.1、vite 8.3.8、@vitejs/plugin-react 6.3.0、typescript 7.0.2、@playwright/test 1.63.0 で、ブラウザは Chromium だけです。Firefox と WebKit、CI サービス上での実行、本物の応答を取ってきて一部だけ書き換える route.fetch、HAR ファイルを使った差し替え、Service Worker を使うアプリは試していません。
テストする画面
画面は、開いたときに GET /api/cats?sort=name で猫の一覧を読み込みます。応答の状態に合わせて「読み込み中…」、エラーと「もう一度読み込む」ボタン、一覧のどれかを出します。一覧の下のフォームで名前を入れて「追加」を押すと、POST /api/cats に名前を送り、返ってきた猫を一覧の末尾に足します。
検証環境には /api/cats を返すサーバーはありません。テストの中で応答を差し替えて、次の3つの画面を出し分けています。

コンポーネントは次のとおりです。fetch は、サーバーが 500 を返しても失敗にはならず、res.ok が false の応答として返ってきます。そのため、res.ok を見て自分でエラーにしています。一方、サーバーにつながらないなど通信そのものが失敗したときは、fetch が TypeError で失敗します(MDN の fetch の説明)。この2つを分けて、別のメッセージを出しています。
// src/App.tsx
import { useEffect, useState } from 'react';
import type { FormEvent } from 'react';
type Cat = { id: number; name: string };
type State =
| { type: 'loading' }
| { type: 'error'; message: string }
| { type: 'done'; cats: Cat[] };
export default function App() {
const [state, setState] = useState<State>({ type: 'loading' });
const [reload, setReload] = useState(0);
const [name, setName] = useState('');
useEffect(() => {
let ignore = false;
setState({ type: 'loading' });
fetch('/api/cats?sort=name')
.then(async (res) => {
if (!res.ok) throw new Error(`読み込みに失敗しました(${res.status})`);
return (await res.json()) as Cat[];
})
.then((cats) => {
if (!ignore) setState({ type: 'done', cats });
})
.catch((e: unknown) => {
if (ignore) return;
const message =
e instanceof TypeError ? 'サーバーに接続できませんでした' : (e as Error).message;
setState({ type: 'error', message });
});
return () => {
ignore = true;
};
}, [reload]);
async function handleSubmit(e: FormEvent<HTMLFormElement>) {
e.preventDefault();
const res = await fetch('/api/cats', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ name }),
});
const created = (await res.json()) as Cat;
setState((prev) =>
prev.type === 'done' ? { type: 'done', cats: [...prev.cats, created] } : prev,
);
setName('');
}
return (
<main>
<h1>猫の一覧</h1>
{state.type === 'loading' && <p>読み込み中…</p>}
{state.type === 'error' && (
<div role="alert">
<p className="error">{state.message}</p>
<button type="button" onClick={() => setReload((n) => n + 1)}>
もう一度読み込む
</button>
</div>
)}
{state.type === 'done' && (
<>
{state.cats.length === 0 ? (
<p>まだ猫がいません</p>
) : (
<ul>
{state.cats.map((cat) => (
<li key={cat.id}>{cat.name}</li>
))}
</ul>
)}
<form onSubmit={handleSubmit}>
<label>
名前
<input value={name} onChange={(e) => setName(e.target.value)} />
</label>
<button type="submit">追加</button>
</form>
</>
)}
</main>
);
}
main.tsx は、Vite のひな形のまま <StrictMode> で App を囲んでいます。これが、後で説明する通信の回数に関わります。
Playwright の設定では、テストの前に npm run dev で Vite の開発サーバーを起動させています。この記事では、毎回 Playwright が開発サーバーを起動するように、CI=1 を付けて実行しました(reuseExistingServer については、公式ドキュメントの開発サーバーの起動の説明を参照してください)。
// playwright.config.ts
import { defineConfig, devices } from '@playwright/test';
export default defineConfig({
testDir: './e2e',
use: {
baseURL: 'http://localhost:5173',
},
projects: [{ name: 'chromium', use: { ...devices['Desktop Chrome'] } }],
webServer: {
command: 'npm run dev',
url: 'http://localhost:5173',
reuseExistingServer: !process.env.CI,
},
});
一覧の応答を差し替える
いちばん基本の形です。page.route に URL のパターンと関数を渡すと、パターンに合う通信がその関数に届きます。関数の中で route.fulfill を呼ぶと、サーバーに問い合わせずに、渡した内容をそのまま応答として返します。json に値を渡すと、JSON の本文になり、Content-Type も application/json になります。
// e2e/cats.spec.ts
import { test, expect } from '@playwright/test';
test('APIが返した一覧を表示する', async ({ page }) => {
await page.route('**/api/cats?*', (route) =>
route.fulfill({
json: [
{ id: 1, name: 'たま' },
{ id: 2, name: 'みけ' },
],
}),
);
await page.goto('/');
await expect(page.getByRole('listitem')).toHaveText(['たま', 'みけ']);
});
この画面は開いた直後に一覧を読み込むので、page.route は page.goto より前に呼んでいます。公式ドキュメントの API のモックの例でも、ページを開く前に差し替えています。
パターンの **/api/cats?* は、/api/cats? の後ろに / を含まない文字列が続く URL に合います。Playwright のパターンでは * が「/ 以外の文字の並び」、** が「/ も含む文字の並び」です。? は1文字を表す記号ではなく、? という文字そのものにだけ合います(URL のパターンの説明)。?* を付け忘れたときにどうなるかは、最後の節で試しています。
500 を返して、エラーと再読み込みを確かめる
サーバーのエラーを再現するには、route.fulfill の status に 500 を渡します(省くと 200 です)。このテストでは、最初は 500 を返し、「もう一度読み込む」を押したあとは一覧を返すようにしました。
test('500が返ると、エラーと再読み込みのボタンを出す', async ({ page }) => {
let failing = true;
await page.route('**/api/cats?*', (route) => {
if (failing) return route.fulfill({ status: 500, body: 'Internal Server Error' });
return route.fulfill({ json: [{ id: 1, name: 'たま' }] });
});
await page.goto('/');
await expect(page.getByRole('alert')).toContainText('読み込みに失敗しました(500)');
failing = false;
await page.getByRole('button', { name: 'もう一度読み込む' }).click();
await expect(page.getByRole('listitem')).toHaveText(['たま']);
});
応答の切り替えは、テストの中の変数 failing で行っています。エラーが出たのを確かめてから false にして、ボタンを押します。「1回目の通信だけ 500 にする」と回数で切り替える書き方も試しましたが、この画面では失敗しました。理由は後の節で説明します。
通信の失敗と、読み込み中の表示を確かめる
サーバーにつながらない場面は、route.abort で作れます。応答を返さずに通信を失敗させるので、画面の fetch は TypeError で失敗し、「サーバーに接続できませんでした」が出ます。route.abort には失敗の種類を渡せて、省くと failed(一般的な失敗)になります。
test('サーバーにつながらないと、接続のエラーを出す', async ({ page }) => {
await page.route('**/api/cats?*', (route) => route.abort());
await page.goto('/');
await expect(page.getByRole('alert')).toContainText('サーバーに接続できませんでした');
});
読み込み中の表示は、応答を返すタイミングをテストの側で決めて確かめます。page.route を登録すると、パターンに合う通信は、関数の中で fulfill・continue・abort のどれかを呼ぶまで止まったままになります(page.route の説明)。そこで、関数の中で Promise を待たせておき、「読み込み中…」を確かめてから release() で応答を返しました。
test('応答が届くまで、読み込み中と表示する', async ({ page }) => {
let release!: () => void;
const released = new Promise<void>((resolve) => (release = resolve));
await page.route('**/api/cats?*', async (route) => {
await released;
await route.fulfill({ json: [] });
});
await page.goto('/');
await expect(page.getByText('読み込み中…')).toBeVisible();
release();
await expect(page.getByText('まだ猫がいません')).toBeVisible();
await expect(page.getByText('読み込み中…')).toHaveCount(0);
});
こうすると、応答を返す前と後の両方の表示を、順番に確かめられます。
POST で送った中身を確かめる
追加のフォームのテストでは、画面が送った内容も確かめます。route.request() で通信の情報を取り出し、method() でメソッドを、postDataJSON() で本文を JSON として読めます。
test('追加すると、入力した名前をPOSTで送る', async ({ page }) => {
await page.route('**/api/cats?*', (route) => route.fulfill({ json: [] }));
await page.route('**/api/cats', async (route) => {
const request = route.request();
expect(request.method()).toBe('POST');
expect(request.postDataJSON()).toEqual({ name: 'くろ' });
await route.fulfill({ status: 201, json: { id: 10, name: 'くろ' } });
});
await page.goto('/');
await page.getByLabel('名前').fill('くろ');
await page.getByRole('button', { name: '追加' }).click();
await expect(page.getByRole('listitem')).toHaveText(['くろ']);
});
ここでは2つのパターンを登録しています。**/api/cats は ? の付かない /api/cats だけに合い、**/api/cats?* は ?sort=name の付いた一覧の読み込みだけに合います。そのため、一覧の GET が POST 用の関数に届くことはありません。
関数の中の expect が外れたときにテストが落ちるかも確かめました。期待する名前を「しろ」に変えたコピーのファイルを実行すると、toEqual の違いを示して失敗しました(出力は一部です)。
✘ 5 [chromium] › e2e/post-wrong.spec.ts:51:1 › 追加すると、入力した名前をPOSTで送る (294ms)
Error: expect(received).toEqual(expected) // deep equality
- Expected - 1
+ Received + 1
Object {
- "name": "しろ",
+ "name": "くろ",
}
ここまでの5つのテストをまとめて実行すると、すべて通りました。
$ CI=1 npx playwright test e2e/cats.spec.ts --reporter=list; echo "exit=$?"
Running 5 tests using 1 worker
✓ 1 [chromium] › e2e/cats.spec.ts:3:1 › APIが返した一覧を表示する (245ms)
✓ 2 [chromium] › e2e/cats.spec.ts:16:1 › 500が返ると、エラーと再読み込みのボタンを出す (259ms)
✓ 3 [chromium] › e2e/cats.spec.ts:30:1 › サーバーにつながらないと、接続のエラーを出す (209ms)
✓ 4 [chromium] › e2e/cats.spec.ts:36:1 › 応答が届くまで、読み込み中と表示する (224ms)
✓ 5 [chromium] › e2e/cats.spec.ts:51:1 › 追加すると、入力した名前をPOSTで送る (300ms)
5 passed (2.8s)
exit=0
StrictMode では、回数で応答を切り替えるテストが失敗する
500 のテストを、通信の回数を数えて「1回目だけ 500」にする形でも書いてみました。
test('1回目だけ500を返す(回数で切り替える)', async ({ page }) => {
let calls = 0;
await page.route('**/api/cats?*', (route) => {
calls++;
if (calls === 1) return route.fulfill({ status: 500, body: 'Internal Server Error' });
return route.fulfill({ json: [{ id: 1, name: 'たま' }] });
});
await page.goto('/');
await expect(page.getByRole('alert')).toContainText('読み込みに失敗しました(500)');
});
このテストは、エラーの表示が見つからずに失敗しました。失敗したときに Playwright が残す error-context.md を見ると、画面にはエラーではなく「たま」の一覧が出ていました。端末の出力は次のとおりです(一部です)。
Error: expect(locator).toContainText(expected) failed
Locator: getByRole('alert')
Expected substring: "読み込みに失敗しました(500)"
Timeout: 5000ms
Error: element(s) not found
画面を開いたときの /api/cats への通信を数えると、2回でした(出力は一部です)。
通信の回数: 2
✓ 1 [chromium] › e2e/count.spec.ts:3:1 › 最初に開いたときの /api/cats への通信を数える (348ms)
React の StrictMode は、開発中だけ、Effect を余分に1回実行します。1回目の Effect はすぐにクリーンアップされ(ignore が true になり)、その結果は捨てられます。画面に使われるのは2回目の通信の応答です。回数で切り替えると、捨てられる1回目に 500 が返り、画面には2回目の一覧が出ていました。
main.tsx から <StrictMode> を一時的に外して実行すると、通信は1回になり、回数で切り替えるテストも通りました(出力は一部です)。
通信の回数: 1
✓ 1 [chromium] › e2e/count.spec.ts:3:1 › 最初に開いたときの /api/cats への通信を数える (431ms)
✓ 2 [chromium] › e2e/retry-count.spec.ts:3:1 › 1回目だけ500を返す(回数で切り替える) (456ms)
パターンがクエリ文字列に合わないと、差し替わらない
最後に、パターンを **/api/cats?* ではなく **/api/cats にしたテストです。
test('パターンに ?* を付けずに差し替える', async ({ page }) => {
await page.route('**/api/cats', (route) => route.fulfill({ json: [{ id: 1, name: 'たま' }] }));
await page.goto('/');
await expect(page.getByRole('listitem')).toHaveText(['たま']);
});
このテストは、一覧の項目が1つも見つからないまま、5秒待って失敗しました。error-context.md に残った画面の内容は次のとおりで、JSON を読めなかったというエラーが出ています。
- main [ref=e3]:
- heading "猫の一覧" [level=1] [ref=e4]
- alert [ref=e5]:
- paragraph [ref=e6]: Unexpected token '<', "<!doctype "... is not valid JSON
- button "もう一度読み込む" [ref=e7]
パターンは URL の全体に合う必要があります(URL のパターンの説明)。**/api/cats は ?sort=name の付いた URL に合わないので、通信は差し替えられずに Vite の開発サーバーまで届きます。開発サーバーに同じ URL を curl で問い合わせると、200 OK で Content-Type: text/html の、アプリの HTML が返ってきました。
$ curl -s -i 'http://localhost:5173/api/cats?sort=name' | head -5; echo; curl -s 'http://localhost:5173/api/cats?sort=name' | head -3
HTTP/1.1 200 OK
Vary: Origin
Content-Type: text/html
Cache-Control: no-cache
Etag: W/"262-jTvT37rIKggjZPfoIHfBJpBLdkQ"
<!doctype html>
<html lang="en">
<head>
状態は 200 なので res.ok は true になり、HTML を JSON として読もうとしたところでエラーになっていました。差し替えたつもりのテストが、開発サーバーの返した HTML を読んでいたことになります。モックしたはずの画面に「is not valid JSON」のようなエラーが出たら、まずパターンが URL の全体に合っているかを見直してください。





