playwright-skill-v2

Playwright スキル v2

playwright-cli（Microsoft 公式の Playwright CLI）を使ったブラウザー自動化です。デーモンの管理は不要です。ブラウザーは自動的に起動および終了します。

---

1. セッションの起動と分離

必ず bin/open から開始してください（playwright-cli open を直接実行しないでください）。

bin/open --headed
playwright-cli goto <url>

bin/open は現在のディレクトリからセッション名を取得し（例：my-project）、Claude Code で実行中の場合は短いエージェント識別子を追加して、その名前のセッションでブラウザーを起動します。ほかのすべての bin/ スクリプトはセッションを自動的に解決します。

セッションの分離： CLAUDE_SESSION_ID が設定されている場合（Claude Code では自動的に設定されます）、各エージェントには独自のセッション名（例：my-project-a1b2c3d4）とセッションファイルが割り当てられます。並行して動作するエージェント同士が干渉することはありません。このエージェントのセッションがすでに開いている場合、bin/open は孤立した Chrome プロセスを防ぐためにそのセッションを先に閉じます。他のエージェントのセッションには影響しません。

新しいセッションを開く前に、 すでにセッションがあるか確認してください。

playwright-cli list    # see all open sessions

自分のセッションが一覧にあり、開いている場合は、bin/open をスキップしてそのまま使用してください。

タスクの最後に、次のコマンドでクリーンアップします。

bin/close

これにより、ブラウザーが閉じられ、セッション追跡ファイルが削除されます。ブラウザーが応答しない場合は、代わりに playwright-cli kill-all を使用してください。

セッション名の上書き：

bin/open --headed --session my-custom-name

---

2. スナップショットの読み取り

すべての コマンドの実行後、標準出力には現在のアクセシビリティツリーへのリンクが表示されます。

### Snapshot
- [Snapshot](.playwright-cli/page-<timestamp>.yml)

ページの内容を確認するため、必ずスナップショットファイルを読んでください。

Read .playwright-cli/page-<timestamp>.yml

スナップショットには、クリック、入力、ホバーに使う [ref=eN] 識別子付きのすべての操作可能な要素が含まれています。

---

3. 基本コマンド

ナビゲーション

playwright-cli goto <url>          # navigate to URL
playwright-cli go-back             # browser back
playwright-cli go-forward          # browser forward
playwright-cli reload              # reload page

ナビゲーションの安全性： プロジェクトの baseUrl（skill/worktrees.json で定義）およびそのサブパスに一致する URL にのみ移動してください。ユーザーから明示的に要求されない限り、外部ドメインや不明なドメインには移動しないでください。これにより、Cookie や認証トークンがサードパーティーのサイトに誤って漏えいするのを防ぎます。

要素の操作（スナップショットの ref を使用）

playwright-cli click <ref>         # click element
playwright-cli fill <ref> <value>  # fill input (clears first)
playwright-cli type <text>         # type text (appends)
playwright-cli press <key>         # press key: Enter, Tab, Escape, Control+A
playwright-cli hover <ref>         # hover to reveal menus/tooltips
playwright-cli select <ref> <val>  # select dropdown option

表示の確認

playwright-cli snapshot            # capture accessibility tree
playwright-cli screenshot          # take screenshot

ダイアログ

playwright-cli dialog-accept       # accept alert/confirm/prompt
playwright-cli dialog-dismiss      # dismiss dialog

セッション管理

bin/close                          # close browser session + clean up session file (preferred)
playwright-cli kill-all            # force-kill all playwright-cli daemons (use when stuck)
playwright-cli list                # list all open sessions

代替手段

playwright-cli run-code '<async page => { }>'   # run arbitrary Playwright JS

---

4. CSS セレクターによる代替手段

ARIA-ref コマンドが失敗する場合に使用してください。たとえば、フレームワークによって描画された要素がメインの ARIA ツリーの外にある場合などです。

モーダルダイアログ — DOM ポータルとして描画されることがよくあります。

bin/click-css "[data-modal-confirm]"
bin/click-css "button[data-dismiss]"

非表示のファイル入力 — アクセシビリティツリーに表示されないことがよくあります。

bin/upload "input[type=file]" /path/to/file.pdf

フレームワークのイベントターゲット — ARIA-ref によるクリックでは、フレームワークのイベントハンドラーが常に実行されるとは限りません。

bin/fill-css "[data-field=email]" "[email protected]"
bin/click-css "[data-action=save]"

プロジェクト固有のセレクターパターンについては、skill/CONFIG.md を参照してください。

---

5. 認証プロファイル

認証プロファイル名とベース URL は skill/worktrees.json で定義されています（gitignore 対象）。 セットアップ手順については、skill/CONFIG.md を参照してください。

認証後に保存する：

bin/auth-save <profile-name>          # profile names from skill/worktrees.json

新しいセッションで復元する：

bin/open --headed
playwright-cli goto <baseUrl>          # baseUrl from skill/worktrees.json
bin/auth-load <profile-name>
playwright-cli goto <baseUrl>/dashboard

プロファイルは .playwright-skill/auth/ に保存され、gitignore 対象です。

---

6. 復旧

問題	解決方法
ブラウザーが応答しない／デーモンがハングしている	playwright-cli kill-all を実行してから bin/open --headed
セッションが開いていない（bin/context エラー）	bin/open --headed
認証の有効期限切れ	bin/auth-load <profile> を実行してから再読み込み
要素の ref が見つからない	playwright-cli snapshot を実行してから、新しいスナップショットファイルを読む
Filament のモーダルがクリックできない	CSS セレクターを指定して bin/click-css を使用
タスク終了時のクリーンアップ	bin/close

---

7. run-code の例

# Wait for a specific element
playwright-cli run-code 'await page.waitForSelector(".loading-complete")'

# Dispatch a Livewire event
playwright-cli run-code 'await page.evaluate(() => window.Livewire.dispatch("refresh"))'

# Scroll to bottom
playwright-cli run-code 'await page.evaluate(() => window.scrollTo(0, document.body.scrollHeight))'

# Get element count
playwright-cli run-code 'console.log(await page.locator("table tbody tr").count())'

---

8. コンテキスト取得と QA ワークフロー

3 つのツールが ResponseBuilder と CacheStore を v2 スキルに統合し、ページの詳細な診断を可能にします。

ツール

コマンド	説明
bin/context [--screenshot]	ページ全体のコンテキストを取得 → コンパクトな TrimmedResponse JSON を標準出力に表示
bin/inject-capture	ブラウザー側にコンソールおよび fetch/XHR のパッチを適用
bin/cache-query <cmd> [args]	ID と種類を指定してキャッシュ済みデータを検索

bin/context

3 つのソースからコンテキストを収集し、.playwright-skill/cache/ に保存します：

1. playwright-cli snapshot — アクセシビリティツリー（YAML）
2. playwright-cli console / playwright-cli network — ブラウザーのネイティブログ
3. playwright-cli run-code — ページ URL、タイトル、HTML、Cookie、注入されたキャプチャ

約 200 トークンの TrimmedResponse を出力します。内容は以下のとおりです：

• pageState — URL、タイトル、認証状態、エラーフラグ
• cacheRef.id — 後で完全なコンテキストを取得するための参照 ID
• cacheRef.available — 利用可能なデータ型の一覧

bin/context             # text/ARIA capture only
bin/context --screenshot  # also capture PNG screenshot

bin/inject-capture

ブラウザー内の console.*、window.fetch、XMLHttpRequest にパッチを適用し、イベントを window.__capturedConsole と window.__capturedRequests にキャプチャします。これらは bin/context によって Playwright レイヤーのキャプチャと統合されます。

冪等です。複数回実行しても安全です。注入後に発生したイベントのみをキャプチャします。

bin/inject-capture
# → {"success":true,"hasCapture":true}

bin/cache-query

bin/context によって保存された完全なコンテキストを取得します。

bin/cache-query query <id> snapshot    # accessibility tree YAML
bin/cache-query query <id> html        # full page HTML
bin/cache-query query <id> console     # console messages JSON
bin/cache-query query <id> network     # network requests JSON
bin/cache-query query <id> screenshot  # base64-encoded PNG
bin/cache-query list                   # JSON array of all cached entries
bin/cache-query stats                  # entry count, total size, max entries
bin/cache-query clear                  # clear all entries
bin/cache-query clear <id>             # clear one entry

典型的な QA ワークフロー

# 1. Start browser and navigate
bin/open --headed
playwright-cli goto http://localhost:8000
bin/auth-load <profile>

# 2. Inject browser-side capture (optional but recommended)
bin/inject-capture

# 3. Perform actions (click, fill, navigate...)
playwright-cli click e5
playwright-cli fill e7 "search term"
playwright-cli press Enter

# 4. Capture full context
bin/context --screenshot
# Read cacheRef.id from the TrimmedResponse output

# 5. Diagnose issues
bin/cache-query query <id> console     # check for JS errors
bin/cache-query query <id> network     # check API responses
bin/cache-query query <id> snapshot    # review page structure
bin/cache-query query <id> screenshot  # view page visually (base64 PNG)

# 6. Clean up
bin/close

複数プロジェクト／並列エージェントに関する注意： Claude Code で実行すると、各エージェントには CLAUDE_SESSION_ID を介して分離されたセッションが自動的に割り当てられます。開いているセッションが 1 つだけの場合は、playwright-cli コマンド（goto、click、fill など）をそのまま実行できます。複数のセッションが有効な場合は、先頭に -s=<session> を付けます。例：playwright-cli -s=my-project-a1b2c3d4 goto <url>。セッション名は bin/open の実行時に表示されます。

コンソールエラーの確認

bin/cache-query query <id> console | python3 -c "
import sys, json
msgs = json.load(sys.stdin)
errors = [m for m in msgs if m['type'] == 'error']
for e in errors:
    print(e['text'])
"