Sanity Studio 中的浏览器自动化 Tracing 实战用 playwright-cli 捕获 DOM、网络与控制台证据链【免费下载链接】sanitySanity Studio – Rapidly configure content workspaces powered by structured content项目地址: https://gitcode.com/GitHub_Trending/sa/sanity本篇技术指南围绕仓库中 playwright-cli 技能参考文档 tracing.md 展开讲解如何用playwright-cli的tracing-start/tracing-stop命令对浏览器自动化会话进行完整执行追踪涵盖追踪产出文件.trace动作日志、.network网络日志、resources/资源缓存的结构与用途、调试失败操作、性能分析与证据留存的三类实战场景以及 trace / video / screenshot 三种产物形态的选型依据。读完本文你将掌握在 Sanity Studio 这类 Studio 类 Web 应用中定位“点击为何失败”“哪个资源慢”的具体取证方法并能把 trace 产物与仓库 e2e 测试体系的失败诊断流程对接起来。1. Tracing 在 playwright-cli 技能中的位置playwright-cli是本仓库 Agent 技能 SKILL.md 描述的浏览器自动化工具提供open、goto、click、fill、snapshot等核心命令。Tracing 命令归属于该技能文档中的DevTools命令组与console、network、run-code、video-start并列playwright-cli console playwright-cli console warning playwright-cli network playwright-cli run-code async page await page.context().grantPermissions([geolocation]) playwright-cli tracing-start playwright-cli tracing-stop playwright-cli video-start playwright-cli video-stop video.webm也就是说tracing 与 console/network 检查、代码注入、视频录制共同构成了一组“会话级诊断能力”。与只能看当前时刻的snapshot不同tracing 把整个操作序列的上下文记录下来供事后逐步回放。2. 基本用法在操作序列外层包裹 tracing-start / tracing-stop参考文档给出的标准用法是“先开始录制 → 执行操作 → 停止录制”的三明治结构# Start trace recording playwright-cli tracing-start # Perform actions playwright-cli open https://example.com playwright-cli click e1 playwright-cli fill e2 test # Stop trace recording playwright-cli tracing-stop其中click e1、fill e2 test里的e1/e2是 playwright-cli snapshot 中的元素引用refs每条命令执行后 CLI 会返回一份页面状态快照快照为可交互元素编号e1、e5、e15……后续命令直接引用这些编号。这个机制同样适用于 tracing 场景——被追踪的每个动作最终都会以带 ref 的形式写进 trace 的动作日志。SKILL.md 中还有一个“Debugging with DevTools”的完整示例展示了 tracing 在真实工作流中的位置playwright-cli open https://example.com playwright-cli tracing-start playwright-cli click e4 playwright-cli fill e7 test playwright-cli tracing-stop playwright-cli close要点是tracing-start必须在open之后、第一个想记录的动作之前执行tracing-stop之后建议close结束会话确保产物落盘。若全局二进制不可用技能文档说明可以回退到npx playwright-cli command的等价调用方式。3. 追踪产物traces/ 目录里的三类文件调用tracing-start后Playwright 会创建一个traces/目录在 playwright-cli 会话中位于.playwright-cli/traces这一点由文档中清理命令find .playwright-cli/traces -mtime 7 -delete可以印证其中包含三类核心产物3.1trace-{timestamp}.trace动作日志Action log主追踪文件内容覆盖每个被执行的动作clicks、fills、navigations每个动作前后的完整 DOM 快照每一步的截图screenshots at each step时序信息timing information控制台消息console messages源码位置source locations。“动作前后的 DOM 快照”是它相对截图和视频的决定性优势当一次点击失败时你可以直接检视点击发生那一刻页面长什么样——元素是否被遮挡、是否尚未渲染完成、ref 指向的节点是否还存在。3.2trace-{timestamp}.network网络日志Network log完整记录会话期间的网络活动所有 HTTP 请求与响应请求头与请求体、响应头与响应体各阶段耗时DNS、connect、TLS、TTFB、download资源大小失败的请求与错误。对 Sanity Studio 这类依赖大量 API 调用的应用数据集查询、发布流程、资产处理网络日志可以直接回答“这一步慢在 DNS/TLS 建连还是 TTFB”“哪个响应体内容不符合预期”这类问题。3.3resources/资源缓存目录缓存会话期间用到的资源图片、字体、样式表、脚本以及用于回放replay的响应体和重建页面状态所需的资产。它保证 trace 在事后查看时能够还原页面当时的渲染上下文而不需要重新访问线上服务。3.4 追踪捕获矩阵参考文档用一张表总结了 trace 覆盖的维度类别捕获内容Actions点击、输入、悬停、键盘输入、导航DOM每个动作前后的完整 DOM 快照Screenshots每一步的视觉状态Network所有请求、响应、头、体、耗时Console所有 console.log / warn / error 消息Timing每个操作的精确耗时4. 三类典型实战场景4.1 调试失败动作Debugging Failed Actionsplaywright-cli tracing-start playwright-cli open https://app.example.com # This click fails - why? playwright-cli click e5 playwright-cli tracing-stop # Open trace to see DOM state when click was attempted场景要点不要只在失败那一步临时开 tracing而是把导致问题的完整流程都录进去见第 6 节最佳实践第 1 条。停止录制后打开 trace查看点击尝试发生时的 DOM 状态即可判断是元素未出现、被遮挡还是 ref 失效。4.2 性能分析Analyzing Performanceplaywright-cli tracing-start playwright-cli open https://slow-site.com playwright-cli tracing-stop # View network waterfall to identify slow resources停止后查看网络瀑布图waterfall结合.network日志中每段耗时DNS / connect / TLS / TTFB / download定位慢资源。注意这里 trace 的文件体积通常小于视频适合在 CI 中保留。4.3 留存完整流程证据Capturing Evidence# Record a complete user flow for documentation playwright-cli tracing-start playwright-cli open https://app.example.com/checkout playwright-cli fill e1 4111111111111111 playwright-cli fill e2 12/25 playwright-cli fill e3 123 playwright-cli click e4 playwright-cli tracing-stop # Trace shows exact sequence of events用于文档化的完整用户流示例为结账流程trace 会精确呈现事件序列可替代“口头描述操作步骤”作为回归依据。需要提醒的是这类示例中出现的卡号是国际卡组织保留的测试专用卡号实际录入敏感数据时应使用测试环境。5. 选型Trace vs Video vs Screenshot参考文档给出了三种产物形态的对比这也是做取证/文档化方案时的核心决策表特性TraceVideoScreenshot格式.trace 文件.webm 视频.png/.jpeg 图片DOM 检查支持不支持不支持网络详情支持不支持不支持逐步回放支持连续播放单帧文件体积中等大小最适用场景调试演示快速抓取同目录下的 video-recording.md 从视频侧做了交叉印证视频WebMVP8/VP9 编码“用于演示与文档体积更大”而 tracing“用于调试与分析体积更小”。两条文档共同给出的结论是需要可检查的 DOM/网络/控制台细节就选 trace需要可传播的连续画面就选 video只需一帧证据就选 screenshot。6. 最佳实践与限制6.1 在问题出现之前就开始追踪# Trace the entire flow, not just the failing step playwright-cli tracing-start playwright-cli open https://example.com # ... all steps leading to the issue ... playwright-cli tracing-stop失败步骤往往由前序状态引起导航未完成、前一次 fill 未生效只录失败那一步会丢失因果链。6.2 定期清理旧 tracetrace 会占用可观的磁盘空间参考文档建议按时间清理# Remove traces older than 7 days find .playwright-cli/traces -mtime 7 -delete6.3 已知限制参考文档明确列出了三条限制方案落地时应将其计入成本tracing 会给自动化增加开销overhead大 trace 会占用大量磁盘空间部分动态内容可能无法完美回放。7. 仓库佐证Sanity Studio 的 e2e 体系如何对待 trace 产物本仓库自身有一套完整的 Playwright e2e 测试体系e2e/playwright.config.ts其配置从侧面印证了 tracing 文档中“开销与体积”两条限制的工程处理方式——按需采集而非全程录制全局配置采用trace: on-first-retrye2e/playwright.config.ts 第 113 行e2e/playwright.auth.config.ts 第 34 行同样如此首次失败不产生 trace只有重试时才开始录制把体积开销集中在真正失败的路径上所有测试产物截图、视频、trace统一落到outputDir: ./resultse2e/playwright.config.ts 第 26、101 行与 trace 文档中“traces 目录需要定期清理”的建议形成呼应配套的 flake 分析报告工具 e2e/scripts/flakeReport/index.ts 在下载 CI 分片产物时会处理“含失败视频与 trace、单份可达数十 MB”的 shard 产物该文件第 51–53 行注释明确说明了对并发下载数的限制动机并对同目录中的视频/trace 产物做了跳过解压的处理e2e/scripts/flakeReport/blobReport.ts。从源码结构看这体现了一个与 playwright-cli tracing 文档一致的工程共识trace 的价值在于失败路径上的高信息密度而它的代价是体积因此在自动化体系里普遍采取“失败时采集 集中产物目录 按时间或按分片清理”的组合策略。8. 小结tracing-start/tracing-stop包裹操作序列即可得到一份可回放的执行证据链产物为traces/目录下的.trace动作日志含前后 DOM 快照、每步截图、时序、控制台消息、.network网络日志含各阶段耗时与请求/响应体和resources/资源缓存三大场景调试失败动作看点击时刻的 DOM、性能分析看网络瀑布、流程证据留存记录精确事件序列选型上trace 提供 DOM/网络/逐步回放video 适合演示screenshot 适合单帧取证实践上遵循“问题出现前就开始追踪、按天清理旧产物”两条最佳实践并将开销与体积限制纳入成本考量本仓库 e2e 体系以trace: on-first-retry 统一outputDir flake 报告工具链展示了 trace 产物在规模化 CI 环境中的工程化处置方式可作为上述实践原则的参考实现。【免费下载链接】sanitySanity Studio – Rapidly configure content workspaces powered by structured content项目地址: https://gitcode.com/GitHub_Trending/sa/sanity创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Sanity Studio 中的浏览器自动化 Tracing 实战：用 playwright-cli 捕获 DOM、网络与控制台证据链
Sanity Studio 中的浏览器自动化 Tracing 实战用 playwright-cli 捕获 DOM、网络与控制台证据链【免费下载链接】sanitySanity Studio – Rapidly configure content workspaces powered by structured content项目地址: https://gitcode.com/GitHub_Trending/sa/sanity本篇技术指南围绕仓库中 playwright-cli 技能参考文档 tracing.md 展开讲解如何用playwright-cli的tracing-start/tracing-stop命令对浏览器自动化会话进行完整执行追踪涵盖追踪产出文件.trace动作日志、.network网络日志、resources/资源缓存的结构与用途、调试失败操作、性能分析与证据留存的三类实战场景以及 trace / video / screenshot 三种产物形态的选型依据。读完本文你将掌握在 Sanity Studio 这类 Studio 类 Web 应用中定位“点击为何失败”“哪个资源慢”的具体取证方法并能把 trace 产物与仓库 e2e 测试体系的失败诊断流程对接起来。1. Tracing 在 playwright-cli 技能中的位置playwright-cli是本仓库 Agent 技能 SKILL.md 描述的浏览器自动化工具提供open、goto、click、fill、snapshot等核心命令。Tracing 命令归属于该技能文档中的DevTools命令组与console、network、run-code、video-start并列playwright-cli console playwright-cli console warning playwright-cli network playwright-cli run-code async page await page.context().grantPermissions([geolocation]) playwright-cli tracing-start playwright-cli tracing-stop playwright-cli video-start playwright-cli video-stop video.webm也就是说tracing 与 console/network 检查、代码注入、视频录制共同构成了一组“会话级诊断能力”。与只能看当前时刻的snapshot不同tracing 把整个操作序列的上下文记录下来供事后逐步回放。2. 基本用法在操作序列外层包裹 tracing-start / tracing-stop参考文档给出的标准用法是“先开始录制 → 执行操作 → 停止录制”的三明治结构# Start trace recording playwright-cli tracing-start # Perform actions playwright-cli open https://example.com playwright-cli click e1 playwright-cli fill e2 test # Stop trace recording playwright-cli tracing-stop其中click e1、fill e2 test里的e1/e2是 playwright-cli snapshot 中的元素引用refs每条命令执行后 CLI 会返回一份页面状态快照快照为可交互元素编号e1、e5、e15……后续命令直接引用这些编号。这个机制同样适用于 tracing 场景——被追踪的每个动作最终都会以带 ref 的形式写进 trace 的动作日志。SKILL.md 中还有一个“Debugging with DevTools”的完整示例展示了 tracing 在真实工作流中的位置playwright-cli open https://example.com playwright-cli tracing-start playwright-cli click e4 playwright-cli fill e7 test playwright-cli tracing-stop playwright-cli close要点是tracing-start必须在open之后、第一个想记录的动作之前执行tracing-stop之后建议close结束会话确保产物落盘。若全局二进制不可用技能文档说明可以回退到npx playwright-cli command的等价调用方式。3. 追踪产物traces/ 目录里的三类文件调用tracing-start后Playwright 会创建一个traces/目录在 playwright-cli 会话中位于.playwright-cli/traces这一点由文档中清理命令find .playwright-cli/traces -mtime 7 -delete可以印证其中包含三类核心产物3.1trace-{timestamp}.trace动作日志Action log主追踪文件内容覆盖每个被执行的动作clicks、fills、navigations每个动作前后的完整 DOM 快照每一步的截图screenshots at each step时序信息timing information控制台消息console messages源码位置source locations。“动作前后的 DOM 快照”是它相对截图和视频的决定性优势当一次点击失败时你可以直接检视点击发生那一刻页面长什么样——元素是否被遮挡、是否尚未渲染完成、ref 指向的节点是否还存在。3.2trace-{timestamp}.network网络日志Network log完整记录会话期间的网络活动所有 HTTP 请求与响应请求头与请求体、响应头与响应体各阶段耗时DNS、connect、TLS、TTFB、download资源大小失败的请求与错误。对 Sanity Studio 这类依赖大量 API 调用的应用数据集查询、发布流程、资产处理网络日志可以直接回答“这一步慢在 DNS/TLS 建连还是 TTFB”“哪个响应体内容不符合预期”这类问题。3.3resources/资源缓存目录缓存会话期间用到的资源图片、字体、样式表、脚本以及用于回放replay的响应体和重建页面状态所需的资产。它保证 trace 在事后查看时能够还原页面当时的渲染上下文而不需要重新访问线上服务。3.4 追踪捕获矩阵参考文档用一张表总结了 trace 覆盖的维度类别捕获内容Actions点击、输入、悬停、键盘输入、导航DOM每个动作前后的完整 DOM 快照Screenshots每一步的视觉状态Network所有请求、响应、头、体、耗时Console所有 console.log / warn / error 消息Timing每个操作的精确耗时4. 三类典型实战场景4.1 调试失败动作Debugging Failed Actionsplaywright-cli tracing-start playwright-cli open https://app.example.com # This click fails - why? playwright-cli click e5 playwright-cli tracing-stop # Open trace to see DOM state when click was attempted场景要点不要只在失败那一步临时开 tracing而是把导致问题的完整流程都录进去见第 6 节最佳实践第 1 条。停止录制后打开 trace查看点击尝试发生时的 DOM 状态即可判断是元素未出现、被遮挡还是 ref 失效。4.2 性能分析Analyzing Performanceplaywright-cli tracing-start playwright-cli open https://slow-site.com playwright-cli tracing-stop # View network waterfall to identify slow resources停止后查看网络瀑布图waterfall结合.network日志中每段耗时DNS / connect / TLS / TTFB / download定位慢资源。注意这里 trace 的文件体积通常小于视频适合在 CI 中保留。4.3 留存完整流程证据Capturing Evidence# Record a complete user flow for documentation playwright-cli tracing-start playwright-cli open https://app.example.com/checkout playwright-cli fill e1 4111111111111111 playwright-cli fill e2 12/25 playwright-cli fill e3 123 playwright-cli click e4 playwright-cli tracing-stop # Trace shows exact sequence of events用于文档化的完整用户流示例为结账流程trace 会精确呈现事件序列可替代“口头描述操作步骤”作为回归依据。需要提醒的是这类示例中出现的卡号是国际卡组织保留的测试专用卡号实际录入敏感数据时应使用测试环境。5. 选型Trace vs Video vs Screenshot参考文档给出了三种产物形态的对比这也是做取证/文档化方案时的核心决策表特性TraceVideoScreenshot格式.trace 文件.webm 视频.png/.jpeg 图片DOM 检查支持不支持不支持网络详情支持不支持不支持逐步回放支持连续播放单帧文件体积中等大小最适用场景调试演示快速抓取同目录下的 video-recording.md 从视频侧做了交叉印证视频WebMVP8/VP9 编码“用于演示与文档体积更大”而 tracing“用于调试与分析体积更小”。两条文档共同给出的结论是需要可检查的 DOM/网络/控制台细节就选 trace需要可传播的连续画面就选 video只需一帧证据就选 screenshot。6. 最佳实践与限制6.1 在问题出现之前就开始追踪# Trace the entire flow, not just the failing step playwright-cli tracing-start playwright-cli open https://example.com # ... all steps leading to the issue ... playwright-cli tracing-stop失败步骤往往由前序状态引起导航未完成、前一次 fill 未生效只录失败那一步会丢失因果链。6.2 定期清理旧 tracetrace 会占用可观的磁盘空间参考文档建议按时间清理# Remove traces older than 7 days find .playwright-cli/traces -mtime 7 -delete6.3 已知限制参考文档明确列出了三条限制方案落地时应将其计入成本tracing 会给自动化增加开销overhead大 trace 会占用大量磁盘空间部分动态内容可能无法完美回放。7. 仓库佐证Sanity Studio 的 e2e 体系如何对待 trace 产物本仓库自身有一套完整的 Playwright e2e 测试体系e2e/playwright.config.ts其配置从侧面印证了 tracing 文档中“开销与体积”两条限制的工程处理方式——按需采集而非全程录制全局配置采用trace: on-first-retrye2e/playwright.config.ts 第 113 行e2e/playwright.auth.config.ts 第 34 行同样如此首次失败不产生 trace只有重试时才开始录制把体积开销集中在真正失败的路径上所有测试产物截图、视频、trace统一落到outputDir: ./resultse2e/playwright.config.ts 第 26、101 行与 trace 文档中“traces 目录需要定期清理”的建议形成呼应配套的 flake 分析报告工具 e2e/scripts/flakeReport/index.ts 在下载 CI 分片产物时会处理“含失败视频与 trace、单份可达数十 MB”的 shard 产物该文件第 51–53 行注释明确说明了对并发下载数的限制动机并对同目录中的视频/trace 产物做了跳过解压的处理e2e/scripts/flakeReport/blobReport.ts。从源码结构看这体现了一个与 playwright-cli tracing 文档一致的工程共识trace 的价值在于失败路径上的高信息密度而它的代价是体积因此在自动化体系里普遍采取“失败时采集 集中产物目录 按时间或按分片清理”的组合策略。8. 小结tracing-start/tracing-stop包裹操作序列即可得到一份可回放的执行证据链产物为traces/目录下的.trace动作日志含前后 DOM 快照、每步截图、时序、控制台消息、.network网络日志含各阶段耗时与请求/响应体和resources/资源缓存三大场景调试失败动作看点击时刻的 DOM、性能分析看网络瀑布、流程证据留存记录精确事件序列选型上trace 提供 DOM/网络/逐步回放video 适合演示screenshot 适合单帧取证实践上遵循“问题出现前就开始追踪、按天清理旧产物”两条最佳实践并将开销与体积限制纳入成本考量本仓库 e2e 体系以trace: on-first-retry 统一outputDir flake 报告工具链展示了 trace 产物在规模化 CI 环境中的工程化处置方式可作为上述实践原则的参考实现。【免费下载链接】sanitySanity Studio – Rapidly configure content workspaces powered by structured content项目地址: https://gitcode.com/GitHub_Trending/sa/sanity创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考