午前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時間のセットアップは最初のスプリント内に元が取れる。

