Playwright CLI Video Recording: Recording, Chapter Markers, Overlays, and Debugging Tradeoffs

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

If you want to record browser automation sessions as video for debugging, documentation, or proof of work, Playwright CLI already provides a fairly direct workflow. It produces WebM video using the VP8/VP9 codec.

This article follows the official video-recording reference and focuses on the parts that matter most in practice: the basic recording flow, chapter markers, full hero-script recording, the Overlay API, and the difference between video and tracing. The command lines, code snippets, and parameter details are preserved from the reference.

01 Basic Recording Flow

The basic pattern is simple: open the browser, start recording, perform actions, then stop and save.

# 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

These commands already cover the most common recording flow. video-chapter is useful for inserting chapter cards between stages so the final video is easier to follow.

02 Best Practices

1. Use Descriptive Filenames

If the video is meant for other people or for later review, the filename should include enough context to make it understandable at a glance.

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. Record Entire Hero Scripts

The official recommendation is that when a video is for a user or serves as proof of work, it is best to turn the scenario into a code snippet and execute it with run-code. That gives you better control over pacing, pauses, and annotations in the video. The reference also notes that Playwright now includes APIs designed specifically for this kind of recording flow.

The suggested process is:

First perform the scenario with the CLI and note all locators and actions. You will need those locators later if you want their bounding boxes for highlight overlays.
Create a dedicated script file for the video and write it in the style shown below. Use pressSequentially with delay for smoother typing, and add pauses where they feel natural.
Use 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();
}

The value of this script is not only that it records the flow, but that it makes the video easier to understand: chapter cards handle transitions, pressSequentially makes typing look natural, and showOverlay adds explanation, highlights, and context.

The reference closes this section with a short reminder: Embrace creativity, overlays are powerful.

03 Overlay API Summary

When recording video, the Overlay API is especially useful for section transitions, local callouts, and sticky annotations. The official summary is:

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

If your goal is to turn automation into a video people can comfortably watch, this API set is one of the most valuable pieces to learn first.

04 Tracing vs Video

The official documentation makes the difference between the two very clear:

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

A simple way to think about it:

video is better for demos, delivery, and reviewing what a user would see
tracing is better for debugging, inspecting action details, and analyzing execution context

They are not replacements for each other. Each serves a different purpose.

05 Limitations

The reference also points out two practical limitations:

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

So while video recording is very useful, it does add some runtime overhead, and longer recordings can grow large on disk.

06 Quick Summary

If you only want the essentials, remember these points:

video-start / video-stop are the core commands for recording
video-chapter adds section transitions and makes demos easier to follow
More advanced recording scenarios are best written as scripts and executed with run-code
showOverlay and showChapter can significantly improve video readability
video is best for demos, while tracing is best for debugging

If your workflow already includes automation demos, acceptance evidence, or proof-of-work recordings, video recording is a very worthwhile part of Playwright CLI to add.

References

Playwright CLI video-recording reference: https://github.com/microsoft/playwright-cli/blob/main/skills/playwright-cli/references/video-recording.md
Playwright CLI project homepage: https://github.com/microsoft/playwright-cli

Debugging on KnightLi Blog