@@ -8,8 +8,9 @@ Capture browser automation sessions as video for debugging, documentation, or ve
88# Open browser first
99playwright-cli open
1010
11- # Start recording
12- playwright-cli video-start demo.webm
11+ # Start recording, --cursor renders an animated mouse cursor that travels to each action point
12+ # and paces actions by 800ms so that it has time to travel
13+ playwright-cli video-start demo.webm --cursor --fps=60
1314
1415# Add a chapter marker for section transitions
1516playwright-cli video-chapter " Getting Started" --description=" Opening the homepage" --duration=2000
@@ -27,6 +28,56 @@ playwright-cli fill e2 "test input"
2728playwright-cli video-stop
2829```
2930
31+ ## Cursor, Target Highlight and Click Point
32+
33+ Three decorations can be drawn for each action: the mouse ** cursor** , a ** highlight** box around the
34+ target element and a ** point** marker at the click point. A ** title** callout naming the action comes
35+ with ` video-show-actions ` . The cursor is the only one ` video-start --cursor ` turns on; the rest are
36+ opt-in and styled with plain CSS declarations, so they look exactly the way you want.
37+
38+ ``` bash
39+ # Cursor only, nothing else on screen
40+ playwright-cli video-start demo.webm --cursor
41+
42+ # Action callout, plus a red click point and a dark frame around the target
43+ playwright-cli video-show-actions --duration=800 --position=top-right \
44+ --point-style=" width: 20px; height: 20px; border-radius: 50%; background: rgba(255,0,0,.7)" \
45+ --highlight-style=" outline: 2px solid #333; background: rgba(0,128,255,.15)" \
46+ --title-style=" font-size: 16px"
47+
48+ # Stop annotating actions
49+ playwright-cli video-hide-actions
50+ ```
51+
52+ The same options are available programmatically, which is the better choice for hero scripts:
53+
54+ ``` js
55+ await page .screencast .showActions ({
56+ // 'pointer' (default) animates the cursor from the previous action point, 'none' hides it.
57+ cursor: ' pointer' ,
58+ // How long decorations stay on screen. Actions are paced by this delay, 500ms by default.
59+ duration: 800 ,
60+ // Where the action title goes: top-left, top, top-right, bottom-left, bottom, bottom-right.
61+ position: ' top-right' ,
62+ style: {
63+ // Marker at the click point. The element is zero-sized and centered on the point,
64+ // so give it a size, or draw around the point with box-shadow. Hidden when omitted.
65+ point: ' width: 20px; height: 20px; border-radius: 50%; background: rgba(255, 0, 0, .7)' ,
66+ // Box that covers the target element. Hidden when omitted.
67+ // Prefer `outline` over `border`, it does not shrink the box.
68+ highlight: ' outline: 2px solid #333; background: rgba(0, 128, 255, .15)' ,
69+ // The action title. Use 'display: none' to keep the cursor but drop the callout.
70+ title: ' font-size: 16px' ,
71+ },
72+ });
73+ ```
74+
75+ Notes:
76+ - All decorations fade out over ` duration ` . Override ` animation ` in a style to do something else.
77+ - The cursor stays on screen at the last action point between actions and across navigations,
78+ and travels along a slightly curved path, so it reads as a hand moving a mouse.
79+ - Call ` page.screencast.hideActions() ` to stop annotating and hide the cursor.
80+
3081## Best Practices
3182
3283### 1. Use Descriptive Filenames
@@ -50,7 +101,15 @@ It allows inserting appropriate pauses between the actions and annotating the vi
50101
51102``` js
52103async page => {
53- await page .screencast .start ({ path: ' video.webm' , size: { width: 1280 , height: 800 } });
104+ await page .screencast .start ({ path: ' video.webm' , size: { width: 1280 , height: 800 }, fps: 60 });
105+ // Show the cursor and mark the click point, and pace actions by 800ms.
106+ await page .screencast .showActions ({
107+ duration: 800 ,
108+ style: {
109+ point: ' width: 20px; height: 20px; border-radius: 50%; background: rgba(255, 0, 0, .7)' ,
110+ title: ' display: none' ,
111+ },
112+ });
54113 await page .goto (' https://demo.playwright.dev/todomvc' );
55114
56115 // Show a chapter card — blurs the page and shows a dialog.
@@ -127,6 +186,8 @@ Embrace creativity, overlays are powerful.
127186| ` page.screencast.showOverlay(html, { duration? }) ` | Custom HTML overlay — use for callouts, labels, highlights |
128187| ` disposable.dispose() ` | Remove a sticky overlay added without duration |
129188| ` page.screencast.hideOverlays() ` / ` page.screencast.showOverlays() ` | Temporarily hide/show all overlays |
189+ | ` page.screencast.showActions({ cursor, duration, position, style }) ` | Cursor, click point, target highlight and action title |
190+ | ` page.screencast.hideActions() ` | Stop annotating actions and hide the cursor |
130191
131192### 3. Attach the recording to the pull request
132193
0 commit comments