recording-browser-flow-as-test

ブラウザの操作フローを Playwright テストとして記録する

レコーダーとしてbrowser MCP を使用します。ナビゲーション、クリック、入力、キー入力のたびに、スクリプトに行が追加されます。その後、エージェントがそのトレースを、リポジトリ内の Playwright テストファイル（または既存の spec に貼り付けるコードスニペット）に変換します。

これは browser_snapshot（refs + roles + names）と構造化されたアクションを組み合わせているため、Cursor ネイティブです。別のレコーダー拡張機能は使用しません。

前提条件

• 対象アプリにアクセスできること（例：開発サーバーが起動している）。必要に応じて finding-dev-server-url を使用します。
• リポジトリに Playwright（@playwright/test）がインストール済みであるか、インストールする予定があること。未インストールの場合は、adding-e2e-tests またはプロジェクト標準のセットアップで追加します。

記録ワークフロー

1. フローを定義する

範囲を一文で示します。例：「ログインして、設定を開き、ダークモードを切り替えて保存する。」

2. 各ステップを順番に実行する

1. browser_snapshot — アクセシビリティツリーと要素の refs を取得します。

2. 最小限の操作を選びます。

   • browser_click は snapshot の ref を使います（必要な場合を除き、座標クリックは使いません）。
   • 入力には browser_fill または browser_type を使います。
   • セレクトには browser_select_option を使います。
   • URL 全体を変更する場合は browser_navigate を使います。

3. ステップを記録し、メインエージェントが管理する構造化リストに追加します。

   • ステップ番号
   • アクションの動詞（navigate、click、fill、press、select）
   • Playwright のロケーター戦略 — 以下を優先します。
     • getByRole('button', { name: '...' })
     • getByLabel('...')
     • getByPlaceholder('...')
     • アプリでテスト ID を使用している場合は getByTestId('...')
   • 値（入力の場合）、URL（ナビゲーションの場合）
   • 任意：短いアサーション（「URL に /settings が含まれることを確認する」など）

4. DOM を変更する操作やナビゲーションの後は、次の操作の前に新しい browser_snapshot を取得します。

5. フローで非同期コンテンツの読み込みを待つ必要がある場合は、browser_wait_for または cursor-ide-browser のガイダンスに従った短い段階的な待機を使用し、その後もう一度 snapshot を取得します。

3. アサーションを追加する

最終 snapshot と URL をもとに、少なくとも以下を追加します。

• expect(page).toHaveURL(...) または URL フラグメントの確認
• テキスト、ロール、テスト ID のいずれかによる表示されている結果の確認

4. Playwright の出力を生成する

例として tests/recorded/<flow-name>.spec.ts のようなテストファイルを出力します。ファイルには以下を含めます。

• test.describe および test('...', async ({ page }) => { ... })
• await page.goto(...)、await page.getByRole(...).click() などのステップ
• 最終ファイルに snapshot の refs は含めません。これらはセッション固有のものです。

5. 実行して安定性を高める

npx playwright test tests/recorded/<flow-name>.spec.ts

不安定さを修正します。クリック前に expect(locator).toBeVisible() を優先し、非同期リストには toPass() の再試行を使い、最後の手段を除いて任意の waitForTimeout は避けます。

ヒント

• 安定したセレクター：ロールとアクセシブル名は、devtools の CSS よりも優先されます。名前が曖昧な場合は、アプリのコードに data-testid を追加します。
• 認証：フローでログインが必要な場合は、テスト用認証情報に環境変数を使用するか、Playwright の storageState を使います。シークレットは決してコミットしないでください。
• 並列実行：テストデータがほかのテストと競合しないようにします。

使用しないケース

• 手動の 2FA、CAPTCHA、またはメールリンクが必要なフローでは使用しないでください。そこで停止し、テスト用のバイパス手段またはモックをユーザーに依頼します。