Playwright Trace ViewerJava/Python 实战从录制 Trace 到交互式时间线调试【免费下载链接】playwrightPlaywright is a framework for Web Testing and Automation. It allows testing Chromium, Firefox and WebKit with a single API.项目地址: https://gitcode.com/GitHub_Trending/pl/playwrightPlaywright Trace Viewer 是一款 GUI 调试工具用于回放测试运行期间录制的 Trace你可以逐步前进/后退每一个测试动作直观看到每个动作发生时页面的状态、日志、源码与网络请求。本文以 Playwright 官方文档中的 Java/Python 版 Trace Viewer 入门指南为主体结合本仓库中 Trace 客户端、CLI 与录制器的源码实现完整讲解“如何录制 trace、如何打开 trace、trace.zip 里到底有什么”帮助你在 CI 失败后无需重跑测试即可定位问题。一、Trace Viewer 能做什么官方文档将其定位概括为探索已录制的 Playwright trace回到或前进到测试中的每一步并可视化地看到每步动作期间发生了什么。核心能力包括点击左侧 Actions 列表中的任意动作或使用 Timeline 查看该动作前后页面的状态逐步查看每一步的日志Log、源码Source与网络请求NetworkTrace Viewer 会为每个动作重建 DOM 快照因此你可以与快照完全交互——悬停、点击、甚至打开 DevTools。这些交互能力的具体界面组件位于 packages/trace-viewer/src/ui/ 目录下例如动作列表 actionList.tsx、时间线 timeline.tsx、快照面板 snapshotTab.tsx、网络面板 networkTab.tsx 等与文档中“Actions / Screenshots / Snapshots / Source / Call / Log / Errors / Console / Network / Metadata”各功能 Tab 一一对应。二、录制 Trace2.1 Python用 pytest 的--tracing标志在 Python 中如果你的测试基于 pytest 运行器最省事的录制方式是给pytest追加--tracing标志pytest --tracing on--tracing支持的取值取值行为on为每个测试录制 traceoff不录制 trace默认值retain-on-failure为每个测试录制 trace但删除所有成功测试产生的 trace录制完成后trace 会被写入test-results目录下的trace.zip文件。这个“每个测试一个trace.zip、统一放在test-results/下”的行为由 Python 语言包的 pytest 运行器提供该运行器不在本仓库内本仓库维护的是核心引擎与 CLI见下文 packages/playwright-core/src/cli/program.ts。2.2 Python使用BrowserContext.tracingAPI非 pytest 场景如果不用 pytest 运行器可以直接调用tracingAPI在创建/导航页面之前启动录制结束时导出为 zip 归档。异步写法browser await chromium.launch() context await browser.new_context() # Start tracing before creating / navigating a page. await context.tracing.start(screenshotsTrue, snapshotsTrue, sourcesTrue) page await context.new_page() await page.goto(https://playwright.dev) # Stop tracing and export it into a zip archive. await context.tracing.stop(pathtrace.zip)同步写法browser chromium.launch() context browser.new_context() # Start tracing before creating / navigating a page. context.tracing.start(screenshotsTrue, snapshotsTrue, sourcesTrue) page context.new_page() page.goto(https://playwright.dev) # Stop tracing and export it into a zip archive. context.tracing.stop(pathtrace.zip)各参数的含义可从本仓库的客户端实现 packages/playwright-core/src/client/tracing.ts 得到印证start除了文档示例中的三个开关外底层还支持snapshots为对象时细分dom/aria/screen三种快照模式以及live边录制边实时查看和name/title标注 trace 名称与标题等选项// start(options) 支持的选项节选自 client/tracing.ts { name?: string; title?: string; snapshots?: boolean | { dom?: boolean, aria?: boolean, screen?: boolean }; screenshots?: boolean; // 底层映射为 screencast 录制 sources?: boolean; live?: boolean; }也就是说文档示例中的screenshotsTrue在内部实际启动了屏幕录制screencastsnapshotsTrue启动 DOM 快照器sourcesTrue则让导出时把测试源码一并打包进 trace源码字段includeSources见 tracing.ts 中的_saveChunk。2.3 Java使用tracing()APIJava 的录制方式同样基于BrowserContext.tracing()APIBrowser browser browserType.launch(); BrowserContext context browser.newContext(); // Start tracing before creating / navigating a page. context.tracing().start(new Tracing.StartOptions() .setScreenshots(true) .setSnapshots(true) .setSources(true)); Page page context.newPage(); page.navigate(https://playwright.dev); // Stop tracing and export it into a zip archive. context.tracing().stop(new Tracing.StopOptions() .setPath(Paths.get(trace.zip)));运行后会生成trace.zip文件。客户端stop(options)的调用链是stop→_doStopChunk→_saveChunk在 tracing.ts 中可以看到stop会先保存当前 chunk写入 zip再发送tracingStop结束整个录制若未指定path则直接以discard模式丢弃数据不落盘。2.4 zip 是如何生成的源码视角trace.zip的落盘逻辑在 packages/playwright-core/src/client/tracing.ts 中分两种路径本地连接客户端请求服务端以entries模式返回 trace 条目再由localUtils.zip()在本地直接写入 zip 文件并追加 stacks 信息、按需包含源码远程连接服务端以archive模式返回一个 Artifactzip 产物客户端通过artifact.saveAs(path)保存后再追加 stacks 与源码。服务端的录制核心位于 packages/playwright-core/src/server/trace/recorder/tracing.ts从源码结构看Tracing类实现了InstrumentationListener拦截每个 API 调用生成 action 事件、SnapshotterDelegate驱动 DOM 快照器Snapshotter与HarTracerDelegate内置 HAR 网络录制对应 Network Tab 的数据来源同时还维护ScreencastTracingRecorder列表用于逐页屏幕录制——这正是“动作列表、快照、film strip 截图、网络请求”四类数据的来源。三、打开 Trace3.1 使用 CLI 打开本地 trace打开trace.zip时请提供文件的完整路径。各语言的命令如下直接继承自官方文档Pythonplaywright show-trace trace.zipJava通过 Maven exec 插件调用 Playwright 内置 CLImvn exec:java -e -D exec.mainClasscom.microsoft.playwright.CLI -D exec.argsshow-trace trace.zipshow-trace子命令的核心定义在 packages/playwright-core/src/cli/program.ts。除了 trace 路径本身它还支持以下选项选项说明-b, --browser browserType打开 Viewer 使用的浏览器cr/chromium、ff/firefox、wk/webkit默认chromium-h, --host host指定 host 后 trace 改为在浏览器标签页中打开而非独立窗口-p, --port port指定端口0表示随机空闲端口指定后同样在浏览器标签页中打开--stdin接受从标准输入传入的 trace URL用于更新 Viewer适合服务端场景当指定了--host或--port时CLI 走runTraceInBrowser分支在浏览器标签页中打开否则走runTraceViewerApp分支启动独立的 Trace Viewer 应用窗口。3.2 在浏览器中打开静态托管版 Trace Viewer除 CLI 外还可以使用官方静态托管的 Web 版 Trace Viewer域名 trace.playwright.dev纯文本表述不展开链接通过拖拽或“Select file”按钮上传trace.zip。该版本完全在浏览器端加载 trace不会向外发送任何数据。3.3 直接查看远程 traceCLI 还支持直接以 URL 打开远程 trace例如 CI 上传到制品存储后的地址省去手动下载步骤playwright show-trace https://example.com/trace.zipJava 下等价命令mvn exec:java -e -D exec.mainClasscom.microsoft.playwright.CLI -D exec.argsshow-trace https://example.com/trace.zip这与show-trace命令参数定义为可选路径show-trace [trace]可传 URL的实现一致参见 program.ts。使用 Web 版 Viewer 时也可以通过查询参数?traceurl传入可访问存储上的 trace 地址可能受 CORS 限制以官方站点说明为准。四、在 Trace Viewer 中如何排查问题打开 trace 后的典型调试路径对应文档“Opening the trace”一节的展开说明细节参考 docs/src/trace-viewer.md 的完整功能说明Actions 列表每个动作都标注所用 locator 与耗时悬停即可在 DOM 快照中预览该动作引起的变化点击动作进入检查模式。选中动作后可看到动作快照、动作日志与源码位置Timeline / Film Strip开启screenshots后 trace 会记录 screencast 并渲染为胶片条film strip悬停查看放大帧双击动作查看其时间区间可用时间线滑块框选多个动作Console 与 Network 会随之过滤Snapshots开启snapshots后Playwright 为每个动作捕获完整 DOM 快照按动作类型分为 Before调用时、Action输入执行瞬间可用于精确定位实际点击位置、After动作结束后三类快照中还高亮目标 DOM 节点与精确点击坐标Source点击侧边栏动作后对应代码行会在源码面板中高亮前提是录制时开启sourcesCall展示动作耗时、所用 locator、是否 strict 模式、按键等元信息Log展示 Playwright 内部行为日志如滚动到可见区域、等待元素可见/启用/稳定后再执行 click/fill/press 等Errors测试失败时错误信息集中展示时间线上以红线标出错误发生位置并可跳转出错源码行Console区分来自浏览器与测试文件的控制台日志图标不同Network列出测试期间的全部请求可按类型、状态码、方法、内容类型、耗时、大小排序点击进入查看请求/响应头与正文Metadata展示浏览器、viewport 尺寸、测试时长等环境信息。由于快照是完整 DOM 重建你可以在任意一帧上悬停、点击、打开 DevTools相当于“冻结了测试当时那一秒的浏览器现场”这对 CI 上无法复现的失败尤为关键。五、验证与延伸阅读端到端的 trace 录制测试见 tests/library/tracing.spec.ts覆盖start/stopChunk/startChunk、snapshots、sources、HAR 组合等场景Trace 事件的数据模型context-options、action、snapshot 事件结构定义在 packages/protocol/spec/ 的 YAML 规范中packages/isomorphic/trace/下则是 trace 解析与展示的共享实现完整功能指南docs/src/trace-viewer.md含 JS 运行器的--trace on/on-first-retry等 CI 推荐配置CI 集成场景docs/src/ci-intro.md。小结Python 用户可在 pytest 中一行pytest --tracing on获得逐测试 trace不依赖 pytest 或 Java 用户则统一走BrowserContext.tracing().start({screenshots, snapshots, sources})→stop(path)的 API 模式产物trace.zip用playwright show-trace或 Java 的com.microsoft.playwright.CLI打开即可在时间线上交互式回放日志、快照、网络与源码。【免费下载链接】playwrightPlaywright is a framework for Web Testing and Automation. It allows testing Chromium, Firefox and WebKit with a single API.项目地址: https://gitcode.com/GitHub_Trending/pl/playwright创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考