pw-debug-live

ライブ接続による Playwright テストのデバッグ

playwright-cli を使って、一時停止中の実行テストセッションに接続し、Playwright の E2E テストをデバッグします。実行後に凍結されたトレースを調べる pw-debug-test とは異なり、このスキルではライブブラウザーを操作して、実行途中のページを調査できます。

重要： このスキルでは、page.pause() を挿入するために spec ファイルを編集することはありません。CLI に組み込まれている pause-at <file>:<line> を使えば、ソースに手を加えずに同じことができます。spec の Edit を使おうとしていることに気づいたら、そこで止めて、代わりに pause-at を使ってください。

ステップ 0：ユーザーから入力を集める

AskUserQuestion を使って、以下を確認します。

1. テストファイルのパス — リポジトリルートからの相対パス。例：tests/user/article-create.spec.ts。
2. テスト名 — test('...') のタイトル（またはタイトルに含まれる一意のキーワード）。-g <pattern> に使用します。
3. 行番号 — 実行を一時停止する行。選択したテストの本体内である必要があります。
4. 失敗のヒント (任意) — 失敗が疑われる箇所（例：「公開ボタンのクリックがタイムアウトする」）。調査の焦点を絞るのに役立ちます。

ユーザーから確認質問なしで進めるよう求められていても、どのような場合もこのステップを省略しないでください。続行する前に、4 つすべての回答が必要です。

ステップ 1：入力とワークスペースを検証する

何かを起動する前に、以下を確認します。

1. ファイルが存在すること。 テストファイルを Read で読み込みます。存在しない場合は、停止して確認を求めます。
2. 行が正しいテスト内にあること。 行番号が test('<name>', ...) の開始行から閉じ波括弧までの範囲内にあることを確認します。行が指定されたテストの外（たとえば beforeEach、別のテスト、または import ブロック内）にある場合は、ユーザーに警告し、そのまま進めるか別の行を選ぶか尋ねます。
3. ワークスペースがクリーンであること。 npx playwright-cli list を実行します。アクティブな tw-* ブラウザーセッションが報告された場合は、続行する前にユーザーに確認します。これらが接続先を曖昧にする可能性があるためです。クリーンアップのために npx playwright-cli close-all を実行することを提案してください。
4. プロジェクトを特定すること。 playwright.config.ts（または .js / .mts）を読み込みます。projects: で複数の名前付きプロジェクトが定義されている場合は、対象ファイルが属するプロジェクトを（testDir、testMatch、またはパスで）推測し、<proj> として記録します。判断できない場合は、ユーザーに確認します。projects: 配列がない場合は、--project フラグを省略します。

ステップ 2：テストを --debug=cli モードで起動する

テストをバックグラウンドで実行します。

PLAYWRIGHT_HTML_OPEN=never npx playwright test <test-file> -g "<test-name>" --project=<proj> --debug=cli

run_in_background: true を指定して Bash を使います。ハーネスからバックグラウンドタスク ID と、キャプチャした stdout/stderr のパスが返されます。両方を記録してください。以下のステップでは、そのパスを $LOG として参照します。

テスト終了時に HTML レポーターがブラウザータブで停止しないよう、必ず PLAYWRIGHT_HTML_OPEN=never を指定してください。

名前付き projects: 配列がない場合は --project を省略します。スペースを含むテスト名を扱えるよう、テスト名を引用符で囲みます。

ステップ 3：セッション ID を待つ

デバッグ手順のブロックが表示されるまで、ハーネスがキャプチャした出力ファイルをポーリングし、tw-XXXXXX セッション ID を取り出します。プロトコルでは、次の内容がそのまま出力されます。

### The test is currently paused at the start

### Debugging Instructions
- Run "playwright-cli attach tw-79c225" to attach to this test

until によるポーリングと絞り込んだ grep を使い、run_in_background: true を指定した単一の Bash 呼び出しを使います。セッションが開始したらすぐに通知されます。ステップ 2 でハーネスから返された実際のログパスに置き換えてください。

until grep -oE 'tw-[a-z0-9]+' <log-path> >/dev/null 2>&1; do sleep 0.5; done
grep -oE 'tw-[a-z0-9]+' <log-path> | head -1

セッション ID を <session> として記録します。

3a：目的のテストであることを確認する

「Debugging Instructions」ブロックの直前に、ランナーが一時停止しているテストを出力します。例：

[user] › tests/user/article-create.spec.ts:8:7 › Article create › Authenticated user can publish...

これがユーザーから指定されたファイルと一致することを確認します。一致しない場合（多くの場合、auth-setup や別の依存プロジェクトが先に一時停止しています）は、その先へ進みます。

npx playwright-cli attach <session>
npx playwright-cli -s=<session> resume

その後、ステップ 3 に戻り、ログに次の tw-XXXX が表示されるのを待ちます。最初のセッションが目的のものだと決めつけないでください。

ステップ 4：ライブセッションに接続する

npx playwright-cli attach <session>

attach 呼び出しは、初期スナップショットを .playwright-cli/page-*.yml に書き込みます。その後の CLI 呼び出しではすべて -s=<session> を渡す必要があります。暗黙のデフォルト接続先はありません。

ステップ 5：pause-at でブレークポイントを設定する

npx playwright-cli -s=<session> pause-at "<test-file>:<line>"

pause-at は <file>:<line> を直接受け取ります。これは page.pause() の代わりとなるものであり、このスキルがユーザーのソースを編集しない理由でもあります。呼び出しが {} を返した場合、ブレークポイントは設定されています。

ステップ 6：ブレークポイントまで再開する

npx playwright-cli -s=<session> resume

テストは現在の一時停止位置（テストの開始位置）から、設定した行まで全速力で実行され、その後停止します。ブラウザーは、その行が実行される直前のテストとまったく同じ状態になっています。

resume が Session closed を返した場合、テストはブレークポイントに到達する前に完了しています。その行には現在の状態から到達できません（たとえば、テストが通らなかった if 分岐の後や、例外が発生した await の後にある場合など）。行を再確認して、もう一度実行してください。

ステップ 7：調査する

エージェントは、ユーザーのヒントとスナップショットで明らかになった内容に基づいて、cli のインターフェースからツールを選びます。解析可能な出力を得るため、必ず -s=<session> と --json を渡してください。

目的	コマンド
ページの要素を一覧表示する（参照 ID は e1、e2、…）	npx playwright-cli -s=<session> snapshot --json
候補のロケーターを試す	npx playwright-cli -s=<session> generate-locator <ref> --json
プロパティ／属性を読み取る	npx playwright-cli -s=<session> eval "el => el.getAttribute('disabled')" <ref> --json
ページレベルの状態を読み取る	npx playwright-cli -s=<session> eval "location.href" --json
コンソール出力を確認する	npx playwright-cli -s=<session> console --json
ネットワークを調べる	npx playwright-cli -s=<session> requests --json の後に request <n> --json
一度に 1 つのアクションを実行する	npx playwright-cli -s=<session> step-over
実行中のテストに対して Playwright TS スニペットを実行する	npx playwright-cli -s=<session> run-code "await page.getByRole('button', { name: 'Publish' }).click()"

一般的な診断の流れ：

1. snapshot を実行して、現在ページに表示されているものを確認します。
2. ロケーターが疑わしい場合は、eval でその disabled、aria-hidden、offsetParent などを調べ、Playwright がアクション可能ではないと判断した理由を確認します。
3. 次にアクションを実行する場合は、generate-locator または run-code で修正後の呼び出しを試します。cli は、spec に貼り付けられる Playwright TypeScript を出力します。
4. ページ上に期待したものが何もない場合は、console と requests で、アプリでエラーが発生したのか、ネットワーク呼び出しが失敗したのかを確認できます。

すべてのアクションを記録してください。cli の各アクションは、同等の page.foo() TS を出力します。これは、修正案を提示する際の材料になります。

ステップ 8：診断して報告する

根本原因が明らかになったら、次の内容をユーザーに要約して伝えます。

• 根本原因 — ロケーターのずれ、待機不足、競合状態、アプリのバグなどです。テストのバグ、アプリのバグ、環境の問題 を区別してください。
• 証拠 — スナップショットの抜粋、eval の結果、またはネットワーク障害の内容を引用して、根拠を示します。
• 修正案 — path:line と置き換える行を正確に示した、具体的なコード変更を提示します。ロケーターを修正する場合は、cli がすでに出力した TS を貼り付けます。

spec に修正を適用する前に、ユーザーに確認してください。ユーザーが承認した場合は、Edit を使用して修正を適用します（page.pause() やその他のデバッグ用コードは追加しないでください）。

ステップ 9：クリーンアップ（常に実行）

このステップは、成功、エラー、ユーザーによる中断を問わず、すべての終了経路で実行する必要があります。

npx playwright-cli close-all                      # closes the attached browser, ends the session
# the background test process exits naturally once the session closes;
# if it's still running, kill the background task by id.

ハーネスのキャプチャ出力ファイルは、バックグラウンドタスクの終了時に自動的に削除されるため、手動でクリーンアップする必要はありません。

次に、以下を確認します。

npx playwright-cli list                            # should print "(no browsers)"

確認ステップでブラウザーがまだ表示される場合は、npx playwright-cli kill-all で強制終了してください。

ソースの復元は必要ありません — このスキルが仕様を編集することはありません。ステップ 8 で修正を適用した場合は、ユーザーの保留中の変更として残し、自動的に元に戻さないでください。

ステップ 10：修正を確認するために再実行（修正を適用した場合のみ）

npx playwright-cli list                            # confirm clean
PLAYWRIGHT_HTML_OPEN=never npx playwright test <test-file> -g "<test-name>" --project=<proj>

成功した場合は、問題が解消したことを報告してください。それでも失敗する場合は、自動的に別の --debug=cli セッションに戻らず、新たな失敗を報告して、どのように進めるかユーザーに確認してください。

リファレンス：cli のコマンド一覧

コマンドの全一覧：npx playwright-cli --help。ここでよく使うコマンド：

コマンド	用途
attach <session>	一時停止中のテストセッションに接続する
-s=<session> pause-at <file>:<line>	ソースの場所にブレークポイントを設定する
-s=<session> resume	次のブレークポイントまたは終了まで実行する
-s=<session> step-over	1 つのアクションをステップ実行する
-s=<session> snapshot	eN 要素参照付きの DOM スナップショット
-s=<session> generate-locator <ref>	参照用の Playwright ロケーターを生成する
-s=<session> eval <fn> [ref]	ページまたは要素上で JS を実行する
-s=<session> run-code <ts>	Playwright の TS スニペットをその場で実行する
-s=<session> console	コンソールメッセージを表示する
-s=<session> requests / request <n>	ネットワークを調査する
list	アクティブな cli ブラウザーをすべて表示する
close-all	すべての cli ブラウザーを閉じる
kill-all	古いセッションを強制終了する

グローバルフラグ：構造化出力には --json、値のみの出力には --raw、コマンドごとのヘルプには --help [command] を使用します。