Skip to content

Playwright is a framework for Web Testing and Automation. It allows testing Chromium, Firefox and WebKit with a single API.

chore: screencast.showActions api (#39968)

Pavel Feldman9149caf40a1a
diff --git a/docs/src/api/class-screencast.md b/docs/src/api/class-screencast.md
index 435dd5041c..8a0be7261f 100644
--- a/docs/src/api/class-screencast.md
+++ b/docs/src/api/class-screencast.md
@@ -105,11 +105,40 @@ Optional description text displayed below the title.
Duration in milliseconds after which the overlay is automatically removed. Defaults to `2000`.
+## async method: Screencast.showActions
+* since: v1.59
+- returns: <[Disposable]>
+
+Enables visual annotations on interacted elements. Returns a disposable that stops showing actions when disposed.
+
+### option: Screencast.showActions.duration
+* since: v1.59
+- `duration` ?<[float]>
+
+How long each annotation is displayed in milliseconds. Defaults to `500`.
+
+### option: Screencast.showActions.position
+* since: v1.59
+- `position` ?<[AnnotatePosition]<"top-left"|"top"|"top-right"|"bottom-left"|"bottom"|"bottom-right">>
+
+Position of the action title overlay. Defaults to `"top-right"`.
+
+### option: Screencast.showActions.fontSize
+* since: v1.59
+- `fontSize` ?<[int]>
+
+Font size of the action title in pixels. Defaults to `24`.
+
## async method: Screencast.showOverlays
* since: v1.59
Shows overlays.
+## async method: Screencast.hideActions
+* since: v1.59
+
+Removes action decorations.
+
## async method: Screencast.hideOverlays
* since: v1.59
diff --git a/docs/src/api/params.md b/docs/src/api/params.md
index e2d6de0682..391504655c 100644
--- a/docs/src/api/params.md
+++ b/docs/src/api/params.md
@@ -810,7 +810,7 @@ When set to `minimal`, only record information necessary for routing from HAR. T
Actual picture of each page will be scaled down if necessary to fit the specified size.
- `width` <[int]> Video frame width.
- `height` <[int]> Video frame height.
- - `annotate` ?<[Object=VideoAnnotation]> If specified, enables visual annotations on interacted elements during video recording.
+ - `showActions` ?<[Object=ShowActionsOptions]> If specified, enables visual annotations on interacted elements during video recording.
- `duration` ?<[float]> How long each annotation is displayed in milliseconds. Defaults to `500`.
- `position` ?<[AnnotatePosition]<"top-left"|"top"|"top-right"|"bottom-left"|"bottom"|"bottom-right">> Position of the action title overlay. Defaults to `"top-right"`.
- `fontSize` ?<[int]> Font size of the action title in pixels. Defaults to `24`.
diff --git a/docs/src/release-notes-csharp.md b/docs/src/release-notes-csharp.md
index beed46b9e2..cc78828d17 100644
--- a/docs/src/release-notes-csharp.md
+++ b/docs/src/release-notes-csharp.md
@@ -33,13 +33,10 @@ await page.Screencast.StartAsync(new() {
**Action annotations** — enable built-in visual annotations that highlight interacted elements and display action titles during recording:
```csharp
-await page.Screencast.StartAsync(new() {
- Path = "video.webm",
- Annotate = new() { Position = "top-right" },
-});
+await page.Screencast.ShowActionsAsync(new() { Position = "top-right" });
```
-The `Annotate` option accepts `Position` (`"top-left"`, `"top"`, `"top-right"`, `"bottom-left"`, `"bottom"`, `"bottom-right"`), `Duration` (ms per annotation), and `FontSize` (px).
+`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.
**Visual overlays** — add chapter titles and custom HTML overlays on top of the page for richer narration:
@@ -55,10 +52,8 @@ await page.Screencast.ShowOverlayAsync("<div style=\"color: red\">Recording</div
**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:
```csharp
-await page.Screencast.StartAsync(new() {
- Path = "receipt.webm",
- Annotate = new() { Position = "top-right" },
-});
+await page.Screencast.StartAsync(new() { Path = "receipt.webm" });
+await page.Screencast.ShowActionsAsync(new() { Position = "top-right" });
await page.Screencast.ShowChapterAsync("Verifying checkout flow", new() {
Description = "Added coupon code support per ticket #1234",
@@ -91,7 +86,8 @@ The resulting video serves as a receipt: chapter titles provide context, action
- [`property: Page.screencast`] provides video recording, real-time frame streaming, and overlay management.
- Methods [`method: Screencast.start`] and [`method: Screencast.stop`] for recording and frame capture.
-- Methods [`method: Screencast.showChapter`] and [`method: Screencast.showOverlay`] for visual annotations.
+- Methods [`method: Screencast.showActions`] and [`method: Screencast.hideActions`] for action annotations.
+- Methods [`method: Screencast.showChapter`] and [`method: Screencast.showOverlay`] for visual overlays.
- Methods [`method: Screencast.showOverlays`] and [`method: Screencast.hideOverlays`] for overlay visibility control.
#### Storage, Console and Errors
diff --git a/docs/src/release-notes-java.md b/docs/src/release-notes-java.md
index 81c3c1f1a9..27b103ad9f 100644
--- a/docs/src/release-notes-java.md
+++ b/docs/src/release-notes-java.md
@@ -32,12 +32,10 @@ page.screencast().start(new Screencast.StartOptions()
**Action annotations** — enable built-in visual annotations that highlight interacted elements and display action titles during recording:
```java
-page.screencast().start(new Screencast.StartOptions()
- .setPath(Paths.get("video.webm"))
- .setAnnotate(new Screencast.Annotate().setPosition("top-right")));
+page.screencast().showActions(new Screencast.ShowActionsOptions().setPosition("top-right"));
```
-The `annotate` option accepts `position` (`"top-left"`, `"top"`, `"top-right"`, `"bottom-left"`, `"bottom"`, `"bottom-right"`), `duration` (ms per annotation), and `fontSize` (px).
+[`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.
**Visual overlays** — add chapter titles and custom HTML overlays on top of the page for richer narration:
@@ -54,8 +52,8 @@ page.screencast().showOverlay("<div style=\"color: red\">Recording</div>");
```java
page.screencast().start(new Screencast.StartOptions()
- .setPath(Paths.get("receipt.webm"))
- .setAnnotate(new Screencast.Annotate().setPosition("top-right")));
+ .setPath(Paths.get("receipt.webm")));
+page.screencast().showActions(new Screencast.ShowActionsOptions().setPosition("top-right"));
page.screencast().showChapter("Verifying checkout flow",
new Screencast.ShowChapterOptions()
@@ -88,7 +86,8 @@ The resulting video serves as a receipt: chapter titles provide context, action
- [`property: Page.screencast`] provides video recording, real-time frame streaming, and overlay management.
- Methods [`method: Screencast.start`] and [`method: Screencast.stop`] for recording and frame capture.
-- Methods [`method: Screencast.showChapter`] and [`method: Screencast.showOverlay`] for visual annotations.
+- Methods [`method: Screencast.showActions`] and [`method: Screencast.hideActions`] for action annotations.
+- Methods [`method: Screencast.showChapter`] and [`method: Screencast.showOverlay`] for visual overlays.
- Methods [`method: Screencast.showOverlays`] and [`method: Screencast.hideOverlays`] for overlay visibility control.
#### Storage, Console and Errors
diff --git a/docs/src/release-notes-js.md b/docs/src/release-notes-js.md
index 083df54931..4e08228c94 100644
--- a/docs/src/release-notes-js.md
+++ b/docs/src/release-notes-js.md
@@ -34,13 +34,27 @@ await page.screencast.start({
**Action annotations** — enable built-in visual annotations that highlight interacted elements and display action titles during recording:
```js
-await page.screencast.start({
- path: 'video.webm',
- annotate: { position: 'top-right' },
-});
+await page.screencast.showActions({ position: 'top-right' });
```
-The `annotate` option accepts `position` (`'top-left'`, `'top'`, `'top-right'`, `'bottom-left'`, `'bottom'`, `'bottom-right'`), `duration` (ms per annotation), and `fontSize` (px).
+[`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.
+
+Action annotations can also be enabled in test fixtures via the `video` option:
+
+```js
+// playwright.config.ts
+export default defineConfig({
+ use: {
+ video: {
+ mode: 'on',
+ show: {
+ actions: { position: 'top-left' },
+ test: { position: 'top-right' },
+ },
+ },
+ },
+});
+```
**Visual overlays** — add chapter titles and custom HTML overlays on top of the page for richer narration:
@@ -56,10 +70,8 @@ await page.screencast.showOverlay('<div style="color: red">Recording</div>');
**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:
```js
-await page.screencast.start({
- path: 'receipt.webm',
- annotate: { position: 'top-right' },
-});
+await page.screencast.start({ path: 'receipt.webm' });
+await page.screencast.showActions({ position: 'top-right' });
await page.screencast.showChapter('Verifying checkout flow', {
description: 'Added coupon code support per ticket #1234',
@@ -162,7 +174,8 @@ await using page = await context.newPage();
- [`property: Page.screencast`] provides video recording, real-time frame streaming, and overlay management.
- Methods [`method: Screencast.start`] and [`method: Screencast.stop`] for recording and frame capture.
-- Methods [`method: Screencast.showChapter`] and [`method: Screencast.showOverlay`] for visual annotations.
+- Methods [`method: Screencast.showActions`] and [`method: Screencast.hideActions`] for action annotations.
+- Methods [`method: Screencast.showChapter`] and [`method: Screencast.showOverlay`] for visual overlays.
- Methods [`method: Screencast.showOverlays`] and [`method: Screencast.hideOverlays`] for overlay visibility control.
#### Storage, Console and Errors
diff --git a/docs/src/release-notes-python.md b/docs/src/release-notes-python.md
index 41745ad3c6..1d4e237879 100644
--- a/docs/src/release-notes-python.md
+++ b/docs/src/release-notes-python.md
@@ -33,13 +33,10 @@ page.screencast.start(
**Action annotations** — enable built-in visual annotations that highlight interacted elements and display action titles during recording:
```python
-page.screencast.start(
- path="video.webm",
- annotate={"position": "top-right"},
-)
+page.screencast.show_actions(position="top-right")
```
-The `annotate` option accepts `position` (`'top-left'`, `'top'`, `'top-right'`, `'bottom-left'`, `'bottom'`, `'bottom-right'`), `duration` (ms per annotation), and `font_size` (px).
+[`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.
**Visual overlays** — add chapter titles and custom HTML overlays on top of the page for richer narration:
@@ -55,10 +52,8 @@ page.screencast.show_overlay('<div style="color: red">Recording</div>')
**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:
```python
-page.screencast.start(
- path="receipt.webm",
- annotate={"position": "top-right"},
-)
+page.screencast.start(path="receipt.webm")
+page.screencast.show_actions(position="top-right")
page.screencast.show_chapter("Verifying checkout flow",
description="Added coupon code support per ticket #1234",
@@ -91,7 +86,8 @@ The resulting video serves as a receipt: chapter titles provide context, action
- [`property: Page.screencast`] provides video recording, real-time frame streaming, and overlay management.
- Methods [`method: Screencast.start`] and [`method: Screencast.stop`] for recording and frame capture.
-- Methods [`method: Screencast.showChapter`] and [`method: Screencast.showOverlay`] for visual annotations.
+- Methods [`method: Screencast.showActions`] and [`method: Screencast.hideActions`] for action annotations.
+- Methods [`method: Screencast.showChapter`] and [`method: Screencast.showOverlay`] for visual overlays.
- Methods [`method: Screencast.showOverlays`] and [`method: Screencast.hideOverlays`] for overlay visibility control.
#### Storage, Console and Errors
diff --git a/docs/src/test-api/class-testoptions.md b/docs/src/test-api/class-testoptions.md
index 922db3bb9f..fdd5b13cb7 100644
--- a/docs/src/test-api/class-testoptions.md
+++ b/docs/src/test-api/class-testoptions.md
@@ -625,8 +625,8 @@ export default defineConfig({
- `size` ?<[Object]> Size of the recorded video. Optional.
- `width` <[int]>
- `height` <[int]>
- - `annotate` ?<[Object]> If specified, visually annotates the video with test information and action highlights.
- - `action` ?<[Object]> Controls visual annotations on interacted elements.
+ - `show` ?<[Object]> If specified, visually annotates the video with test information and action highlights.
+ - `actions` ?<[Object]> Controls visual annotations on interacted elements.
- `duration` ?<[float]> How long each annotation is displayed in milliseconds. Defaults to `500`.
- `position` ?<[AnnotatePosition]<"top-left"|"top"|"top-right"|"bottom-left"|"bottom"|"bottom-right">> Position of the action title overlay. Defaults to `"top-right"`.
- `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'`.
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.
-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.
+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.
**Usage**
diff --git a/docs/src/videos.md b/docs/src/videos.md
index 6d1a59f9e7..07e1c32210 100644
--- a/docs/src/videos.md
+++ b/docs/src/videos.md
@@ -38,7 +38,9 @@ await context.close();
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.
-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).
+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).
+
+When `show: { test }` is specified, video will be annotated with the current test information with configurable `level`.
```js title="playwright.config.ts"
import { defineConfig } from '@playwright/test';
@@ -47,8 +49,8 @@ export default defineConfig({
video: {
mode: 'on-first-retry',
size: { width: 640, height: 480 },
- annotate: {
- action: {
+ show: {
+ actions: {
duration: 500,
position: 'top-right',
fontSize: 14,
diff --git a/examples/todomvc/playwright.config.ts b/examples/todomvc/playwright.config.ts
index 403a0e5ce6..94db99302e 100644
--- a/examples/todomvc/playwright.config.ts
+++ b/examples/todomvc/playwright.config.ts
@@ -46,8 +46,15 @@ export default defineConfig({
// baseURL: 'http://localhost:3000',
/* Collect trace when retrying the failed test. See https://playwright.dev/docs/trace-viewer */
- trace: 'on',
- video: 'on',
+ trace: 'on-first-retry',
+
+ video: {
+ mode: 'on',
+ show: {
+ actions: { position: 'top-left' },
+ test: { position: 'top-right' },
+ },
+ },
},
/* Configure projects for major browsers */
diff --git a/packages/playwright-client/types/types.d.ts b/packages/playwright-client/types/types.d.ts
index afd509576b..637fa2b031 100644
--- a/packages/playwright-client/types/types.d.ts
+++ b/packages/playwright-client/types/types.d.ts
@@ -10197,7 +10197,7 @@ export interface Browser {
/**
* If specified, enables visual annotations on interacted elements during video recording.
*/
- annotate?: {
+ showActions?: {
/**
* How long each annotation is displayed in milliseconds. Defaults to `500`.
*/
@@ -15496,7 +15496,7 @@ export interface BrowserType<Unused = {}> {
/**
* If specified, enables visual annotations on interacted elements during video recording.
*/
- annotate?: {
+ showActions?: {
/**
* How long each annotation is displayed in milliseconds. Defaults to `500`.
*/
@@ -16225,11 +16225,37 @@ export interface Screencast {
fontSize?: number;
};
}): Promise<Disposable>;
+ /**
+ * Removes action decorations.
+ */
+ hideActions(): Promise<void>;
+
/**
* Hides overlays without removing them.
*/
hideOverlays(): Promise<void>;
+ /**
+ * Enables visual annotations on interacted elements. Returns a disposable that stops showing actions when disposed.
+ * @param options
+ */
+ showActions(options?: {
+ /**
+ * How long each annotation is displayed in milliseconds. Defaults to `500`.
+ */
+ duration?: number;
+
+ /**
+ * Font size of the action title in pixels. Defaults to `24`.
+ */
+ fontSize?: number;
+
+ /**
+ * Position of the action title overlay. Defaults to `"top-right"`.
+ */
+ position?: "top-left"|"top"|"top-right"|"bottom-left"|"bottom"|"bottom-right";
+ }): Promise<Disposable>;
+
/**
* Shows a chapter overlay with a title and optional description, centered on the page with a blurred backdrop. Useful
* for narrating video recordings. The overlay is removed after the specified duration, or 2000ms.
@@ -17441,7 +17467,7 @@ export interface AndroidDevice {
/**
* If specified, enables visual annotations on interacted elements during video recording.
*/
- annotate?: {
+ showActions?: {
/**
* How long each annotation is displayed in milliseconds. Defaults to `500`.
*/
@@ -20049,7 +20075,7 @@ export interface Electron {
/**
* If specified, enables visual annotations on interacted elements during video recording.
*/
- annotate?: {
+ showActions?: {
/**
* How long each annotation is displayed in milliseconds. Defaults to `500`.
*/
@@ -23022,7 +23048,7 @@ export interface BrowserContextOptions {
/**
* If specified, enables visual annotations on interacted elements during video recording.
*/
- annotate?: {
+ showActions?: {
/**
* How long each annotation is displayed in milliseconds. Defaults to `500`.
*/
diff --git a/packages/playwright-core/src/client/screencast.ts b/packages/playwright-core/src/client/screencast.ts
index e85203b292..83c21db702 100644
--- a/packages/playwright-core/src/client/screencast.ts
+++ b/packages/playwright-core/src/client/screencast.ts
@@ -19,7 +19,6 @@ import { DisposableStub } from './disposable';
import type * as api from '../../types/types';
import type { Page } from './page';
-import type { AnnotateOptions } from './types';
export class Screencast implements api.Screencast {
private _page: Page;
@@ -35,7 +34,7 @@ export class Screencast implements api.Screencast {
});
}
- async start(options: { onFrame?: (frame: { data: Buffer }) => Promise<any>|any, path?: string, size?: { width: number, height: number }, quality?: number, annotate?: AnnotateOptions } = {}): Promise<DisposableStub> {
+ async start(options: { onFrame?: (frame: { data: Buffer }) => Promise<any>|any, path?: string, size?: { width: number, height: number }, quality?: number } = {}): Promise<DisposableStub> {
if (this._started)
throw new Error('Screencast is already started');
this._started = true;
@@ -46,7 +45,6 @@ export class Screencast implements api.Screencast {
quality: options.quality,
sendFrames: !!options.onFrame,
record: !!options.path,
- annotate: options.annotate,
});
if (result.artifact) {
this._artifact = Artifact.from(result.artifact);
@@ -67,20 +65,29 @@ export class Screencast implements api.Screencast {
});
}
+ async showActions(options?: { duration?: number, position?: 'top-left' | 'top' | 'top-right' | 'bottom-left' | 'bottom' | 'bottom-right', fontSize?: number }): Promise<DisposableStub> {
+ await this._page._channel.screencastShowActions({ duration: options?.duration, position: options?.position, fontSize: options?.fontSize });
+ return new DisposableStub(() => this._page._channel.screencastHideActions());
+ }
+
+ async hideActions(): Promise<void> {
+ await this._page._channel.screencastHideActions();
+ }
+
async showOverlay(html: string, options?: { duration?: number }): Promise<DisposableStub> {
- const { id } = await this._page._channel.overlayShow({ html, duration: options?.duration });
- return new DisposableStub(() => this._page._channel.overlayRemove({ id }));
+ const { id } = await this._page._channel.screencastShowOverlay({ html, duration: options?.duration });
+ return new DisposableStub(() => this._page._channel.screencastRemoveOverlay({ id }));
}
async showChapter(title: string, options?: { description?: string, duration?: number }): Promise<void> {
- await this._page._channel.overlayChapter({ title, ...options });
+ await this._page._channel.screencastChapter({ title, ...options });
}
async showOverlays(): Promise<void> {
- await this._page._channel.overlaySetVisible({ visible: true });
+ await this._page._channel.screencastSetOverlayVisible({ visible: true });
}
async hideOverlays(): Promise<void> {
- await this._page._channel.overlaySetVisible({ visible: false });
+ await this._page._channel.screencastSetOverlayVisible({ visible: false });
}
}
diff --git a/packages/playwright-core/src/protocol/validator.ts b/packages/playwright-core/src/protocol/validator.ts
index d34aeb7424..9389553c93 100644
--- a/packages/playwright-core/src/protocol/validator.ts
+++ b/packages/playwright-core/src/protocol/validator.ts
@@ -50,11 +50,6 @@ scheme.Rect = tObject({
width: tFloat,
height: tFloat,
});
-scheme.AnnotateOptions = tObject({
- duration: tOptional(tFloat),
- position: tOptional(tEnum(['top-left', 'top', 'top-right', 'bottom-left', 'bottom', 'bottom-right'])),
- fontSize: tOptional(tInt),
-});
scheme.SerializedValue = tObject({
n: tOptional(tFloat),
b: tOptional(tBoolean),
@@ -616,7 +611,11 @@ scheme.BrowserTypeLaunchPersistentContextParams = tObject({
width: tInt,
height: tInt,
})),
- annotate: tOptional(tType('AnnotateOptions')),
+ showActions: tOptional(tObject({
+ duration: tOptional(tFloat),
+ position: tOptional(tEnum(['top-left', 'top', 'top-right', 'bottom-left', 'bottom', 'bottom-right'])),
+ fontSize: tOptional(tInt),
+ })),
})),
strictSelectors: tOptional(tBoolean),
serviceWorkers: tOptional(tEnum(['allow', 'block'])),
@@ -728,7 +727,11 @@ scheme.BrowserNewContextParams = tObject({
width: tInt,
height: tInt,
})),
- annotate: tOptional(tType('AnnotateOptions')),
+ showActions: tOptional(tObject({
+ duration: tOptional(tFloat),
+ position: tOptional(tEnum(['top-left', 'top', 'top-right', 'bottom-left', 'bottom', 'bottom-right'])),
+ fontSize: tOptional(tInt),
+ })),
})),
strictSelectors: tOptional(tBoolean),
serviceWorkers: tOptional(tEnum(['allow', 'block'])),
@@ -800,7 +803,11 @@ scheme.BrowserNewContextForReuseParams = tObject({
width: tInt,
height: tInt,
})),
- annotate: tOptional(tType('AnnotateOptions')),
+ showActions: tOptional(tObject({
+ duration: tOptional(tFloat),
+ position: tOptional(tEnum(['top-left', 'top', 'top-right', 'bottom-left', 'bottom', 'bottom-right'])),
+ fontSize: tOptional(tInt),
+ })),
})),
strictSelectors: tOptional(tBoolean),
serviceWorkers: tOptional(tEnum(['allow', 'block'])),
@@ -919,7 +926,11 @@ scheme.BrowserContextInitializer = tObject({
width: tInt,
height: tInt,
})),
- annotate: tOptional(tType('AnnotateOptions')),
+ showActions: tOptional(tObject({
+ duration: tOptional(tFloat),
+ position: tOptional(tEnum(['top-left', 'top', 'top-right', 'bottom-left', 'bottom', 'bottom-right'])),
+ fontSize: tOptional(tInt),
+ })),
})),
strictSelectors: tOptional(tBoolean),
serviceWorkers: tOptional(tEnum(['allow', 'block'])),
@@ -1548,27 +1559,35 @@ scheme.PagePickLocatorResult = tObject({
});
scheme.PageCancelPickLocatorParams = tOptional(tObject({}));
scheme.PageCancelPickLocatorResult = tOptional(tObject({}));
-scheme.PageOverlayShowParams = tObject({
+scheme.PageScreencastShowOverlayParams = tObject({
html: tString,
duration: tOptional(tFloat),
});
-scheme.PageOverlayShowResult = tObject({
+scheme.PageScreencastShowOverlayResult = tObject({
id: tString,
});
-scheme.PageOverlayRemoveParams = tObject({
+scheme.PageScreencastRemoveOverlayParams = tObject({
id: tString,
});
-scheme.PageOverlayRemoveResult = tOptional(tObject({}));
-scheme.PageOverlayChapterParams = tObject({
+scheme.PageScreencastRemoveOverlayResult = tOptional(tObject({}));
+scheme.PageScreencastChapterParams = tObject({
title: tString,
description: tOptional(tString),
duration: tOptional(tFloat),
});
-scheme.PageOverlayChapterResult = tOptional(tObject({}));
-scheme.PageOverlaySetVisibleParams = tObject({
+scheme.PageScreencastChapterResult = tOptional(tObject({}));
+scheme.PageScreencastSetOverlayVisibleParams = tObject({
visible: tBoolean,
});
-scheme.PageOverlaySetVisibleResult = tOptional(tObject({}));
+scheme.PageScreencastSetOverlayVisibleResult = tOptional(tObject({}));
+scheme.PageScreencastShowActionsParams = tObject({
+ duration: tOptional(tFloat),
+ position: tOptional(tEnum(['top-left', 'top', 'top-right', 'bottom-left', 'bottom', 'bottom-right'])),
+ fontSize: tOptional(tInt),
+});
+scheme.PageScreencastShowActionsResult = tOptional(tObject({}));
+scheme.PageScreencastHideActionsParams = tOptional(tObject({}));
+scheme.PageScreencastHideActionsResult = tOptional(tObject({}));
scheme.PageScreencastStartParams = tObject({
size: tOptional(tObject({
width: tInt,
@@ -1577,7 +1596,6 @@ scheme.PageScreencastStartParams = tObject({
quality: tOptional(tInt),
sendFrames: tOptional(tBoolean),
record: tOptional(tBoolean),
- annotate: tOptional(tType('AnnotateOptions')),
});
scheme.PageScreencastStartResult = tObject({
artifact: tOptional(tChannel(['Artifact'])),
@@ -2678,7 +2696,11 @@ scheme.ElectronLaunchParams = tObject({
width: tInt,
height: tInt,
})),
- annotate: tOptional(tType('AnnotateOptions')),
+ showActions: tOptional(tObject({
+ duration: tOptional(tFloat),
+ position: tOptional(tEnum(['top-left', 'top', 'top-right', 'bottom-left', 'bottom', 'bottom-right'])),
+ fontSize: tOptional(tInt),
+ })),
})),
strictSelectors: tOptional(tBoolean),
timezoneId: tOptional(tString),
@@ -2915,7 +2937,11 @@ scheme.AndroidDeviceLaunchBrowserParams = tObject({
width: tInt,
height: tInt,
})),
- annotate: tOptional(tType('AnnotateOptions')),
+ showActions: tOptional(tObject({
+ duration: tOptional(tFloat),
+ position: tOptional(tEnum(['top-left', 'top', 'top-right', 'bottom-left', 'bottom', 'bottom-right'])),
+ fontSize: tOptional(tInt),
+ })),
})),
strictSelectors: tOptional(tBoolean),
serviceWorkers: tOptional(tEnum(['allow', 'block'])),
diff --git a/packages/playwright-core/src/server/dispatchers/pageDispatcher.ts b/packages/playwright-core/src/server/dispatchers/pageDispatcher.ts
index 949eca0b66..b6e02c7362 100644
--- a/packages/playwright-core/src/server/dispatchers/pageDispatcher.ts
+++ b/packages/playwright-core/src/server/dispatchers/pageDispatcher.ts
@@ -357,23 +357,31 @@ export class PageDispatcher extends Dispatcher<Page, channels.PageChannel, Brows
await recorder?.setMode('none');
}
- async overlayShow(params: channels.PageOverlayShowParams): Promise<channels.PageOverlayShowResult> {
+ async screencastShowOverlay(params: channels.PageScreencastShowOverlayParams): Promise<channels.PageScreencastShowOverlayResult> {
const id = await this._page.overlay.show(params.html, params.duration);
return { id };
}
- async overlayRemove(params: channels.PageOverlayRemoveParams): Promise<channels.PageOverlayRemoveResult> {
+ async screencastRemoveOverlay(params: channels.PageScreencastRemoveOverlayParams): Promise<channels.PageScreencastRemoveOverlayResult> {
await this._page.overlay.remove(params.id);
}
- async overlayChapter(params: channels.PageOverlayChapterParams): Promise<channels.PageOverlayChapterResult> {
+ async screencastChapter(params: channels.PageScreencastChapterParams): Promise<channels.PageScreencastChapterResult> {
await this._page.overlay.chapter(params);
}
- async overlaySetVisible(params: channels.PageOverlaySetVisibleParams): Promise<channels.PageOverlaySetVisibleResult> {
+ async screencastSetOverlayVisible(params: channels.PageScreencastSetOverlayVisibleParams): Promise<channels.PageScreencastSetOverlayVisibleResult> {
await this._page.overlay.setVisible(params.visible);
}
+ async screencastShowActions(params: channels.PageScreencastShowActionsParams): Promise<channels.PageScreencastShowActionsResult> {
+ this._page.screencast.showActions({ duration: params.duration, position: params.position, fontSize: params.fontSize });
+ }
+
+ async screencastHideActions(): Promise<channels.PageScreencastHideActionsResult> {
+ this._page.screencast.hideActions();
+ }
+
async screencastStart(params: channels.PageScreencastStartParams, progress?: Progress): Promise<channels.PageScreencastStartResult> {
if (this._screencastClient || this._videoRecorder)
throw new Error('Screencast is already running');
diff --git a/packages/playwright-core/src/server/screencast.ts b/packages/playwright-core/src/server/screencast.ts
index 4944b52689..318dd2babe 100644
--- a/packages/playwright-core/src/server/screencast.ts
+++ b/packages/playwright-core/src/server/screencast.ts
@@ -27,13 +27,20 @@ export type ScreencastClient = {
dispose: () => void;
size?: types.Size;
quality?: number;
- annotate?: types.AnnotateOptions;
+};
+
+type AnnotatePosition = 'top-left' | 'top' | 'top-right' | 'bottom-left' | 'bottom' | 'bottom-right';
+
+type ActionOptions = {
+ duration?: number,
+ position?: AnnotatePosition,
+ fontSize?: number,
};
export class Screencast implements InstrumentationListener {
readonly page: Page;
private _clients = new Set<ScreencastClient>();
- private _annotate: types.AnnotateOptions | undefined;
+ private _actions: ActionOptions | undefined;
private _size: types.Size | undefined;
constructor(page: Page) {
@@ -57,10 +64,16 @@ export class Screencast implements InstrumentationListener {
this.page.instrumentation.removeListener(this);
}
+ showActions(options: ActionOptions) {
+ this._actions = options;
+ }
+
+ hideActions() {
+ this._actions = undefined;
+ }
+
addClient(client: ScreencastClient): { size: types.Size } {
this._clients.add(client);
- if (!this._annotate && client.annotate)
- this._annotate = client.annotate;
if (this._clients.size === 1)
this._startScreencast(client.size, client.quality);
return { size: this._size! };
@@ -72,7 +85,6 @@ export class Screencast implements InstrumentationListener {
this._clients.delete(client);
if (!this._clients.size)
this._stopScreencast();
- this._annotate = Array.from(this._clients).find(c => c.annotate)?.annotate;
}
size(): types.Size | undefined {
@@ -126,13 +138,13 @@ export class Screencast implements InstrumentationListener {
}
async onBeforeCall(sdkObject: SdkObject, metadata: CallMetadata, parentId?: string): Promise<void> {
- if (!this._annotate)
+ if (!this._actions)
return;
metadata.annotate = true;
}
async onBeforeInputAction(sdkObject: SdkObject, metadata: CallMetadata): Promise<void> {
- if (!this._annotate)
+ if (!this._actions)
return;
const page = sdkObject.attribution.page;
@@ -150,12 +162,12 @@ export class Screencast implements InstrumentationListener {
injected.setScreencastAnnotation(null);
}, {
injected: await utility.injectedScript(),
- duration: this._annotate?.duration ?? 500,
+ duration: this._actions?.duration ?? 500,
point: metadata.point,
box: metadata.box,
actionTitle,
- position: this._annotate?.position,
- fontSize: this._annotate?.fontSize,
+ position: this._actions?.position,
+ fontSize: this._actions?.fontSize,
}).catch(e => debugLogger.log('error', e));
}
}
diff --git a/packages/playwright-core/src/server/types.ts b/packages/playwright-core/src/server/types.ts
index 86dbcc4229..1b28efb468 100644
--- a/packages/playwright-core/src/server/types.ts
+++ b/packages/playwright-core/src/server/types.ts
@@ -43,19 +43,10 @@ export type PointerActionWaitOptions = CommonActionOptions & {
trial?: boolean;
};
-export type AnnotatePosition = 'top-left' | 'top' | 'top-right' | 'bottom-left' | 'bottom' | 'bottom-right';
-
-export type AnnotateOptions = {
- duration?: number,
- position?: AnnotatePosition,
- fontSize?: number,
-};
-
export type VideoOptions = {
width: number,
height: number,
outputFile: string,
- annotate?: AnnotateOptions,
};
export type ScreencastFrame = {
diff --git a/packages/playwright-core/src/server/videoRecorder.ts b/packages/playwright-core/src/server/videoRecorder.ts
index 4702d8d297..d055553918 100644
--- a/packages/playwright-core/src/server/videoRecorder.ts
+++ b/packages/playwright-core/src/server/videoRecorder.ts
@@ -39,7 +39,7 @@ export class VideoRecorder {
this._screencast = screencast;
}
- start(options: { fileName?: string, size?: { width: number, height: number }, annotate?: types.AnnotateOptions }) {
+ start(options: { fileName?: string, size?: { width: number, height: number } }) {
assert(!this._artifact);
// Do this first, it likes to throw.
const ffmpegPath = registry.findExecutable('ffmpeg')!.executablePathOrDie(this._screencast.page.browserContext._browser.sdkLanguage());
@@ -50,7 +50,6 @@ export class VideoRecorder {
gracefulClose: () => this.stop(),
dispose: () => this.stop().catch(e => debugLogger.log('error', `Failed to stop video recorder: ${String(e)}`)),
size: options.size,
- annotate: options.annotate,
};
const { size } = this._screencast.addClient(this._client);
@@ -85,8 +84,10 @@ export function startAutomaticVideoRecording(page: Page) {
if (!recordVideo)
return;
const recorder = new VideoRecorder(page.screencast);
+ if (page.browserContext._options.recordVideo?.showActions)
+ page.screencast.showActions(page.browserContext._options.recordVideo?.showActions);
const dir = recordVideo.dir ?? page.browserContext._browser.options.artifactsDir;
- const artifact = recorder.start({ size: recordVideo.size, annotate: recordVideo.annotate, fileName: path.join(dir, page.guid + '.webm') });
+ const artifact = recorder.start({ size: recordVideo.size, fileName: path.join(dir, page.guid + '.webm') });
page.video = artifact;
}
diff --git a/packages/playwright-core/src/utils/isomorphic/protocolMetainfo.ts b/packages/playwright-core/src/utils/isomorphic/protocolMetainfo.ts
index 1795985a38..9f2e384000 100644
--- a/packages/playwright-core/src/utils/isomorphic/protocolMetainfo.ts
+++ b/packages/playwright-core/src/utils/isomorphic/protocolMetainfo.ts
@@ -148,10 +148,12 @@ export const methodMetainfo = new Map<string, MethodMetainfo>([
['Page.bringToFront', { title: 'Bring to front', }],
['Page.pickLocator', { title: 'Pick locator', group: 'configuration', }],
['Page.cancelPickLocator', { title: 'Cancel pick locator', group: 'configuration', }],
- ['Page.overlayShow', { title: 'Show overlay', group: 'configuration', }],
- ['Page.overlayRemove', { title: 'Remove overlay', group: 'configuration', }],
- ['Page.overlayChapter', { title: 'Show chapter overlay', group: 'configuration', }],
- ['Page.overlaySetVisible', { title: 'Set overlay visibility', group: 'configuration', }],
+ ['Page.screencastShowOverlay', { title: 'Show overlay', group: 'configuration', }],
+ ['Page.screencastRemoveOverlay', { title: 'Remove overlay', group: 'configuration', }],
+ ['Page.screencastChapter', { title: 'Show chapter overlay', group: 'configuration', }],
+ ['Page.screencastSetOverlayVisible', { title: 'Set overlay visibility', group: 'configuration', }],
+ ['Page.screencastShowActions', { title: 'Show actions', group: 'configuration', }],
+ ['Page.screencastHideActions', { title: 'Remove actions', group: 'configuration', }],
['Page.screencastStart', { title: 'Start screencast', group: 'configuration', }],
['Page.screencastStop', { title: 'Stop screencast', group: 'configuration', }],
['Page.updateSubscription', { internal: true, }],
diff --git a/packages/playwright-core/types/types.d.ts b/packages/playwright-core/types/types.d.ts
index afd509576b..637fa2b031 100644
--- a/packages/playwright-core/types/types.d.ts
+++ b/packages/playwright-core/types/types.d.ts
@@ -10197,7 +10197,7 @@ export interface Browser {
/**
* If specified, enables visual annotations on interacted elements during video recording.
*/
- annotate?: {
+ showActions?: {
/**
* How long each annotation is displayed in milliseconds. Defaults to `500`.
*/
@@ -15496,7 +15496,7 @@ export interface BrowserType<Unused = {}> {
/**
* If specified, enables visual annotations on interacted elements during video recording.
*/
- annotate?: {
+ showActions?: {
/**
* How long each annotation is displayed in milliseconds. Defaults to `500`.
*/
@@ -16225,11 +16225,37 @@ export interface Screencast {
fontSize?: number;
};
}): Promise<Disposable>;
+ /**
+ * Removes action decorations.
+ */
+ hideActions(): Promise<void>;
+
/**
* Hides overlays without removing them.
*/
hideOverlays(): Promise<void>;
+ /**
+ * Enables visual annotations on interacted elements. Returns a disposable that stops showing actions when disposed.
+ * @param options
+ */
+ showActions(options?: {
+ /**
+ * How long each annotation is displayed in milliseconds. Defaults to `500`.
+ */
+ duration?: number;
+
+ /**
+ * Font size of the action title in pixels. Defaults to `24`.
+ */
+ fontSize?: number;
+
+ /**
+ * Position of the action title overlay. Defaults to `"top-right"`.
+ */
+ position?: "top-left"|"top"|"top-right"|"bottom-left"|"bottom"|"bottom-right";
+ }): Promise<Disposable>;
+
/**
* Shows a chapter overlay with a title and optional description, centered on the page with a blurred backdrop. Useful
* for narrating video recordings. The overlay is removed after the specified duration, or 2000ms.
@@ -17441,7 +17467,7 @@ export interface AndroidDevice {
/**
* If specified, enables visual annotations on interacted elements during video recording.
*/
- annotate?: {
+ showActions?: {
/**
* How long each annotation is displayed in milliseconds. Defaults to `500`.
*/
@@ -20049,7 +20075,7 @@ export interface Electron {
/**
* If specified, enables visual annotations on interacted elements during video recording.
*/
- annotate?: {
+ showActions?: {
/**
* How long each annotation is displayed in milliseconds. Defaults to `500`.
*/
@@ -23022,7 +23048,7 @@ export interface BrowserContextOptions {
/**
* If specified, enables visual annotations on interacted elements during video recording.
*/
- annotate?: {
+ showActions?: {
/**
* How long each annotation is displayed in milliseconds. Defaults to `500`.
*/
diff --git a/packages/playwright/src/index.ts b/packages/playwright/src/index.ts
index f79a96ae58..c85a161a28 100644
--- a/packages/playwright/src/index.ts
+++ b/packages/playwright/src/index.ts
@@ -372,12 +372,12 @@ const playwrightFixtures: Fixtures<TestFixtures, WorkerFixtures> = ({
`If you would like to configure your page before each test, do that in beforeEach hook instead.`,
].join('\n'));
}
- const annotate = typeof video === 'string' ? undefined : video.annotate;
+ const show = typeof video === 'string' ? undefined : video.show;
const videoOptions: BrowserContextOptions = captureVideo ? {
recordVideo: {
dir: tracing().artifactsDir(),
size: typeof video === 'string' ? undefined : video.size,
- annotate: annotate?.action,
+ showActions: show?.actions,
}
} : {};
const context = await browser.newContext({ ...videoOptions, ...options }) as BrowserContextImpl;
@@ -442,13 +442,13 @@ const playwrightFixtures: Fixtures<TestFixtures, WorkerFixtures> = ({
context: async ({ browser, video, _reuseContext, _contextFactory }, use, testInfoPublic) => {
const browserImpl = browser as BrowserImpl;
const testInfo = testInfoPublic as TestInfoImpl;
- const annotate = typeof video === 'string' ? undefined : video.annotate;
+ const show = typeof video === 'string' ? undefined : video.show;
attachConnectedHeaderIfNeeded(testInfo, browserImpl);
if (!_reuseContext) {
const { context, close } = await _contextFactory();
testInfo._onCustomMessageCallback = createCustomMessageHandler(testInfo, context);
await runDaemonForContext(testInfo, context);
- await installScreencastTitleUpdater(testInfo, context, annotate?.test);
+ await installScreencastTitleUpdater(testInfo, context, show?.test);
await use(context);
await close();
return;
@@ -457,7 +457,7 @@ const playwrightFixtures: Fixtures<TestFixtures, WorkerFixtures> = ({
const context = await browserImpl._wrapApiCall(() => browserImpl._newContextForReuse(), { internal: true });
testInfo._onCustomMessageCallback = createCustomMessageHandler(testInfo, context);
await runDaemonForContext(testInfo, context);
- await installScreencastTitleUpdater(testInfo, context, annotate?.test);
+ await installScreencastTitleUpdater(testInfo, context, show?.test);
await use(context);
const closeReason = testInfo.status === 'timedOut' ? 'Test timeout of ' + testInfo.timeout + 'ms exceeded.' : 'Test ended.';
await browserImpl._wrapApiCall(() => browserImpl._disconnectFromReusedContext(closeReason), { internal: true });
diff --git a/packages/playwright/types/test.d.ts b/packages/playwright/types/test.d.ts
index 395b684f2e..23e7e12e03 100644
--- a/packages/playwright/types/test.d.ts
+++ b/packages/playwright/types/test.d.ts
@@ -6934,9 +6934,9 @@ export interface PlaywrightWorkerOptions {
* 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.
*
- * 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.
+ * 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.
*
* **Usage**
*
@@ -6953,7 +6953,7 @@ export interface PlaywrightWorkerOptions {
*
* Learn more about [recording video](https://playwright.dev/docs/test-use-options#recording-options).
*/
- video: VideoMode | /** deprecated */ 'retry-with-video' | { mode: VideoMode, size?: ViewportSize, annotate?: { action?: { duration?: number, position?: 'top-left' | 'top' | 'top-right' | 'bottom-left' | 'bottom' | 'bottom-right', fontSize?: number }, test?: { level?: 'file' | 'title' | 'step', position?: 'top-left' | 'top' | 'top-right' | 'bottom-left' | 'bottom' | 'bottom-right', fontSize?: number } } };
+ video: VideoMode | /** deprecated */ 'retry-with-video' | { mode: VideoMode, size?: ViewportSize, show?: { actions?: { duration?: number, position?: 'top-left' | 'top' | 'top-right' | 'bottom-left' | 'bottom' | 'bottom-right', fontSize?: number }, test?: { level?: 'file' | 'title' | 'step', position?: 'top-left' | 'top' | 'top-right' | 'bottom-left' | 'bottom' | 'bottom-right', fontSize?: number } } };
}
export type ScreenshotMode = 'off' | 'on' | 'only-on-failure' | 'on-first-failure';
diff --git a/packages/protocol/src/channels.d.ts b/packages/protocol/src/channels.d.ts
index b895f41528..1ed3c901eb 100644
--- a/packages/protocol/src/channels.d.ts
+++ b/packages/protocol/src/channels.d.ts
@@ -176,12 +176,6 @@ export type Rect = {
height: number,
};
-export type AnnotateOptions = {
- duration?: number,
- position?: 'top-left' | 'top' | 'top-right' | 'bottom-left' | 'bottom' | 'bottom-right',
- fontSize?: number,
-};
-
export type SerializedValue = {
n?: number,
b?: boolean,
@@ -1033,7 +1027,11 @@ export type BrowserTypeLaunchPersistentContextParams = {
width: number,
height: number,
},
- annotate?: AnnotateOptions,
+ showActions?: {
+ duration?: number,
+ position?: 'top-left' | 'top' | 'top-right' | 'bottom-left' | 'bottom' | 'bottom-right',
+ fontSize?: number,
+ },
},
strictSelectors?: boolean,
serviceWorkers?: 'allow' | 'block',
@@ -1117,7 +1115,11 @@ export type BrowserTypeLaunchPersistentContextOptions = {
width: number,
height: number,
},
- annotate?: AnnotateOptions,
+ showActions?: {
+ duration?: number,
+ position?: 'top-left' | 'top' | 'top-right' | 'bottom-left' | 'bottom' | 'bottom-right',
+ fontSize?: number,
+ },
},
strictSelectors?: boolean,
serviceWorkers?: 'allow' | 'block',
@@ -1269,7 +1271,11 @@ export type BrowserNewContextParams = {
width: number,
height: number,
},
- annotate?: AnnotateOptions,
+ showActions?: {
+ duration?: number,
+ position?: 'top-left' | 'top' | 'top-right' | 'bottom-left' | 'bottom' | 'bottom-right',
+ fontSize?: number,
+ },
},
strictSelectors?: boolean,
serviceWorkers?: 'allow' | 'block',
@@ -1338,7 +1344,11 @@ export type BrowserNewContextOptions = {
width: number,
height: number,
},
- annotate?: AnnotateOptions,
+ showActions?: {
+ duration?: number,
+ position?: 'top-left' | 'top' | 'top-right' | 'bottom-left' | 'bottom' | 'bottom-right',
+ fontSize?: number,
+ },
},
strictSelectors?: boolean,
serviceWorkers?: 'allow' | 'block',
@@ -1410,7 +1420,11 @@ export type BrowserNewContextForReuseParams = {
width: number,
height: number,
},
- annotate?: AnnotateOptions,
+ showActions?: {
+ duration?: number,
+ position?: 'top-left' | 'top' | 'top-right' | 'bottom-left' | 'bottom' | 'bottom-right',
+ fontSize?: number,
+ },
},
strictSelectors?: boolean,
serviceWorkers?: 'allow' | 'block',
@@ -1479,7 +1493,11 @@ export type BrowserNewContextForReuseOptions = {
width: number,
height: number,
},
- annotate?: AnnotateOptions,
+ showActions?: {
+ duration?: number,
+ position?: 'top-left' | 'top' | 'top-right' | 'bottom-left' | 'bottom' | 'bottom-right',
+ fontSize?: number,
+ },
},
strictSelectors?: boolean,
serviceWorkers?: 'allow' | 'block',
@@ -1615,7 +1633,11 @@ export type BrowserContextInitializer = {
width: number,
height: number,
},
- annotate?: AnnotateOptions,
+ showActions?: {
+ duration?: number,
+ position?: 'top-left' | 'top' | 'top-right' | 'bottom-left' | 'bottom' | 'bottom-right',
+ fontSize?: number,
+ },
},
strictSelectors?: boolean,
serviceWorkers?: 'allow' | 'block',
@@ -2160,10 +2182,12 @@ export interface PageChannel extends PageEventTarget, EventTargetChannel {
bringToFront(params?: PageBringToFrontParams, progress?: Progress): Promise<PageBringToFrontResult>;
pickLocator(params?: PagePickLocatorParams, progress?: Progress): Promise<PagePickLocatorResult>;
cancelPickLocator(params?: PageCancelPickLocatorParams, progress?: Progress): Promise<PageCancelPickLocatorResult>;
- overlayShow(params: PageOverlayShowParams, progress?: Progress): Promise<PageOverlayShowResult>;
- overlayRemove(params: PageOverlayRemoveParams, progress?: Progress): Promise<PageOverlayRemoveResult>;
- overlayChapter(params: PageOverlayChapterParams, progress?: Progress): Promise<PageOverlayChapterResult>;
- overlaySetVisible(params: PageOverlaySetVisibleParams, progress?: Progress): Promise<PageOverlaySetVisibleResult>;
+ screencastShowOverlay(params: PageScreencastShowOverlayParams, progress?: Progress): Promise<PageScreencastShowOverlayResult>;
+ screencastRemoveOverlay(params: PageScreencastRemoveOverlayParams, progress?: Progress): Promise<PageScreencastRemoveOverlayResult>;
+ screencastChapter(params: PageScreencastChapterParams, progress?: Progress): Promise<PageScreencastChapterResult>;
+ screencastSetOverlayVisible(params: PageScreencastSetOverlayVisibleParams, progress?: Progress): Promise<PageScreencastSetOverlayVisibleResult>;
+ screencastShowActions(params: PageScreencastShowActionsParams, progress?: Progress): Promise<PageScreencastShowActionsResult>;
+ screencastHideActions(params?: PageScreencastHideActionsParams, progress?: Progress): Promise<PageScreencastHideActionsResult>;
screencastStart(params: PageScreencastStartParams, progress?: Progress): Promise<PageScreencastStartResult>;
screencastStop(params?: PageScreencastStopParams, progress?: Progress): Promise<PageScreencastStopResult>;
updateSubscription(params: PageUpdateSubscriptionParams, progress?: Progress): Promise<PageUpdateSubscriptionResult>;
@@ -2681,40 +2705,54 @@ export type PagePickLocatorResult = {
export type PageCancelPickLocatorParams = {};
export type PageCancelPickLocatorOptions = {};
export type PageCancelPickLocatorResult = void;
-export type PageOverlayShowParams = {
+export type PageScreencastShowOverlayParams = {
html: string,
duration?: number,
};
-export type PageOverlayShowOptions = {
+export type PageScreencastShowOverlayOptions = {
duration?: number,
};
-export type PageOverlayShowResult = {
+export type PageScreencastShowOverlayResult = {
id: string,
};
-export type PageOverlayRemoveParams = {
+export type PageScreencastRemoveOverlayParams = {
id: string,
};
-export type PageOverlayRemoveOptions = {
+export type PageScreencastRemoveOverlayOptions = {
};
-export type PageOverlayRemoveResult = void;
-export type PageOverlayChapterParams = {
+export type PageScreencastRemoveOverlayResult = void;
+export type PageScreencastChapterParams = {
title: string,
description?: string,
duration?: number,
};
-export type PageOverlayChapterOptions = {
+export type PageScreencastChapterOptions = {
description?: string,
duration?: number,
};
-export type PageOverlayChapterResult = void;
-export type PageOverlaySetVisibleParams = {
+export type PageScreencastChapterResult = void;
+export type PageScreencastSetOverlayVisibleParams = {
visible: boolean,
};
-export type PageOverlaySetVisibleOptions = {
+export type PageScreencastSetOverlayVisibleOptions = {
};
-export type PageOverlaySetVisibleResult = void;
+export type PageScreencastSetOverlayVisibleResult = void;
+export type PageScreencastShowActionsParams = {
+ duration?: number,
+ position?: 'top-left' | 'top' | 'top-right' | 'bottom-left' | 'bottom' | 'bottom-right',
+ fontSize?: number,
+};
+export type PageScreencastShowActionsOptions = {
+ duration?: number,
+ position?: 'top-left' | 'top' | 'top-right' | 'bottom-left' | 'bottom' | 'bottom-right',
+ fontSize?: number,
+};
+export type PageScreencastShowActionsResult = void;
+export type PageScreencastHideActionsParams = {};
+export type PageScreencastHideActionsOptions = {};
+export type PageScreencastHideActionsResult = void;
export type PageScreencastStartParams = {
size?: {
width: number,
@@ -2723,7 +2761,6 @@ export type PageScreencastStartParams = {
quality?: number,
sendFrames?: boolean,
record?: boolean,
- annotate?: AnnotateOptions,
};
export type PageScreencastStartOptions = {
size?: {
@@ -2733,7 +2770,6 @@ export type PageScreencastStartOptions = {
quality?: number,
sendFrames?: boolean,
record?: boolean,
- annotate?: AnnotateOptions,
};
export type PageScreencastStartResult = {
artifact?: ArtifactChannel,
@@ -4669,7 +4705,11 @@ export type ElectronLaunchParams = {
width: number,
height: number,
},
- annotate?: AnnotateOptions,
+ showActions?: {
+ duration?: number,
+ position?: 'top-left' | 'top' | 'top-right' | 'bottom-left' | 'bottom' | 'bottom-right',
+ fontSize?: number,
+ },
},
strictSelectors?: boolean,
timezoneId?: string,
@@ -4707,7 +4747,11 @@ export type ElectronLaunchOptions = {
width: number,
height: number,
},
- annotate?: AnnotateOptions,
+ showActions?: {
+ duration?: number,
+ position?: 'top-left' | 'top' | 'top-right' | 'bottom-left' | 'bottom' | 'bottom-right',
+ fontSize?: number,
+ },
},
strictSelectors?: boolean,
timezoneId?: string,
@@ -5096,7 +5140,11 @@ export type AndroidDeviceLaunchBrowserParams = {
width: number,
height: number,
},
- annotate?: AnnotateOptions,
+ showActions?: {
+ duration?: number,
+ position?: 'top-left' | 'top' | 'top-right' | 'bottom-left' | 'bottom' | 'bottom-right',
+ fontSize?: number,
+ },
},
strictSelectors?: boolean,
serviceWorkers?: 'allow' | 'block',
@@ -5163,7 +5211,11 @@ export type AndroidDeviceLaunchBrowserOptions = {
width: number,
height: number,
},
- annotate?: AnnotateOptions,
+ showActions?: {
+ duration?: number,
+ position?: 'top-left' | 'top' | 'top-right' | 'bottom-left' | 'bottom' | 'bottom-right',
+ fontSize?: number,
+ },
},
strictSelectors?: boolean,
serviceWorkers?: 'allow' | 'block',
diff --git a/packages/protocol/src/protocol.yml b/packages/protocol/src/protocol.yml
index 9dea9482a5..bc3183ae8c 100644
--- a/packages/protocol/src/protocol.yml
+++ b/packages/protocol/src/protocol.yml
@@ -59,8 +59,8 @@ Rect:
width: float
height: float
-AnnotateOptions:
- type: object
+ShowActionsOptions:
+ type: mixin
properties:
duration: float?
position:
@@ -613,7 +613,10 @@ ContextOptions:
properties:
width: int
height: int
- annotate: AnnotateOptions?
+ showActions:
+ type: object?
+ properties:
+ $mixin: ShowActionsOptions
strictSelectors: boolean?
serviceWorkers:
type: enum?
@@ -2108,7 +2111,7 @@ Page:
title: Cancel pick locator
group: configuration
- overlayShow:
+ screencastShowOverlay:
title: Show overlay
group: configuration
parameters:
@@ -2117,13 +2120,13 @@ Page:
returns:
id: string
- overlayRemove:
+ screencastRemoveOverlay:
title: Remove overlay
group: configuration
parameters:
id: string
- overlayChapter:
+ screencastChapter:
title: Show chapter overlay
group: configuration
parameters:
@@ -2131,12 +2134,22 @@ Page:
description: string?
duration: float?
- overlaySetVisible:
+ screencastSetOverlayVisible:
title: Set overlay visibility
group: configuration
parameters:
visible: boolean
+ screencastShowActions:
+ title: Show actions
+ group: configuration
+ parameters:
+ $mixin: ShowActionsOptions
+
+ screencastHideActions:
+ title: Remove actions
+ group: configuration
+
screencastStart:
title: Start screencast
group: configuration
@@ -2149,7 +2162,6 @@ Page:
quality: int?
sendFrames: boolean?
record: boolean?
- annotate: AnnotateOptions?
returns:
artifact: Artifact?
@@ -4169,7 +4181,10 @@ Electron:
properties:
width: int
height: int
- annotate: AnnotateOptions?
+ showActions:
+ type: object?
+ properties:
+ $mixin: ShowActionsOptions
strictSelectors: boolean?
timezoneId: string?
tracesDir: string?
diff --git a/tests/library/screencast-actions.spec.ts b/tests/library/screencast-actions.spec.ts
new file mode 100644
index 0000000000..6dbf0b8179
--- /dev/null
+++ b/tests/library/screencast-actions.spec.ts
@@ -0,0 +1,201 @@
+/**
+ * Copyright Microsoft Corporation. All rights reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import { expect, browserTest as test } from '../config/browserTest';
+
+test.skip(({ mode }) => mode !== 'default', 'Annotations use an open shadow root only in default mode');
+
+test('should show annotation on click', async ({ browser, server }) => {
+ const context = await browser.newContext();
+ const page = await context.newPage();
+ await page.goto(server.PREFIX + '/input/button.html');
+
+ await page.screencast.showActions({ duration: 5000 });
+ page.click('button').catch(() => {});
+
+ await expect(page.locator('x-pw-highlight')).toBeVisible();
+ await expect(page.locator('x-pw-action-point')).toBeVisible();
+ await expect(page.locator('x-pw-title')).toBeVisible();
+ await expect(page.locator('x-pw-title')).toHaveText(/click/i);
+
+ await context.close();
+});
+
+test('should render annotation styles', async ({ browser, server }) => {
+ const context = await browser.newContext();
+ const page = await context.newPage();
+ await page.goto(server.PREFIX + '/input/button.html');
+
+ await page.screencast.showActions({ duration: 5000, fontSize: 32 });
+ page.click('button').catch(() => {});
+
+ // Highlight box: blue overlay with non-zero dimensions.
+ const highlight = page.locator('x-pw-highlight');
+ await expect(highlight).toBeVisible();
+ const highlightStyle = await highlight.evaluate((el: HTMLElement) => ({
+ backgroundColor: el.style.backgroundColor,
+ borderColor: el.style.borderColor,
+ }));
+ expect(highlightStyle.backgroundColor).toBe('rgba(0, 128, 255, 0.15)');
+ expect(highlightStyle.borderColor).toBe('rgba(0, 128, 255, 0.6)');
+ const box = await highlight.boundingBox();
+ expect(box!.width).toBeGreaterThan(0);
+ expect(box!.height).toBeGreaterThan(0);
+
+ // Action point: 20x20 red circle.
+ const actionPoint = page.locator('x-pw-action-point');
+ await expect(actionPoint).toBeVisible();
+ const apStyle = await actionPoint.evaluate((el: HTMLElement) => {
+ const cs = getComputedStyle(el);
+ return { width: cs.width, height: cs.height, background: cs.backgroundColor, borderRadius: cs.borderRadius };
+ });
+ expect(apStyle.width).toBe('20px');
+ expect(apStyle.height).toBe('20px');
+ expect(apStyle.background).toBe('rgb(255, 0, 0)');
+ expect(apStyle.borderRadius).toBe('10px');
+
+ // Title: white text, dark background, positioned top-right by default, custom fontSize.
+ const title = page.locator('x-pw-title');
+ await expect(title).toBeVisible();
+ const titleStyle = await title.evaluate((el: HTMLElement) => {
+ const cs = getComputedStyle(el);
+ return {
+ color: cs.color, borderRadius: cs.borderRadius, padding: cs.padding,
+ top: el.style.top, right: el.style.right, fontSize: el.style.fontSize,
+ };
+ });
+ expect(titleStyle.color).toBe('rgb(255, 255, 255)');
+ expect(titleStyle.borderRadius).toBe('6px');
+ expect(titleStyle.padding).toBe('6px');
+ expect(titleStyle.top).toBe('6px');
+ expect(titleStyle.right).toBe('6px');
+ expect(titleStyle.fontSize).toBe('32px');
+
+ await context.close();
+});
+
+for (const { position, expected } of [
+ { position: 'top-left' as const, expected: { top: '6px', left: '6px' } },
+ { position: 'top' as const, expected: { top: '6px', left: '50%' } },
+ { position: 'bottom-left' as const, expected: { bottom: '6px', left: '6px' } },
+ { position: 'bottom' as const, expected: { bottom: '6px', left: '50%' } },
+ { position: 'bottom-right' as const, expected: { bottom: '6px', right: '6px' } },
+] as const) {
+ test(`should position title at ${position}`, async ({ browser, server }) => {
+ const context = await browser.newContext();
+ const page = await context.newPage();
+ await page.goto(server.PREFIX + '/input/button.html');
+
+ await page.screencast.showActions({ duration: 5000, position });
+ page.click('button').catch(() => {});
+
+ const title = page.locator('x-pw-title');
+ await expect(title).toBeVisible();
+
+ const titleStyle = await title.evaluate((el: HTMLElement) => ({
+ top: el.style.top,
+ bottom: el.style.bottom,
+ left: el.style.left,
+ right: el.style.right,
+ })) as any;
+
+ for (const [key, value] of Object.entries(expected))
+ expect(titleStyle[key]).toBe(value);
+
+ await context.close();
+ });
+}
+
+test('should clear annotation after duration', async ({ browser, server }) => {
+ const context = await browser.newContext();
+ const page = await context.newPage();
+ await page.goto(server.PREFIX + '/input/button.html');
+
+ await page.screencast.showActions({ duration: 1000 });
+ await page.click('button');
+
+ await expect(page.locator('x-pw-action-point')).toBeHidden();
+ await expect(page.locator('x-pw-title')).toBeHidden();
+
+ await context.close();
+});
+
+test('should annotate fill action', async ({ browser, server }) => {
+ const context = await browser.newContext();
+ const page = await context.newPage();
+ await page.goto(server.PREFIX + '/input/textarea.html');
+
+ await page.screencast.showActions({ duration: 5000 });
+ page.fill('textarea', 'hello').catch(() => {});
+
+ const title = page.locator('x-pw-title');
+ await expect(title).toBeVisible();
+ await expect(title).toHaveText(/fill/i);
+
+ await context.close();
+});
+
+test('should stop showing actions after dispose', async ({ browser, server }) => {
+ const context = await browser.newContext();
+ const page = await context.newPage();
+ await page.goto(server.PREFIX + '/input/button.html');
+
+ const actions = await page.screencast.showActions({ duration: 1000 });
+ await page.click('button');
+ await actions.dispose();
+
+ await page.goto(server.PREFIX + '/input/button.html');
+ await page.click('button');
+
+ await expect(page.locator('x-pw-title')).toBeHidden();
+
+ await context.close();
+});
+
+test('should stop showing actions after hideActions', async ({ browser, server }) => {
+ const context = await browser.newContext();
+ const page = await context.newPage();
+ await page.goto(server.PREFIX + '/input/button.html');
+
+ await page.screencast.showActions({ duration: 1000 });
+ await page.click('button');
+ await page.screencast.hideActions();
+
+ await page.goto(server.PREFIX + '/input/button.html');
+ await page.click('button');
+
+ await expect(page.locator('x-pw-title')).toBeHidden();
+
+ await context.close();
+});
+
+test('should survive navigation', async ({ browser, server }) => {
+ const context = await browser.newContext();
+ const page = await context.newPage();
+ await page.goto(server.PREFIX + '/input/button.html');
+
+ await page.screencast.showActions({ duration: 5000 });
+ page.click('button').catch(() => {});
+
+ await expect(page.locator('x-pw-title')).toBeVisible();
+
+ await page.goto(server.PREFIX + '/input/button.html');
+ page.click('button').catch(() => {});
+
+ await expect(page.locator('x-pw-title')).toBeVisible();
+
+ await context.close();
+});
diff --git a/tests/library/overlay.spec.ts b/tests/library/screencast-overlay.spec.ts
similarity index 100%
rename from tests/library/overlay.spec.ts
rename to tests/library/screencast-overlay.spec.ts
diff --git a/utils/generate_types/overrides-test.d.ts b/utils/generate_types/overrides-test.d.ts
index e21a0d33ec..02df783768 100644
--- a/utils/generate_types/overrides-test.d.ts
+++ b/utils/generate_types/overrides-test.d.ts
@@ -260,7 +260,7 @@ export interface PlaywrightWorkerOptions {
connectOptions: ConnectOptions | undefined;
screenshot: ScreenshotMode | { mode: ScreenshotMode } & Pick<PageScreenshotOptions, 'fullPage' | 'omitBackground'>;
trace: TraceMode | /** deprecated */ 'retry-with-trace' | { mode: TraceMode, snapshots?: boolean, screenshots?: boolean, sources?: boolean, attachments?: boolean };
- video: VideoMode | /** deprecated */ 'retry-with-video' | { mode: VideoMode, size?: ViewportSize, annotate?: { action?: { duration?: number, position?: 'top-left' | 'top' | 'top-right' | 'bottom-left' | 'bottom' | 'bottom-right', fontSize?: number }, test?: { level?: 'file' | 'title' | 'step', position?: 'top-left' | 'top' | 'top-right' | 'bottom-left' | 'bottom' | 'bottom-right', fontSize?: number } } };
+ video: VideoMode | /** deprecated */ 'retry-with-video' | { mode: VideoMode, size?: ViewportSize, show?: { actions?: { duration?: number, position?: 'top-left' | 'top' | 'top-right' | 'bottom-left' | 'bottom' | 'bottom-right', fontSize?: number }, test?: { level?: 'file' | 'title' | 'step', position?: 'top-left' | 'top' | 'top-right' | 'bottom-left' | 'bottom' | 'bottom-right', fontSize?: number } } };
}
export type ScreenshotMode = 'off' | 'on' | 'only-on-failure' | 'on-first-failure';