Playwright CLI ビデオ録画: 画面録画、チャプターマーカー、オーバーレイおよびデバッグの比較

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

ブラウザ自動化プロセスをデバッグ用、ドキュメントデモンストレーション用、または実行結果のファイルとしてビデオに記録したい場合、Playwright CLI は比較的簡単なソリューションを提供します。 VP8/VP9 としてエンコードされた WebM ビデオを出力します。

この記事は、公式 video-recording リファレンスドキュメントに従って構成されており、基本的な録画プロセス、チャプターマーカー、ヒーロースクリプト全体の録画、オーバーレイ API、およびビデオとトレースの違いに焦点を当てています。この記事のコマンドライン、コードスニペット、およびパラメーターの説明は、参照コンテンツとして保持されています。

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. 完全なヒーロースクリプトを記録する

公式アドバイス: ビデオをユーザーに配信する場合、または作業証明として使用する場合は、シーンをコードにまとめて run-code で実行するのが最善です。これにより、ビデオ内のアクションのリズム、一時停止のタイミング、注釈効果を制御しやすくなります。リファレンスドキュメントには、Playwright がシーンの記録に適した新しい API をいくつか追加したことも具体的に記載されています。

推奨されるプロセスは次のとおりです。

まず、CLI を使用してシーンをウォークスルーし、すべてのロケーターとアクションを書き留めます。後でハイライトしたい場合は、これらのロケーターを使用して境界ボックスをリクエストする必要があります。
ビデオ用に別のスクリプトファイルを作成し、次のように記述します。コンテンツを入力する際には、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 はプロンプト、ハイライト、説明を実行できます。

この文書の最後には、「創造性を受け入れ、オーバーレイは強力です」という一文も追加されています。

03 オーバーレイ API の概要

ビデオを録画する場合、オーバーレイ 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 トレースとビデオの違い

公式ドキュメントでは、この 2 つの位置付けが明確に区別されています。

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 は、問題のトラブルシューティング、アクションの詳細の分析、実行コンテキストの表示に適しています。

2 人はお互いの代わりではありませんが、それぞれが異なる目的を果たします。

05 利用制限

この文書では、次の 2 つの非常に実際的な制限も指摘しています。

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 を自動デモンストレーション、承認ファイル、またはプルーフオブワークに使用している場合、video recording は非常に価値のある追加となります。

参考リンク

Playwright CLI ビデオ録画リファレンスドキュメント: 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ブログ

Playwright CLI ビデオ録画: 画面録画、チャプター マーカー、オーバーレイおよびデバッグの比較