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

Debugging on KnightLi的博客