ReactとPlaywrightで、APIをモックしてテストする方法

​​React​Playwright,TypeScript,Vite,テスト

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つの画面を出し分けています。

「猫の一覧」の画面を3つ縦に並べた図。上から、「読み込み中…」だけの画面、赤い文字の「読み込みに失敗しました(500)」と「もう一度読み込む」ボタンの画面、「たま」「みけ」の一覧と名前の入力欄の画面
差し替えた応答ごとの画面。上から、応答を止めている間、500 を返したとき、2件の一覧を返したとき

コンポーネントは次のとおりです。fetch は、サーバーが 500 を返しても失敗にはならず、res.ok が false の応答として返ってきます。そのため、res.ok を見て自分でエラーにしています。一方、サーバーにつながらないなど通信そのものが失敗したときは、fetch が TypeError で失敗します(MDN の fetch の説明)。この2つを分けて、別のメッセージを出しています。

tsx
// 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 については、公式ドキュメントの開発サーバーの起動の説明を参照してください)。

ts
// 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 になります。

ts
// 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 を返し、「もう一度読み込む」を押したあとは一覧を返すようにしました。

ts
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(一般的な失敗)になります。

ts
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() で応答を返しました。

ts
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 として読めます。

ts
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 の違いを示して失敗しました(出力は一部です)。

text
  ✘  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つのテストをまとめて実行すると、すべて通りました。

text
$ 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」にする形でも書いてみました。

ts
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 を見ると、画面にはエラーではなく「たま」の一覧が出ていました。端末の出力は次のとおりです(一部です)。

text
    Error: expect(locator).toContainText(expected) failed

    Locator: getByRole('alert')
    Expected substring: "読み込みに失敗しました(500)"
    Timeout: 5000ms
    Error: element(s) not found

画面を開いたときの /api/cats への通信を数えると、2回でした(出力は一部です)。

text
通信の回数: 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回になり、回数で切り替えるテストも通りました(出力は一部です)。

text
通信の回数: 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 にしたテストです。

ts
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 を読めなかったというエラーが出ています。

text
- 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 が返ってきました。

text
$ 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 の全体に合っているかを見直してください。

​Posted by 86