QA Testing (Playwright)

Webアプリケーション向けの高い精度、コスト効率的なE2Eテスト。

コアドキュメント:

• https://playwright.dev/docs/best-practices
• https://playwright.dev/docs/locators
• https://playwright.dev/docs/test-retries
• https://playwright.dev/docs/trace-viewer
• https://playwright.dev/docs/test-sharding
• https://playwright.dev/docs/ci

デフォルト設定 (2026)

• E2Eテストを薄く保つ: 重要なユーザーフロー のみを保護し、カバレッジはダウン(ユニット/インテグレーション/コントラクト)に移す。
• ロケーター優先順位: getByRole → getByLabel/getByText → getByTestId (フォールバック)。
• 待機: Playwright自動待機 + web-first アサーションに依存し、sleepや時間ベースの待機は不可。
• 分離: テストは単独で、並列で、任意の順序で実行可能でなければならず、共有可変状態を排除する。
• フレーク対策: リトライはデバッグツール; リラン成功を失敗シグナルとして扱い、根本原因を修正する。
• CI対策: PR上でスモークゲートを実施; スケジュール時に回帰を sharding/並列化; 常にアーティファクト(trace/video/screenshot)を保持する。

クイックスタート

コマンド	目的
npm init playwright@latest	Playwrightを初期化
npx playwright test	すべてのテストを実行
npx playwright test --grep @smoke	スモークテストを実行
npx playwright test --project=chromium	単一プロジェクトを実行
npx playwright test --ui	UIモードでデバッグ
npx playwright test --debug	テストをステップスルー
npx playwright show-trace trace.zip	traceアーティファクトを検査
npx playwright show-report	HTMLレポートを検査

使用場面

• Webアプリケーションのe2eテスト
• ユーザー認証フローのテスト
• フォーム送信の検証
• レスポンシブデザインのテスト
• ブラウザインタラクションの自動化
• CI/CDでのPlaywright設定

使用しない場面

シナリオ	代わりに使用
ユニットテスト	Jest, Vitest, pytest
APIコントラクト	qa-api-testing-contracts
ロードテスト	k6, Locust, Artillery
モバイルネイティブ	Appium

オーサリングルール

ロケーター戦略

// 1. ロールロケーター (推奨)
await page.getByRole('button', { name: 'Sign in' }).click();

// 2. ラベル/テキストロケーター
await page.getByLabel('Email').fill('user@example.com');

// 3. テストID (フォールバック)
await page.getByTestId('user-avatar').click();

フレーク制御

• sleepを避け、Playwright自動待機を使用する
• リトライをシグナルとして扱う、杖ではなく
• 失敗時にtrace/screenshot/videoをキャプチャする
• ユーザーライクなインタラクションを優先; force: true を避ける

ワークフロー

• ユーザー結果(意図+オラクル)を証明する最小のテストを記述する。
• さらにステップを追加する前にロケーターとアサーションを安定化させる。
• 状態を明示的にする: テスト/ワーカーごとにシード、決定論的にクリーンアップ、サードパーティ境界をモック。
• CI内: sharding/並列化、アーティファクトをキャプチャ、リラン成功フレークで速く失敗させる。

デバッグチェックリスト

何かがフレーキーな場合:

• traceを最初に開き、ロケーター曖昧性、待機漏れ、状態漏洩のいずれかを特定する。
• 脆弱なセレクターを意味論的ロケーターに置き換え、sleepを expect(...) または的を絞った待機に置き換える。
• グローバルタイムアウトを削減; 製品が本当に必要な場合のみスコープ付きタイムアウトを追加する。
• CIでのみ失敗する場合、並行性、コールドスタート、CPU飢餓、環境差異を確認する。

する / 避ける

• テストを独立し決定論的にする

• サードパーティ依存にはネットワークモッキングを使用する

• PR上でスモークE2Eを実行; スケジュール上で完全な回帰を実行する

• デフォルトとして「すべてをE2Eテストする」

• フレークを「修正」するためにアサーションを弱める

• アサーションを弱めるオートヒーリング

実行事前チェック (高ROI)

高コストなE2E実行の前にこの事前チェックを実行して、回避可能な失敗を防止する。

事前チェックリスト

1. リポジトリ構造:

• ワーキングディレクトリと期待されるアプリルートの存在を確認する。
• spec パスを実行前に検証する(rg --files tests/e2e | rg <target>)。

2. ポート/プロセス衛生:

• 実行前にスティール状態開発サーバーポートを確認およびクリアする(例: lsof -i :3001)。
• 並列ローカルサーバーがPlaywright webServer と衝突するのを避ける。

3. コマンド妥当性:

• バッチ実行前に現在のツールバージョンのCLIフラグを検証する。
• トリアージ中は広いグロブよりも正確なspec パスまたは --grep を優先する。

4. アーティファクト期待値:

• 読む前に結果アーティファクトパスが存在することを確認する(test -f <error-context.md>)。
• アーティファクトパスが見つからない場合は、最新の test-results インデックスを最初に検査する。

必須サンドボックス/ポート決定

サンドボックス化されたターミナル、CIコンテナ、共有開発ホストなど制約された環境でPlaywrightを実行する前に、以下を決定し文書化する:

• ホスト/ポートのバインド: アプリサーバーが 127.0.0.1 または 0.0.0.0 を使用する必要があるかを確認し、選択されたポートが空いていることを検証する。
• エスカレーションパス: バインド試行が EPERM/EACCES で失敗した場合、リトライループの代わりに直ちにエスカレーションする。
• 長フロータイムアウト予算: グローバルタイムアウトを増加させるのではなく、API負荷の高いフロー(生成/チェックアウト/レポート)に対して明示的なテストごとのタイムアウトを設定する。
• ビルドロック衛生: リラン前にスティール状態の .next/lock をクリアし、スティール状態のビルド/開発PIDを終了する。

トリアージシーケンス (最速シグナル)

1. --workers=1 で失敗した単一テストを再現する。
2. その単一失敗のtrace/video/screenshotをキャプチャする。
3. 決定論的根本原因を修正する。
4. 的を絞ったスイートを再実行する。
5. その後のみ広い回帰を実行する。

製品バグではなく環境として扱うべき失敗パターン

• Playwright Webサーバーポートの EADDRINUSE
• スティール状態の想定からのmissingspec/結果パス
• ブラケット付きルートセグメントのシェルglob展開失敗

リソース

リソース	目的
references/playwright-mcp.md	MCP & AIテスト
references/playwright-patterns.md	高度なパターン
references/playwright-ci.md	CI設定
references/playwright-authentication.md	認証パターンとセッション管理
references/visual-regression-testing.md	ビジュアルリグレッション戦略
references/api-testing-playwright.md	APIRequestContextでのAPIテスト
references/playwright-preflight-sandbox.md	サンドボックス/ポート事前チェックとエスカレーション決定
data/sources.json	ドキュメントリンク

テンプレート

テンプレート	目的
assets/template-playwright-e2e-review-checklist.md	E2eレビューチェックリスト
assets/template-playwright-fail-on-flaky-reporter.js	リラン成功フレークでCIを失敗させる
assets/template-playwright-preflight-checklist.md	ポート/サンドボックス/タイムアウトの事前チェックリスト

関連スキル

スキル	目的
qa-testing-strategy	全体的なテスト戦略
software-frontend	フロントエンド開発
ops-devops-platform	CI/CD統合

ファクトチェック

• 最終回答の前に、ウェブ検索/ウェブフェッチを使用して現在の外部ファクト、バージョン、価格、期限、規制、またはプラットフォーム動作を検証する。
• プライマリソースを優先; 揮発性情報のソースリンクと日付を報告する。
• ウェブアクセスが利用不可の場合、制限を述べ、ガイダンスを未検証とマークする。