Skip to content

Commit 0c65a75

Browse files
pavelfeldmanpavelfeldman
committed
cherry-pick(#39968): chore: screencast.showActions api
1 parent f04155b commit 0c65a75

25 files changed

Lines changed: 577 additions & 168 deletions

File tree

‎docs/src/api/class-screencast.md‎

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -105,11 +105,40 @@ Optional description text displayed below the title.
105105

106106
Duration in milliseconds after which the overlay is automatically removed. Defaults to `2000`.
107107

108+
## async method: Screencast.showActions
109+
* since: v1.59
110+
- returns: <[Disposable]>
111+
112+
Enables visual annotations on interacted elements. Returns a disposable that stops showing actions when disposed.
113+
114+
### option: Screencast.showActions.duration
115+
* since: v1.59
116+
- `duration` ?<[float]>
117+
118+
How long each annotation is displayed in milliseconds. Defaults to `500`.
119+
120+
### option: Screencast.showActions.position
121+
* since: v1.59
122+
- `position` ?<[AnnotatePosition]<"top-left"|"top"|"top-right"|"bottom-left"|"bottom"|"bottom-right">>
123+
124+
Position of the action title overlay. Defaults to `"top-right"`.
125+
126+
### option: Screencast.showActions.fontSize
127+
* since: v1.59
128+
- `fontSize` ?<[int]>
129+
130+
Font size of the action title in pixels. Defaults to `24`.
131+
108132
## async method: Screencast.showOverlays
109133
* since: v1.59
110134

111135
Shows overlays.
112136

137+
## async method: Screencast.hideActions
138+
* since: v1.59
139+
140+
Removes action decorations.
141+
113142
## async method: Screencast.hideOverlays
114143
* since: v1.59
115144

‎docs/src/api/params.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -810,7 +810,7 @@ When set to `minimal`, only record information necessary for routing from HAR. T
810810
Actual picture of each page will be scaled down if necessary to fit the specified size.
811811
- `width` <[int]> Video frame width.
812812
- `height` <[int]> Video frame height.
813-
- `annotate` ?<[Object=VideoAnnotation]> If specified, enables visual annotations on interacted elements during video recording.
813+
- `showActions` ?<[Object=ShowActionsOptions]> If specified, enables visual annotations on interacted elements during video recording.
814814
- `duration` ?<[float]> How long each annotation is displayed in milliseconds. Defaults to `500`.
815815
- `position` ?<[AnnotatePosition]<"top-left"|"top"|"top-right"|"bottom-left"|"bottom"|"bottom-right">> Position of the action title overlay. Defaults to `"top-right"`.
816816
- `fontSize` ?<[int]> Font size of the action title in pixels. Defaults to `24`.

‎docs/src/release-notes-csharp.md‎

Lines changed: 6 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -33,13 +33,10 @@ await page.Screencast.StartAsync(new() {
3333
**Action annotations** — enable built-in visual annotations that highlight interacted elements and display action titles during recording:
3434

3535
```csharp
36-
await page.Screencast.StartAsync(new() {
37-
Path = "video.webm",
38-
Annotate = new() { Position = "top-right" },
39-
});
36+
await page.Screencast.ShowActionsAsync(new() { Position = "top-right" });
4037
```
4138

42-
The `Annotate` option accepts `Position` (`"top-left"`, `"top"`, `"top-right"`, `"bottom-left"`, `"bottom"`, `"bottom-right"`), `Duration` (ms per annotation), and `FontSize` (px).
39+
`ShowActionsAsync` accepts `Position` (`"top-left"`, `"top"`, `"top-right"`, `"bottom-left"`, `"bottom"`, `"bottom-right"`), `Duration` (ms per annotation), and `FontSize` (px). Returns a disposable to stop showing actions.
4340

4441
**Visual overlays** — add chapter titles and custom HTML overlays on top of the page for richer narration:
4542

@@ -55,10 +52,8 @@ await page.Screencast.ShowOverlayAsync("<div style=\"color: red\">Recording</div
5552
**Agentic video receipts** — coding agents can produce video evidence of their work. After completing a task, an agent can record a walkthrough video with rich annotations for human review:
5653

5754
```csharp
58-
await page.Screencast.StartAsync(new() {
59-
Path = "receipt.webm",
60-
Annotate = new() { Position = "top-right" },
61-
});
55+
await page.Screencast.StartAsync(new() { Path = "receipt.webm" });
56+
await page.Screencast.ShowActionsAsync(new() { Position = "top-right" });
6257

6358
await page.Screencast.ShowChapterAsync("Verifying checkout flow", new() {
6459
Description = "Added coupon code support per ticket #1234",
@@ -91,7 +86,8 @@ The resulting video serves as a receipt: chapter titles provide context, action
9186

9287
- [`property: Page.screencast`] provides video recording, real-time frame streaming, and overlay management.
9388
- Methods [`method: Screencast.start`] and [`method: Screencast.stop`] for recording and frame capture.
94-
- Methods [`method: Screencast.showChapter`] and [`method: Screencast.showOverlay`] for visual annotations.
89+
- Methods [`method: Screencast.showActions`] and [`method: Screencast.hideActions`] for action annotations.
90+
- Methods [`method: Screencast.showChapter`] and [`method: Screencast.showOverlay`] for visual overlays.
9591
- Methods [`method: Screencast.showOverlays`] and [`method: Screencast.hideOverlays`] for overlay visibility control.
9692

9793
#### Storage, Console and Errors

‎docs/src/release-notes-java.md‎

Lines changed: 6 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -32,12 +32,10 @@ page.screencast().start(new Screencast.StartOptions()
3232
**Action annotations** — enable built-in visual annotations that highlight interacted elements and display action titles during recording:
3333

3434
```java
35-
page.screencast().start(new Screencast.StartOptions()
36-
.setPath(Paths.get("video.webm"))
37-
.setAnnotate(new Screencast.Annotate().setPosition("top-right")));
35+
page.screencast().showActions(new Screencast.ShowActionsOptions().setPosition("top-right"));
3836
```
3937

40-
The `annotate` option accepts `position` (`"top-left"`, `"top"`, `"top-right"`, `"bottom-left"`, `"bottom"`, `"bottom-right"`), `duration` (ms per annotation), and `fontSize` (px).
38+
[`method: Screencast.showActions`] accepts `position` (`"top-left"`, `"top"`, `"top-right"`, `"bottom-left"`, `"bottom"`, `"bottom-right"`), `duration` (ms per annotation), and `fontSize` (px). Returns a disposable to stop showing actions.
4139

4240
**Visual overlays** — add chapter titles and custom HTML overlays on top of the page for richer narration:
4341

@@ -54,8 +52,8 @@ page.screencast().showOverlay("<div style=\"color: red\">Recording</div>");
5452

5553
```java
5654
page.screencast().start(new Screencast.StartOptions()
57-
.setPath(Paths.get("receipt.webm"))
58-
.setAnnotate(new Screencast.Annotate().setPosition("top-right")));
55+
.setPath(Paths.get("receipt.webm")));
56+
page.screencast().showActions(new Screencast.ShowActionsOptions().setPosition("top-right"));
5957

6058
page.screencast().showChapter("Verifying checkout flow",
6159
new Screencast.ShowChapterOptions()
@@ -88,7 +86,8 @@ The resulting video serves as a receipt: chapter titles provide context, action
8886

8987
- [`property: Page.screencast`] provides video recording, real-time frame streaming, and overlay management.
9088
- Methods [`method: Screencast.start`] and [`method: Screencast.stop`] for recording and frame capture.
91-
- Methods [`method: Screencast.showChapter`] and [`method: Screencast.showOverlay`] for visual annotations.
89+
- Methods [`method: Screencast.showActions`] and [`method: Screencast.hideActions`] for action annotations.
90+
- Methods [`method: Screencast.showChapter`] and [`method: Screencast.showOverlay`] for visual overlays.
9291
- Methods [`method: Screencast.showOverlays`] and [`method: Screencast.hideOverlays`] for overlay visibility control.
9392

9493
#### Storage, Console and Errors

‎docs/src/release-notes-js.md‎

Lines changed: 23 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -34,13 +34,27 @@ await page.screencast.start({
3434
**Action annotations** — enable built-in visual annotations that highlight interacted elements and display action titles during recording:
3535

3636
```js
37-
await page.screencast.start({
38-
path: 'video.webm',
39-
annotate: { position: 'top-right' },
40-
});
37+
await page.screencast.showActions({ position: 'top-right' });
4138
```
4239

43-
The `annotate` option accepts `position` (`'top-left'`, `'top'`, `'top-right'`, `'bottom-left'`, `'bottom'`, `'bottom-right'`), `duration` (ms per annotation), and `fontSize` (px).
40+
[`method: Screencast.showActions`] accepts `position` (`'top-left'`, `'top'`, `'top-right'`, `'bottom-left'`, `'bottom'`, `'bottom-right'`), `duration` (ms per annotation), and `fontSize` (px). Returns a disposable to stop showing actions.
41+
42+
Action annotations can also be enabled in test fixtures via the `video` option:
43+
44+
```js
45+
// playwright.config.ts
46+
export default defineConfig({
47+
use: {
48+
video: {
49+
mode: 'on',
50+
show: {
51+
actions: { position: 'top-left' },
52+
test: { position: 'top-right' },
53+
},
54+
},
55+
},
56+
});
57+
```
4458

4559
**Visual overlays** — add chapter titles and custom HTML overlays on top of the page for richer narration:
4660

@@ -56,10 +70,8 @@ await page.screencast.showOverlay('<div style="color: red">Recording</div>');
5670
**Agentic video receipts** — coding agents can produce video evidence of their work. After completing a task, an agent can record a walkthrough video with rich annotations for human review:
5771

5872
```js
59-
await page.screencast.start({
60-
path: 'receipt.webm',
61-
annotate: { position: 'top-right' },
62-
});
73+
await page.screencast.start({ path: 'receipt.webm' });
74+
await page.screencast.showActions({ position: 'top-right' });
6375

6476
await page.screencast.showChapter('Verifying checkout flow', {
6577
description: 'Added coupon code support per ticket #1234',
@@ -162,7 +174,8 @@ await using page = await context.newPage();
162174

163175
- [`property: Page.screencast`] provides video recording, real-time frame streaming, and overlay management.
164176
- Methods [`method: Screencast.start`] and [`method: Screencast.stop`] for recording and frame capture.
165-
- Methods [`method: Screencast.showChapter`] and [`method: Screencast.showOverlay`] for visual annotations.
177+
- Methods [`method: Screencast.showActions`] and [`method: Screencast.hideActions`] for action annotations.
178+
- Methods [`method: Screencast.showChapter`] and [`method: Screencast.showOverlay`] for visual overlays.
166179
- Methods [`method: Screencast.showOverlays`] and [`method: Screencast.hideOverlays`] for overlay visibility control.
167180

168181
#### Storage, Console and Errors

‎docs/src/release-notes-python.md‎

Lines changed: 6 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -33,13 +33,10 @@ page.screencast.start(
3333
**Action annotations** — enable built-in visual annotations that highlight interacted elements and display action titles during recording:
3434

3535
```python
36-
page.screencast.start(
37-
path="video.webm",
38-
annotate={"position": "top-right"},
39-
)
36+
page.screencast.show_actions(position="top-right")
4037
```
4138

42-
The `annotate` option accepts `position` (`'top-left'`, `'top'`, `'top-right'`, `'bottom-left'`, `'bottom'`, `'bottom-right'`), `duration` (ms per annotation), and `font_size` (px).
39+
[`method: Screencast.showActions`] accepts `position` (`'top-left'`, `'top'`, `'top-right'`, `'bottom-left'`, `'bottom'`, `'bottom-right'`), `duration` (ms per annotation), and `font_size` (px). Returns a disposable to stop showing actions.
4340

4441
**Visual overlays** — add chapter titles and custom HTML overlays on top of the page for richer narration:
4542

@@ -55,10 +52,8 @@ page.screencast.show_overlay('<div style="color: red">Recording</div>')
5552
**Agentic video receipts** — coding agents can produce video evidence of their work. After completing a task, an agent can record a walkthrough video with rich annotations for human review:
5653

5754
```python
58-
page.screencast.start(
59-
path="receipt.webm",
60-
annotate={"position": "top-right"},
61-
)
55+
page.screencast.start(path="receipt.webm")
56+
page.screencast.show_actions(position="top-right")
6257

6358
page.screencast.show_chapter("Verifying checkout flow",
6459
description="Added coupon code support per ticket #1234",
@@ -91,7 +86,8 @@ The resulting video serves as a receipt: chapter titles provide context, action
9186

9287
- [`property: Page.screencast`] provides video recording, real-time frame streaming, and overlay management.
9388
- Methods [`method: Screencast.start`] and [`method: Screencast.stop`] for recording and frame capture.
94-
- Methods [`method: Screencast.showChapter`] and [`method: Screencast.showOverlay`] for visual annotations.
89+
- Methods [`method: Screencast.showActions`] and [`method: Screencast.hideActions`] for action annotations.
90+
- Methods [`method: Screencast.showChapter`] and [`method: Screencast.showOverlay`] for visual overlays.
9591
- Methods [`method: Screencast.showOverlays`] and [`method: Screencast.hideOverlays`] for overlay visibility control.
9692

9793
#### Storage, Console and Errors

‎docs/src/test-api/class-testoptions.md‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -625,8 +625,8 @@ export default defineConfig({
625625
- `size` ?<[Object]> Size of the recorded video. Optional.
626626
- `width` <[int]>
627627
- `height` <[int]>
628-
- `annotate` ?<[Object]> If specified, visually annotates the video with test information and action highlights.
629-
- `action` ?<[Object]> Controls visual annotations on interacted elements.
628+
- `show` ?<[Object]> If specified, visually annotates the video with test information and action highlights.
629+
- `actions` ?<[Object]> Controls visual annotations on interacted elements.
630630
- `duration` ?<[float]> How long each annotation is displayed in milliseconds. Defaults to `500`.
631631
- `position` ?<[AnnotatePosition]<"top-left"|"top"|"top-right"|"bottom-left"|"bottom"|"bottom-right">> Position of the action title overlay. Defaults to `"top-right"`.
632632
- `fontSize` ?<[int]> Font size of the action title in pixels. Defaults to `24`.
@@ -643,7 +643,7 @@ Whether to record video for each test. Defaults to `'off'`.
643643

644644
To control video size, pass an object with `mode` and `size` properties. If video size is not specified, it will be equal to [`property: TestOptions.viewport`] scaled down to fit into 800x800. If `viewport` is not configured explicitly the video size defaults to 800x450. Actual picture of each page will be scaled down if necessary to fit the specified size.
645645

646-
To annotate actions in the video, pass `annotate` with `action` and/or `test` sub-options. The `action` option controls visual highlights on interacted elements with an optional `delay` in milliseconds (defaults to `500`). The `test` option controls which test information is displayed as a status overlay.
646+
To annotate actions in the video, pass `show` with `action` and/or `test` sub-options. The `action` option controls visual highlights on interacted elements with an optional `delay` in milliseconds (defaults to `500`). The `test` option controls which test information is displayed as a status overlay.
647647

648648
**Usage**
649649

‎docs/src/videos.md‎

Lines changed: 5 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -38,7 +38,9 @@ await context.close();
3838

3939
You can also specify video size and annotation. The video size defaults to the viewport size scaled down to fit 800x800. The video of the viewport is placed in the top-left corner of the output video, scaled down to fit if necessary. You may need to set the viewport size to match your desired video size.
4040

41-
When `annotate` is specified, each action will be visually highlighted in the video with the element outline and action title subtitle. The optional `duration` property controls how long each annotation is displayed (defaults to `500`ms).
41+
When `show: { actions }` is specified, each action will be visually highlighted in the video with the element outline and action title subtitle. The optional `duration` property controls how long each annotation is displayed (defaults to `500`ms).
42+
43+
When `show: { test }` is specified, video will be annotated with the current test information with configurable `level`.
4244

4345
```js title="playwright.config.ts"
4446
import { defineConfig } from '@playwright/test';
@@ -47,8 +49,8 @@ export default defineConfig({
4749
video: {
4850
mode: 'on-first-retry',
4951
size: { width: 640, height: 480 },
50-
annotate: {
51-
action: {
52+
show: {
53+
actions: {
5254
duration: 500,
5355
position: 'top-right',
5456
fontSize: 14,

‎examples/todomvc/playwright.config.ts‎

Lines changed: 9 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -46,8 +46,15 @@ export default defineConfig({
4646
// baseURL: 'http://localhost:3000',
4747

4848
/* Collect trace when retrying the failed test. See https://playwright.dev/docs/trace-viewer */
49-
trace: 'on',
50-
video: 'on',
49+
trace: 'on-first-retry',
50+
51+
video: {
52+
mode: 'on',
53+
show: {
54+
actions: { position: 'top-left' },
55+
test: { position: 'top-right' },
56+
},
57+
},
5158
},
5259

5360
/* Configure projects for major browsers */

‎packages/playwright-client/types/types.d.ts‎

Lines changed: 31 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -10197,7 +10197,7 @@ export interface Browser {
1019710197
/**
1019810198
* If specified, enables visual annotations on interacted elements during video recording.
1019910199
*/
10200-
annotate?: {
10200+
showActions?: {
1020110201
/**
1020210202
* How long each annotation is displayed in milliseconds. Defaults to `500`.
1020310203
*/
@@ -15496,7 +15496,7 @@ export interface BrowserType<Unused = {}> {
1549615496
/**
1549715497
* If specified, enables visual annotations on interacted elements during video recording.
1549815498
*/
15499-
annotate?: {
15499+
showActions?: {
1550015500
/**
1550115501
* How long each annotation is displayed in milliseconds. Defaults to `500`.
1550215502
*/
@@ -16225,11 +16225,37 @@ export interface Screencast {
1622516225
fontSize?: number;
1622616226
};
1622716227
}): Promise<Disposable>;
16228+
/**
16229+
* Removes action decorations.
16230+
*/
16231+
hideActions(): Promise<void>;
16232+
1622816233
/**
1622916234
* Hides overlays without removing them.
1623016235
*/
1623116236
hideOverlays(): Promise<void>;
1623216237

16238+
/**
16239+
* Enables visual annotations on interacted elements. Returns a disposable that stops showing actions when disposed.
16240+
* @param options
16241+
*/
16242+
showActions(options?: {
16243+
/**
16244+
* How long each annotation is displayed in milliseconds. Defaults to `500`.
16245+
*/
16246+
duration?: number;
16247+
16248+
/**
16249+
* Font size of the action title in pixels. Defaults to `24`.
16250+
*/
16251+
fontSize?: number;
16252+
16253+
/**
16254+
* Position of the action title overlay. Defaults to `"top-right"`.
16255+
*/
16256+
position?: "top-left"|"top"|"top-right"|"bottom-left"|"bottom"|"bottom-right";
16257+
}): Promise<Disposable>;
16258+
1623316259
/**
1623416260
* Shows a chapter overlay with a title and optional description, centered on the page with a blurred backdrop. Useful
1623516261
* for narrating video recordings. The overlay is removed after the specified duration, or 2000ms.
@@ -17441,7 +17467,7 @@ export interface AndroidDevice {
1744117467
/**
1744217468
* If specified, enables visual annotations on interacted elements during video recording.
1744317469
*/
17444-
annotate?: {
17470+
showActions?: {
1744517471
/**
1744617472
* How long each annotation is displayed in milliseconds. Defaults to `500`.
1744717473
*/
@@ -20049,7 +20075,7 @@ export interface Electron {
2004920075
/**
2005020076
* If specified, enables visual annotations on interacted elements during video recording.
2005120077
*/
20052-
annotate?: {
20078+
showActions?: {
2005320079
/**
2005420080
* How long each annotation is displayed in milliseconds. Defaults to `500`.
2005520081
*/
@@ -23022,7 +23048,7 @@ export interface BrowserContextOptions {
2302223048
/**
2302323049
* If specified, enables visual annotations on interacted elements during video recording.
2302423050
*/
23025-
annotate?: {
23051+
showActions?: {
2302623052
/**
2302723053
* How long each annotation is displayed in milliseconds. Defaults to `500`.
2302823054
*/

0 commit comments

Comments
 (0)