playwriter

playwriter

Playwriter は、起動中のブラウザーを操作するブラウザー自動化スキルです。新しく使い捨てのブラウザーを起動するのではなく、ユーザーが実際のワークフローですでに使用している Chrome/Chromium にエージェントを接続します。そのため、認証が必要なフロー、拡張機能に依存するページ、長時間にわたるタブのコンテキストに役立ちますが、新しいセッションを使うブラウザーツールより再現性は低くなります。

このスキルを使う場面

次のいずれかが必要なタスクでは、playwriter を使います。

• ユーザーがすでに開いているブラウザー
• 既存のログイン状態、Cookie、信頼済みデバイスの状態
• 拡張機能に依存するワークフロー
• 手動でのログイン引き継ぎが現実的な、パスキー／SSO／MFA を多用するフロー
• 人間とエージェントが同じブラウザーを共有する、ライブタブの継続性
• 起動中のブラウザーを使った、Claude／Codex／Gemini 向けの MCP ベースのブラウザー操作

次の用途では、デフォルトで playwriter を使わないでください。

• CI のように繰り返し実行するブラウザーチェック
• ユーザーの実際のブラウザープロファイルに触れずに行うべき、新しいセッションでの検証
• browser-harness で対応できる、単純なスクレイピングや再現性の高いフォームチェック
• 最も強い分離、またはユーザーの状態への依存が最も少ないことが必要なタスク

簡単な選択ルール

タスクに必要なもの...	使用するもの
ユーザーがすでに開いているブラウザー	playwriter
既存のログイン状態／Cookie／拡張機能	playwriter
クリーンで再現可能な使い捨てセッション	browser-harness
ヘッドレス検証／スクリーンショットの差分／分離されたチェック	browser-harness
ホスト型またはクラウドブラウザーのインフラストラクチャ	プロバイダー固有またはクラウドブラウザーのスキル

手順

Step 1：適切なブラウザーランタイムを選ぶ

起動中のブラウザーを再利用する必要がある場合に限り、playwriter を使います。タスクが実際にはクリーンな使い捨てブラウザーや、CI のような再現性を必要とする場合は、代わりに browser-harness を使います。

Step 2：基本のワークフローに従う

常に同じ手順に従います。

1. 起動中のブラウザーとのブリッジを準備する
2. セッションを作成または選択する
3. snapshot({ page }) でまず状態を確認する
4. 一度操作する
5. 次の操作の前にもう一度状態を確認する

Step 1：拡張機能と CLI をインストールする

# install the CLI
npm install -g playwriter
# or use it without global install
npx playwriter@latest --help

Playwriter Chrome 拡張機能をインストールし、操作したいタブで拡張機能アイコンをクリックします。自動化が利用可能だと判断する前に、タブに接続済み／緑色の状態が表示されていることを確認してください。

Step 2：ブラウザーサポートを開始してセッションを作成する

「拡張機能がすべてを自動で起動する」という曖昧な想定ではなく、上流のブラウザー／セッションの手順に従います。

# start the managed browser/runtime if needed
playwriter browser start

# create a stateful sandbox session
playwriter session new

# inspect current sessions
playwriter session list

注意事項：

• playwriter browser start を実行すると、Playwriter 拡張機能を利用できる状態で Chrome for Testing／Chromium を起動できます。
• playwriter session new はステートフルなサンドボックスを作成し、セッション ID を返します。
• ブラウザーのタブは共有されますが、セッション状態は分離されています。

Step 3：確認 → 操作 → 確認

# navigate
playwriter -s 1 -e 'await page.goto("https://example.com")'

# observe current page state
playwriter -s 1 -e 'console.log(await snapshot({ page }))'

# act using a fresh aria-ref from the snapshot
playwriter -s 1 -e 'await page.locator("aria-ref=e5").click()'

# observe again after the action
playwriter -s 1 -e 'console.log(await snapshot({ page }))'

ルール：

• ページ遷移や大幅な DOM の変更後は、古い aria-ref 値を使い続けないでください。
• テキスト構造で十分な場合は、スクリーンショットより snapshot({ page }) を優先してください。
• 視覚的な証拠が重要な場合に限り、スクリーンショットや録画を使ってください。

有用なコマンドパターン

ナビゲーションと状態

playwriter browser start
playwriter session new
playwriter session list
playwriter session reset 1
playwriter session delete 1

セッション内で Playwright コードを実行する

# basic navigation
playwriter -s 1 -e 'await page.goto("https://github.com")'

# fill + submit
playwriter -s 1 -e 'await page.fill("#search", "playwriter"); await page.keyboard.press("Enter")'

# save reusable state between calls
playwriter -s 1 -e 'state.lastUrl = page.url(); state.heading = await page.textContent("h1")'
playwriter -s 1 -e 'console.log(state.lastUrl, state.heading)'

複数行のコードを安全に扱う

playwriter -s 1 -e "$(cat <<'EOF'
const title = await page.title();
state.title = title;
console.log(await snapshot({ page }));
EOF
)"

引用符の扱いで JavaScript が不安定になりそうな場合は、ヒアドキュメントを使います。

MCP 連携

モデルクライアントが起動中のブラウザー向けのブラウザーツールを必要とする場合は Playwriter を使います。単に何らかのブラウザーツールが必要な場合は使いません。

MCP 設定の例

{
  "mcpServers": {
    "playwriter": {
      "command": "npx",
      "args": ["-y", "playwriter@latest"]
    }
  }
}

よくある用途：

• Claude／Codex／Gemini は、MCP 経由で Playwriter を呼び出せます。
• MCP はエージェントにトランスポート層を提供します。ブラウザー／セッションの動作は引き続き Playwriter が担います。
• セッションの再利用、ブラウザーの表示状態、タブの使用許可は MCP ではなく Playwriter の役割です。

安全性と想定事項

• playwriter はユーザーの実際のブラウザーセッションにアクセスできるため、特権モードです。
• セッションの再利用が本当に必要な場合に限り、使用してください。
• タブ、拡張機能、人間によって状態が変更される可能性があるため、クリーンで分離されたブラウザーより再現性が低くなることを想定してください。
• この用途では、手動ログイン／MFA／CAPTCHAへの引き継ぎは通常のことです。完全な自律性が保証されるかのように振る舞わないでください。
• 適切にデタッチまたはリセットしてください。ユーザーのブラウザーを終了しても安全だと決めつけないでください。

トラブルシューティング

問題	確認すること
何も応答しない	対象のタブに拡張機能がインストールされ、有効になっていることを確認します
タブ／ページの状態が違う	snapshot({ page }) を再実行し、クリックする前に想定したタブが表示されていることを確認します
セッションが古い／壊れている	playwriter session reset <id>
JavaScript のクォートが原因で失敗する	-e の入力にはヒアドキュメントを使用します
繰り返し可能な分離された自動化が必要	代わりに browser-harness に切り替えます
ブラウザーの状態が複雑すぎる／人間による干渉がある	新しいセッションを開始するか、新しいセッション用のブラウザーツールを使用します

例

例 1：ログイン済みの SaaS ワークフロー

• プロンプト：「すでにログインしている Chrome を使って、再認証せずに Jira のチケットを更新してください。」
• 期待されるスキルの動作：playwriter を選び、実行中のブラウザーを再利用することを伝え、セッションを作成してから、まず状態を確認し、その後に操作します。

例 2：クリーンなブラウザーでの検証

• プロンプト：「CI で再現可能なヘッドレスのチェックアウトテストを実行し、スクリーンショットを比較してください。」
• 期待されるスキルの動作：セッションの再利用よりも分離が重要なため、playwriter ではなく browser-harness または別の新しいセッション用ツールに切り替えます。

例 3：MCP ブラウザーブリッジ

• プロンプト：「Codex または Claude を、すでに開いているブラウザーに接続して、現在のタブと Cookie を使えるようにしてください。」
• 期待されるスキルの動作：playwriter を選び、MCP の設定を説明し、実行中のブラウザーがあることを前提としている点を明示します。

ベストプラクティス

1. 「ブラウザー」という言葉が出てくるからではなく、ブラウザーの状態が重要だから playwriter を選びます。
2. 誤ったタブや古い UI の状態に影響する可能性のある操作を行う前に、snapshot({ page }) で状態を確認します。
3. 意味のある操作を行うたびに、スナップショットを再取得します。ライブブラウザーの状態は、分離された自動化の状態より速く変化します。
4. 複雑な JavaScript にはヒアドキュメントを使用し、シェルのクォートによる不具合を防ぎます。
5. この用途では、手動ログイン／MFA／CAPTCHAへの引き継ぎは通常のこととして扱います。
6. 実行中のブラウザーが必要だった理由と、新しいセッション用ツールのほうが安全だった状況を報告します。

参考資料

このスキルの詳細ドキュメント：

• modes-and-routing
• session-workflow
• mcp-integration

主な参照元：

• https://raw.githubusercontent.com/remorses/playwriter/main/README.md
• https://playwright.dev/docs/auth
• https://playwright.dev/docs/api/class-browsertype#browser-type-connect-over-cdp
• https://modelcontextprotocol.io/introduction

出力に関する想定事項

このスキルを使用する場合、次の内容を報告します：

• 新しいセッション用ブラウザーツールではなく playwriter を選んだ理由
• セッション／ランタイムに関する前提
• 実行した主な操作
• 取得した証拠（snapshot、スクリーンショット、録画、ログ）
• 発生した手動引き継ぎや認証関連の制約