Skip to content

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

feat: add Page.cancelPickLocator() API (#39488)

Yury Semikhatskya3ce55552979
diff --git a/docs/src/api/class-page.md b/docs/src/api/class-page.md
index 7f2fb1dea7..fa226172ac 100644
--- a/docs/src/api/class-page.md
+++ b/docs/src/api/class-page.md
@@ -2845,6 +2845,12 @@ the place it was paused.
This method requires Playwright to be started in a headed mode, with a falsy [`option: BrowserType.launch.headless`] option.
:::
+## async method: Page.cancelPickLocator
+* since: v1.59
+
+Cancels an ongoing [`method: Page.pickLocator`] call by deactivating pick locator mode.
+If no pick locator mode is active, this method is a no-op.
+
## async method: Page.pickLocator
* since: v1.59
- returns: <[Locator]>
diff --git a/packages/playwright-client/types/types.d.ts b/packages/playwright-client/types/types.d.ts
index 9669ee26c4..979a929dd6 100644
--- a/packages/playwright-client/types/types.d.ts
+++ b/packages/playwright-client/types/types.d.ts
@@ -2187,6 +2187,12 @@ export interface Page {
*/
bringToFront(): Promise<void>;
+ /**
+ * Cancels an ongoing [page.pickLocator()](https://playwright.dev/docs/api/class-page#page-pick-locator) call by
+ * deactivating pick locator mode. If no pick locator mode is active, this method is a no-op.
+ */
+ cancelPickLocator(): Promise<void>;
+
/**
* **NOTE** Use locator-based [locator.check([options])](https://playwright.dev/docs/api/class-locator#locator-check) instead.
* Read more about [locators](https://playwright.dev/docs/locators).
diff --git a/packages/playwright-core/src/client/page.ts b/packages/playwright-core/src/client/page.ts
index 7631491213..42f14dec3b 100644
--- a/packages/playwright-core/src/client/page.ts
+++ b/packages/playwright-core/src/client/page.ts
@@ -824,6 +824,10 @@ export class Page extends ChannelOwner<channels.PageChannel> implements api.Page
return this.locator(selector);
}
+ async cancelPickLocator(): Promise<void> {
+ await this._channel.cancelPickLocator({});
+ }
+
async pdf(options: PDFOptions = {}): Promise<Buffer> {
const transportOptions: channels.PagePdfParams = { ...options } as channels.PagePdfParams;
if (transportOptions.margin)
diff --git a/packages/playwright-core/src/protocol/validator.ts b/packages/playwright-core/src/protocol/validator.ts
index 346a2f6106..d554ad8983 100644
--- a/packages/playwright-core/src/protocol/validator.ts
+++ b/packages/playwright-core/src/protocol/validator.ts
@@ -1534,6 +1534,8 @@ scheme.PagePickLocatorParams = tOptional(tObject({}));
scheme.PagePickLocatorResult = tObject({
selector: tString,
});
+scheme.PageCancelPickLocatorParams = tOptional(tObject({}));
+scheme.PageCancelPickLocatorResult = tOptional(tObject({}));
scheme.PageVideoStartParams = tObject({
size: tOptional(tObject({
width: tInt,
diff --git a/packages/playwright-core/src/server/debugController.ts b/packages/playwright-core/src/server/debugController.ts
index a9c4aafc7d..26858e3c07 100644
--- a/packages/playwright-core/src/server/debugController.ts
+++ b/packages/playwright-core/src/server/debugController.ts
@@ -79,10 +79,12 @@ export class DebugController extends SdkObject {
this._generateAutoExpect = !!params.generateAutoExpect;
if (params.mode === 'none') {
+ const promises = [];
for (const recorder of await progress.race(this._allRecorders())) {
- recorder.hideHighlightedSelector();
- recorder.setMode('none');
+ promises.push(recorder.hideHighlightedSelector());
+ promises.push(recorder.setMode('none'));
}
+ await Promise.all(promises);
return;
}
@@ -112,20 +114,24 @@ export class DebugController extends SdkObject {
if (params.selector)
unsafeLocatorOrSelectorAsSelector(this._sdkLanguage, params.selector, 'data-testid');
const ariaTemplate = params.ariaTemplate ? parseAriaSnapshotUnsafe(yaml, params.ariaTemplate) : undefined;
+ const promises = [];
for (const recorder of await progress.race(this._allRecorders())) {
if (ariaTemplate)
- recorder.setHighlightedAriaTemplate(ariaTemplate);
+ promises.push(recorder.setHighlightedAriaTemplate(ariaTemplate));
else if (params.selector)
- recorder.setHighlightedSelector(params.selector);
+ promises.push(recorder.setHighlightedSelector(params.selector));
}
+ await Promise.all(promises);
}
async hideHighlight(progress: Progress) {
+ const promises = [];
// Hide all active recorder highlights.
for (const recorder of await progress.race(this._allRecorders()))
- recorder.hideHighlightedSelector();
+ promises.push(recorder.hideHighlightedSelector());
// Hide all locator.highlight highlights.
- await Promise.all(this._playwright.allPages().map(p => p.hideHighlight().catch(() => {})));
+ promises.push(...this._playwright.allPages().map(p => p.hideHighlight().catch(() => {})));
+ await Promise.all(promises);
}
async resume(progress: Progress) {
diff --git a/packages/playwright-core/src/server/devtoolsController.ts b/packages/playwright-core/src/server/devtoolsController.ts
index 35c7f19ce1..0a85d3498d 100644
--- a/packages/playwright-core/src/server/devtoolsController.ts
+++ b/packages/playwright-core/src/server/devtoolsController.ts
@@ -257,20 +257,22 @@ class DevToolsConnection implements Transport, DevToolsChannel {
await page.screencast.startScreencast(this, { width: 1280, height: 800, quality: 90 });
}
- private _deselectPage() {
+ private async _deselectPage() {
if (!this.selectedPage)
return;
- this._cancelPicking();
+ const promises = [];
+ promises.push(this._cancelPicking());
eventsHelper.removeEventListeners(this._pageListeners);
this._pageListeners = [];
- this.selectedPage.screencast.stopScreencast(this);
+ promises.push(this.selectedPage.screencast.stopScreencast(this));
this.selectedPage = null;
this._lastFrameData = null;
this._lastViewportSize = null;
+ await Promise.all(promises);
}
async pickLocator() {
- this._cancelPicking();
+ await this._cancelPicking();
const recorder = await Recorder.forContext(this._context, { omitCallTracking: true, hideToolbar: true });
this._recorder = recorder;
this._recorderListeners.push(
@@ -279,18 +281,18 @@ class DevToolsConnection implements Transport, DevToolsChannel {
this._cancelPicking();
}),
);
- recorder.setMode('inspecting');
+ await recorder.setMode('inspecting');
}
async cancelPickLocator() {
- this._cancelPicking();
+ await this._cancelPicking();
}
- private _cancelPicking() {
+ private async _cancelPicking() {
eventsHelper.removeEventListeners(this._recorderListeners);
this._recorderListeners = [];
if (this._recorder) {
- this._recorder.setMode('none');
+ await this._recorder.setMode('none');
this._recorder = null;
}
}
diff --git a/packages/playwright-core/src/server/dispatchers/browserContextDispatcher.ts b/packages/playwright-core/src/server/dispatchers/browserContextDispatcher.ts
index 1d71932c28..49ba7cbda3 100644
--- a/packages/playwright-core/src/server/dispatchers/browserContextDispatcher.ts
+++ b/packages/playwright-core/src/server/dispatchers/browserContextDispatcher.ts
@@ -338,8 +338,7 @@ export class BrowserContextDispatcher extends Dispatcher<BrowserContext, channel
async disableRecorder(params: channels.BrowserContextDisableRecorderParams, progress: Progress): Promise<void> {
const recorder = await Recorder.existingForContext(this._context);
- if (recorder)
- recorder.setMode('none');
+ await recorder?.setMode('none');
}
async exposeConsoleApi(params: channels.BrowserContextExposeConsoleApiParams, progress: Progress): Promise<void> {
diff --git a/packages/playwright-core/src/server/dispatchers/pageDispatcher.ts b/packages/playwright-core/src/server/dispatchers/pageDispatcher.ts
index a834b2bfb5..96875090ee 100644
--- a/packages/playwright-core/src/server/dispatchers/pageDispatcher.ts
+++ b/packages/playwright-core/src/server/dispatchers/pageDispatcher.ts
@@ -29,7 +29,6 @@ import { SdkObject } from '../instrumentation';
import { deserializeURLMatch, urlMatches } from '../../utils/isomorphic/urlMatch';
import { PageAgentDispatcher } from './pageAgentDispatcher';
import { Recorder } from '../recorder';
-import { isUnderTest } from '../utils/debug';
import type { Artifact } from '../artifact';
import type { BrowserContext } from '../browserContext';
@@ -347,13 +346,16 @@ export class PageDispatcher extends Dispatcher<Page, channels.PageChannel, Brows
}
async pickLocator(params: channels.PagePickLocatorParams, progress: Progress): Promise<channels.PagePickLocatorResult> {
- if (!this._page.browserContext._browser.options.headful && !isUnderTest())
- throw new Error('pickLocator() is only available in headed mode');
const recorder = await Recorder.forContext(this._page.browserContext, { omitCallTracking: true, hideToolbar: true });
const selector = await recorder.pickLocator(progress);
return { selector };
}
+ async cancelPickLocator(params: channels.PageCancelPickLocatorParams, progress: Progress): Promise<void> {
+ const recorder = await Recorder.existingForContext(this._page.browserContext);
+ await recorder?.setMode('none');
+ }
+
async videoStart(params: channels.PageVideoStartParams, progress: Progress): Promise<channels.PageVideoStartResult> {
const artifact = await this._page.screencast.startExplicitVideoRecording(params);
return { artifact: createVideoDispatcher(this.parentScope(), artifact) };
diff --git a/packages/playwright-core/src/server/recorder.ts b/packages/playwright-core/src/server/recorder.ts
index 490b7b82f1..c66a0cb27b 100644
--- a/packages/playwright-core/src/server/recorder.ts
+++ b/packages/playwright-core/src/server/recorder.ts
@@ -198,7 +198,7 @@ export class Recorder extends EventEmitter<RecorderEventMap> implements Instrume
await this._context.exposeBinding(progress, '__pw_recorderSetMode', false, async ({ frame }, mode: Mode) => {
if (frame.parentFrame())
return;
- this.setMode(mode);
+ await this.setMode(mode);
});
await this._context.exposeBinding(progress, '__pw_recorderSetOverlayState', false, async ({ frame }, state: OverlayState) => {
@@ -252,7 +252,7 @@ export class Recorder extends EventEmitter<RecorderEventMap> implements Instrume
return this._mode;
}
- setMode(mode: Mode) {
+ async setMode(mode: Mode) {
if (this._mode === mode)
return;
this._highlightedElement = {};
@@ -262,7 +262,7 @@ export class Recorder extends EventEmitter<RecorderEventMap> implements Instrume
this._debugger.setMuted(this._isRecording());
if (this._mode !== 'none' && this._mode !== 'standby' && this._context.pages().length === 1)
this._context.pages()[0].bringToFront().catch(() => {});
- this._refreshOverlay();
+ await this._refreshOverlay();
}
async pickLocator(progress: Progress): Promise<string> {
@@ -272,6 +272,8 @@ export class Recorder extends EventEmitter<RecorderEventMap> implements Instrume
selectorPromise.resolve(elementInfo.selector);
};
const onModeChanged = () => {
+ if (this._mode === 'inspecting')
+ return;
recorderChangedState = true;
selectorPromise.reject(new Error('Locator picking was cancelled'));
};
@@ -279,21 +281,23 @@ export class Recorder extends EventEmitter<RecorderEventMap> implements Instrume
recorderChangedState = true;
selectorPromise.reject(new Error('Context was closed'));
};
- // Register listeners after setMode() to avoid consuming the ModeChanged
- // event that fires synchronously from our own setMode('inspecting') call.
- this.setMode('inspecting');
const listeners: RegisteredListener[] = [
eventsHelper.addEventListener(this, RecorderEvent.ElementPicked, onElementPicked),
eventsHelper.addEventListener(this, RecorderEvent.ModeChanged, onModeChanged),
eventsHelper.addEventListener(this, RecorderEvent.ContextClosed, onContextClosed),
];
try {
- return await progress.race(selectorPromise);
+ const doPickLocator = async () => {
+ // Prevent unhandled rejection in case of cancellation during setMode
+ selectorPromise.catch(() => {});
+ await this.setMode('inspecting');
+ return await selectorPromise;
+ };
+ return await progress.race(doPickLocator());
} finally {
- // Remove listeners before setMode('none') to avoid triggering onModeChanged.
eventsHelper.removeEventListeners(listeners);
if (!recorderChangedState)
- this.setMode('none');
+ await this.setMode('none');
}
}
@@ -302,23 +306,23 @@ export class Recorder extends EventEmitter<RecorderEventMap> implements Instrume
return page?.mainFrame().url();
}
- setHighlightedSelector(selector: string) {
+ async setHighlightedSelector(selector: string) {
this._highlightedElement = { selector: locatorOrSelectorAsSelector(this._currentLanguage, selector, this._context.selectors().testIdAttributeName()) };
- this._refreshOverlay();
+ await this._refreshOverlay();
}
- setHighlightedAriaTemplate(ariaTemplate: AriaTemplateNode) {
+ async setHighlightedAriaTemplate(ariaTemplate: AriaTemplateNode) {
this._highlightedElement = { ariaTemplate };
- this._refreshOverlay();
+ await this._refreshOverlay();
}
step() {
this._debugger.resume(true);
}
- setLanguage(language: Language) {
+ async setLanguage(language: Language) {
this._currentLanguage = language;
- this._refreshOverlay();
+ await this._refreshOverlay();
}
resume() {
@@ -337,9 +341,9 @@ export class Recorder extends EventEmitter<RecorderEventMap> implements Instrume
this._debugger.resume(false);
}
- hideHighlightedSelector() {
+ async hideHighlightedSelector() {
this._highlightedElement = {};
- this._refreshOverlay();
+ await this._refreshOverlay();
}
pausedSourceId() {
@@ -386,11 +390,9 @@ export class Recorder extends EventEmitter<RecorderEventMap> implements Instrume
}
}
- private _refreshOverlay() {
- for (const page of this._context.pages()) {
- for (const frame of page.frames())
- frame.evaluateExpression('window.__pw_refreshOverlay()').catch(() => {});
- }
+ private async _refreshOverlay() {
+ await Promise.all(this._context.pages().map(
+ page => page.safeNonStallingEvaluateInAllFrames('window.__pw_refreshOverlay()', 'main')));
}
async onBeforeCall(sdkObject: SdkObject, metadata: CallMetadata) {
diff --git a/packages/playwright-core/src/server/recorder/recorderApp.ts b/packages/playwright-core/src/server/recorder/recorderApp.ts
index a9184bfcc6..52713cab70 100644
--- a/packages/playwright-core/src/server/recorder/recorderApp.ts
+++ b/packages/playwright-core/src/server/recorder/recorderApp.ts
@@ -142,7 +142,7 @@ export class RecorderApp {
if (source) {
if (source.isRecorded)
this._selectedGeneratorId = source.id;
- this._recorder.setLanguage(source.language);
+ await this._recorder.setLanguage(source.language);
}
},
setAutoExpect: async (params: { autoExpect: boolean }) => {
@@ -150,7 +150,7 @@ export class RecorderApp {
this._updateActions();
},
setMode: async (params: { mode: Mode }) => {
- this._recorder.setMode(params.mode);
+ await this._recorder.setMode(params.mode);
},
resume: async () => {
this._recorder.resume();
@@ -163,9 +163,9 @@ export class RecorderApp {
},
highlightRequested: async (params: { selector?: string; ariaTemplate?: AriaTemplateNode }) => {
if (params.selector)
- this._recorder.setHighlightedSelector(params.selector);
+ await this._recorder.setHighlightedSelector(params.selector);
if (params.ariaTemplate)
- this._recorder.setHighlightedAriaTemplate(params.ariaTemplate);
+ await this._recorder.setHighlightedAriaTemplate(params.ariaTemplate);
},
};
diff --git a/packages/playwright-core/src/utils/isomorphic/protocolMetainfo.ts b/packages/playwright-core/src/utils/isomorphic/protocolMetainfo.ts
index 7f93d5cf1a..2cdbb3dec7 100644
--- a/packages/playwright-core/src/utils/isomorphic/protocolMetainfo.ts
+++ b/packages/playwright-core/src/utils/isomorphic/protocolMetainfo.ts
@@ -146,7 +146,8 @@ export const methodMetainfo = new Map<string, { internal?: boolean, title?: stri
['Page.startCSSCoverage', { title: 'Start CSS coverage', group: 'configuration', }],
['Page.stopCSSCoverage', { title: 'Stop CSS coverage', group: 'configuration', }],
['Page.bringToFront', { title: 'Bring to front', }],
- ['Page.pickLocator', { title: 'Pick locator', }],
+ ['Page.pickLocator', { title: 'Pick locator', group: 'configuration', }],
+ ['Page.cancelPickLocator', { title: 'Cancel pick locator', group: 'configuration', }],
['Page.videoStart', { title: 'Start video recording', group: 'configuration', }],
['Page.videoStop', { title: 'Stop video recording', 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 9669ee26c4..979a929dd6 100644
--- a/packages/playwright-core/types/types.d.ts
+++ b/packages/playwright-core/types/types.d.ts
@@ -2187,6 +2187,12 @@ export interface Page {
*/
bringToFront(): Promise<void>;
+ /**
+ * Cancels an ongoing [page.pickLocator()](https://playwright.dev/docs/api/class-page#page-pick-locator) call by
+ * deactivating pick locator mode. If no pick locator mode is active, this method is a no-op.
+ */
+ cancelPickLocator(): Promise<void>;
+
/**
* **NOTE** Use locator-based [locator.check([options])](https://playwright.dev/docs/api/class-locator#locator-check) instead.
* Read more about [locators](https://playwright.dev/docs/locators).
diff --git a/packages/protocol/src/channels.d.ts b/packages/protocol/src/channels.d.ts
index b4a848f06f..f7206cdc00 100644
--- a/packages/protocol/src/channels.d.ts
+++ b/packages/protocol/src/channels.d.ts
@@ -2147,6 +2147,7 @@ export interface PageChannel extends PageEventTarget, EventTargetChannel {
stopCSSCoverage(params?: PageStopCSSCoverageParams, progress?: Progress): Promise<PageStopCSSCoverageResult>;
bringToFront(params?: PageBringToFrontParams, progress?: Progress): Promise<PageBringToFrontResult>;
pickLocator(params?: PagePickLocatorParams, progress?: Progress): Promise<PagePickLocatorResult>;
+ cancelPickLocator(params?: PageCancelPickLocatorParams, progress?: Progress): Promise<PageCancelPickLocatorResult>;
videoStart(params: PageVideoStartParams, progress?: Progress): Promise<PageVideoStartResult>;
videoStop(params?: PageVideoStopParams, progress?: Progress): Promise<PageVideoStopResult>;
updateSubscription(params: PageUpdateSubscriptionParams, progress?: Progress): Promise<PageUpdateSubscriptionResult>;
@@ -2658,6 +2659,9 @@ export type PagePickLocatorOptions = {};
export type PagePickLocatorResult = {
selector: string,
};
+export type PageCancelPickLocatorParams = {};
+export type PageCancelPickLocatorOptions = {};
+export type PageCancelPickLocatorResult = void;
export type PageVideoStartParams = {
size?: {
width: number,
diff --git a/packages/protocol/src/protocol.yml b/packages/protocol/src/protocol.yml
index 8f19cf2a22..1e27b0edbd 100644
--- a/packages/protocol/src/protocol.yml
+++ b/packages/protocol/src/protocol.yml
@@ -2066,9 +2066,14 @@ Page:
pickLocator:
title: Pick locator
+ group: configuration
returns:
selector: string
+ cancelPickLocator:
+ title: Cancel pick locator
+ group: configuration
+
videoStart:
title: Start video recording
group: configuration
diff --git a/tests/library/inspector/recorder-api.spec.ts b/tests/library/inspector/recorder-api.spec.ts
index 4e897caead..75fd778003 100644
--- a/tests/library/inspector/recorder-api.spec.ts
+++ b/tests/library/inspector/recorder-api.spec.ts
@@ -165,3 +165,16 @@ test('page.pickLocator should return locator for picked element', async ({ page
const locator = await pickPromise;
await expect(locator).toHaveText('Submit');
});
+
+test('page.cancelPickLocator should cancel ongoing pickLocator', async ({ page }) => {
+ await page.setContent(`<button>Submit</button>`);
+
+ const scriptReady = page.waitForEvent('console', msg => msg.text() === 'Recorder script ready for test');
+ const pickPromise = page.pickLocator();
+ await scriptReady;
+
+ await Promise.all([
+ page.cancelPickLocator(),
+ expect(pickPromise).rejects.toThrow('Locator picking was cancelled'),
+ ]);
+});