Playwright CLI 视频录制：录屏、章节标记、Overlay 与调试对比

Wed, 15 Apr 2026 08:22:45 +0800

如果你想把浏览器自动化过程录成视频，用来做调试、文档演示，或者作为执行结果留档，Playwright CLI 已经提供了比较直接的方案。它输出的是 WebM 视频，编码为 VP8/VP9。

这篇按官方 video-recording 参考文档整理，重点包括基础录制流程、章节标记、整段 hero script 录制、Overlay API，以及 video 与 tracing 的区别。文中的命令行、代码片段与参数说明均按参考内容保留。

01 基础录制流程

最基础的流程就是：先打开浏览器，再开始录制，执行操作，最后停止并保存。

# Open browser first
playwright-cli open

# Start recording
playwright-cli video-start demo.webm

# Add a chapter marker for section transitions
playwright-cli video-chapter "Getting Started" --description="Opening the homepage" --duration=2000

# Navigate and perform actions
playwright-cli goto https://example.com
playwright-cli snapshot
playwright-cli click e1
# Add another chapter
playwright-cli video-chapter "Filling Form" --description="Entering test data" --duration=2000
playwright-cli fill e2 "test input"

# Stop and save
playwright-cli video-stop

这组命令已经覆盖了最常见的录制路径。video-chapter 适合在不同阶段之间插入章节卡片，让录出来的视频更容易看懂。

02 最佳实践

1. 使用更清晰的文件名

如果视频是给别人看，或者后面还要回查，文件名最好直接带上场景和上下文。

1
2
3

# Include context in filename
playwright-cli video-start recordings/login-flow-2024-01-15.webm
playwright-cli video-start recordings/checkout-test-run-42.webm

2. 录制完整 hero script

官方建议：如果视频是要交付给用户，或者要作为 proof of work，最好把场景整理成一段代码，然后用 run-code 执行。这样更容易控制动作节奏、停顿时机，以及视频里的标注效果。参考文档也特别提到，Playwright 新增了一些适合录制场景的 API。

推荐流程如下：

先用 CLI 走一遍场景，并记下所有 locator 和 action。后面如果要做高亮，需要用这些 locator 去请求它们的 bounding box。
为视频单独创建一个脚本文件，并按下面的方式编写。输入内容时用 pressSequentially 配合 delay，停顿时间也尽量安排得自然。
使用 playwright-cli run-code --filename your-script.js 执行。

Important: Overlays are pointer-events: none — they do not interfere with page interactions. You can safely keep sticky overlays visible while clicking, filling, or performing any actions on the page.

async page => {
  await page.screencast.start({ path: 'video.webm', size: { width: 1280, height: 800 } });
  await page.goto('https://demo.playwright.dev/todomvc');
  // Show a chapter card — blurs the page and shows a dialog.
  // Blocks until duration expires, then auto-removes.
  // Use this for simple use cases, but always feel free to hand-craft your own beautiful
  // overlay via await page.screencast.showOverlay().
  await page.screencast.showChapter('Adding Todo Items', {
    description: 'We will add several items to the todo list.',
    duration: 2000,
  });
  // Perform action
  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);

  // Show next chapter
  await page.screencast.showChapter('Verifying Results', {
    description: 'Checking the item appeared in the list.',
    duration: 2000,
  });
  // Add a sticky annotation that stays while you perform actions.
  // Overlays are pointer-events: none, so they won't block clicks.
  const annotation = await page.screencast.showOverlay(`
    <div style="position: 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>
  `);
  // Perform more actions while the annotation is visible
  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);

  // Remove the annotation when done
  await annotation.dispose();
  // You can also highlight relevant locators and provide contextual annotations.
  const bounds = await page.getByText('Walk the dog').boundingBox();
  await page.screencast.showOverlay(`
    <div style="position: absolute;
      top: ${bounds.y}px;
      left: ${bounds.x}px;
      width: ${bounds.width}px;
      height: ${bounds.height}px;
      border: 1px solid red;">
    </div>
    <div style="position: 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();
}

这一段代码的重点不只是“录下来”，而是把视频做得更清楚：章节卡片负责分段，pressSequentially 让输入动作更自然，showOverlay 则可以做提示、高亮和说明。

文档最后还补了一句：Embrace creativity, overlays are powerful.

03 Overlay API 速览

录制视频时，Overlay API 很适合做章节切换、局部提示和持续注释。官方给出的摘要如下：

Method	Use Case
`page.screencast.showChapter(title, { description?, duration?, styleSheet? })`	Full-screen chapter card with blurred backdrop — ideal for section transitions
`page.screencast.showOverlay(html, { duration? })`	Custom HTML overlay — use for callouts, labels, highlights
`disposable.dispose()`	Remove a sticky overlay added without duration
`page.screencast.hideOverlays()` / `page.screencast.showOverlays()`	Temporarily hide/show all overlays

如果你的目标是把自动化过程做成“可观看的视频”，这一组 API 基本就是最值得优先掌握的部分。

04 Tracing 和 Video 的区别

官方文档把两者的定位区分得很清楚：

Feature	Video	Tracing
Output	WebM file	Trace file (viewable in Trace Viewer)
Shows	Visual recording	DOM snapshots, network, console, actions
Use case	Demos, documentation	Debugging, analysis
Size	Larger	Smaller

简单理解：

video 更适合演示、交付和复盘“用户看到的过程”
tracing 更适合排查问题、分析动作细节和查看执行上下文

这两者并不是互相替代，而是各自服务于不同目标。

05 使用限制

文档里也提醒了两个很实际的限制：

Recording adds slight overhead to automation
Large recordings can consume significant disk space

也就是说，录制功能虽然很实用，但会给自动化流程增加一些开销；如果视频很长，磁盘占用也会明显上升。

06 快速总结

如果只抓重点，可以记住下面几件事：

video-start / video-stop 对应最基本的视频录制流程
video-chapter 可以给视频加章节过渡，适合让演示更清晰
更复杂的视频场景，适合写成脚本后用 run-code 执行
showOverlay 和 showChapter 可以显著提升视频的可读性
video 适合演示，tracing 适合调试，两者最好按目标选择

如果你已经在用 Playwright CLI 做自动化演示、验收留档或 proof of work，那么 video recording 会是一块非常值得补上的能力。

参考链接

Playwright CLI video-recording 参考文档：https://github.com/microsoft/playwright-cli/blob/main/skills/playwright-cli/references/video-recording.md
Playwright CLI 项目主页：https://github.com/microsoft/playwright-cli

Video Recording on KnightLi的博客