From 5c2c2970a7904d72c91ca798caa760fd296c2434 Mon Sep 17 00:00:00 2001 From: Yury Semikhatsky Date: Tue, 3 Mar 2026 17:16:10 -0800 Subject: [PATCH] chore: move pickLocator to Page.inspector --- docs/src/api/class-inspector.md | 22 ++++--- docs/src/api/class-page.md | 24 -------- packages/playwright-client/types/types.d.ts | 58 +++++++------------ .../playwright-core/src/client/inspector.ts | 10 ++++ packages/playwright-core/src/client/page.ts | 9 --- packages/playwright-core/types/types.d.ts | 58 +++++++------------ tests/library/inspector/recorder-api.spec.ts | 10 ++-- 7 files changed, 74 insertions(+), 117 deletions(-) diff --git a/docs/src/api/class-inspector.md b/docs/src/api/class-inspector.md index 07a4f39503feb..a642cc9752e52 100644 --- a/docs/src/api/class-inspector.md +++ b/docs/src/api/class-inspector.md @@ -4,16 +4,24 @@ Interface to the Playwright inspector. +## async method: Inspector.cancelPickLocator +* since: v1.59 + +Cancels an ongoing [`method: Inspector.pickLocator`] call by deactivating pick locator mode. +If no pick locator mode is active, this method is a no-op. + +## async method: Inspector.pickLocator +* since: v1.59 +- returns: <[Locator]> + +Enters pick locator mode where hovering over page elements highlights them and shows the corresponding locator. +Once the user clicks an element, the mode is deactivated and the [Locator] for the picked element is returned. + **Usage** ```js -const inspector = page.inspector(); -inspector.on('screencastframe', ({ data, width, height }) => { - console.log(`received frame ${width}x${height}, jpeg size: ${data.length}`); -}); -await inspector.startScreencast(); -// ... perform actions ... -await inspector.stopScreencast(); +const locator = await page.inspector().pickLocator(); +console.log(locator); ``` ## event: Inspector.screencastFrame diff --git a/docs/src/api/class-page.md b/docs/src/api/class-page.md index 4618253e18d4d..8e89b1af12a95 100644 --- a/docs/src/api/class-page.md +++ b/docs/src/api/class-page.md @@ -2864,30 +2864,6 @@ 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]> - -Enters pick locator mode where hovering over page elements highlights them and shows the corresponding locator. -Once the user clicks an element, the mode is deactivated and the [Locator] for the picked element is returned. - -:::note -This method requires Playwright to be started in a headed mode. -::: - -**Usage** - -```js -const locator = await page.pickLocator(); -console.log(locator); -``` - ## async method: Page.pdf * since: v1.8 - returns: <[Buffer]> diff --git a/packages/playwright-client/types/types.d.ts b/packages/playwright-client/types/types.d.ts index 5cfbb21320586..e20be3e3d7c98 100644 --- a/packages/playwright-client/types/types.d.ts +++ b/packages/playwright-client/types/types.d.ts @@ -2187,12 +2187,6 @@ export interface Page { */ bringToFront(): Promise; - /** - * 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; - /** * **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). @@ -3928,23 +3922,6 @@ export interface Page { width?: string|number; }): Promise; - /** - * Enters pick locator mode where hovering over page elements highlights them and shows the corresponding locator. - * Once the user clicks an element, the mode is deactivated and the - * [Locator](https://playwright.dev/docs/api/class-locator) for the picked element is returned. - * - * **NOTE** This method requires Playwright to be started in a headed mode. - * - * **Usage** - * - * ```js - * const locator = await page.pickLocator(); - * console.log(locator); - * ``` - * - */ - pickLocator(): Promise; - /** * **NOTE** Use locator-based [locator.press(key[, options])](https://playwright.dev/docs/api/class-locator#locator-press) * instead. Read more about [locators](https://playwright.dev/docs/locators). @@ -20438,19 +20415,6 @@ export interface FrameLocator { /** * Interface to the Playwright inspector. - * - * **Usage** - * - * ```js - * const inspector = page.inspector(); - * inspector.on('screencastframe', ({ data, width, height }) => { - * console.log(`received frame ${width}x${height}, jpeg size: ${data.length}`); - * }); - * await inspector.startScreencast(); - * // ... perform actions ... - * await inspector.stopScreencast(); - * ``` - * */ export interface Inspector { /** @@ -20615,6 +20579,28 @@ export interface Inspector { height: number; }) => any): this; + /** + * Cancels an ongoing + * [inspector.pickLocator()](https://playwright.dev/docs/api/class-inspector#inspector-pick-locator) call by + * deactivating pick locator mode. If no pick locator mode is active, this method is a no-op. + */ + cancelPickLocator(): Promise; + + /** + * Enters pick locator mode where hovering over page elements highlights them and shows the corresponding locator. + * Once the user clicks an element, the mode is deactivated and the + * [Locator](https://playwright.dev/docs/api/class-locator) for the picked element is returned. + * + * **Usage** + * + * ```js + * const locator = await page.inspector().pickLocator(); + * console.log(locator); + * ``` + * + */ + pickLocator(): Promise; + /** * Starts capturing screencast frames. Frames are emitted as * [inspector.on('screencastframe')](https://playwright.dev/docs/api/class-inspector#inspector-event-screencast-frame) diff --git a/packages/playwright-core/src/client/inspector.ts b/packages/playwright-core/src/client/inspector.ts index 98b81c347cb15..c59816888fef6 100644 --- a/packages/playwright-core/src/client/inspector.ts +++ b/packages/playwright-core/src/client/inspector.ts @@ -17,6 +17,7 @@ import { EventEmitter } from './eventEmitter'; import type * as api from '../../types/types'; +import type { Locator } from './locator'; import type { Page } from './page'; export class Inspector extends EventEmitter implements api.Inspector { @@ -28,6 +29,15 @@ export class Inspector extends EventEmitter implements api.Inspector { this._page._channel.on('screencastFrame', ({ data, width, height }) => this.emit('screencastframe', { data, width, height })); } + async pickLocator(): Promise { + const { selector } = await this._page._channel.pickLocator({}); + return this._page.locator(selector); + } + + async cancelPickLocator(): Promise { + await this._page._channel.cancelPickLocator({}); + } + async startScreencast(options: { size?: { width: number, height: number } } = {}): Promise { await this._page._channel.startScreencast(options); } diff --git a/packages/playwright-core/src/client/page.ts b/packages/playwright-core/src/client/page.ts index d1eaca443e12e..72a4f9eda5218 100644 --- a/packages/playwright-core/src/client/page.ts +++ b/packages/playwright-core/src/client/page.ts @@ -826,15 +826,6 @@ export class Page extends ChannelOwner implements api.Page this._browserContext.setDefaultTimeout(defaultTimeout); } - async pickLocator(): Promise { - const { selector } = await this._channel.pickLocator({}); - return this.locator(selector); - } - - async cancelPickLocator(): Promise { - await this._channel.cancelPickLocator({}); - } - async pdf(options: PDFOptions = {}): Promise { const transportOptions: channels.PagePdfParams = { ...options } as channels.PagePdfParams; if (transportOptions.margin) diff --git a/packages/playwright-core/types/types.d.ts b/packages/playwright-core/types/types.d.ts index 5cfbb21320586..e20be3e3d7c98 100644 --- a/packages/playwright-core/types/types.d.ts +++ b/packages/playwright-core/types/types.d.ts @@ -2187,12 +2187,6 @@ export interface Page { */ bringToFront(): Promise; - /** - * 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; - /** * **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). @@ -3928,23 +3922,6 @@ export interface Page { width?: string|number; }): Promise; - /** - * Enters pick locator mode where hovering over page elements highlights them and shows the corresponding locator. - * Once the user clicks an element, the mode is deactivated and the - * [Locator](https://playwright.dev/docs/api/class-locator) for the picked element is returned. - * - * **NOTE** This method requires Playwright to be started in a headed mode. - * - * **Usage** - * - * ```js - * const locator = await page.pickLocator(); - * console.log(locator); - * ``` - * - */ - pickLocator(): Promise; - /** * **NOTE** Use locator-based [locator.press(key[, options])](https://playwright.dev/docs/api/class-locator#locator-press) * instead. Read more about [locators](https://playwright.dev/docs/locators). @@ -20438,19 +20415,6 @@ export interface FrameLocator { /** * Interface to the Playwright inspector. - * - * **Usage** - * - * ```js - * const inspector = page.inspector(); - * inspector.on('screencastframe', ({ data, width, height }) => { - * console.log(`received frame ${width}x${height}, jpeg size: ${data.length}`); - * }); - * await inspector.startScreencast(); - * // ... perform actions ... - * await inspector.stopScreencast(); - * ``` - * */ export interface Inspector { /** @@ -20615,6 +20579,28 @@ export interface Inspector { height: number; }) => any): this; + /** + * Cancels an ongoing + * [inspector.pickLocator()](https://playwright.dev/docs/api/class-inspector#inspector-pick-locator) call by + * deactivating pick locator mode. If no pick locator mode is active, this method is a no-op. + */ + cancelPickLocator(): Promise; + + /** + * Enters pick locator mode where hovering over page elements highlights them and shows the corresponding locator. + * Once the user clicks an element, the mode is deactivated and the + * [Locator](https://playwright.dev/docs/api/class-locator) for the picked element is returned. + * + * **Usage** + * + * ```js + * const locator = await page.inspector().pickLocator(); + * console.log(locator); + * ``` + * + */ + pickLocator(): Promise; + /** * Starts capturing screencast frames. Frames are emitted as * [inspector.on('screencastframe')](https://playwright.dev/docs/api/class-inspector#inspector-event-screencast-frame) diff --git a/tests/library/inspector/recorder-api.spec.ts b/tests/library/inspector/recorder-api.spec.ts index 75fd778003d96..c0874ff83884f 100644 --- a/tests/library/inspector/recorder-api.spec.ts +++ b/tests/library/inspector/recorder-api.spec.ts @@ -152,11 +152,11 @@ test('should disable recorder', async ({ context }) => { expect(log.action('click')).toHaveLength(2); }); -test('page.pickLocator should return locator for picked element', async ({ page }) => { +test('inspector.pickLocator should return locator for picked element', async ({ page }) => { await page.setContent(``); const scriptReady = page.waitForEvent('console', msg => msg.text() === 'Recorder script ready for test'); - const pickPromise = page.pickLocator(); + const pickPromise = page.inspector().pickLocator(); await scriptReady; const box = await page.getByRole('button', { name: 'Submit' }).boundingBox(); @@ -166,15 +166,15 @@ test('page.pickLocator should return locator for picked element', async ({ page await expect(locator).toHaveText('Submit'); }); -test('page.cancelPickLocator should cancel ongoing pickLocator', async ({ page }) => { +test('inspector.cancelPickLocator should cancel ongoing pickLocator', async ({ page }) => { await page.setContent(``); const scriptReady = page.waitForEvent('console', msg => msg.text() === 'Recorder script ready for test'); - const pickPromise = page.pickLocator(); + const pickPromise = page.inspector().pickLocator(); await scriptReady; await Promise.all([ - page.cancelPickLocator(), + page.inspector().cancelPickLocator(), expect(pickPromise).rejects.toThrow('Locator picking was cancelled'), ]); });