# Playwright Trace Viewer 教程：从遮挡点击的失败轨迹找到真正拦截元素

Playwright原生点击超时与官方Trace Viewer实跑，关闭遮挡层后正常导出12行；未使用force click。

## 环境

- Node.js 24+；进入 reference 后 npm install。依赖为锁定的直接版本，首次安装需要网络。
- 执行 npx playwright install chromium；也可用 CHROME_BIN 指向你自己已安装的 Chromium。Mac生成的截图基线不能保证跨操作系统像素相同。

## 启动

~~~sh
cd reference
npm install
npx playwright install chromium
# 另一个终端在reference运行 python3 -m http.server 8787
EXERCISE_URL=http://127.0.0.1:8787 node verify.mjs
~~~

## 七步操作

1. 准备遮挡页面

先打开原创订单导出页，按钮存在于 DOM，却被首次说明弹窗的 overlay 覆盖。输入有12条虚构练习订单，不使用真实交易数据。

2. 启动原生Trace

使用 Playwright context.tracing.start 记录截图与页面快照。追踪必须在操作之前开启，事后截图无法完整还原点击前的页面状态。

3. 复现点击失败

直接点击被遮挡的导出按钮，等待真实 actionability 超时。日志出现 intercepts pointer events，说明问题是遮挡层，而不是选择器没有找到元素。

4. 打开Trace Viewer

用未修改的官方 Trace Viewer 打开 failed-trace.zip。选中 Click locator，观察当时页面快照和操作耗时；截图来自真正的 Trace Viewer。

5. 查看遮挡日志

切换到 Errors 或 Log 查看重试与遮挡信息。不要直接加 force:true 让测试变绿，这会绕过用户实际无法点击的问题。

6. 关闭弹窗重试

在参考页先点“知道了”关闭弹窗，再正常点击导出。界面显示12行练习订单已准备，成功追踪另存 fixed-trace.zip。

7. 保留两份追踪

下载两份追踪与源码，用 show-trace 再打开比较。下载版去除了作者机器路径，保留原生页面快照、操作时间与错误；AI助手账号会话未运行。

## 目录身份

- starter：待完成的任务接口与原创输入，TODO不是已完成实现。
- reference：作者原生完成参考和实际产物。records.json/browser-result.json为本地实测记录，不是AI助手回复。
- TASK.md：可交给相应AI助手的原始任务合同。该助手账号生成会话未运行。

## 依赖与许可

原创教学代码以MIT许可提供。第三方项目、模型及浏览器遵循其自身许可。第三方依赖由本地安装获取，不包含node_modules、模型权重、WASM运行时、数据库、缓存或凭据。

## 官方依据

- https://playwright.dev/docs/trace-viewer