1# Video Recording
2 
3Capture browser automation sessions as video for debugging, documentation, or verification. Produces WebM (VP8/VP9 codec).
4 
5## Basic Recording
6 
7```bash
8# Open browser first
9playwright-cli open
10 
11# Start recording
12playwright-cli video-start demo.webm
13 
14# Add a chapter marker for section transitions
15playwright-cli video-chapter "Getting Started" --description="Opening the homepage" --duration=2000
16 
17# Navigate and perform actions
18playwright-cli goto https://example.com
19playwright-cli snapshot
20playwright-cli click e1
21 
22# Add another chapter
23playwright-cli video-chapter "Filling Form" --description="Entering test data" --duration=2000
24playwright-cli fill e2 "test input"
25 
26# Stop and save
27playwright-cli video-stop
28```
29 
30## Best Practices
31 
32### 1. Use Descriptive Filenames
33 
34```bash
35# Include context in filename
36playwright-cli video-start recordings/login-flow-2024-01-15.webm
37playwright-cli video-start recordings/checkout-test-run-42.webm
38```
39 
40### 2. Record entire hero scripts.
41 
42When recording a video for the user or as a proof of work, it is best to create a code snippet and execute it with run-code.
43It allows pulling appropriate pauses between the actions and annotating the video. There are new Playwright APIs for that.
44 
451) Perform scenario using CLI and take note of all locators and actions. You'll need those locators to request their bounding boxes for highlight.
462) Create a file with the intended script for video (below). Use pressSequentially w/ delay for nice typing, make reasonable pauses.
473) Use playwright-cli run-code --filename your-script.js
48 
49**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.
50 
51```js
52async page => {
53  await page.screencast.start({ path: 'video.webm', size: { width: 1280, height: 800 } });
54  await page.goto('https://demo.playwright.dev/todomvc');
55 
56  // Show a chapter card — blurs the page and shows a dialog.
57  // Blocks until duration expires, then auto-removes.
58  // Use this for simple use cases, but always feel free to hand-craft your own beautiful
59  // overlay via await page.screencast.showOverlay().
60  await page.screencast.showChapter('Adding Todo Items', {
61    description: 'We will add several items to the todo list.',
62    duration: 2000,
63  });
64 
65  // Perform action
66  await page.getByRole('textbox', { name: 'What needs to be done?' }).pressSequentially('Walk the dog', { delay: 60 });
67  await page.getByRole('textbox', { name: 'What needs to be done?' }).press('Enter');
68  await page.waitForTimeout(1000);
69 
70  // Show next chapter
71  await page.screencast.showChapter('Verifying Results', {
72    description: 'Checking the item appeared in the list.',
73    duration: 2000,
74  });
75 
76  // Add a sticky annotation that stays while you perform actions.
77  // Overlays are pointer-events: none, so they won't block clicks.
78  const annotation = await page.screencast.showOverlay(`
79    <div style="position: absolute; top: 8px; right: 8px;
80      padding: 6px 12px; background: rgba(0,0,0,0.7);
81      border-radius: 8px; font-size: 13px; color: white;">
82      ✓ Item added successfully
83    </div>
84  `);
85 
86  // Perform more actions while the annotation is visible
87  await page.getByRole('textbox', { name: 'What needs to be done?' }).pressSequentially('Buy groceries', { delay: 60 });
88  await page.getByRole('textbox', { name: 'What needs to be done?' }).press('Enter');
89  await page.waitForTimeout(1500);
90 
91  // Remove the annotation when done
92  await annotation.dispose();
93 
94  // You can also highlight relevant locators and provide contextual annotations.
95  const bounds = await page.getByText('Walk the dog').boundingBox();
96  await page.screencast.showOverlay(`
97    <div style="position: absolute;
98      top: ${bounds.y}px;
99      left: ${bounds.x}px;
100      width: ${bounds.width}px;
101      height: ${bounds.height}px;
102      border: 1px solid red;">
103    </div>
104    <div style="position: absolute;
105      top: ${bounds.y + bounds.height + 5}px;
106      left: ${bounds.x + bounds.width / 2}px;
107      transform: translateX(-50%);
108      padding: 6px;
109      background: #808080;
110      border-radius: 10px;
111      font-size: 14px;
112      color: white;">Check it out, it is right above this text
113    </div>
114  `, { duration: 2000 });
115 
116  await page.screencast.stop();
117}
118```
119 
120Embrace creativity, overlays are powerful.
121 
122### Overlay API Summary
123 
124| Method | Use Case |
125|--------|----------|
126| `page.screencast.showChapter(title, { description?, duration?, styleSheet? })` | Full-screen chapter card with blurred backdrop — ideal for section transitions |
127| `page.screencast.showOverlay(html, { duration? })` | Custom HTML overlay — use for callouts, labels, highlights |
128| `disposable.dispose()` | Remove a sticky overlay added without duration |
129| `page.screencast.hideOverlays()` / `page.screencast.showOverlays()` | Temporarily hide/show all overlays |
130 
131## Tracing vs Video
132 
133| Feature | Video | Tracing |
134|---------|-------|---------|
135| Output | WebM file | Trace file (viewable in Trace Viewer) |
136| Shows | Visual recording | DOM snapshots, network, console, actions |
137| Use case | Demos, documentation | Debugging, analysis |
138| Size | Larger | Smaller |
139 
140## Limitations
141 
142- Recording adds slight overhead to automation
143- Large recordings can consume significant disk space
144