本地 Playwright 测试报告怎么远程复盘？Trace Viewer 跑起来后，用 cpolar 分享失败现场

前端 E2E 测试最气人的一件事：本地跑是绿的，CI 上挂了，但 CI 上的截图、视频、日志怎么看都不对劲，想叫前端/测试同事一起来看，发现他连不上你的电脑，只能截图发群里。

Playwright 自带的 Trace Viewer 能解决"一个人怎么复盘"的问题------把一次 E2E 的每一步展开：截图、网络请求、控制台日志、DOM 快照、执行时间，全在一个页面里拖拽查看。但问题是，Trace Viewer 默认绑在本地端口，同事打不开。

这条流程解决的就是：Playwright 测试报告和 trace 本地生成后，用 cpolar 开一个短时 HTTPS 入口，让远程同事直接打开浏览器复盘失败现场。不部署测试报告平台，不用 Jenkins/Allure，不走内网穿透，只用一个命令就把 Trace Viewer 分享出去。

适用场景

这套流程在实际工作中用得上的几种情况：

本地 E2E 测试挂了一个 case，生成的 trace.zip 太大没法发截图，想给同事直接打开 Trace Viewer 看完整时间轴。
CI 失败后，下载了 artifact 里的 trace 文件，想在公司办公网环境下打开复盘，但 CI 机器没有公网入口。
排查前端 bug 时发现是某个步骤的请求参数不对，想叫后端同事一起看当时发出的 payload 和响应。
代码还没合入，想验证某个页面在 Chrome/Edge 上的交互路径，跑完测试后把报告 URL 发给测试同事验收。
跨地域团队协作，不想传几十 MB 的 zip 文件，直接给链接让对方在浏览器里打开看。

这套流程有一个明确边界：只分享脱敏后的测试报告和 trace，不暴露源码、Cookie、token、数据库等生产信息。

最终效果

跑通之后得到两个入口：

入口	用途	是否给同事
`http://localhost:9323`	Playwright HTML Report 本地查看	不给
`http://localhost:9323/trace?trace=xxx`	单条 trace 的 Viewer 时间轴	不给
`https://xxxx.cpolar.top`	远程同事打开的 HTTPS 复盘入口	只在复盘时给

同事打开 https://xxxx.cpolar.top 后，能看到完整的 HTML Report 列表，点开一条失败 case 就能展开 Trace Viewer。截图、网络请求、DOM 快照、console 日志、执行时间都在一条时间线上。

环境准备

本文用一台 Linux 机器做演示。Windows / macOS 上的原理和命令一致，只有安装步骤的包管理器不同（apt 换 brew / chocolatey 即可）。

前置条件：

Linux 机器或 Windows WSL2（Ubuntu 22.04 / Debian 12 以上）
Node.js 18+ 和 npm
Playwright 已安装（全局或项目内都行）
Docker 和 Docker Compose（用于跑 Trace Viewer Docker 镜像，如果本机已装 Node，直接用 npx playwright show-trace 也可以）
已注册 cpolar 账号并拿到 authtoken

先确认环境正常：

bash 复制代码

node --version
npm --version
docker --version
docker compose version

如果还没有 Playwright 项目，新建一个最小 E2E 测试项目来生成报告：

bash 复制代码

mkdir -p ~/playwright-trace-demo
cd ~/playwright-trace-demo
npm init -y
npm install @playwright/test
npx playwright install chromium

新建一个测试文件 demo.spec.js，故意写一个会失败的测试：

bash 复制代码

cat > demo.spec.js <<'EOF'
const { test, expect } = require('@playwright/test');

test('打开百度并搜索 Playwright，验证结果', async ({ page }) => {
  await page.goto('https://www.baidu.com');
  await page.locator('#kw').fill('Playwright trace viewer');
  await page.locator('#su').click();
  await page.waitForTimeout(2000);
  // 故意断言一个不存在的文本，触发失败
  await expect(page.locator('.result')).toHaveCount(999);
});

test('打开百度并搜索 cpolar，验证结果', async ({ page }) => {
  await page.goto('https://www.baidu.com');
  await page.locator('#kw').fill('cpolar 内网穿透');
  await page.locator('#su').click();
  await page.waitForTimeout(2000);
  const title = await page.title();
  expect(title).toContain('百度搜索');
});
EOF

配置 Playwright 开启 trace：

bash 复制代码

cat > playwright.config.js <<'EOF'
const { defineConfig } = require('@playwright/test');

module.exports = defineConfig({
  testDir: '.',
  retries: 0,
  use: {
    trace: 'on-first-retry',
    screenshot: 'on',
    video: 'on-first-retry',
  },
});
EOF

运行测试：

bash 复制代码

npx playwright test

运行结束后，测试目录下会出现 test-results 文件夹，里面有每一条失败 case 的 trace.zip、截图和视频。同时项目根目录下会生成 playwright-report 文件夹，里面就是 HTML Report。

启动 Playwright Trace Viewer

Playwright 提供了两种方式查看 trace 和 report。我通常把两条命令都记住，按场景选：

方式一：在线 HTML Report（团队复盘时用这个）

bash 复制代码

npx playwright show-report playwright-report

默认监听 http://localhost:9323。浏览器打开后能看到所有 case 的执行结果列表，通过率、失败 case、执行时间一目了然。点进一条失败 case，就能看到 Trace Viewer 完整界面。

方式二：只查看单条 trace（快速定位一条 case）

bash 复制代码

npx playwright show-trace test-results/demo-打开百度并搜索Playwright验证结果-chromium/trace.zip

也会在 localhost:9323 启动，但只加载这一条 trace。

如果本机没有 Node.js，或者你想把 report 服务跑成一个稳定的 Docker 容器，可以用 Playwright 官方提供的 Docker 镜像：

bash 复制代码

docker run --rm -d \
  --name playwright-report \
  -p 9323:9323 \
  -v $(pwd)/playwright-report:/report \
  mcr.microsoft.com/playwright:v1.52.0-jammy \
  npx playwright show-report /report

这个容器会把当前目录的 playwright-report 挂进去，然后启动 report 服务。Docker 方式的好处是：容器退出后自动清理，不和本机 Node 版本打架。

启动之后，打开浏览器访问 http://localhost:9323 确认能看到报告。

查看 Trace 报告：一条失败 case 的复盘清单

Trace Viewer 打开后，重点关注这几个要素。我把复盘清单列出来，每次排查对着走就行：

Action 时间线：左侧是每一步操作的时序图，点击每一步，右侧自动定位到对应截图。失败的那一步一般标红了，一眼就能看到。
网络请求：点击某个 action 后，旁边的 Network 选项卡会展示这一步发出去的所有请求。看请求 URL、方法、状态码、请求体、响应体。
Console 日志：看浏览器控制台有没有红色报错。跨域、资源加载失败、接口 500，这里都记着。
Source 快照：DOM 快照能展开看当时页面的 HTML 结构。定位器失效、元素不存在、文本不匹配，看这个最清楚。
参数字段展开 ：某些 action 点开能看到传入的参数，比如 fill('cpolar 内网穿透') 是不是写对了。
Screenshot 对比：失败步骤会有一张截图，看当时的页面实际长什么样，是加载慢了还是文案变了。

用这套清单走一遍，大多数 E2E 失败的原因都能定位到。如果确认是环境问题或数据问题，就可以把 trace URL 分享给同事一起看。

用 cpolar 临时 HTTPS 分享给同事分析失败现场

现在 localhost:9323 上已经有完整的 HTML Report 和 Trace Viewer。接下来用 cpolar 开一个临时 HTTPS 入口。

安装 cpolar：

bash 复制代码

curl -L https://www.cpolar.com/static/downloads/install-release-cpolar.sh | sudo bash
cpolar version

绑定 authtoken：

bash 复制代码

cpolar authtoken 你的_cpolar_authtoken

启动隧道：

bash 复制代码

cpolar http 9323

终端会输出：

text 复制代码

Forwarding  https://xxxx.cpolar.top -> http://localhost:9323

把 https://xxxx.cpolar.top 发给同事。对方在浏览器打开后，看到的页面和你在本地 localhost:9323 看到的一模一样：case 列表、trace viewer、截图、网络请求全可交互。

注意几个细节------我自己发链接前的检查项：

用手机断开 WiFi，用 4G/5G 打开一次链接，确认加载正常。
点击一条失败 case，确认 Trace Viewer 能展开、截图能显示。
看一眼 Network 和 Console，确认没有把内网接口 URL、测试账号密码、内部 token 带进报告里。
如果报告中有截图包含敏感信息（真实手机号、内部工单号、邮箱），先跑一次脱敏再分享。

分享完成后关闭资源

这套流程每次用完之后，必须做三件事关闭入口。不要偷懒，不要明天再关------明天就会忘记，关闭不及时的临时入口会被搜索引擎收录或被恶意扫描。

步骤一：关闭 cpolar

如果 cpolar 在前台运行，直接按：

text 复制代码

Ctrl + C

然后在本地浏览器访问 https://xxxx.cpolar.top，确认已经返回 502 或无法连接。

步骤二：关闭 Playwright Report

如果用的是 npx playwright show-report，也是 Ctrl + C。

如果用的是 Docker 容器：

bash 复制代码

docker stop playwright-report

步骤三：清理测试产物（可选）

复盘结束后，测试报告和 trace 文件不再需要的话，可以一起清掉：

bash 复制代码

rm -rf test-results playwright-report

如果要在不同分支多次复盘，也可以保留报告目录，下一次跑测试时 npx playwright test 会自动覆盖。

安全边界

复盘测试报告不等于开放整个开发环境。边界很清楚：

cpolar 只映射 report/trace viewer 端口。 不要映射开发服务器端口 5173/3000，不要映射 Node.js inspect 端口 9229，不要映射 SSH 端口。

测试数据和凭证不能留在报告里。 Playwright trace 会把每一步的 Cookie 头、localStorage、sessionStorage 都记录下来。如果你的测试用了真实账号或真实 token，优先跑一个专用测试账号，跑完后及时清理。

测试环境用脱敏数据。 注册、登录、提单这类流程，测试数据不要直接用生产或预发环境的真实手机号、身份证、银行卡信息。trace 里的截图和请求每一步都看得见。

时效控制好。 复盘窗口从 cpolar 启动到关闭，原则上不应该超过 1 小时。用完即关，不留过夜。

不要让同事直接登录测试环境。 复盘只要看 trace viewer 里的记录就够了，不需要给对方提供测试环境账号。

常见问题和排错

1. trace.zip 没生成

检查 playwright.config.js 里的 trace 配置：

javascript 复制代码

use: {
  trace: 'on-first-retry',  // 第一次失败后重跑时生成
}

如果想每次跑都生成，改成 'on'：

javascript 复制代码

trace: 'on',

生成的位置：

text 复制代码

test-results/测试名-chromium/trace.zip

除了 trace.zip，目录里还会有一张截图 screenshot.png 和一段视频 video.webm。如果目录里只有截图没有 zip，大概率是配置的问题。

2. cpolar 地址打开后报告显示 "Not Found"

cpolar 映射的端口不对。确认一下：

bash 复制代码

curl -I http://localhost:9323

返回 200 才是正确的端口。如果 report 在别的端口（比如 9324），重新映射：

bash 复制代码

cpolar http 9324

3. Trace Viewer 加载很慢

trace.zip 体积一般在几百 KB 到几 MB 之间。如果一次跑了很多 case、打开了 video 录制，单个 trace.zip 超过 20 MB 是正常的。加载慢通常有几个原因：

报告里包含了大量截图和视频文件。
多条 case 同时展开 Trace Viewer。
网络带宽不够（cpolar 免费隧道走共享带宽，国内访问速度取决于节点负载）。

可以只打开一条 trace 来复盘，不要一次展开所有 case。

4. 截图正常，但 DOM 快照是空的

Trace Viewer 的 Source 选项卡会存储每个步骤的 DOM 快照，但快照默认不包含 iframe 内部的内容。如果你的测试交互发生在 iframe 内，用 frame.locator 定位并 page.frameLocator 处理，否则 DOM 快照里看不到 iframe 内容。

另一个常见原因是：某些页面元素是动态渲染的（例如 React/Vue 的异步组件），trace 记录的快照时间点和元素实际渲染的时间点有偏差。可以在步骤之间加 await page.waitForSelector。

5. 报告里有敏感信息怎么办

如果 trace 已经跑完了，但截图里出现了真实手机号、token、内部接口地址，处理方式是按先后顺序来：

在测试代码里，把敏感字段 mock 掉再跑一次。
在 playwright.config.js 配置 trace: 'on-first-retry'，确保只对失败 case 生成 trace；把通过的 case 关掉 trace 可以减少曝光面。
如果实在无法避免，跑完后在复盘的聊天消息里明确标注"截图含演示数据，阅后即焚"。

不要在已生成的 trace.zip 上手动 P 图或者替换字符串压缩包里的文件。

6. 本机能打开，同事打不开

先检查 playwight report 服务监听的地址：

bash 复制代码

ss -lntp | grep 9323

如果只看到 127.0.0.1:9323，说明只监听了本地回环，docker 的端口映射和 cpolar 都会连不上。在 show-report 命令中加 --host 0.0.0.0：

bash 复制代码

npx playwright show-report --host 0.0.0.0 playwright-report

或者直接用 Docker 方式启动，端口映射天然处理了：

bash 复制代码

docker run --rm -d \
  --name playwright-report \
  -p 9323:9323 \
  -v $(pwd)/playwright-report:/report \
  mcr.microsoft.com/playwright:v1.52.0-jammy \
  npx playwright show-report --host 0.0.0.0 /report

再用 ss 确认现在监听的是 0.0.0.0:9323，然后重新开 cpolar。

7. 非 Java 工具（macOS/Linux）联调时，安全边界检查清单

复盘结束后，把下面几项过一遍：

cpolar 进程已停止（ps aux | grep cpolar 无对应 PID）
report 服务已停止（ss -lntp | grep 9323 无对应端口）
trace.zip 和截图视频已删除或移入安全目录
同事确认链接已失效

关闭提醒

复盘完成之后，第一件事：

text 复制代码

Ctrl + C 停止 cpolar
Ctrl + C 停止 report

两条命令做的事完全不同，关掉第一个只是断开公网入口，关掉第二个是停止 report 服务。

如果之后几周还要反复复盘同样的 trace，可以把 playwright-report 目录和 test-results 保留。如果复盘结束、问题已定位，执行清理：

bash 复制代码

rm -rf test-results playwright-report

一个复盘入口只在一个时间窗口内有效。窗口到期之后，这个入口不再存在------这比给任何访问控制策略都更干净。