Playwright is a framework for Web Testing and Automation. It allows testing Chromium, Firefox and WebKit with a single API.
TypeScript automationchromechromiume2e-testingelectronend-to-end-testingfirefoxjavascriptplaywrighttesttest-automationtestingtesting-toolswebwebkit
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.mdindex 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.59diff --git a/packages/injected/src/highlight.css b/packages/injected/src/highlight.cssindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.ymlindex 9d7cd06678..c950b7f2b6 100644--- a/packages/protocol/spec/mixins.yml+++ b/packages/protocol/spec/mixins.yml@@ -26,6 +26,11 @@ ShowActionsOptions:- bottom- bottom-rightfontSize: int?+ cursor:+ type: enum?+ literals:+ - none+ - pointerCommonScreenshotOptions:type: mixindiff --git a/packages/protocol/src/channels.d.ts b/packages/protocol/src/channels.d.tsindex 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.tsindex 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();