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: add Page.cancelPickLocator() API (#39488)
Yury Semikhatskya3ce55552979
diff --git a/docs/src/api/class-page.md b/docs/src/api/class-page.mdindex 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.tsindex 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.tsindex 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.Pagereturn 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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, channelasync 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.tsindex 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.tsindex 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 Instrumeawait 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 Instrumereturn 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 Instrumethis._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 InstrumeselectorPromise.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 InstrumerecorderChangedState = 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 Instrumereturn 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 Instrumethis._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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.ymlindex 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: configurationreturns:selector: string+ cancelPickLocator:+ title: Cancel pick locator+ group: configuration+videoStart:title: Start video recordinggroup: configurationdiff --git a/tests/library/inspector/recorder-api.spec.ts b/tests/library/inspector/recorder-api.spec.tsindex 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 ({ pageconst 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'),+ ]);+});