使用 playwright-cli 录制浏览器自动化视频：WebM 录制、章节标注与 Overlay API 完全指南

前端富文本UI组件AI 应用【免费下载链接】BlockNoteA React Rich Text Editor thats block-based (Notion style) and extensible. Built on top of Prosemirror and Tiptap.项目地址https://gitcode.com/gh_mirrors/bl/BlockNote点击查看免费下载导读本指南以仓库内 playwright-cli 技能文档 为主体系统讲解如何使用playwright-cli将浏览器自动化会话录制为 WebMVP8/VP9 编码视频用于调试、文档演示与自动化验证。你将掌握 CLI 基础录制流程、章节标记、基于run-code与page.screencastAPI 的高质量成片脚本编写技巧以及 Overlay 标注体系与 Tracing 的选型对比。文中所有命令与 API 均可在当前仓库的.claude/skills/playwright-cli/技能包中对照使用。一、录制能力概览为什么需要视频录制在浏览器自动化尤其是以 playwright-cli 为代表的 CLI 驱动模式中文字快照snapshot与静态截图只能记录某一时刻的页面状态无法还原过程。视频录制则能调试回放完整操作序列定位点击失败、动画异常、时序问题文档化为演示、教学、验收报告提供可直接播放的过程证据验证作为自动化工作流的交付物向用户证明端到端流程真实可用。录制产物为WebM 容器VP8/VP9 视频编解码器文件具有体积可控、浏览器原生可播、无需额外播放器的特点。关联技能入口完整的 CLI 命令清单见 SKILL.md 的 DevTools 小节playwright-cli video-start/video-chapter/video-stop命令定义位于该文件的第 166-168 行。二、基础录制流程三步走CLI 层的录制围绕三个命令展开形成开始 → 录制 → 停止的完整闭环# 1. 先打开浏览器可同时指定初始页面 playwright-cli open # 2. 开始录制指定输出文件名 playwright-cli video-start demo.webm # 3. 为章节转场添加标记可选见下文章节标记 playwright-cli video-chapter Getting Started --descriptionOpening the homepage --duration2000 # 4. 执行任意导航与交互操作 playwright-cli goto https://example.com playwright-cli snapshot playwright-cli click e1 # 5. 再次添加章节标记 playwright-cli video-chapter Filling Form --descriptionEntering test data --duration2000 playwright-cli fill e2 test input # 6. 停止录制并保存文件 playwright-cli video-stop要点说明playwright-cli open必须先于video-start执行因为录制的对象是当前已建立的浏览器会话交互命令goto、click、fill、snapshot等的用法与 SKILL.md 中 Core 命令一致录制期间照常执行即可video-chapter的三个参数第一个位置参数为章节标题--description提供章节补充说明--duration毫秒控制章节卡片在画面中的停留时长。三、最佳实践一使用描述性文件名WebM 文件一旦生成便难以追溯其内容场景因此命名应当携带上下文信息便于日后检索与归档# 包含业务场景与时间/批次信息 playwright-cli video-start recordings/login-flow-2024-01-15.webm playwright-cli video-start recordings/checkout-test-run-42.webm推荐格式为recordings/场景-日期或批次.webm将录像统一归档到recordings/目录避免散落各处。这与仓库内其他技能如 tracing.md 建议将 trace 清理归档的目录管理思路一致。四、最佳实践二录制完整成片脚本核心章节对于需要交付给用户、或作为工作证明的高质量视频文档明确推荐不要依赖 CLI 逐条命令而是先跑一遍场景用 CLI 完整执行目标流程记录所有 locator 与动作序列——这些 locator 后续将用于请求元素 bounding box 以实现高亮编写录制脚本文件把要录制的流程写成独立的 JS 脚本见下方模板使用pressSequentially配合delay模拟自然打字并在动作之间插入合理的暂停用run-code执行playwright-cli run-code --filename your-script.js。run-code的完整能力geolocation、权限、媒体模拟、等待策略、frame 操作等参见 running-code.md。脚本须为单个async (page) {...}函数表达式不支持 import/export/require 语法。4.1 完整脚本模板async (page) { // 启动录屏指定输出路径与画幅尺寸 await page.screencast.start({ path: video.webm, size: { width: 1280, height: 800 }, }); await page.goto(https://demo.playwright.dev/todomvc); // 章节卡片模糊页面并弹出对话框式标题duration 到期后自动消失 await page.screencast.showChapter(Adding Todo Items, { description: We will add several items to the todo list., duration: 2000, }); // 模拟自然打字输入每 60ms 敲一个字符 await page .getByRole(textbox, { name: What needs to be done? }) .pressSequentially(Walk the dog, { delay: 60 }); await page .getByRole(textbox, { name: What needs to be done? }) .press(Enter); await page.waitForTimeout(1000); // 下一个章节 await page.screencast.showChapter(Verifying Results, { description: Checking the item appeared in the list., duration: 2000, }); // 粘性标注不设 duration 时持续显示操作页面时不会遮挡点击 const annotation await page.screencast.showOverlay( div styleposition: absolute; top: 8px; right: 8px; padding: 6px 12px; background: rgba(0,0,0,0.7); border-radius: 8px; font-size: 13px; color: white; ✓ Item added successfully /div ); // 标注可见期间继续执行动作 await page .getByRole(textbox, { name: What needs to be done? }) .pressSequentially(Buy groceries, { delay: 60 }); await page .getByRole(textbox, { name: What needs to be done? }) .press(Enter); await page.waitForTimeout(1500); // 动作完成后移除粘性标注 await annotation.dispose(); // 基于 boundingBox 动态高亮相关元素并附加上下文说明 const bounds await page.getByText(Walk the dog).boundingBox(); await page.screencast.showOverlay( div styleposition: absolute; top: ${bounds.y}px; left: ${bounds.x}px; width: ${bounds.width}px; height: ${bounds.height}px; border: 1px solid red; /div div styleposition: absolute; top: ${bounds.y bounds.height 5}px; left: ${bounds.x bounds.width / 2}px; transform: translateX(-50%); padding: 6px; background: #808080; border-radius: 10px; font-size: 14px; color: white;Check it out, it is right above this text /div , { duration: 2000 }, ); // 结束录屏 await page.screencast.stop(); };4.2 模板要点拆解手段作用参数说明screencast.start({ path, size })开始录屏path输出 WebM 路径size分辨率示例 1280×800screencast.showChapter(title, opts)章节转场卡片description描述文本duration停留毫秒数styleSheet自定义样式screencast.showOverlay(html, { duration })自定义 HTML 标注不传duration时为粘性标注需手动dispose()pressSequentially(text, { delay })模拟打字delay为两次按键间隔毫秒越大越接近真人输入boundingBox()获取元素几何信息返回{x, y, width, height}用于动态计算高亮框位置annotation.dispose()移除粘性标注仅对未设duration的 overlay 有效关键注意事项所有 Overlay 均为pointer-events: none不会拦截页面上的点击、填充等任何交互因此可以放心让粘性标注在操作全程保持可见。五、Overlay API 汇总表方法适用场景page.screencast.showChapter(title, { description?, duration?, styleSheet? })全屏章节卡片 模糊背景适合章节转场page.screencast.showOverlay(html, { duration? })自定义 HTML 标注用于提示框、标签、高亮disposable.dispose()移除未设置 duration 的粘性标注page.screencast.hideOverlays()/page.screencast.showOverlays()临时隐藏 / 恢复全部标注设计建议章节卡片适合粗粒度的阶段划分而showOverlay提供完全的自由度——文档特别强调Embrace creativity, overlays are powerful即鼓励利用 HTML/CSS 自由构造符合品牌或演示需求的标注效果。六、Tracing 与 Video 的选型对比录制并不总是最优解。当目标是调试与分析而非演示时应优先选择 Tracingtracing.md 有完整用法。两者的能力边界如下特性视频Video追踪Tracing输出产物WebM 文件Trace 文件可在 Trace Viewer 中查看记录内容视觉录制DOM 快照、网络请求、控制台日志、动作序列适用场景演示、文档调试、分析文件体积较大较小从 tracing.md 的对比表还可进一步看出三者的定位差异Screenshot 适合单帧快速捕获Video 适合连续过程的演示Trace 则额外具备 DOM 检查、网络细节与逐步回放能力。选型建议交付演示选视频定位问题选 Trace随手记录选截图。七、限制与注意事项性能开销录制会给自动化过程增加一定运行时开销同样Tracing 也存在此问题见 tracing.md 的 Limitations 小节磁盘占用长时录制可能消耗大量磁盘空间建议结合具体场景控制录制时长并为输出文件建立归档与定期清理机制可参照 Tracing 章节中find .playwright-cli/traces -mtime 7 -delete的清理思路会话前提CLI 录制依赖已打开的浏览器会话务必先执行playwright-cli open再video-start。八、小结围绕 video-recording.md 这份文档本指南完整覆盖了三层能力CLI 命令层video-start/video-chapter/video-stop的三步录制、脚本层通过run-code驱动page.screencast编排带章节、标注、高亮的成片、选型层Video 与 Tracing 的适用边界。实践上建议正式交付的录像一律走脚本化录制路线先跑场景记录 locator再以pressSequentially模拟真实输入、以 Overlay 丰富画面信息最终产出可直接播放的 WebM 演示素材。延伸阅读playwright-cli 技能总览全部 CLI 命令、快照、会话与安装方式Tracing 文档Trace 文件结构、捕获内容与清理最佳实践Running Code 文档run-code的语法约束、等待策略与复杂工作流测试仓库体系当前仓库基于 Playwright 的浏览器端到端测试环境playwright/test1.60.0赞分享前端富文本UI组件AI 应用【免费下载链接】BlockNoteA React Rich Text Editor thats block-based (Notion style) and extensible. Built on top of Prosemirror and Tiptap.项目地址https://gitcode.com/gh_mirrors/bl/BlockNote点击查看免费下载相关推荐Playwright CLI 视频录制指南用 playwright-cli 与 Screencast API 生成带章节与标注的 WebM 演示视频Playwright CLI 视频录制指南用 playwright cli 与 Screencast API 生成带章节与标注的 WebM 演示视频 Play测试开发工具浏览器控制Wave Terminal 发布流程全解从版本号管理、CI 构建到多渠道分发与自动更新Wave Terminal 发布流程全解从版本号管理、CI 构建到多渠道分发与自动更新 本篇技术指南以 Wave TerminalWave开源仓库的 RE人工智能AI AgentAgent 框架后端多智能体RAG工具调用Agent 记忆Agent 工作流AI 评测MCP 服务MCP Clients语音Sanity 仓库中的 playwright-cli 视频录制用 WebM 捕获浏览器自动化会话Sanity 仓库中的 playwright cli 视频录制用 WebM 捕获浏览器自动化会话 本文基于 Sanity 仓库内的 Agent 技能文档 .aCMS前端上一篇探索 Magiblots TVision一个开源的计算机视觉库下一篇告别邮件开发痛点SendWithUs Templates全攻略创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考