pw-debug-live

实时附加 Playwright 测试进行调试

你正在通过 playwright-cli 附加到一个已暂停的运行中测试会话，以调试 Playwright E2E 测试。与 pw-debug-test（在运行结束后检查冻结的跟踪记录）不同，此技能会操作实时浏览器，让你能够在执行过程中探查页面。

**重要：**此技能绝不会编辑 spec 文件来插入 page.pause()。CLI 内置的 pause-at <file>:<line> 能实现同样的功能，而且不会改动源文件。如果你发现自己想对 spec 使用 Edit，请停下来，改用 pause-at。

步骤 0：向用户收集输入

使用 AskUserQuestion 收集：

1. 测试文件路径——相对于仓库根目录，例如 tests/user/article-create.spec.ts。
2. 测试名称——test('...') 标题（或其中独一无二的关键词）。用作 -g <pattern>。
3. 行号——执行应暂停的位置。该行应位于所选测试的主体内。
4. 失败提示（可选）——怀疑失败的内容（例如“点击发布按钮超时”）。这有助于聚焦调查。

无论任何情况都不要跳过此步骤，即使用户要求不进行澄清也不例外。继续之前，你需要获得全部四项答案。

步骤 1：验证输入和工作区

在启动任何进程之前：

1. 文件存在。Read 测试文件。如果文件不存在，请停止并询问。
2. **行号位于正确的测试中。**确认行号处于 test('<name>', ...) 的开头与其结束花括号之间。如果该行不在指定测试中（例如位于 beforeEach、另一个测试或导入块中），请提醒用户，并询问是否继续或选择其他行号。
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

使用 Bash 并设置 run_in_background: true。运行环境会返回后台任务 ID 和捕获的标准输出/标准错误文件路径——请记住这两项。下文将此路径称为 $LOG。

务必包含 PLAYWRIGHT_HTML_OPEN=never，以防测试结束时 HTML 报告器因等待浏览器标签页而阻塞。

如果项目没有命名的 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

使用单次 Bash 调用（设置 run_in_background: true），配合 until 轮询和精确的 grep 筛选——会话启动后你会立即收到通知。将实际日志路径替换为运行环境在步骤 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：排查问题

Agent 会根据用户提供的线索和快照内容，从 cli 界面中选择工具。始终传入 -s=<session> 和 --json，以便解析输出。

目标	命令
查看页面内容（引用标记为 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 then request <n> --json
一次执行一个步骤	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 会输出可粘贴到规范文件中的 Playwright TypeScript 代码。
4. 如果页面内容与预期不符，使用 console 和 requests 检查应用是否出错或网络调用是否失败。

记录每项操作的结果——每个 cli 操作都会输出等效的 page.foo() TS 代码，这些代码可用于提供修复建议。

步骤 8：诊断并报告

确定根本原因后，向用户总结：

• 根本原因——定位器偏移、缺少等待、竞态条件、应用缺陷等。区分_测试缺陷_、应用缺陷_和_环境问题。
• 证据——引用能够证明问题的快照片段、eval 结果或网络故障信息。
• 建议修复方案——提供具体代码更改，注明 path:line 和要替换的准确代码行。对于定位器修复，请粘贴 cli 已输出的 TS 代码。

应用修复到规范文件前，请先征求用户同意。如果用户同意，请通过 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.

后台任务结束时，harness 会自动清理捕获输出文件，无需手动清理。

然后进行验证：

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	单步执行一个操作
-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] 用于查看各命令的帮助。