Skip to content

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

feat(screencast): animate a mouse cursor between action points (#40916)

Pavel Feldman83ef991c9f37
diff --git a/docs/src/api/class-screencast.md b/docs/src/api/class-screencast.md
index b5d2c2757d..12e3111ffe 100644
--- a/docs/src/api/class-screencast.md
+++ b/docs/src/api/class-screencast.md
@@ -135,6 +135,14 @@ Position of the action title overlay. Defaults to `"top-right"`.
Font size of the action title in pixels. Defaults to `24`.
+### option: Screencast.showActions.cursor
+* since: v1.61
+- `cursor` ?<[ScreencastCursor]<"none"|"pointer">>
+
+Cursor decoration shown for pointer actions. `"pointer"` (the default) renders
+a mouse pointer that animates from the previous action point to the next one.
+`"none"` disables the cursor decoration.
+
## async method: Screencast.showOverlays
* since: v1.59
diff --git a/packages/injected/src/highlight.css b/packages/injected/src/highlight.css
index 54dc68ceb3..61a376f4eb 100644
--- a/packages/injected/src/highlight.css
+++ b/packages/injected/src/highlight.css
@@ -108,6 +108,21 @@ x-pw-action-point {
z-index: 2;
}
+x-pw-action-cursor {
+ position: absolute;
+ width: 18px;
+ height: 22px;
+ pointer-events: none;
+ z-index: 4;
+ filter: drop-shadow(0 1px 2px rgba(0, 0, 0, 0.4));
+}
+
+x-pw-action-cursor svg {
+ width: 100%;
+ height: 100%;
+ position: static;
+}
+
x-pw-title {
position: absolute;
backdrop-filter: blur(5px);
diff --git a/packages/injected/src/highlight.ts b/packages/injected/src/highlight.ts
index e1c927bc62..fbd012c4bc 100644
--- a/packages/injected/src/highlight.ts
+++ b/packages/injected/src/highlight.ts
@@ -55,6 +55,7 @@ export class Highlight {
private _glassPaneShadow: ShadowRoot;
private _renderedEntries: RenderedHighlightEntry[] = [];
private _actionPointElement: HTMLElement;
+ private _actionCursorElement: HTMLElement;
private _titleElement: HTMLElement;
private _userOverlayContainer: HTMLElement;
private _userOverlays = new Map<string, HTMLElement>();
@@ -85,6 +86,9 @@ export class Highlight {
this._glassPaneElement.style.backgroundColor = 'transparent';
this._actionPointElement = document.createElement('x-pw-action-point');
this._actionPointElement.setAttribute('hidden', 'true');
+ this._actionCursorElement = document.createElement('x-pw-action-cursor');
+ this._actionCursorElement.style.visibility = 'hidden';
+ this._actionCursorElement.appendChild(this._createCursorSvg(document));
this._titleElement = document.createElement('x-pw-title');
this._titleElement.setAttribute('hidden', 'true');
this._userOverlayContainer = document.createElement('x-pw-user-overlays');
@@ -102,6 +106,7 @@ export class Highlight {
this._glassPaneShadow.appendChild(styleElement);
}
this._glassPaneShadow.appendChild(this._actionPointElement);
+ this._glassPaneShadow.appendChild(this._actionCursorElement);
this._glassPaneShadow.appendChild(this._titleElement);
this._glassPaneShadow.appendChild(this._userOverlayContainer);
}
@@ -186,6 +191,32 @@ export class Highlight {
this._actionPointElement.hidden = true;
}
+ moveActionCursor(x: number, y: number, fadeDuration?: number) {
+ const moveDuration = fadeDuration ? Math.max(80, Math.min(fadeDuration * 0.6, 400)) : 0;
+ this._actionCursorElement.style.transition = `top ${moveDuration}ms ease, left ${moveDuration}ms ease`;
+ this._actionCursorElement.style.left = x + 'px';
+ this._actionCursorElement.style.top = y + 'px';
+ this._actionCursorElement.style.visibility = 'visible';
+ }
+
+ hideActionCursor() {
+ this._actionCursorElement.style.visibility = 'hidden';
+ }
+
+ private _createCursorSvg(document: Document): SVGSVGElement {
+ const svgNs = 'http://www.w3.org/2000/svg';
+ const svg = document.createElementNS(svgNs, 'svg');
+ svg.setAttribute('viewBox', '0 0 18 22');
+ const path = document.createElementNS(svgNs, 'path');
+ path.setAttribute('d', 'M1 1 L1 17 L5.5 13 L8 20.5 L11 19.5 L8.5 12 L15 12 Z');
+ path.setAttribute('fill', 'white');
+ path.setAttribute('stroke', 'black');
+ path.setAttribute('stroke-width', '1.5');
+ path.setAttribute('stroke-linejoin', 'round');
+ svg.appendChild(path);
+ return svg;
+ }
+
showActionTitle(text: string, fadeDuration: number, position?: string, fontSize?: number) {
this._titleElement.textContent = text;
this._titleElement.hidden = false;
diff --git a/packages/injected/src/injectedScript.ts b/packages/injected/src/injectedScript.ts
index 0b3e9f4e58..e7b476fd1c 100644
--- a/packages/injected/src/injectedScript.ts
+++ b/packages/injected/src/injectedScript.ts
@@ -1337,12 +1337,13 @@ export class InjectedScript {
highlight.removeElementHighlight(selector);
}
- setScreencastAnnotation(annotation: { point?: channels.Point, box?: channels.Rect, actionTitle?: string, duration?: number, position?: string, fontSize?: number } | null) {
+ setScreencastAnnotation(annotation: { point?: channels.Point, box?: channels.Rect, actionTitle?: string, duration?: number, position?: string, fontSize?: number, cursor?: 'none' | 'pointer' } | null) {
const highlight = this._ensureHighlight();
if (!annotation) {
highlight.updateHighlight([]);
highlight.hideActionPoint();
highlight.hideActionTitle();
+ highlight.hideActionCursor();
return;
}
const fadeDuration = annotation.duration ?? 500;
@@ -1355,8 +1356,11 @@ export class InjectedScript {
fadeDuration,
}]);
}
- if (annotation.point)
+ if (annotation.point) {
+ if (annotation.cursor !== 'none')
+ highlight.moveActionCursor(annotation.point.x, annotation.point.y, fadeDuration);
highlight.showActionPoint(annotation.point.x, annotation.point.y, fadeDuration);
+ }
if (annotation.actionTitle)
highlight.showActionTitle(annotation.actionTitle, fadeDuration, annotation.position, annotation.fontSize);
}
diff --git a/packages/playwright-client/types/types.d.ts b/packages/playwright-client/types/types.d.ts
index cde7893fa4..9697f25c49 100644
--- a/packages/playwright-client/types/types.d.ts
+++ b/packages/playwright-client/types/types.d.ts
@@ -16647,6 +16647,12 @@ export interface Screencast {
* @param options
*/
showActions(options?: {
+ /**
+ * Cursor decoration shown for pointer actions. `"pointer"` (the default) renders a mouse pointer that animates from
+ * the previous action point to the next one. `"none"` disables the cursor decoration.
+ */
+ cursor?: "none"|"pointer";
+
/**
* 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 e4a775688e..c9cdf535bf 100644
--- a/packages/playwright-core/src/client/screencast.ts
+++ b/packages/playwright-core/src/client/screencast.ts
@@ -65,8 +65,8 @@ 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 });
+ async showActions(options?: { duration?: number, position?: 'top-left' | 'top' | 'top-right' | 'bottom-left' | 'bottom' | 'bottom-right', fontSize?: number, cursor?: 'none' | 'pointer' }): Promise<DisposableStub> {
+ await this._page._channel.screencastShowActions({ duration: options?.duration, position: options?.position, fontSize: options?.fontSize, cursor: options?.cursor });
return new DisposableStub(() => this._page._channel.screencastHideActions());
}
diff --git a/packages/playwright-core/src/protocol/validator.ts b/packages/playwright-core/src/protocol/validator.ts
index a7f4ffd992..a89255ed20 100644
--- a/packages/playwright-core/src/protocol/validator.ts
+++ b/packages/playwright-core/src/protocol/validator.ts
@@ -207,6 +207,7 @@ scheme.AndroidDeviceLaunchBrowserParams = tObject({
duration: tOptional(tFloat),
position: tOptional(tEnum(['top-left', 'top', 'top-right', 'bottom-left', 'bottom', 'bottom-right'])),
fontSize: tOptional(tInt),
+ cursor: tOptional(tEnum(['none', 'pointer'])),
})),
})),
strictSelectors: tOptional(tBoolean),
@@ -489,6 +490,7 @@ scheme.BrowserNewContextParams = tObject({
duration: tOptional(tFloat),
position: tOptional(tEnum(['top-left', 'top', 'top-right', 'bottom-left', 'bottom', 'bottom-right'])),
fontSize: tOptional(tInt),
+ cursor: tOptional(tEnum(['none', 'pointer'])),
})),
})),
strictSelectors: tOptional(tBoolean),
@@ -565,6 +567,7 @@ scheme.BrowserNewContextForReuseParams = tObject({
duration: tOptional(tFloat),
position: tOptional(tEnum(['top-left', 'top', 'top-right', 'bottom-left', 'bottom', 'bottom-right'])),
fontSize: tOptional(tInt),
+ cursor: tOptional(tEnum(['none', 'pointer'])),
})),
})),
strictSelectors: tOptional(tBoolean),
@@ -663,6 +666,7 @@ scheme.BrowserContextInitializer = tObject({
duration: tOptional(tFloat),
position: tOptional(tEnum(['top-left', 'top', 'top-right', 'bottom-left', 'bottom', 'bottom-right'])),
fontSize: tOptional(tInt),
+ cursor: tOptional(tEnum(['none', 'pointer'])),
})),
})),
strictSelectors: tOptional(tBoolean),
@@ -1066,6 +1070,7 @@ scheme.BrowserTypeLaunchPersistentContextParams = tObject({
duration: tOptional(tFloat),
position: tOptional(tEnum(['top-left', 'top', 'top-right', 'bottom-left', 'bottom', 'bottom-right'])),
fontSize: tOptional(tInt),
+ cursor: tOptional(tEnum(['none', 'pointer'])),
})),
})),
strictSelectors: tOptional(tBoolean),
@@ -1159,6 +1164,7 @@ scheme.ElectronLaunchParams = tObject({
duration: tOptional(tFloat),
position: tOptional(tEnum(['top-left', 'top', 'top-right', 'bottom-left', 'bottom', 'bottom-right'])),
fontSize: tOptional(tInt),
+ cursor: tOptional(tEnum(['none', 'pointer'])),
})),
})),
strictSelectors: tOptional(tBoolean),
@@ -2633,6 +2639,7 @@ scheme.PageScreencastShowActionsParams = tObject({
duration: tOptional(tFloat),
position: tOptional(tEnum(['top-left', 'top', 'top-right', 'bottom-left', 'bottom', 'bottom-right'])),
fontSize: tOptional(tInt),
+ cursor: tOptional(tEnum(['none', 'pointer'])),
});
scheme.PageScreencastShowActionsResult = tOptional(tObject({}));
scheme.PageScreencastHideActionsParams = tOptional(tObject({}));
diff --git a/packages/playwright-core/src/server/dispatchers/pageDispatcher.ts b/packages/playwright-core/src/server/dispatchers/pageDispatcher.ts
index 1e2e7d0c0f..45eee1bbba 100644
--- a/packages/playwright-core/src/server/dispatchers/pageDispatcher.ts
+++ b/packages/playwright-core/src/server/dispatchers/pageDispatcher.ts
@@ -384,7 +384,7 @@ export class PageDispatcher extends Dispatcher<Page, channels.PageChannel, Brows
}
async screencastShowActions(params: channels.PageScreencastShowActionsParams): Promise<channels.PageScreencastShowActionsResult> {
- this._page.screencast.showActions({ duration: params.duration, position: params.position, fontSize: params.fontSize });
+ this._page.screencast.showActions({ duration: params.duration, position: params.position, fontSize: params.fontSize, cursor: params.cursor });
}
async screencastHideActions(): Promise<channels.PageScreencastHideActionsResult> {
diff --git a/packages/playwright-core/src/server/screencast.ts b/packages/playwright-core/src/server/screencast.ts
index 2ef83140e9..085d20b28f 100644
--- a/packages/playwright-core/src/server/screencast.ts
+++ b/packages/playwright-core/src/server/screencast.ts
@@ -38,6 +38,7 @@ type ActionOptions = {
duration?: number,
position?: AnnotatePosition,
fontSize?: number,
+ cursor?: 'none' | 'pointer',
};
export class Screencast implements InstrumentationListener {
@@ -182,6 +183,7 @@ export class Screencast implements InstrumentationListener {
actionTitle,
position: this._actions?.position,
fontSize: this._actions?.fontSize,
+ cursor: this._actions?.cursor ?? 'pointer',
}).catch(e => debugLogger.log('error', e));
}
}
diff --git a/packages/playwright-core/src/tools/backend/video.ts b/packages/playwright-core/src/tools/backend/video.ts
index 5ed2237ae3..ad49b09bc2 100644
--- a/packages/playwright-core/src/tools/backend/video.ts
+++ b/packages/playwright-core/src/tools/backend/video.ts
@@ -95,6 +95,7 @@ const videoChapter = defineTool({
});
const actionPosition = z.enum(['top-left', 'top', 'top-right', 'bottom-left', 'bottom', 'bottom-right']);
+const actionCursor = z.enum(['none', 'pointer']);
const videoShowActions = defineTool({
capability: 'devtools',
@@ -106,6 +107,7 @@ const videoShowActions = defineTool({
inputSchema: z.object({
duration: z.number().optional().describe('How long each action annotation stays on screen, in milliseconds. Defaults to 500.'),
position: actionPosition.optional().describe('Where to place the action title relative to the page. Defaults to top-right.'),
+ cursor: actionCursor.optional().describe('Cursor decoration for pointer actions. "pointer" (default) animates a mouse pointer from the previous action point to the next one; "none" disables the cursor decoration.'),
}),
type: 'readOnly',
},
@@ -115,6 +117,7 @@ const videoShowActions = defineTool({
await tab.page.screencast.showActions({
duration: params.duration,
position: params.position,
+ cursor: params.cursor,
});
response.addTextResult('Action annotations enabled.');
},
diff --git a/packages/playwright-core/src/tools/cli-daemon/commands.ts b/packages/playwright-core/src/tools/cli-daemon/commands.ts
index a280825b20..689f7b0e35 100644
--- a/packages/playwright-core/src/tools/cli-daemon/commands.ts
+++ b/packages/playwright-core/src/tools/cli-daemon/commands.ts
@@ -973,6 +973,7 @@ const videoChapter = declareCommand({
});
const actionPositionArg = z.enum(['top-left', 'top', 'top-right', 'bottom-left', 'bottom', 'bottom-right']);
+const actionCursorArg = z.enum(['none', 'pointer']);
const videoShowActions = declareCommand({
name: 'video-show-actions',
@@ -982,9 +983,10 @@ const videoShowActions = declareCommand({
options: z.object({
duration: numberArg.optional().describe('How long each action annotation stays on screen, in milliseconds. Defaults to 500.'),
position: actionPositionArg.optional().describe('Where to place the action title: top-left, top, top-right, bottom-left, bottom, bottom-right. Defaults to top-right.'),
+ cursor: actionCursorArg.optional().describe('Cursor decoration: "pointer" (default) animates a mouse pointer between action points; "none" disables it.'),
}),
toolName: 'browser_video_show_actions',
- toolParams: ({ duration, position }) => ({ duration, position }),
+ toolParams: ({ duration, position, cursor }) => ({ duration, position, cursor }),
});
const videoHideActions = declareCommand({
diff --git a/packages/playwright-core/types/types.d.ts b/packages/playwright-core/types/types.d.ts
index cde7893fa4..9697f25c49 100644
--- a/packages/playwright-core/types/types.d.ts
+++ b/packages/playwright-core/types/types.d.ts
@@ -16647,6 +16647,12 @@ export interface Screencast {
* @param options
*/
showActions(options?: {
+ /**
+ * Cursor decoration shown for pointer actions. `"pointer"` (the default) renders a mouse pointer that animates from
+ * the previous action point to the next one. `"none"` disables the cursor decoration.
+ */
+ cursor?: "none"|"pointer";
+
/**
* How long each annotation is displayed in milliseconds. Defaults to `500`.
*/
diff --git a/packages/protocol/spec/mixins.yml b/packages/protocol/spec/mixins.yml
index 9d7cd06678..c950b7f2b6 100644
--- a/packages/protocol/spec/mixins.yml
+++ b/packages/protocol/spec/mixins.yml
@@ -26,6 +26,11 @@ ShowActionsOptions:
- bottom
- bottom-right
fontSize: int?
+ cursor:
+ type: enum?
+ literals:
+ - none
+ - pointer
CommonScreenshotOptions:
type: mixin
diff --git a/packages/protocol/src/channels.d.ts b/packages/protocol/src/channels.d.ts
index f1e8d0c685..4990815165 100644
--- a/packages/protocol/src/channels.d.ts
+++ b/packages/protocol/src/channels.d.ts
@@ -443,6 +443,7 @@ export type AndroidDeviceLaunchBrowserParams = {
duration?: number,
position?: 'top-left' | 'top' | 'top-right' | 'bottom-left' | 'bottom' | 'bottom-right',
fontSize?: number,
+ cursor?: 'none' | 'pointer',
},
},
strictSelectors?: boolean,
@@ -514,6 +515,7 @@ export type AndroidDeviceLaunchBrowserOptions = {
duration?: number,
position?: 'top-left' | 'top' | 'top-right' | 'bottom-left' | 'bottom' | 'bottom-right',
fontSize?: number,
+ cursor?: 'none' | 'pointer',
},
},
strictSelectors?: boolean,
@@ -957,6 +959,7 @@ export type BrowserNewContextParams = {
duration?: number,
position?: 'top-left' | 'top' | 'top-right' | 'bottom-left' | 'bottom' | 'bottom-right',
fontSize?: number,
+ cursor?: 'none' | 'pointer',
},
},
strictSelectors?: boolean,
@@ -1030,6 +1033,7 @@ export type BrowserNewContextOptions = {
duration?: number,
position?: 'top-left' | 'top' | 'top-right' | 'bottom-left' | 'bottom' | 'bottom-right',
fontSize?: number,
+ cursor?: 'none' | 'pointer',
},
},
strictSelectors?: boolean,
@@ -1106,6 +1110,7 @@ export type BrowserNewContextForReuseParams = {
duration?: number,
position?: 'top-left' | 'top' | 'top-right' | 'bottom-left' | 'bottom' | 'bottom-right',
fontSize?: number,
+ cursor?: 'none' | 'pointer',
},
},
strictSelectors?: boolean,
@@ -1179,6 +1184,7 @@ export type BrowserNewContextForReuseOptions = {
duration?: number,
position?: 'top-left' | 'top' | 'top-right' | 'bottom-left' | 'bottom' | 'bottom-right',
fontSize?: number,
+ cursor?: 'none' | 'pointer',
},
},
strictSelectors?: boolean,
@@ -1294,6 +1300,7 @@ export type BrowserContextInitializer = {
duration?: number,
position?: 'top-left' | 'top' | 'top-right' | 'bottom-left' | 'bottom' | 'bottom-right',
fontSize?: number,
+ cursor?: 'none' | 'pointer',
},
},
strictSelectors?: boolean,
@@ -1948,6 +1955,7 @@ export type BrowserTypeLaunchPersistentContextParams = {
duration?: number,
position?: 'top-left' | 'top' | 'top-right' | 'bottom-left' | 'bottom' | 'bottom-right',
fontSize?: number,
+ cursor?: 'none' | 'pointer',
},
},
strictSelectors?: boolean,
@@ -2035,6 +2043,7 @@ export type BrowserTypeLaunchPersistentContextOptions = {
duration?: number,
position?: 'top-left' | 'top' | 'top-right' | 'bottom-left' | 'bottom' | 'bottom-right',
fontSize?: number,
+ cursor?: 'none' | 'pointer',
},
},
strictSelectors?: boolean,
@@ -2163,6 +2172,7 @@ export type ElectronLaunchParams = {
duration?: number,
position?: 'top-left' | 'top' | 'top-right' | 'bottom-left' | 'bottom' | 'bottom-right',
fontSize?: number,
+ cursor?: 'none' | 'pointer',
},
},
strictSelectors?: boolean,
@@ -2205,6 +2215,7 @@ export type ElectronLaunchOptions = {
duration?: number,
position?: 'top-left' | 'top' | 'top-right' | 'bottom-left' | 'bottom' | 'bottom-right',
fontSize?: number,
+ cursor?: 'none' | 'pointer',
},
},
strictSelectors?: boolean,
@@ -4648,11 +4659,13 @@ export type PageScreencastShowActionsParams = {
duration?: number,
position?: 'top-left' | 'top' | 'top-right' | 'bottom-left' | 'bottom' | 'bottom-right',
fontSize?: number,
+ cursor?: 'none' | 'pointer',
};
export type PageScreencastShowActionsOptions = {
duration?: number,
position?: 'top-left' | 'top' | 'top-right' | 'bottom-left' | 'bottom' | 'bottom-right',
fontSize?: number,
+ cursor?: 'none' | 'pointer',
};
export type PageScreencastShowActionsResult = void;
export type PageScreencastHideActionsParams = {};
diff --git a/tests/library/screencast-actions.spec.ts b/tests/library/screencast-actions.spec.ts
index 6dbf0b8179..abd57834bf 100644
--- a/tests/library/screencast-actions.spec.ts
+++ b/tests/library/screencast-actions.spec.ts
@@ -182,6 +182,65 @@ test('should stop showing actions after hideActions', async ({ browser, server }
await context.close();
});
+test('should render an action cursor that animates to the click point', 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(() => {});
+
+ const cursor = page.locator('x-pw-action-cursor');
+ await expect(cursor).toBeVisible();
+
+ const initial = await cursor.evaluate((el: HTMLElement) => ({
+ top: el.style.top,
+ left: el.style.left,
+ }));
+ expect(initial.top).toMatch(/\d+px/);
+ expect(initial.left).toMatch(/\d+px/);
+
+ await context.close();
+});
+
+test('cursor moves between two pointer actions', async ({ browser, server }) => {
+ const context = await browser.newContext();
+ const page = await context.newPage();
+ await page.setContent(`
+ <div style="position: fixed; top: 20px; left: 20px; width: 60px; height: 60px;" id="a">A</div>
+ <div style="position: fixed; bottom: 20px; right: 20px; width: 60px; height: 60px;" id="b">B</div>
+ `);
+
+ await page.screencast.showActions({ duration: 5000 });
+ const cursor = page.locator('x-pw-action-cursor');
+
+ page.click('#a', { force: true }).catch(() => {});
+ await expect(cursor).toBeVisible();
+ const first = await cursor.evaluate((el: HTMLElement) => ({ top: el.style.top, left: el.style.left }));
+
+ page.click('#b', { force: true }).catch(() => {});
+ await expect.poll(async () => {
+ return await cursor.evaluate((el: HTMLElement) => ({ top: el.style.top, left: el.style.left }));
+ }).not.toEqual(first);
+
+ await context.close();
+});
+
+test('cursor: "none" suppresses the action cursor decoration', 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, cursor: 'none' });
+ page.click('button').catch(() => {});
+
+ // The click marker still renders, but the cursor does not.
+ await expect(page.locator('x-pw-action-point')).toBeVisible();
+ await expect(page.locator('x-pw-action-cursor')).toBeHidden();
+
+ await context.close();
+});
+
test('should survive navigation', async ({ browser, server }) => {
const context = await browser.newContext();
const page = await context.newPage();