feat(page): Pick best locator for existing element.

Improve programmatic API of accessing the "pick locator" functionality
as exposed by the playwright trace viewer/codegenerator.

Fixes microsoft#13900

docs/src/api/class-page.md

@@ -851,6 +851,39 @@ Gets the full HTML contents of the page, including the doctype.
 
 Get the browser context that the page belongs to.
 
+## method: Page.pickBestLocator
+* since: v1.36
+- returns: <[Promise<{ locator: string; selector: string}>]>
+
+Get the best locator and selector for the specified selector.
+
+**Usage**
+
+```js
+await page.pickBestLocator('#id');
+```
+
+```java
+page.pickBestLocator("#id");
+```
+
+```python async
+await page.pickBestLocator("#id")
+```
+
+```python sync
+page.pickBestLocator("#id")
+```
+
+```csharp
+await page.PickBestLocatorAsync("#id");
+```
+
+Will pick the most stable locator available for the element defined by the selector parameter and return it.
+
+### param: Page.pickBestLocator.selector = %%-input-selector-%%
+* since: v1.36
+
 ## property: Page.coverage
 * since: v1.8
 * langs: js

packages/playwright-core/src/client/page.ts

@@ -774,6 +774,10 @@ export class Page extends ChannelOwner<channels.PageChannel> implements api.Page
     }
     return result.pdf;
   }
+
+  pickBestLocator(selector: string): Promise<{ locator: string; selector: string }> {
+    return this._channel.pickBestLocator({ selector });
+  }
 }
 
 export class BindingCall extends ChannelOwner<channels.BindingCallChannel> {

packages/playwright-core/src/protocol/validator.ts

@@ -999,6 +999,13 @@ scheme.PageWebSocketEvent = tObject({
 scheme.PageWorkerEvent = tObject({
   worker: tChannel(['Worker']),
 });
+scheme.PagePickBestLocatorParams = tObject({
+  selector: tString,
+});
+scheme.PagePickBestLocatorResult = tObject({
+  selector: tString,
+  locator: tString,
+});
 scheme.PageSetDefaultNavigationTimeoutNoReplyParams = tObject({
   timeout: tOptional(tNumber),
 });

packages/playwright-core/src/server/dispatchers/pageDispatcher.ts

@@ -35,6 +35,7 @@ import { ArtifactDispatcher } from './artifactDispatcher';
 import type { Download } from '../download';
 import { createGuid, urlMatches } from '../../utils';
 import type { BrowserContextDispatcher } from './browserContextDispatcher';
+import type { PagePickBestLocatorResult } from '@protocol/channels';
 
 export class PageDispatcher extends Dispatcher<Page, channels.PageChannel, BrowserContextDispatcher> implements channels.PageChannel {
   _type_EventTarget = true;
@@ -101,6 +102,10 @@ export class PageDispatcher extends Dispatcher<Page, channels.PageChannel, Brows
     return this._page;
   }
 
+  async pickBestLocator(params: channels.PagePickBestLocatorParams, metadata: CallMetadata): Promise<PagePickBestLocatorResult> {
+    return this._page.pickBestLocator(params.selector);
+  }
+
   async setDefaultNavigationTimeoutNoReply(params: channels.PageSetDefaultNavigationTimeoutNoReplyParams, metadata: CallMetadata): Promise<void> {
     this._page.setDefaultNavigationTimeout(params.timeout);
   }

packages/playwright-core/types/types.d.ts

@@ -3540,6 +3540,21 @@ export interface Page {
     width?: string|number;
   }): Promise<Buffer>;
 
+  /**
+   * Get the best locator and selector for the specified selector.
+   *
+   * **Usage**
+   *
+   * ```js
+   * await page.pickBestLocator('#id');
+   * ```
+   *
+   * Will pick the most stable locator available for the element defined by the selector parameter and return it.
+   * @param selector A selector to search for an element. If there are multiple elements satisfying the selector, the first will be
+   * used.
+   */
+  pickBestLocator(selector: string): Promise<{ locator: string; selector: string}>;
+
   /**
    * **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).

packages/protocol/src/channels.ts

@@ -1772,6 +1772,7 @@ export interface PageEventTarget {
 }
 export interface PageChannel extends PageEventTarget, EventTargetChannel {
   _type_Page: boolean;
+  pickBestLocator(params: PagePickBestLocatorParams, metadata?: CallMetadata): Promise<PagePickBestLocatorResult>;
   setDefaultNavigationTimeoutNoReply(params: PageSetDefaultNavigationTimeoutNoReplyParams, metadata?: CallMetadata): Promise<PageSetDefaultNavigationTimeoutNoReplyResult>;
   setDefaultTimeoutNoReply(params: PageSetDefaultTimeoutNoReplyParams, metadata?: CallMetadata): Promise<PageSetDefaultTimeoutNoReplyResult>;
   addInitScript(params: PageAddInitScriptParams, metadata?: CallMetadata): Promise<PageAddInitScriptResult>;
@@ -1843,6 +1844,16 @@ export type PageWebSocketEvent = {
 export type PageWorkerEvent = {
   worker: WorkerChannel,
 };
+export type PagePickBestLocatorParams = {
+  selector: string,
+};
+export type PagePickBestLocatorOptions = {
+
+};
+export type PagePickBestLocatorResult = {
+  selector: string,
+  locator: string,
+};
 export type PageSetDefaultNavigationTimeoutNoReplyParams = {
   timeout?: number,
 };

packages/protocol/src/protocol.yml

@@ -1273,6 +1273,12 @@ Page:
     opener: Page?
 
   commands:
+    pickBestLocator:
+      parameters:
+        selector: string
+      returns:
+        selector: string
+        locator: string
 
     setDefaultNavigationTimeoutNoReply:
       parameters:

tests/page/locator-convenience.spec.ts

@@ -17,6 +17,37 @@
 
 import { test as it, expect } from './pageTest';
 
+it.describe('picking the best available locator for an existing element', () => {
+
+  const html = '<div><input id="inputId" placeholder="somePlaceholder"/><button id="buttonId">Some Text</button></div>';
+
+  const testCases = [
+    {
+      originalSelector: '#buttonId',
+      expectedSelector: 'internal:role=button[name="Some Text"i]',
+      expectedLocator: "getByRole('button', { name: 'Some Text' })"
+    },
+    {
+      originalSelector: '#inputId',
+      expectedSelector: 'internal:attr=[placeholder="somePlaceholder"i]',
+      expectedLocator: "getByPlaceholder('somePlaceholder')"
+    }];
+
+  for (const testCase of testCases) {
+    it(`should allow selecting the best locator from an existing selector ${testCase.originalSelector}`, async ({ page }) => {
+      await page.setContent(html);
+
+      const locatorReference = await page.pickBestLocator(testCase.originalSelector);
+
+      expect(locatorReference.locator).toEqual(testCase.expectedLocator);
+      expect(locatorReference.selector).toEqual(testCase.expectedSelector);
+      await page.close();
+    });
+  }
+
+});
+
+
 it('should have a nice preview', async ({ page, server }) => {
   await page.goto(`${server.PREFIX}/dom.html`);
   const outer = page.locator('#outer');