e2e-testing

E2E テスト

概要

Playwright を使用した E2E テストのアーキテクチャとパターンについて説明します。テストスイートの構成、テストの整理、認証、モック、ビジュアルリグレッション、アクセシビリティ監査、CI の並列実行に関する実証済みのパターンの適用方法を解説します。Playwright API の詳細ではなく、各テストパターンを使う理由とタイミングに焦点を当てています。

使用する場面： テストスイートのアーキテクチャ設計、ページオブジェクトモデルの構成、CI のシャーディング戦略の計画、認証フローの設定、タグやアノテーションを使ったテストの整理、ビジュアルリグレッションワークフローの実装、ネットワークリクエストのモック、アクセシビリティ監査。

使用しない場面： 単体テスト（Vitest/Jest を使用）、API のみのテスト（統合テストを使用）、コンポーネント単体のテスト（コンポーネントテストランナーを使用）。Playwright API の詳細、ブラウザーの自動化、スクレイピング、Playwright のエラーのトラブルシューティングには、playwright スキルを使用してください。

クイックリファレンス

パターン	API／ツール	主なポイント
ロールベースのロケーター	getByRole, getByText, getByLabel	CSS／XPath セレクターより推奨されます
ページオブジェクトモデル	tests/pages/ 内のクラス	ページ固有のロケーターとアクションをすべてカプセル化します
認証	storageState + セットアッププロジェクト	一度認証すれば、テスト間で再利用できます
ビジュアルリグレッション	expect(page).toHaveScreenshot()	動的なコンテンツをマスクして、不安定さを防ぎます
アクセシビリティ監査	@axe-core/playwright の AxeBuilder	主要なフローで .withTags() + .analyze() を使用します
トレースデバッグ	trace: 'on-first-retry'	完全な DOM スナップショット、ネットワークログ、タイムライン
ネットワークモック	page.route()	サードパーティへの依存なしで安定したテストを実行できます
HAR の再生	page.routeFromHAR()	記録したトラフィックから忠実度の高いモックを作成します
画像のブロック	page.route('**/*.{png,jpg}', abort)	画像をスキップしてテストを高速化します
CI シャーディング	--shard=1/4	テストスイートを並列 CI マシンに分割します
Blob レポート	--reporter=blob + merge-reports	シャーディングした結果を単一のレポートに統合します
テストタグ	{ tag: ['@smoke'] }	--grep でカテゴリ別にテストを絞り込みます
テストステップ	test.step('name', async () => {})	トレースビューアーとレポートでアクションをグループ化します
変更されたテストのみ	--only-changed=$GITHUB_BASE_REF	ベースブランチ以降に変更されたテストファイルのみを実行します
ネイティブ a11y チェック	toHaveAccessibleName, toHaveRole	axe-core の全スキャンに代わる軽量な方法です
レポート内の Git 情報	captureGitInfo レポーターオプション	CI のデバッグ用にテストレポートをコミットに紐付けます
Web ファーストアサーション	expect(element).toBeVisible()	waitForTimeout の代わりに自動待機します
フィクスチャの合成	mergeTests() / mergeExpects()	3 つ以上のフィクスチャモジュールを 1 つの test にまとめます
自動フィクスチャ	test.extend() の { auto: true }	すべてのテストで実行します（ログ記録、スクリーンショットなど）
フィクスチャオプション	test.extend() の { option: true }	config または test.use() で設定できます
データ駆動テスト	test() 呼び出しを生成する for...of ループ	配列または CSV ファイルからパラメーター化されたテストを作成します
コンテキストのエミュレーション	browser.newContext() のオプション	locale、timezone、colorScheme、offline、isMobile
1 つのテストで 2 つのロール	並行する browser.newContext() 呼び出し	コンテキストごとに storageState を分けます

よくある間違い

間違い	正しいパターン
要素の表示確認に page.waitForTimeout() を使う	自動で待機する expect(element).toBeVisible() などの Web ファーストアサーションを使う
テストファイルにロケーターを直接記述する	すべてのセレクターを Page Object Model クラスにカプセル化する
サードパーティ API（Stripe、Auth0）を直接テストする	page.route() で外部サービスをモックし、安定した高速なテストを実現する
トレースの代わりにスクリーンショットで CI の失敗をデバッグする	trace: 'on-first-retry' を設定し、Playwright Trace Viewer を使う
グローバル変数を使ってテスト間で状態を共有する	完全に分離するため、テストごとに新しい BrowserContext を使う
すべてのテストを 1 つの CI ジョブで実行する	Playwright のシャーディング（--shard=1/N）を使って複数のマシンで並列実行する
要素の特定に CSS／XPath セレクターを使う	リファクタリング後も機能し、アクセシビリティを確保できるロールベースのロケーターを使う
すべてのテストで UI からログインする	setup プロジェクトで storageState を使い、一度だけ認証する
axe-playwright の injectAxe／checkA11y を使う	@axe-core/playwright の AxeBuilder で .analyze() を使う
storageState の JSON ファイルを git にコミットする	.gitignore に playwright/.auth/ を追加する
サインアウトのテストで storageState に頼る	サインアウトするとサーバーセッションが無効になるため、各サインアウトテストで UI からサインインする
storageState が sessionStorage を保持すると想定する	保存されるのは Cookie と localStorage のみです。sessionStorage には addInitScript() を使います
ロケール／通貨ごとにテストコードを重複させる	プロジェクトごとの設定オーバーライドとフィクスチャオプション（{ option: true }）を使う
3 つ以上のモジュールで mergeTests() を使わずにフィクスチャを作成する	mergeTests() でフィクスチャファイルを合成し、単一の test エクスポートにまとめる

委任

• E2E カバレッジが不足しているユーザーフローを見つける：Explore エージェントを使います
• アプリケーション向けに完全な Page Object Model テストスイートを構築する：Task エージェントを使います
• 大規模なテストスイートの CI シャーディング戦略を計画する：Plan エージェントを使います

Playwright API の詳細、ブラウザー自動化、スクレイピング、ステルスモード、スクリーンショット／PDF、Docker へのデプロイ、または Playwright エラーのトラブルシューティングには、playwright スキルを使ってください。

参考資料

• ロールベースのロケーター、自動待機、連結、フィルタリング、ロケーター戦略
• Page Object Model のアーキテクチャ、フィクスチャとの統合、ベースページのパターン
• フィクスチャ：スコープ設定、合成、自動フィクスチャ、オプション、データ駆動テスト
• storageState、setup プロジェクト、複数ロールのテストによる認証
• ネットワークのモック、ルートのインターセプト、HAR の再生、WebSocket のモック
• AxeBuilder、WCAG タグ、再利用可能なフィクスチャによるアクセシビリティ監査
• ビジュアルリグレッション、スナップショットテスト、マスキング、許容しきい値、ベースライン管理
• CI シャーディング、並列処理、blob レポート、ブラウザーキャッシュ
• タグ、アノテーション、test.step、プロジェクト設定によるテストの整理