视频录制

🌐 Video Recording

将浏览器会话录制为带章节标记和操作提示的 WebM 视频。

🌐 Record browser sessions as WebM videos with chapter markers and action callouts.

命令

🌐 Commands

命令	描述
video-start [filename]	开始录制
video-stop	停止并保存
video-chapter <title>	显示全屏章节卡并标记位置
video-show-actions	用标注和高亮标记后续操作
video-hide-actions	停止标注操作

基本录音

🌐 Basic recording

playwright-cli open https://example.com
playwright-cli video-start demo.webm
playwright-cli click e5
playwright-cli fill e3 "test"
playwright-cli video-stop
# Video saved to: .playwright-cli/demo.webm

如果没有文件名，视频会以 video-{timestamp}.webm 的名字保存在输出目录里。

🌐 Without a filename the video is saved as video-{timestamp}.webm in the output directory.

视频大小

🌐 Video size

playwright-cli video-start --size=800x600

如果省略 --size，录音会按比例调整以适应 800x800。

🌐 If --size is omitted, the recording is scaled to fit 800x800.

章节标记

🌐 Chapter markers

video-chapter 会模糊页面并显示指定时间的章节卡片，然后将其移除——在攻略中的章节过渡时很有用。

playwright-cli video-start

playwright-cli video-chapter "Step 1: Login" --description="Signing in as a returning user" --duration=2000
playwright-cli goto https://app.example.com/login
playwright-cli fill e3 "user@example.com"
playwright-cli fill e5 "password"
playwright-cli click e7

playwright-cli video-chapter "Step 2: Navigate to settings"
playwright-cli goto /settings

playwright-cli video-chapter "Step 3: Update profile"
playwright-cli fill e10 "New Display Name"
playwright-cli click e15

playwright-cli video-stop

动作提示

🌐 Action callouts

video-show-actions 会让每个后续命令在录制中自我叙述：会有一个标注说出动作名称，并且目标元素会被高亮显示，同时一个动画指针会在动作点之间移动。

playwright-cli video-start walkthrough.webm
playwright-cli video-show-actions --duration=600 --position=top-right

playwright-cli click e5
playwright-cli fill e3 "test"

playwright-cli video-hide-actions
playwright-cli video-stop

选项	描述
--duration=<ms>	每个提示停留在屏幕上的时间（默认 500）
--position=<pos>	top-left、top、top-right、bottom-left、bottom、bottom-right（默认 top-right）
--cursor=<mode>	pointer 会动画显示鼠标指针（默认），none 禁用它

脚本视频

🌐 Scripted videos

为了获得精致的录制效果——控制节奏、真实的打字效果、自定义叠加——可以用 run-code 从单个脚本驱动整个场景，而不是一次发一个命令。先用 CLI 浏览页面以收集定位器，然后再写脚本：

🌐 For a polished recording — controlled pacing, realistic typing, custom overlays — drive the whole scenario from a single script with run-code instead of issuing commands one at a time. Explore the page with the CLI first to collect the locators, then write the script:

// hero.js
async page => {
  await page.screencast.start({ path: 'video.webm', size: { width: 1280, height: 800 } });
  await page.goto('https://demo.playwright.dev/todomvc');

  // Chapter card: blurs the page, blocks for the duration, then auto-removes.
  await page.screencast.showChapter('Adding Todo Items', {
    description: 'We will add several items to the todo list.',
    duration: 2000,
  });

  const input = page.getByRole('textbox', { name: 'What needs to be done?' });
  await input.pressSequentially('Walk the dog', { delay: 60 });
  await input.press('Enter');
  await page.waitForTimeout(1000);

  // Sticky overlay: pointer-events are disabled, so it never blocks interaction.
  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>
  `);

  await input.pressSequentially('Buy groceries', { delay: 60 });
  await input.press('Enter');
  await page.waitForTimeout(1500);
  await annotation.dispose();

  await page.screencast.stop();
}

playwright-cli run-code --filename=hero.js

覆盖 API

🌐 Overlay API

方法	使用场景
page.screencast.start(options) / stop()	开始和停止录制
page.screencast.showChapter(title, { description?, duration?, styleSheet? })	带模糊背景的全屏章节卡
page.screencast.showOverlay(html, { duration? })	自定义 HTML 覆盖层 — 提示、标签、高亮
page.screencast.showActions(options) / hideActions()	video-show-actions 背后的 API
disposable.dispose()	移除没有设置持续时间的固定覆盖层
page.screencast.hideOverlays() / showOverlays()	临时隐藏或显示所有覆盖层

覆盖层是 pointer-events: none，所以在你点击、填写或与页面互动时它们可以保持可见。要将其放置在特定元素上方，先读取该元素的盒子：

🌐 Overlays are pointer-events: none, so they can stay visible while you click, fill, or interact with the page. To position one over a specific element, read its box first:

const bounds = await page.getByText('Walk the dog').boundingBox();

视频 vs 描摹

🌐 Video vs tracing

功能	视频	跟踪
输出	WebM 文件	可在跟踪查看器中查看的跟踪文件
显示内容	可视化录制	DOM 快照、网络、控制台、操作
最适合	演示、文档、错误报告	调试和分析
文件大小	较大	较小

使用案例

🌐 Use cases

场景	方法
Bug重现	记录步骤，附加到问题中
测试文档	用章节标记记录
代理监控	录制代理会话以供回顾
演示制作	用 run-code 和覆盖效果编写场景脚本