playwright-best-practices

Playwright のベストプラクティス

このスキルでは、新しいテストの作成から既存のテストスイートのデバッグや保守まで、Playwright を使ったテスト開発のあらゆる側面について包括的なガイダンスを提供します。

作業内容に応じたリファレンスガイド

作業内容に応じて、以下のリファレンスを参照してください。

新しいテストの作成

使用する場面：新しいテストファイルの作成、テストケースの作成、テストシナリオの実装

アクティビティ	参考ファイル
E2E テストの作成	test-suite-structure.md, locators.md, assertions-waiting.md
コンポーネントテストの作成	component-testing.md, test-suite-structure.md
API テストの作成	api-testing.md, test-suite-structure.md
GraphQL テストの作成	graphql-testing.md, api-testing.md
ビジュアルリグレッションテストの作成	visual-regression.md, canvas-webgl.md
POM を使ったテストコードの構成	page-object-model.md, test-suite-structure.md
テストデータ／フィクスチャの設定	fixtures-hooks.md, test-data.md
認証の処理	authentication.md, authentication-flows.md
日付／時刻機能のテスト	clock-mocking.md
ファイルのアップロード／ダウンロードのテスト	file-operations.md, file-upload-download.md
フォーム／バリデーションのテスト	forms-validation.md
ドラッグ＆ドロップのテスト	drag-drop.md
アクセシビリティのテスト	accessibility.md
セキュリティ（XSS、CSRF）のテスト	security-testing.md
テストアノテーションの使用	annotations.md
テストタグの使用	test-tags.md
iframe のテスト	iframes.md
canvas/WebGL のテスト	canvas-webgl.md
国際化（i18n）	i18n.md
Electron アプリのテスト	electron.md
ブラウザー拡張機能のテスト	browser-extensions.md

モバイルとレスポンシブのテスト

使用する場面：モバイルデバイス、タッチ操作、レスポンシブレイアウトをテストする場合

アクティビティ	参照ファイル
デバイスのエミュレーション	mobile-testing.md
タッチジェスチャー（スワイプ、タップ）	mobile-testing.md
ビューポートとブレークポイントのテスト	mobile-testing.md
モバイル固有の UI	mobile-testing.md, locators.md

リアルタイム機能とブラウザー API

使用する場面：WebSocket、位置情報、権限、複数タブのフローをテストする場合

アクティビティ	参照ファイル
WebSocket／リアルタイム機能のテスト	websockets.md
位置情報のモック	browser-apis.md
権限の処理	browser-apis.md
クリップボードのテスト	browser-apis.md
カメラ／マイクのモック	browser-apis.md
複数タブ／ポップアップのフロー	multi-context.md
OAuth ポップアップの処理	third-party.md, multi-context.md

デバッグとトラブルシューティング

使用する場面：テストの失敗、要素が見つからない、タイムアウト、予期しない動作

アクティビティ	参照ファイル
テストの失敗をデバッグする	debugging.md、assertions-waiting.md
不安定なテストを修正する	flaky-tests.md、debugging.md、assertions-waiting.md
不安定な並列実行をデバッグする	flaky-tests.md、performance.md、fixtures-hooks.md
テストの分離を確保する／状態の漏洩を防ぐ	flaky-tests.md、fixtures-hooks.md、performance.md
セレクターの問題を修正する	locators.md、debugging.md
タイムアウトの問題を調査する	assertions-waiting.md、debugging.md
トレースビューアーを使用する	debugging.md
競合状態をデバッグする	flaky-tests.md、debugging.md、assertions-waiting.md
コンソール／JS エラーをデバッグする	console-errors.md、debugging.md

エラーとエッジケースのテスト

使用する場面：エラー状態、オフラインモード、ネットワーク障害、検証のテスト

アクティビティ	参照ファイル
エラーバウンダリーのテスト	error-testing.md
ネットワーク障害のシミュレーション	error-testing.md、network-advanced.md
オフラインモードのテスト	error-testing.md、service-workers.md
サービスワーカーのテスト	service-workers.md
読み込み状態のテスト	error-testing.md
フォーム検証のテスト	error-testing.md

マルチユーザーとコラボレーションのテスト

使用する場面：複数のユーザー、ロール、リアルタイムコラボレーションに関する機能をテストする場合

アクティビティ	参照ファイル
1つのテストで複数のユーザーを使用	multi-user.md
リアルタイムコラボレーション	multi-user.md, websockets.md
ロールベースのアクセスをテスト	multi-user.md
同時アクションをテスト	multi-user.md

アーキテクチャの決定

使用する場面：テストパターンの選択、アプローチの比較、テストアーキテクチャの計画

アクティビティ	参照ファイル
POM とフィクスチャの選択	pom-vs-fixtures.md
テストの種類の選択	test-architecture.md
モックと実サービスの比較	when-to-mock.md
テストスイートの構成	test-suite-structure.md

フレームワーク固有のテスト

使用する場面：React、Angular、Vue、Next.js アプリケーションをテストする場合

アクティビティ	参照ファイル
React アプリのテスト	react.md
Angular アプリのテスト	angular.md
Vue/Nuxt アプリのテスト	vue.md
Next.js アプリのテスト	nextjs.md

リファクタリングとメンテナンス

使用する場面：既存のテストの改善、コードレビュー、重複の削減

アクティビティ	参照ファイル
ページオブジェクトモデルへのリファクタリング	page-object-model.md, test-suite-structure.md
テストの整理方法を改善	test-suite-structure.md, page-object-model.md
共通のセットアップ／ティアダウンを抽出	fixtures-hooks.md
壊れやすいセレクターを置き換え	locators.md
明示的な待機を削除	assertions-waiting.md
テストデータファクトリーを作成	test-data.md
設定のセットアップ	configuration.md

インフラストラクチャと設定

使用する場面：プロジェクトのセットアップ、CI/CD の設定、パフォーマンスの最適化

アクティビティ	参照ファイル
Playwright プロジェクトの設定	configuration.md, projects-dependencies.md
CI/CD パイプラインのセットアップ	ci-cd.md, github-actions.md
GitHub Actions のセットアップ	github-actions.md
GitLab CI のセットアップ	gitlab.md
その他の CI プロバイダー	other-providers.md
Docker／コンテナーのセットアップ	docker.md
グローバルセットアップとティアダウン	global-setup.md
プロジェクトの依存関係	projects-dependencies.md
テストパフォーマンスの最適化	performance.md, test-suite-structure.md
並列実行の設定	parallel-sharding.md, performance.md
ワーカー間のテストデータの分離	fixtures-hooks.md, performance.md
テストカバレッジ	test-coverage.md
テストレポート／成果物	reporting.md

高度なパターン

使用する場面：複雑なシナリオ、API のモック、ネットワークのインターセプト

アクティビティ	参照ファイル
API レスポンスのモック	test-suite-structure.md, network-advanced.md
ネットワークのインターセプト	network-advanced.md, assertions-waiting.md
GraphQL のモック	network-advanced.md
HAR の記録／再生	network-advanced.md
カスタムフィクスチャ	fixtures-hooks.md
高度な待機戦略	assertions-waiting.md
OAuth／SSO のモック	third-party.md, multi-context.md
決済ゲートウェイのモック	third-party.md
メール／SMS 認証のモック	third-party.md
コンソールエラー発生時に失敗させる	console-errors.md
セキュリティテスト（XSS、CSRF）	security-testing.md
パフォーマンス予算と Web Vitals	performance-testing.md
Lighthouse の統合	performance-testing.md
テストアノテーション（skip、fixme）	annotations.md
テストタグ（@smoke、@fast）	test-tags.md
レポート用のテストステップ	annotations.md

すばやく判断するためのフローチャート

What are you doing?
│
├─ Writing a new test?
│  ├─ E2E test → core/test-suite-structure.md, core/locators.md, core/assertions-waiting.md
│  ├─ Component test → testing-patterns/component-testing.md
│  ├─ API test → testing-patterns/api-testing.md, core/test-suite-structure.md
│  ├─ GraphQL test → testing-patterns/graphql-testing.md
│  ├─ Visual regression → testing-patterns/visual-regression.md
│  ├─ Visual/canvas test → testing-patterns/canvas-webgl.md, core/test-suite-structure.md
│  ├─ Accessibility test → testing-patterns/accessibility.md
│  ├─ Mobile/responsive test → advanced/mobile-testing.md
│  ├─ i18n/locale test → testing-patterns/i18n.md
│  ├─ Electron app test → testing-patterns/electron.md
│  ├─ Browser extension test → testing-patterns/browser-extensions.md
│  ├─ Multi-user test → advanced/multi-user.md
│  ├─ Form validation test → testing-patterns/forms-validation.md
│  └─ Drag and drop test → testing-patterns/drag-drop.md
│
├─ Testing specific features?
│  ├─ File upload/download → testing-patterns/file-operations.md, testing-patterns/file-upload-download.md
│  ├─ Date/time dependent → advanced/clock-mocking.md
│  ├─ WebSocket/real-time → browser-apis/websockets.md
│  ├─ Geolocation/permissions → browser-apis/browser-apis.md
│  ├─ OAuth/SSO mocking → advanced/third-party.md, advanced/multi-context.md
│  ├─ Payments/email/SMS → advanced/third-party.md
│  ├─ iFrames → browser-apis/iframes.md
│  ├─ Canvas/WebGL/charts → testing-patterns/canvas-webgl.md
│  ├─ Service workers/PWA → browser-apis/service-workers.md
│  ├─ i18n/localization → testing-patterns/i18n.md
│  ├─ Security (XSS, CSRF) → testing-patterns/security-testing.md
│  └─ Performance/Web Vitals → testing-patterns/performance-testing.md
│
├─ Architecture decisions?
│  ├─ POM vs fixtures → architecture/pom-vs-fixtures.md
│  ├─ Test type selection → architecture/test-architecture.md
│  ├─ Mock vs real services → architecture/when-to-mock.md
│  └─ Test suite structure → core/test-suite-structure.md
│
├─ Framework-specific testing?
│  ├─ React app → frameworks/react.md
│  ├─ Angular app → frameworks/angular.md
│  ├─ Vue/Nuxt app → frameworks/vue.md
│  └─ Next.js app → frameworks/nextjs.md
│
├─ Authentication testing?
│  ├─ Basic auth patterns → advanced/authentication.md
│  └─ Complex flows (MFA, reset) → advanced/authentication-flows.md
│
├─ Test is failing/flaky?
│  ├─ Flaky test investigation → debugging/flaky-tests.md
│  ├─ Element not found → core/locators.md, debugging/debugging.md
│  ├─ Timeout issues → core/assertions-waiting.md, debugging/debugging.md
│  ├─ Race conditions → debugging/flaky-tests.md, debugging/debugging.md
│  ├─ Flaky only with multiple workers → debugging/flaky-tests.md, infrastructure-ci-cd/performance.md
│  ├─ State leak / isolation → debugging/flaky-tests.md, core/fixtures-hooks.md
│  ├─ Console/JS errors → debugging/console-errors.md, debugging/debugging.md
│  └─ General debugging → debugging/debugging.md
│
├─ Testing error scenarios?
│  ├─ Network failures → debugging/error-testing.md, advanced/network-advanced.md
│  ├─ Offline (unexpected) → debugging/error-testing.md
│  ├─ Offline-first/PWA → browser-apis/service-workers.md
│  ├─ Error boundaries → debugging/error-testing.md
│  └─ Form validation → testing-patterns/forms-validation.md, debugging/error-testing.md
│
├─ Refactoring existing code?
│  ├─ Implementing POM → core/page-object-model.md
│  ├─ Improving selectors → core/locators.md
│  ├─ Extracting fixtures → core/fixtures-hooks.md
│  ├─ Creating data factories → core/test-data.md
│  └─ Configuration setup → core/configuration.md
│
├─ Setting up infrastructure?
│  ├─ CI/CD → infrastructure-ci-cd/ci-cd.md
│  ├─ GitHub Actions → infrastructure-ci-cd/github-actions.md
│  ├─ GitLab CI → infrastructure-ci-cd/gitlab.md
│  ├─ Other CI providers → infrastructure-ci-cd/other-providers.md
│  ├─ Docker/containers → infrastructure-ci-cd/docker.md
│  ├─ Sharding/parallel → infrastructure-ci-cd/parallel-sharding.md
│  ├─ Reporting/artifacts → infrastructure-ci-cd/reporting.md
│  ├─ Global setup/teardown → core/global-setup.md
│  ├─ Project dependencies → core/projects-dependencies.md
│  ├─ Test performance → infrastructure-ci-cd/performance.md
│  ├─ Test coverage → infrastructure-ci-cd/test-coverage.md
│  └─ Project config → core/configuration.md, core/projects-dependencies.md
│
├─ Organizing tests?
│  ├─ Skip/fixme/slow tests → core/annotations.md
│  ├─ Test tags (@smoke, @fast) → core/test-tags.md
│  ├─ Filtering tests (--grep) → core/test-tags.md
│  ├─ Test steps → core/annotations.md
│  └─ Conditional execution → core/annotations.md
│
└─ Running subset of tests?
   ├─ By tag (@smoke, @critical) → core/test-tags.md
   ├─ Exclude slow/flaky tests → core/test-tags.md
   ├─ PR vs nightly tests → core/test-tags.md, infrastructure-ci-cd/ci-cd.md
   └─ Project-specific filtering → core/test-tags.md, core/configuration.md

テストの検証ループ

テストを作成または変更した後：

1. テストを実行する：npx playwright test --reporter=list
2. テストが失敗した場合：
   • エラー出力とトレースを確認する（npx playwright show-trace）
   • ロケーター、待機処理、またはアサーションを修正する
   • テストを再実行する
3. すべてのテストが成功した場合にのみ次へ進む
4. 重要なテストは複数回実行する：npx playwright test --repeat-each=5