playwright-pro

Playwright Pro

Playwright による本番環境レベルのエンドツーエンドテストです。ユーザーストーリーからテストを生成し、保守性を高める Page Object パターンを実装し、堅牢なテストを実現する適切なロケーター戦略を適用し、不安定なテストの原因を特定して修正し、Cypress または Selenium から移行し、CI/CD と連携し、ビジュアルリグレッションテストを実行して、アクセシビリティ監査を実施します。E2E テストの失敗の 90％を解消する 10 のゴールデンルールを徹底します。

主な機能

• 堅牢なテスト作成 — getByRole／getByLabel／getByText の優先順位に基づくロケーター、Web ファーストの自動再試行アサーション、10 のゴールデンルール。
• Page Object Model — ロケーターを一元管理し、ユーザーの意図に沿ったメソッドを公開して、HTML／セレクターから POM クラスを生成します。
• テスト生成 — 正常系とエラー系を網羅したユーザーストーリーのテスト仕様を作成します。
• 不安定なテストの原因特定 — トレース分析、ブラウザーを表示した状態での実行／デバッグ実行、競合状態や共有状態の修正を行います。
• 移行 — Cypress／Selenium から Playwright へのコマンド対応表と認証セットアップのパターンを提供します。
• CI 連携 — GitHub Actions、シャーディング、条件付きブラウザーインストール、トレース／スクリーンショットのアーティファクトに対応します。
• ビジュアルリグレッションとアクセシビリティ — toHaveScreenshot のベースラインと Axe WCAG AA ゲートに対応します。

使用する場面

• Web アプリの E2E テストを作成または整理するとき。
• 不安定なテストを修正するときや、CI でのみ発生する失敗の原因を調べるとき。
• Cypress または Selenium のテストスイートを移行するとき。
• ビジュアルリグレッションまたは WCAG アクセシビリティゲートを追加するとき。
• Playwright の CI 連携とレポートをセットアップするとき。

最初に確認すること

テストを生成する前に、以下の入力を確認してください。不明な項目や曖昧な項目があれば、推測せずに質問してください。

• タスク／サブスキル — init、generate、fix-flaky、migrate、review（ワークフロー全体を決定します）
• 対象となるユーザーストーリーまたはフロー — テスト仕様で検証する正常系とエラー系（テスト生成の指針になります）
• ロケーターの利用可否 — アプリでロール／ラベル／data-testid が公開されているか（ロケーター戦略と POM の堅牢性を決定します）
• 移行元のフレームワーク（移行する場合） — Cypress または Selenium（コマンド対応表を選択します）

停止ルール：出力を大きく左右する 2～3 項目だけ質問してください。ユーザーが「そのまま下書きして」と言った場合は、作業を進め、成果物の冒頭に前提を列挙してください。

サブスキル

このスキルでは、複合型のサブスキルアーキテクチャを使用します。skills/ 内の各サブスキルが、特定のワークフローを担当します。

サブスキル	ファイル	目的
Init	skills/init.md	プロジェクトに Playwright を導入します。インストール、設定、最初のテストの作成を行います
Generate	skills/generate.md	ユーザーストーリーまたはページの説明からテストファイルを生成します
Fix	skills/fix.md	トレース分析を使って、失敗または不安定なテストの原因を特定し、修正します
Migrate	skills/migrate.md	Cypress または Selenium から Playwright に移行します
Review	skills/review.md	テスト品質、カバレッジの不足、不安定なテストの兆候を監査します
Report	skills/report.md	Playwright の JSON 出力から実行レポートを生成します
Coverage	skills/coverage.md	テストをユーザーストーリーに対応づけ、カバレッジの不足を特定します
BrowserStack	skills/browserstack.md	クロスブラウザーテストのための BrowserStack クラウド連携
TestRail	skills/testrail.md	テストケース管理のための TestRail 連携

サブスキルのフロー： Init → Generate → Review → Fix（必要な場合）；Coverage → Generate（不足分を補完）；Report → BrowserStack／TestRail。

ツール

ツール	目的	コマンド
test_generator.py	ユーザーストーリーの説明から Playwright のテストコードを生成します	python scripts/test_generator.py --story "..." --page LoginPage --output tests/
flaky_detector.py	複数の CI 実行を分析し、不安定なテストのパターンを検出します	python scripts/flaky_detector.py --results-dir results/ --runs 10 --threshold 0.05
coverage_mapper.py	テストをユーザーフローに対応付け、カバレッジの不足箇所を特定します	python scripts/coverage_mapper.py --tests tests/ --flows flows.json --gaps-only
page_object_generator.py	HTML またはセレクターのリストから Page Object クラスを生成します	python scripts/page_object_generator.py --html page.html --name LoginPage --route /login
test_analyzer.py	テストファイルをスキャンして、アンチパターンや品質上の問題を検出します	python scripts/test_analyzer.py tests/ --severity high
test_report_parser.py	Playwright の JSON レポートを解析して要約を作成します	python scripts/test_report_parser.py report.json --top-slow 10

参考資料

タスクに合った参考資料を読み込んでください。このファイルは簡潔に保ち、必要に応じて詳細を参照します。

• references/core-rules-and-patterns.md — 10 の基本ルール、ロケーターの優先順位、playwright.config.ts、Page Object Model クラス、ユーザーストーリーからのテスト生成、共有認証のセットアップについて説明します。テストを作成するときや、プロジェクトを設定するときに読んでください。
• references/playwright-patterns.md — ロケーター選択の判断ツリー、Web-first と再試行しないアサーションのパターン、カスタム／ワーカーのフィクスチャ、ネットワークのモック、アンチパターンのクイックリファレンス、CI のシャーディングパターンについて説明します。ロケーターの選択、API のモック、フィクスチャの構築時に読んでください。
• references/diagnosis-migration-and-ci.md — 不安定なテストの原因と修正方法、診断コマンド、Cypress から Playwright への移行表、GitHub Actions CI、ビジュアルリグレッション、アクセシビリティテスト、よくある落とし穴、ベストプラクティス、トラブルシューティング表、成功基準について説明します。不安定なテストの修正、移行、CI の設定、テストスイートの監査時に読んでください。

対象範囲と制限事項

このスキルの対象：

• Playwright を使用したエンドツーエンドテストの作成、構成、保守
• Page Object Model アーキテクチャとロケーター戦略のベストプラクティス
• 不安定なテストの診断、CI 統合、トレースに基づくデバッグ
• ビジュアルリグレッションテストと WCAG アクセシビリティ監査

このスキルの対象外：

• 単独でのユニットテストやコンポーネントテスト（テストピラミッドの指針については engineering/testing-strategy を参照）
• API コントラクトテストや負荷／パフォーマンステスト（API に特化したテストについては api-test-suite-builder を参照）
• テストデータ管理、データベースのシード処理、テストフィクスチャのファクトリーパターン
• モバイルネイティブアプリのテスト（Appium、Detox）。このスキルの対象は Web ブラウザーのみです

統合ポイント

スキル	統合	データフロー
ci-cd-pipeline-builder	E2E テストは、ビルドとユニットテストの後にパイプラインのステージとして実行されます	パイプライン設定が playwright test を実行し、失敗時にアーティファクト（トレース、スクリーンショット）をアップロードします
api-test-suite-builder	API テストでバックエンドの契約を検証し、Playwright テストで UI フローをエンドツーエンドで検証します	同じ環境で E2E スイートを実行する前に、API テストの結果でエンドポイントの安定性を確認します
pr-review-expert	PR レビューでは、UI の変更に対するテストカバレッジを確認し、不足している E2E 仕様を指摘します	レビューチェックリストでは Playwright Pro の基本ルールを参照し、waitForTimeout や生の CSS セレクターを指摘します
performance-profiler	パフォーマンス予算と E2E テストを組み合わせて、リグレッションを検出します	プロファイラーが低速なページを特定し、Playwright テストで該当するルートに networkidle 待機やパフォーマンスアサーションを追加します
observability-designer	テストの失敗をオブザーバビリティダッシュボードに取り込み、フレークを追跡します	CI テストの結果を JSON レポートとしてエクスポートし、オブザーバビリティパイプラインで合格／不合格／フレークのメトリクスを継続的に取り込みます
release-manager	E2E スイートをリリースゲートとして使用し、デプロイを進める前にスイートの合格を必須とします	リリースワークフローで Playwright CI ジョブを呼び出し、テストが1つでも失敗するとリリースタグの作成をブロックします