playwright-pro

Playwright Pro

AI コーディングエージェント向けの、本番環境対応 Playwright テストツールキットです。

利用可能なコマンド

Claude Code プラグインとしてインストールすると、以下の /pw: コマンドを利用できます。

コマンド	機能
/pw:pw-init	Playwright をセットアップします。フレームワークを検出し、設定、CI、最初のテストを生成します
/pw:generate <spec>	ユーザーストーリー、URL、またはコンポーネントからテストを生成します
/pw:pw-review	テストのアンチパターンとカバレッジの不足を確認します
/pw:fix <test>	失敗するテストや不安定なテストを診断して修正します
/pw:migrate	Cypress または Selenium から Playwright に移行します
/pw:coverage	テスト済みの項目と不足している項目を分析します
/pw:testrail	TestRail と同期します。テストケースを読み込み、結果を送信します
/pw:browserstack	BrowserStack で実行し、クロスブラウザーのレポートを取得します
/pw:report	お好みの形式でテストレポートを生成します

クイックスタートのワークフロー

多くのプロジェクトで推奨される手順です。

1. /pw:pw-init          → scaffolds config, CI pipeline, and a first smoke test
2. /pw:generate      → generates tests from your spec or URL
3. /pw:pw-review        → validates quality and flags anti-patterns      ← always run after generate
4. /pw:fix <test>    → diagnoses and repairs any failing/flaky tests  ← run when CI turns red

検証チェックポイント：

• /pw:generate の後 — コミットする前に必ず /pw:pw-review を実行してください。ロケーターのアンチパターンやアサーションの不足を自動的に検出します。
• /pw:fix の後 — 修正によってリグレッションが発生していないことを確認するため、ローカルでテストスイート全体（npx playwright test）を再実行してください。
• /pw:migrate の後 — Cypress／Selenium のテストを廃止する前に、/pw:coverage を実行して旧テストスイートと同等のカバレッジがあることを確認してください。

例：生成 → レビュー → 修正

# 1. Generate tests from a user story
/pw:generate "As a user I can log in with email and password"

# Generated: tests/auth/login.spec.ts
# → Playwright Pro creates the file using the auth template.

# 2. Review the generated tests
/pw:pw-review tests/auth/login.spec.ts

# → Flags: one test used page.locator('input[type=password]') — suggests getByLabel('Password')
# → Fix applied automatically.

# 3. Run locally to confirm
npx playwright test tests/auth/login.spec.ts --headed

# 4. If a test is flaky in CI, diagnose it
/pw:fix tests/auth/login.spec.ts
# → Identifies missing web-first assertion; replaces waitForTimeout(2000) with expect(locator).toBeVisible()

基本ルール

1. CSS／XPath より getByRole() を優先します。マークアップの変更に強くなります。
2. page.waitForTimeout() は使わず、ウェブファーストのアサーションを使います。
3. expect(locator) は自動で再試行しますが、expect(await locator.textContent()) は再試行しません。
4. すべてのテストを分離し、テスト間で状態を共有しません。
5. 設定で baseURL を指定し、URL のハードコードをなくします。
6. リトライ回数は CI では 2、ローカルでは 0 にします。
7. トレースは 'on-first-retry' に設定し、速度を落とさず詳細なデバッグ情報を取得します。
8. グローバル変数よりフィクスチャを使い、共有状態には test.extend() を使います。
9. 1 つのテストにつき 1 つの動作を検証します。関連する複数のアサーションは問題ありません。
10. 外部サービスのみをモックし、自分のアプリはモックしません。

ロケーターの優先順位

1. getByRole()        — buttons, links, headings, form elements
2. getByLabel()       — form fields with labels
3. getByText()        — non-interactive text
4. getByPlaceholder() — inputs with placeholder
5. getByTestId()      — when no semantic option exists
6. page.locator()     — CSS/XPath as last resort

内容

• 9 個のスキル：詳細な手順を解説
• 3 個の専門エージェント：test-architect、test-debugger、migration-planner
• 55 個のテストテンプレート：認証、CRUD、チェックアウト、検索、フォーム、ダッシュボード、設定、オンボーディング、通知、API、アクセシビリティ
• 2 個の MCP サーバー（TypeScript）：TestRail と BrowserStack の連携（任意。自動登録されません。「連携の設定」を参照してください）
• スマートフック：テスト品質を自動検証し、Playwright プロジェクトを自動検出
• 6 個のリファレンスドキュメント：基本ルール、ロケーター、アサーション、フィクスチャ、落とし穴、不安定なテスト
• 移行ガイド：Cypress と Selenium の対応表

連携の設定

自動登録されません（issue #978）。 TestRail と BrowserStack の MCP サーバーは、プラグインの .mcp.json で宣言されなくなりました（同梱の node_modules がなく、すべてのユーザーで接続に失敗していたためです）。以下の環境変数をエクスポートするだけでは不十分です。サーバーを手動で有効にする（cd integrations/<name>-mcp && npm install を実行し、自分のユーザー／プロジェクトの MCP 設定に登録する）まで、/pw:testrail／/pw:browserstack は「tool not found」エラーで失敗します。CLAUDE.md → Integrations を参照してください。

TestRail（任意）

export TESTRAIL_URL="https://your-instance.testrail.io"
export TESTRAIL_USER="[email protected]"
export TESTRAIL_API_KEY="your-api-key"

BrowserStack（任意）

export BROWSERSTACK_USERNAME="your-username"
export BROWSERSTACK_ACCESS_KEY="your-access-key"

クイックリファレンス

reference/ ディレクトリを参照してください。

• golden-rules.md — 絶対に守るべき 10 のルール
• locators.md — チートシート付きのロケーター優先順位の全解説
• assertions.md — ウェブファーストのアサーションのリファレンス
• fixtures.md — カスタムフィクスチャと storageState のパターン
• common-pitfalls.md — よくある間違いトップ 10 と修正方法
• flaky-tests.md — 診断コマンドとすぐに使える修正方法

テンプレートの一覧は templates/README.md を参照してください。