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.pickLocator() API (#39486)

Yury Semikhatskycd528a2f991a
diff --git a/docs/src/api/class-page.md b/docs/src/api/class-page.md
index 56ef466cba..7f2fb1dea7 100644
--- a/docs/src/api/class-page.md
+++ b/docs/src/api/class-page.md
@@ -2845,6 +2845,24 @@ 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.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 db283f4217..818e762e59 100644
--- a/packages/playwright-client/types/types.d.ts
+++ b/packages/playwright-client/types/types.d.ts
@@ -3904,6 +3904,23 @@ export interface Page {
width?: string|number;
}): Promise<Buffer>;
+ /**
+ * 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<Locator>;
+
/**
* **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).
diff --git a/packages/playwright-core/src/client/page.ts b/packages/playwright-core/src/client/page.ts
index e556bde327..7631491213 100644
--- a/packages/playwright-core/src/client/page.ts
+++ b/packages/playwright-core/src/client/page.ts
@@ -819,6 +819,11 @@ export class Page extends ChannelOwner<channels.PageChannel> implements api.Page
this._browserContext.setDefaultTimeout(defaultTimeout);
}
+ async pickLocator(): Promise<Locator> {
+ const { selector } = await this._channel.pickLocator({});
+ return this.locator(selector);
+ }
+
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 ad44099729..7685b1a3ff 100644
--- a/packages/playwright-core/src/protocol/validator.ts
+++ b/packages/playwright-core/src/protocol/validator.ts
@@ -1530,6 +1530,10 @@ scheme.PageStopCSSCoverageResult = tObject({
});
scheme.PageBringToFrontParams = tOptional(tObject({}));
scheme.PageBringToFrontResult = tOptional(tObject({}));
+scheme.PagePickLocatorParams = tOptional(tObject({}));
+scheme.PagePickLocatorResult = tObject({
+ selector: tString,
+});
scheme.PageVideoStartParams = tObject({
size: tOptional(tObject({
width: tInt,
diff --git a/packages/playwright-core/src/server/dispatchers/pageDispatcher.ts b/packages/playwright-core/src/server/dispatchers/pageDispatcher.ts
index 8c29a14b04..a834b2bfb5 100644
--- a/packages/playwright-core/src/server/dispatchers/pageDispatcher.ts
+++ b/packages/playwright-core/src/server/dispatchers/pageDispatcher.ts
@@ -28,6 +28,8 @@ import { WebSocketRouteDispatcher } from './webSocketRouteDispatcher';
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';
@@ -344,6 +346,14 @@ export class PageDispatcher extends Dispatcher<Page, channels.PageChannel, Brows
await progress.race(this._page.bringToFront());
}
+ 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 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 99b3a8a022..490b7b82f1 100644
--- a/packages/playwright-core/src/server/recorder.ts
+++ b/packages/playwright-core/src/server/recorder.ts
@@ -24,6 +24,8 @@ import { buildFullSelector, generateFrameSelector, metadataToCallLog } from './r
import { locatorOrSelectorAsSelector } from '../utils/isomorphic/locatorParser';
import { stringifySelector } from '../utils/isomorphic/selectorParser';
import { ProgressController } from './progress';
+import { ManualPromise } from '../utils/isomorphic/manualPromise';
+
import { RecorderSignalProcessor } from './recorder/recorderSignalProcessor';
import * as rawRecorderSource from './../generated/pollingRecorderSource';
import { eventsHelper, monotonicTime } from './../utils';
@@ -35,6 +37,7 @@ import type { Language } from './codegen/types';
import type { CallMetadata, InstrumentationListener, SdkObject } from './instrumentation';
import type { Point } from '../utils/isomorphic/types';
import type { AriaTemplateNode } from '@isomorphic/ariaSnapshot';
+import type { Progress } from './progress';
import type * as channels from '@protocol/channels';
import type * as actions from '@recorder/actions';
import type { CallLog, CallLogStatus, ElementInfo, Mode, OverlayState, Source, UIState } from '@recorder/recorderTypes';
@@ -262,6 +265,38 @@ export class Recorder extends EventEmitter<RecorderEventMap> implements Instrume
this._refreshOverlay();
}
+ async pickLocator(progress: Progress): Promise<string> {
+ const selectorPromise = new ManualPromise<string>();
+ let recorderChangedState = false;
+ const onElementPicked = (elementInfo: ElementInfo) => {
+ selectorPromise.resolve(elementInfo.selector);
+ };
+ const onModeChanged = () => {
+ recorderChangedState = true;
+ selectorPromise.reject(new Error('Locator picking was cancelled'));
+ };
+ const onContextClosed = () => {
+ 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);
+ } finally {
+ // Remove listeners before setMode('none') to avoid triggering onModeChanged.
+ eventsHelper.removeEventListeners(listeners);
+ if (!recorderChangedState)
+ this.setMode('none');
+ }
+ }
+
url(): string | undefined {
const page = this._context.pages()[0];
return page?.mainFrame().url();
diff --git a/packages/playwright-core/src/utils/isomorphic/protocolMetainfo.ts b/packages/playwright-core/src/utils/isomorphic/protocolMetainfo.ts
index 9990b7f57e..933a79c3d2 100644
--- a/packages/playwright-core/src/utils/isomorphic/protocolMetainfo.ts
+++ b/packages/playwright-core/src/utils/isomorphic/protocolMetainfo.ts
@@ -146,6 +146,7 @@ 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.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 db283f4217..818e762e59 100644
--- a/packages/playwright-core/types/types.d.ts
+++ b/packages/playwright-core/types/types.d.ts
@@ -3904,6 +3904,23 @@ export interface Page {
width?: string|number;
}): Promise<Buffer>;
+ /**
+ * 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<Locator>;
+
/**
* **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).
diff --git a/packages/protocol/src/channels.d.ts b/packages/protocol/src/channels.d.ts
index 13f74e5af8..5c155194a9 100644
--- a/packages/protocol/src/channels.d.ts
+++ b/packages/protocol/src/channels.d.ts
@@ -2146,6 +2146,7 @@ export interface PageChannel extends PageEventTarget, EventTargetChannel {
startCSSCoverage(params: PageStartCSSCoverageParams, progress?: Progress): Promise<PageStartCSSCoverageResult>;
stopCSSCoverage(params?: PageStopCSSCoverageParams, progress?: Progress): Promise<PageStopCSSCoverageResult>;
bringToFront(params?: PageBringToFrontParams, progress?: Progress): Promise<PageBringToFrontResult>;
+ pickLocator(params?: PagePickLocatorParams, progress?: Progress): Promise<PagePickLocatorResult>;
videoStart(params: PageVideoStartParams, progress?: Progress): Promise<PageVideoStartResult>;
videoStop(params?: PageVideoStopParams, progress?: Progress): Promise<PageVideoStopResult>;
updateSubscription(params: PageUpdateSubscriptionParams, progress?: Progress): Promise<PageUpdateSubscriptionResult>;
@@ -2652,6 +2653,11 @@ export type PageStopCSSCoverageResult = {
export type PageBringToFrontParams = {};
export type PageBringToFrontOptions = {};
export type PageBringToFrontResult = void;
+export type PagePickLocatorParams = {};
+export type PagePickLocatorOptions = {};
+export type PagePickLocatorResult = {
+ selector: string,
+};
export type PageVideoStartParams = {
size?: {
width: number,
diff --git a/packages/protocol/src/protocol.yml b/packages/protocol/src/protocol.yml
index d07e9f4d43..7043f7453f 100644
--- a/packages/protocol/src/protocol.yml
+++ b/packages/protocol/src/protocol.yml
@@ -2064,6 +2064,11 @@ Page:
bringToFront:
title: Bring to front
+ pickLocator:
+ title: Pick locator
+ returns:
+ selector: string
+
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 d195e8cfb8..4e897caead 100644
--- a/tests/library/inspector/recorder-api.spec.ts
+++ b/tests/library/inspector/recorder-api.spec.ts
@@ -151,3 +151,17 @@ test('should disable recorder', async ({ context }) => {
await page.getByRole('button', { name: 'Submit' }).click();
expect(log.action('click')).toHaveLength(2);
});
+
+test('page.pickLocator should return locator for picked element', 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;
+
+ const box = await page.getByRole('button', { name: 'Submit' }).boundingBox();
+ await page.mouse.click(box!.x + box!.width / 2, box!.y + box!.height / 2);
+
+ const locator = await pickPromise;
+ await expect(locator).toHaveText('Submit');
+});