browser-max-automation

name: browser-max-automation description: Browser automation using Playwright MCP, CDP, and direct WebSocket CDP for web testing, UI verification, and form automation. Use when navigating websites, clicking elements, filling forms, taking screenshots, testing web applications, reusing an existing browser session, or troubleshooting CDP / iframe / modal / file chooser / passkey (WebAuthn) issues. argument-hint: "自動化したい URL、操作内容、使いたいモード" user-invocable: true license: CC BY-NC-SA 4.0 metadata: author: yamapan (https://github.com/aktsmm)

Browser Max Automation

Browser automation via Playwright MCP, existing-browser CDP, and direct CDP helpers.

When to Use

• ブラウザ自動化、UI 確認、フォーム操作、スクリーンショット取得
• MCP で手順を確立してから Python で一括実行したいとき
• 既存ブラウザのログイン状態を CDP 経由で使いたいとき
• Playwright MCP / connect_over_cdp() が不安定で、raw CDP WebSocket に切り替えたいとき
• モーダルや file chooser など、通常クリックが壊れやすい UI を扱うとき

Not the Best Fit

• API / CLI を先に検討: 公式 API（YouTube Data API、Microsoft Graph、GitHub API 等）や CLI で read/write が完結するならそちらを優先し、UI が脆い兆候（native file chooser / shadow DOM / 多段ウィザード / レンダラーを止める modal）で固執せず切り替える（例: YouTube Studio UI → captions.insert）
• API / CLI だけで完結するなら、該当 domain skill / script を使う
• PowerPoint / Loop / Dynamics 365 の expense entry 画面など専用 skill がある UI は、該当 skill の操作ルールを優先する
• 認証情報、秘密情報、MFA 応答をチャットで受け取らない。必要な入力はブラウザ上でユーザーに処理してもらう
• 例外: 対象サイトが passkey / FIDO2 / WebAuthn 対応なら、CDP 仮想認証機で完全無人化できる。優先順位は passkey (仮想認証機) > メール OTP > SMS > 物理キー / 生体。詳細は references/instructions/webauthn-virtual-authenticator.md を参照する

Choose Mode First

既存ブラウザ CDP の起動、profile 確認、port drift、認証 URL encode は references/instructions/cdp-existing-browser.md を参照する。 直接 WebSocket CDP の起動フラグ、websocket-client 接続、SPA hash navigation、virtual scroll 操作は references/instructions/cdp-direct-websocket.instructions.md を参照する。

Quick Reference

Core Loop

1. browser_navigate(url)
2. browser_snapshot で ref を取る
3. browser_click / browser_type で操作する
4. browser_snapshot or screenshot で結果確認する

UI verification では、操作前に期待する state と確認方法を決める。成功 toast やボタン押下だけを成功判定にせず、DOM、URL、永続化された一覧行、API の read 結果、または screenshot / trace などの証跡で確認する。

API と DOM の状態が一時的にずれるケースがある。API が stale / capture failure を返しても、画面上の cell / row の aria-label や status text が進展した状態を示しているなら DOM も正本候補として扱う。API 単独で「未完了」と断定しない。

Decision Patterns

MCP で続けるか、CLI に切り替えるか

• MCP: 1 件ずつ画面を見ながら UI フロー、セレクタ、待機時間を確立する
• Python CLI: 手順が固まった後に N 件一括処理する

切り替え基準は単純で、操作手順をまだ探っているなら MCP、手順が固まったら CLI。

snapshot で取れない要素をどう扱うか

• browser_snapshot で ref が取れるなら通常操作する
• 画面には見えるのに ref が取れないなら browser_evaluate で DOM 直接操作する
• 画面にも見えていないなら、待機かページ再読込を優先する

snapshot で ref 取得
  ├─ 取れた → click / type
  └─ 取れない → screenshot で可視確認
      ├─ 見えている → evaluate で直接操作
      └─ 見えていない → wait / reload

read-only データ抽出を高速化する

一覧表、残高、ステータス確認など、読み取りだけ の fallback では、巨大な browser_snapshot を何度も解析しない。手順が分かっている画面は browser_evaluate で DOM から必要な行だけを JSON 化して返す。

• ページ到達やログイン状態の判定: browser_snapshot で証跡を残す
• 表・明細・残高などの定型抽出: browser_evaluate で document.querySelectorAll("tr") や document.body.innerText を処理して JSON を返す
• 不可逆操作の直前・直後: snapshot または screenshot を残す

unsaved editor / draft タブを壊さない

未保存 form を持つ editor / SPA タブに別 URL を踏ませると beforeunload dialog で upload や遷移が崩れる。既存タブは再利用し、新規作業は別タブで開く。dialog.accept() / page.reload() / API トリガー目的の reload で dirty を踏み越さない。詳細と Qiita / CMS 例は references/instructions/unsaved-form-tabs.md を参照する。

Azure Portal iframe / OOPIF / trusted event の注意は references/instructions/azure-portal.md を参照する。 Angular Material / mat-select / cdk-overlay / disabled save の注意は references/instructions/angular-material.md を参照する。

iframe と force click

• iframe が多段なら contentFrame() を順に辿る
• SVG オーバーレイなどで塞がれているだけなら force: true を検討する
• ただし force: true は最後の手段で、まず要素の実在確認と可視確認を優先する

file chooser が残ったとき

• browser_file_upload(paths=[]) で空送信して閉じる
• ダメなら別ページへ移動する
• CDP 競合が疑わしいなら Python プロセスや MCP 接続を整理する

hidden file input、evaluate + fetch、API write の UI fallback は references/instructions/ui-fallbacks.md を参照する。

Safety Rules

CDP 排他制御

MCP Playwright と Python スクリプトは 同じ CDP ポートへ同時接続しない。 とくに Python 側も connect_over_cdp() を使う場合、MCP と Playwright セッションが二重になり、ページ操作が競合して「遷移先が想定外」「フォーム送信が効かない」等の不定失敗が起きる。

raw WebSocket を使う場合は、CDP command id で応答をフィルタし、Runtime.enable / Page.enable など必要な domain を先に有効化する。詳細は references/instructions/cdp-direct-websocket.instructions.md を参照する。

CDP recovery、blocking dialog、context/page selection は references/instructions/cdp-recovery-and-context.md を参照する。

破綻しやすい場面

• modal overlay が snapshot に出ない
• file chooser が残って後続操作を塞ぐ
• CDP 二重接続で入力先が混線する
• CDP の別 context/page を使い、未ログイン画面や別アカウントを操作してしまう
• 「見えているがクリックできない」状態を無理に通常 click で押し切る

Subprocess + CDP Stability (Windows)

Windows の PIPE デッドロック、VS Code terminal の SIGINT、JSON status artifact、taskkill tree kill は references/instructions/windows-subprocess-cdp.md を参照する。

Reference Map

Done Criteria

• MCP または CDP 設定が完了している
• 対象ページまで安定して到達できる
• 目的の操作が完了している
• 成功判定を toast だけに頼らず、DOM / URL / API read / screenshot / status artifact のいずれかで確認している
• modal / file chooser / iframe / CDP context のどこで詰まるか説明できる
• 一括処理が必要なら MCP から CLI / API helper へ切り替える判断ができている