| name | playwright-browser |
| description | Playwright MCPでブラウザ操作・DOM調査・UI検証を行う。ブラウザ操作、E2Eテスト、画面確認、UI検証、DOM調査、ネットワーク確認時に使用する。built-inブラウザではなくPlaywright MCPツールを優先する。 |
Playwright MCP ブラウザ操作
スキルメタデータ
- このスキルファイルの配置先:
~/.cursor/skills/playwright-browser/
- 同ディレクトリ構成:
SKILL.md（本ファイル）scripts/intercept-api.js（APIインターセプトスクリプト）
- 付随ファイルを参照する場合は上記パスを基準に解決すること
Why Playwright MCP
Cursorにはbuilt-inブラウザ（cursor-ide-browser）とPlaywright MCP（user-playwright-mcp）の2系統がある。
Playwright MCPの優位点:
- DOM snapshotで安定した要素ref（操作対象の一意識別）
browser_console_messages でJSエラー・警告をキャプチャbrowser_network_requests でAPI呼び出し・失敗リクエストを確認
常にPlaywright MCPを使うこと。built-inブラウザ（cursor-ide-browser）は使わない。
呼び出し方法
全ツールは CallMcpTool で呼び出す:
server: "user-playwright-mcp"
toolName: "browser_*"
arguments: { ... }
注: mcp.json のキー名は playwright-mcp だが、Cursorが user- プレフィックスを付与するため、CallMcpToolでは user-playwright-mcp を指定する。
基本フロー
すべてのブラウザ操作はこの4ステップで進める:
- Navigate -
browser_navigate でURLに移動
- Snapshot -
browser_snapshot でDOM構造と要素refを取得
- Interact - ref を使って
browser_click, browser_type 等で操作
- Assert - snapshot / screenshot / console / network で結果を確認
snapshot が返す ref は操作のたびに変わる。操作前に必ず最新のsnapshotを取ること。
ツールリファレンス
ナビゲーション
| ツール | 用途 | 主要パラメータ |
|---|
browser_navigate | URLに移動 | url |
browser_navigate_back | 前のページに戻る | - |
browser_tabs | タブ一覧/作成/選択/閉じる | action, index |
状態取得
| ツール | 用途 | 主要パラメータ |
|---|
browser_snapshot | DOMのアクセシビリティツリー取得 | filename (optional) |
browser_take_screenshot | スクリーンショット取得 | type, filename, fullPage, ref+element(要素単位) |
browser_console_messages | コンソールログ取得 | level, filename |
browser_network_requests | ネットワークリクエスト一覧 | includeStatic, filename |
操作
| ツール | 用途 | 主要パラメータ |
|---|
browser_click | 要素クリック | ref, element, button(left/right/middle), doubleClick |
browser_type | テキスト入力（追記） | ref, text, submit, slowly(keyハンドラ発火用) |
browser_fill_form | 複数フィールド一括入力 | fields (下記参照) |
browser_select_option | ドロップダウン選択 | ref, values |
browser_hover | ホバー | ref, element |
browser_press_key | キー押下 | key |
browser_drag | ドラッグ&ドロップ | startElement(必須), startRef(必須), endElement(必須), endRef(必須) |
browser_file_upload | ファイルアップロード | paths |
browser_fill_form の fields 型（全フィールド必須）:
[{ "name": "説明", "type": "textbox|checkbox|radio|combobox|slider", "ref": "refN", "value": "値" }]
待機
| ツール | 用途 | 主要パラメータ |
|---|
browser_wait_for | テキスト出現/消失/時間待機 | text, textGone, time |
高度な操作
| ツール | 用途 | 主要パラメータ |
|---|
browser_evaluate | JavaScript実行 | function, ref |
browser_run_code | Playwrightコード実行 | code（page オブジェクトが利用可能。例: await page.evaluate(...), await page.route(...), await page.request.get(url, {headers})) |
browser_handle_dialog | ダイアログ処理 | accept, promptText |
ブラウザ管理
| ツール | 用途 | 主要パラメータ |
|---|
browser_resize | ウィンドウサイズ変更 | width, height |
browser_close | ページを閉じる | - |
browser_install | ブラウザインストール | - |
よくあるパターン
ページ遷移の確認
1. browser_navigate → 対象URL
2. browser_snapshot → ページ構造を確認
3. browser_take_screenshot → 視覚的に確認
フォーム入力
1. browser_snapshot → フォーム要素のrefを取得
2. browser_fill_form → fields: [{ name: "ユーザー名", type: "textbox", ref: "refN", value: "..." }, ...]
または browser_click + browser_type で個別入力
3. browser_click → 送信ボタン
4. browser_wait_for → 遷移/結果表示を待機
5. browser_snapshot → 結果を確認
エラー調査
1. browser_console_messages → JSエラーや警告を確認
2. browser_network_requests → 失敗リクエスト（4xx/5xx）を特定
3. browser_evaluate → DOM状態を直接調査
レスポンスボディの詳細が必要なら「APIレスポンスボディの取得」パターンを参照。
APIレスポンスボディの取得
browser_network_requests はURL/ステータスのみ。レスポンスボディが必要な場合は、fetch/XHRをインターセプトする。APIを直接fetchするのではなく、ブラウザが通常行うリクエストをキャプチャする方式。認証の問題を回避できる。
- scripts/intercept-api.js の内容を読み取る
（パス解決できない場合:
~/.cursor/skills/playwright-browser/scripts/intercept-api.js）
browser_evaluate の function に読み取った内容を渡して実行（操作やページ遷移の前に設置すること）- SPA内でページ遷移（クリック等）を行う — この間のAPIリクエストが自動キャプチャされる
browser_evaluate で return window.__captured を実行し結果を取得
window.__captured → [{ url, status, body }, ...]
スクリプトのデフォルトURLパターン（/api/, /v{N}/, /graphql/）に合わない場合は、対象サイトのAPIパスに合わせてスクリプトの isApiRequest() を調整する。
注意: browser_evaluate で設置したインターセプターはフルページ遷移でクリアされる。SPA内のクライアントサイドルーティングでは維持されるが、ページリロードや別URLへの直接遷移では再設置が必要。
リクエストヘッダーの調査（Playwright Route傍受）
SPAが実際にどのヘッダーを送信しているか調べる場合、browser_run_code でPlaywrightネイティブのルート傍受を使う。browser_evaluate のJSインターセプターと異なり、ページ遷移でクリアされない。
const captured = [];
await page.route('**/api/**', async (route) => {
const request = route.request();
captured.push({
url: request.url(),
headers: request.headers()
});
await route.continue();
});
結果の取得は browser_evaluate で return window.__playwrightCaptured 等に格納するか、browser_run_code の戻り値として返す。
レスポンシブ確認
1. browser_resize → width: 375, height: 812 (モバイル)
2. browser_snapshot + browser_take_screenshot
3. browser_resize → width: 1920, height: 1080 (デスクトップ)
4. browser_snapshot + browser_take_screenshot
注意事項
browser_evaluate 内の fetch() はhttpOnly Cookieに依存する認証では失敗する。 same-originでhttpOnly でないCookie（JWTトークン等）なら動作するが、確実性を求める場合は「APIレスポンスボディの取得」パターンのインターセプト方式を優先する- 複数のエージェント（メイン・サブエージェント）は同じPlaywright MCPプロセスを共有する。ログイン状態・Cookie・表示ページは引き継がれる
browser_type はテキストを追記する。クリア&入力したい場合は browser_fill_form を使うbrowser_handle_dialog はダイアログが表示される前に呼ぶ（先行登録方式）- 操作のたびにrefが無効化されるため、連続操作の間に
browser_snapshot を挟む
- Playwright MCPが起動できない場合（ブラウザ競合等）、
cursor-ide-browser にフォールバックせず、エラーを報告して制御を返すこと
browser_take_screenshot で filename を指定する場合は .playwright-mcp/ プレフィックスを付けること（例: .playwright-mcp/login-result.png）。ワークスペースルートにファイルが散らばるのを防ぐ- ステージング環境固有のフロー（認証等）はプロジェクト固有スキルで管理する
