Playwright コンポーネントテスト:React と Vue で UI コンポーネントをより速く分離してテストする

Programming tutorial - IT technology blog
Programming tutorial - IT technology blog

午前2時。CI パイプラインがまた落ちた。エンドツーエンドテストがタイムアウトしている — 機能が壊れているわけではなく、無関係な3つの API 呼び出しが不安定なだけだ。こんな経験、前にもあった。画面を見つめながら、アプリ全体を起動せずに UI のバグを検出する、もっと良い方法はないかと考えていた。

そのときに出会ったのが、Playwright コンポーネントテストだ。React または Vue でプロダクション UI を構築しているなら、このツールはテストカバレッジに対する考え方を変えてくれる。

クイックスタート:5分で動かす

Playwright コンポーネントテストを使えば、フルアプリサーバーを起動せずに、Chrome、Firefox、Safari などの実際のブラウザで個々の UI コンポーネントをマウントできる。テスト可能性のための Storybook のようなもの、と考えてほしい。E2E テストで使い慣れた Playwright API で動かす、本物のブラウザレンダリングだ。

既存のプロジェクトにパッケージを追加することから始めよう:

# React プロジェクト向け
npm init playwright@latest -- --ct

# 既存の Playwright プロジェクトに追加する場合
npx playwright install

初期化ウィザードが起動したら、フレームワークを選択する。すると playwright/index.html と playwright.config.ts の設定エントリが生成される:

// playwright.config.ts
import { defineConfig, devices } from '@playwright/test';

export default defineConfig({
  testDir: './src',
  use: { baseURL: 'http://localhost:3100' },
  projects: [
    {
      name: 'chromium',
      use: { ...devices['Desktop Chrome'] },
    },
  ],
});

では、最初のコンポーネントテストを書いてみよう。Badge コンポーネントがあるとする:

// Badge.spec.tsx (React)
import { test, expect } from '@playwright/experimental-ct-react';
import Badge from './Badge';

test('エラー状態をレンダリングする', async ({ mount }) => {
  const component = await mount(<Badge status="error" label="失敗" />);
  await expect(component).toHaveText('失敗');
  await expect(component).toHaveCSS('background-color', 'rgb(220, 38, 38)');
});

実行する:

npx playwright test --project=chromium Badge.spec.tsx

これだけだ。サーバーもなく、アプリ全体をモックする必要もなく、ルーティングが安定するのを待つ必要もない。コンポーネントがマウントされ、Playwright がチェックして、完了。

詳細解説:内部で何が起きているのか

Playwright コンポーネントテストは内部で Vite 上で動作する。mount() を呼び出すと、Playwright は Vite が配信するページを起動し、コンポーネントをフィクスチャコンテナに注入して、Locator ハンドルを返す — フル E2E テストで使うのと同じ型だ。

これが重要なのは、コンポーネントテストが jsdom ではなく本物のブラウザレンダリングを使うからだ。CSS トランジション、スクロール動作、フォーカストラップ — すべてがプロダクションと全く同じように動作する。

Props、スロット、イベントの扱い方

mount() 関数は props オプション(Vue)または JSX props(React)とイベントコールバックを受け取る。カスタムドロップダウンを使った Vue の例を見てみよう:

// Dropdown.spec.ts (Vue)
import { test, expect } from '@playwright/experimental-ct-vue';
import Dropdown from './Dropdown.vue';

test('アイテムクリック時に select イベントを発行する', async ({ mount }) => {
  let selectedValue = '';

  const component = await mount(Dropdown, {
    props: {
      options: ['Alpha', 'Beta', 'Gamma'],
      onSelect: (val: string) => { selectedValue = val; },
    },
  });

  await component.getByRole('button').click();
  await component.getByText('Beta').click();

  expect(selectedValue).toBe('Beta');
});

スパイライブラリを使っていないことに気づくだろう。イベントハンドラは純粋な JavaScript だ — スパイインスタンスも、モック設定も、後片付けも何もいらない。

フェッチと外部依存関係のモック

データをフェッチするコンポーネントにはモックが必要だ。Playwright の page.route() API はコンポーネントテスト内でも動作する:

test('API からユーザーデータを表示する', async ({ page, mount }) => {
  await page.route('**/api/users/1', async route => {
    await route.fulfill({
      json: { id: 1, name: 'Hieu Nguyen', role: 'admin' },
    });
  });

  const component = await mount(<UserProfile userId={1} />);

  await expect(component.getByText('Hieu Nguyen')).toBeVisible();
  await expect(component.getByText('admin')).toBeVisible();
});

これは従来の jest.mock() アプローチより優れている。ネットワーク層でインターセプトしているからだ — 実際のブラウザが行うのとまったく同じ方法で。モジュールレベルの小細工は不要だ。

高度な使い方:スケールするパターン

コンポーネントの状態遷移のテスト

スナップショットテストやユニットテストで最も難しいのは、ステートフルな動作のテストだ — ローディング状態、エラー回復、空のリストと populated リストの比較。Playwright はこれをすっきり処理する:

test('スケルトン表示、コンテンツ表示、再フェッチ処理を確認する', async ({ page, mount }) => {
  let resolveRequest: () => void;
  const requestPending = new Promise<void>(res => { resolveRequest = res; });

  await page.route('**/api/posts', async route => {
    await requestPending;
    await route.fulfill({ json: [{ id: 1, title: '最初の投稿' }] });
  });

  const component = await mount(<PostList />);

  // ローディング状態
  await expect(component.getByTestId('skeleton')).toBeVisible();

  // データをトリガーする
  resolveRequest!();
  await expect(component.getByText('最初の投稿')).toBeVisible();
  await expect(component.getByTestId('skeleton')).not.toBeVisible();
});

テスト間でフィクスチャを再利用する

複数のテストが同じセットアップを必要とする場合 — テーマプロバイダー、ルーターコンテキスト、Pinia ストアなど — カスタムフィクスチャを一度だけ定義しよう:

// fixtures.ts
import { test as base } from '@playwright/experimental-ct-react';
import { MemoryRouter } from 'react-router-dom';
import { QueryClient, QueryClientProvider } from '@tanstack/react-query';

export const test = base.extend({
  mount: async ({ mount }, use) => {
    await use(async (component: JSX.Element) => {
      const qc = new QueryClient();
      return mount(
        <QueryClientProvider client={qc}>
          <MemoryRouter>{component}</MemoryRouter>
        </QueryClientProvider>
      );
    });
  },
});

あとは Playwright から直接インポートする代わりに ./fixtures から test をインポートするだけだ。これでマウントするすべてのコンポーネントにルーティングとクエリコンテキストが付与される — ファイルをまたいでラッパーをコピペする必要がない。

スクリーンショットによるビジュアルリグレッション

Playwright の toHaveScreenshot() はコンポーネントテスト内で動作する。コードレビューと lint の両方が見逃すビジュアルリグレッションを検出する — 2ピクセルずれたボタン、CSS の調整後にレンダリングされなくなったアイコンなど:

test('Button のビジュアルリグレッション — primary バリアント', async ({ mount }) => {
  const component = await mount(<Button variant="primary">送信</Button>);
  await expect(component).toHaveScreenshot('button-primary.png');
});

初回実行時に Playwright がベースラインを保存する。それ以降は、ピクセルの差分があればテストが失敗する。これらのスクリーンショットを Git にコミットしておくことで、チーム全員が同じベースラインを共有できる。

現場から学ぶ実践的なヒント

テストをシンプルに保つ

コンポーネントテストはファイルごとではなく、テストごとに一つの動作をカバーするべきだ。Table コンポーネントにソート、フィルタリング、ページネーションがあるなら、3つの別々のテストを書こう。シンプルなテストは、午前2時に失敗したときのデバッグが速い。

実装の詳細をテストしない

内部の状態変数やプライベートメソッドをアサートしないこと。ユーザーが見るもの — テキスト、可視性、CSS クラス、発行されたイベント — をアサートしよう。これによりテストはリファクタリングに対して耐性を持つ — 内部実装を書き直しても、テストに一切触れる必要がない。

コンポーネントテストを CI で E2E とは別に実行する

ほとんどのコンポーネントテストは 100〜500ms で完了する。毎回のプッシュで実行される別の CI ジョブに入れておこう。フルの E2E 実行はマージリクエストやスケジュールされたナイトリービルド用に取っておく。これによりフィードバックループが数分から数秒に短縮される。

# .github/workflows/test.yml
jobs:
  component-tests:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npm ci
      - run: npx playwright install chromium
      - run: npx playwright test --project=chromium src/

update-snapshots は慎重に使う

コンポーネントの見た目を意図的に変更した場合は、次を実行する:

npx playwright test --update-snapshots

新しいスクリーンショットをコミットする。CI でスナップショットを自動更新することは絶対にしないこと — 予期しないスタイルの変更がベースラインを静かに上書きし、顧客がスクリーンショット添付のバグレポートを送ってくるまで気づけなくなる。

失敗したテストのデバッグ

Playwright の UI モードほどデバッグを速くするものはない。開くだけで、ライブブラウザ、すべてのアクションのタイムライン、各ステップの DOM スナップショットが得られる:

npx playwright test --ui

テストが不安定なときは、テスト本体に await page.pause() を挿入しよう。ブラウザが一時停止し、自由にいじれる DevTools コンソールが使えるようになる。午前3時にスタックトレースを読むよりはるかに良い。

コンポーネントテストと E2E の使い分け

コンポーネントテストはエンドツーエンドテストの代替ではなく、補完するものだ。コンポーネントテストは、単一コンポーネントが分離された状態で行うこと(レンダリング、ユーザーインタラクション、ビジュアル状態)に使おう。E2E テストは境界を越えるフロー(認証、チェックアウト、複数ページのナビゲーション)に使おう。

UI の 80% をコンポーネントテストでカバーすることを目指そう。そして本当に重要なパス — ログイン、チェックアウト、決済や認証に触れるフロー — に絞った E2E テストを書く。その組み合わせで、重要な部分の信頼性を犠牲にせず、ほとんどの変更に対して素早いフィードバックが得られる。

Playwright コンポーネントテストは現在も @playwright/experimental-ct-* というパッケージ名で提供されているが、API はバージョン間で安定しており、多くのチームがプロダクションで使用している。Microsoft は積極的に投資を続けている。React または Vue のコードベースに本格的な UI の複雑さがあるなら、2時間のセットアップは最初のスプリント内に元が取れる。

Share: