# 交付在客户那边到底能不能用？让 trace 来回答

> Playwright trace 记录每一步操作和每个网络请求，客户打开就能看到流程是怎么跑的。

原文: https://fdetimes.net/zh/tools/playwright-trace-proof-for-clients/

周五，你完成了与客户 Web 门户的集成。周一，客户发来消息：“申请表单用不了。”你手里只有一张截图和自己的记忆，对方那边则是一个满肚子火的用户。

“在我机器上是好的”这种说法，最容易让前线部署工程师（FDE）失去信任，而这正是 Playwright 要解决的问题。你写一个测试，像真实用户一样把整个流程走一遍，每次运行都会留下记录，双方都能打开查看。

对于在客户系统里工作的人来说，这是一项部署技能，不该丢给 QA 团队。你需要一种可重复的方式来说明“这个流程是通的”，并拿出证据。

## 这是什么工具，为什么选它？

Microsoft 官方文档把 Playwright Test 定义为面向现代 Web 应用的端到端测试框架。它的 GitHub 仓库归属 microsoft 组织，采用 Apache-2.0 许可证，描述更宽泛：一个用于 Web 测试和自动化的框架。

对 FDE 来说，最大的好处是一个包里什么都有：运行器、断言、测试之间的隔离、并行执行以及配套工具。用 `npm init playwright@latest` 就能装好，不必在客户的笔记本上东拼西凑好几个库。它支持 Chromium、WebKit 和 Firefox，可以在 Windows、Linux 和 macOS 上运行。

所以，客户有 Safari 用户也好，对方 IT 只给你一台 Windows 机器也好，同一套测试都能直接跑，不用重写。

## 为刚交付的流程写一个最小测试

设想你刚上线的流程：用户登录，填写申请表单，点击提交，看到确认信息。测试只需沿着这条路径走：

```ts
import { test, expect } from '@playwright/test';

test('成功提交申请', async ({ page }) => {
  await page.goto('https://portal.example.com/login');
  await page.getByLabel('Email').fill('demo@example.com');
  await page.getByLabel('Password').fill(process.env.DEMO_PASSWORD!);
  await page.getByRole('button', { name: 'Sign in' }).click();

  await page.getByRole('link', { name: 'New request' }).click();
  await page.getByLabel('Details').fill('End-to-end check');
  await page.getByRole('button', { name: 'Submit' }).click();

  await expect(page.getByText('Request received')).toBeVisible();
});
```

这个测试里没有一个 `sleep`，这是有意为之。执行操作前，Playwright 会等待相关的可操作性检查通过；超时后仍未通过，就抛出 `TimeoutError`。客户页面加载慢、第三方脚本又多，这种自动等待能让测试更稳定。

最后一行是 web-first 断言。按照最佳实践指南的说法，这类断言会一直等到预期条件满足。你检查的是用户看到的东西，而不是内部细节。

## trace 是证据，不只是调试工具

Trace Viewer 是一个图形界面工具，用来在脚本运行后查看录制下来的 trace。thoughtbot 的 Justin Toniazzo 把它比作测试运行的“录像机”，并认为开启它几乎不费什么力气。

官方文档建议在 CI 上、失败测试首次重试时录制 trace。配置只需几行：

```ts
// playwright.config.ts
import { defineConfig } from '@playwright/test';

export default defineConfig({
  retries: 1,
  use: { trace: 'on-first-retry' },
});
```

回到周一那条消息。打开 trace，进入 Actions 面板，这里显示每个操作用的定位器和耗时。假设点击“Submit”几乎耗尽了整个超时时间，你就知道该从哪里查起了。

接着，每个操作都有 DOM 快照，可以看到点击那一刻页面的样子。Network 面板列出测试运行期间的所有请求。如果表单提交时客户后端返回了错误，对话就从“你的代码坏了”变成“这个 API 在 9 点返回了错误”，这是双方都能着手解决的技术问题。

**要点:** 给客户一份他们能自己打开的记录，比任何保证都更有说服力。

trace 可以用一条 CLI 命令在本地打开，也可以用 trace.playwright.dev，这是 Trace Viewer 的静态托管版本，直接在浏览器里运行。客户那边的人没装 Node 环境时，这一点很方便。

## 刚开启 trace 时的常见错误

最常见的错误是设置了 `trace: 'on-first-retry'`，却忘了 `retries`。没有重试就没有“首次重试”，测试失败时不会留下任何 trace，而这恰恰是最需要它的时候。在相信 CI 正在录制之前，先检查配置里的这两行。

相反的错误是为了保险，每次运行都开 trace。每个 trace 包含每个操作的 DOM 快照和每个网络请求，把整个通过的测试套件都录下来，只会产生一堆几乎没人打开的大文件。

第三个错误要回到上面的代码：测试不稳定时加 `sleep`。这只会掩盖症状，还拖慢整个套件。Playwright 本来就会等操作就绪，测试仍然失败时，应该打开 trace 看哪一步慢，而不是再多等几秒。

## 要向客户讲清楚的局限

测试通过，只能证明这个流程在那个环境、那份数据、那个时刻是通的。它不能替代单元测试，也不能替代生产环境监控。承诺得比这更多，下次 trace 本身就会让你失去信任。

trace 包含 DOM 快照和网络请求，很可能带有客户的真实数据。把 trace 上传到任何地方或通过聊天工具发送之前，先问清对方的数据政策。最好用演示账号和假数据跑测试。

`TimeoutError` 也只能告诉你某个条件没有满足，不能告诉你原因。真正的工作仍是阅读 trace 并推理，这项技能需要练习。

## 先学什么，怎么写进简历

合理的顺序是：基于角色和标签的定位器、web-first 断言、CI 上的 trace 配置，然后是读懂 trace 里的三样东西：Actions、快照和 Network。先把这四项练扎实，再考虑并行运行或多浏览器。

看 FDE 招聘启事时，留意那些讲端到端负责部署、在客户环境中调试的段落。你的 Playwright 经历就该放在这里。

简历上写一句“为用户引导流程编写端到端测试，并用 CI trace 定位客户 API 中的缺陷”，远比“熟悉 Playwright”更有分量。

下次客户问你的交付能不能用，不必争辩，发一个 trace 文件过去就行。

**本周动手试试:**

- 从最近一次交付中挑出最重要的流程，写一个 Playwright 测试把它从头到尾走一遍，只检查一个用户能看到的结果。
- 在 CI 配置中加上 retries 和 trace: 'on-first-retry'，故意让测试失败一次，然后打开 trace，读一读 Actions 和 Network 面板。
- 在简历或作品集里加一句具体的描述：哪个流程做了端到端测试，在哪些浏览器上跑过，trace 帮你找到了什么缺陷。

## 信源

- [Installation | Playwright](https://playwright.dev/docs/intro)

- [GitHub - microsoft/playwright: Playwright is a framework for Web Testing and Automation.](https://github.com/microsoft/playwright)

- [Trace viewer | Playwright](https://playwright.dev/docs/trace-viewer)

- [Auto-waiting | Playwright](https://playwright.dev/docs/actionability)

- [Best Practices | Playwright](https://playwright.dev/docs/best-practices)

- [The Playwright debugging tool Rails devs aren't using](https://thoughtbot.com/blog/the-playwright-debugging-tool-rails-devs-aren-t-using)
