使用 Playwright Trace Viewer 调试授权测试
为可重复的测试诊断捕获 Playwright trace，并让内容、留存和分享处于批准的隐私边界内。
Playwright trace 包含什么
Playwright tracing 会为获得授权的测试记录时间线，使维护人员能够检查失败附近发生的事情。Trace Viewer 可以显示操作、网络活动、控制台消息、截图和快照，具体取决于启动 tracing 时使用的选项。trace 解释测试观察到的浏览器端顺序；它不会记录每个系统事件，也不能证明应用或服务接受了某个请求。
Trace Viewer 文档说明了如何打开 trace 和检查步骤。Playwright 最佳实践建议使用隔离、确定性的测试和面向用户的断言。两者共同支持一个明确问题：哪个获得授权的操作、浏览器响应或断言首先偏离了预期契约？
trace 文件可能包含敏感材料。页面快照可能包含呈现的文字，截图可能显示账户标签，网络详情可能包含 URL 或请求头。只捕获合成场景或明确批准的场景。不要因为 trace 便于查看，就附加真实用户会话、支付数据、认证令牌或无关页面。
关于隔离决策，可参阅 Playwright BrowserContext 生命周期和浏览器存储模型。上下文边界有助于避免状态意外共享，但不会在数据捕获后替 trace 脱敏。
捕获有界 trace
只在需要它的 fixture 或测试范围内启动 tracing。捕获简短的准备步骤和失败交互，并在 finally 路径中停止 tracing，使断言失败时仍能生成完整产物。常见做法是只保留第一次重试的 trace，而不是记录每次成功运行。选项名称和默认值可能随 Playwright 版本变化，修改 fixture 前应查看当前 API 参考。
await context.tracing.start({ screenshots: true, snapshots: true, sources: false });
try {
await runAuthorizedScenario(page);
} finally {
await context.tracing.stop({ path: tracePath });
}
示例记录测试自有的上下文，并写入 worker 专用路径。运行前创建目录，防止并行 worker 互相覆盖；缺失或不完整的文件应标记为基础设施结果，而不是测试通过。trace 应回答一个有界问题，例如断言前导航是否完成，而不是变成通用浏览器录制服务。
重试测试时，使用新的上下文和同一组获授权的合成输入。不要复用未知失败尝试生成的页面或存储状态。将测试名称、浏览器版本和结果类别作为独立元数据保存；日常 CI 输出不要包含凭据和完整响应正文。
分享前审查和脱敏
在本地或团队批准的产物系统中打开 trace。先看操作时间线和断言，只有在需要区分测试缺陷与应用响应时才检查关联请求或快照。与其把截图复制到聊天频道，不如写下“批准的登录 fixture 后没有出现预期重定向”这样的简短结论。
对外分享前必须脱敏。删除或排除包含令牌、Cookie、个人姓名、支付详情、私有 URL 或客户内容的 trace。事后删除无法收回已经下载的产物。如果 trace 无法安全缩减，就保留在受限测试工作区，只分享诊断结论。
留存期限应匹配调试目的。trace 应保留到负责人能够复现问题，然后按照团队产物政策过期。共享位置使用访问控制和审计记录。trace 是测试证据，不是长期账户备份；context.close() 也不会删除已经上传到 CI 存储的副本。
让证据保持有用的团队流程
阅读 trace 前先定义预期的用户可见契约。记录场景、浏览器和 Playwright 版本、测试结果及清理结果。审查时，把第一个意外事件与团队获准访问的应用日志进行比较。如果失败发生在浏览器边界之外，应停在该边界，请服务负责人提供受支持的诊断记录，不要扩大 trace 去查看无关数据。
使用确定且按 worker 区分的名称，例如 artifacts/traces/<test>-<worker>-<attempt>.zip。只发布定位产物所需的最少元数据。审查者无需打开快照，就应知道 trace 是否完整、代表哪个合成场景以及何时过期。若 trace 缺失、损坏或在 teardown 后才捕获，应明确记录限制。
BotBrowser 可以提供隔离浏览器上下文和可重复配置文件，帮助团队在捕获 trace 前复现同一有界场景。BotBrowser 不能保证 trace 不含敏感页面内容、从快照中移除令牌，或让服务端失败自动可见；测试负责人必须选择合成输入并执行产物访问和留存政策。Playwright 仍负责 tracing、fixture 范围和 Trace Viewer 审查。参见 BotBrowser 多账户隔离文档了解浏览器侧边界。
记录测试标识、合成场景、浏览器版本和 Playwright 版本。
记录首次偏离的步骤和结果类别。
说明 trace 是否包含截图、快照、源码或网络详情。
为每个 worker 使用独立输出路径。
在停止 tracing 后再移动归档文件。
不要把凭据写入 CI 日志。
失败重试必须创建新的上下文。
不要把第二次通过解释为第一次失败无害。
用用户可见契约替代脆弱的时间猜测。
仅在问题需要时启用截图和快照。
归档过大时缩小范围，不要静默截断。
限制 trace 读取者并设置过期时间。
分享前检查截图和网络事件中的敏感值。
应用负责人应通过受支持的服务日志确认服务端行为。
删除失败的清理任务应产生运维记录。
应用流程改变后重新检查留存规则。
本地复现应使用干净目录和命名版本。
测试目录只能清理测试拥有的临时文件。
审查者无需打开快照即可判断归档用途。
保留一个明确的场景所有者。
把服务端证据和浏览器证据分开。
避免用未知状态文件重试。
记录归档是否完整。
不要把 trace 当作账户备份。
让清理路径可以重复执行。
过期后删除受控副本。
变更 fixture 后重新审查敏感字段。
记录归档用途、负责人和过期时间。
运行前写明预期的用户可见契约。
从失败断言回看第一个异常状态。
只按问题需要启用截图和快照。
把归档大小作为运维限制。
每次重试都使用新上下文。
为并行 worker 分离路径。
像保护凭据一样限制 trace 访问。
对归档和导出截图同时脱敏。
把首次偏离转成窄范围回归测试。
使用干净目录和明确的浏览器版本复现。
用用户可见条件替代脆弱等待。
向服务负责人提供受支持的请求标识，而不是浏览器数据。
让清理结果可观测，但不输出归档内容。
结论应注明测试版本和环境；单个 trace 不能证明普遍兼容性。
记录审查后的明确下一步。
在 trace、CI 结果和回归问题中使用同一场景标签。
复制归档时重新检查目标访问策略和过期时间。
区分已观察事实和待验证假设。
关闭不再需要的 trace 访问权限。
保留受限链接而不是复制完整归档。
归档标签不要包含账户标识符。
服务端结论需要受支持的日志确认。
问题结束后保留脱敏结论即可。
调试清单
- 确定一个获授权的场景和预期断言。
- 只为需要的 fixture 或第一次重试启动 tracing。
- 将每个 worker 的 trace 写入私有且唯一的路径，并在
finally中停止。 - 先检查时间线；分享前脱敏或限制快照、URL 和网络详情。
- 记录结论、版本、清理结果、负责人和过期时间，不复制秘密。