chore: move pickLocator to Page.inspector

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

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]>

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

@@ -2187,12 +2187,6 @@ 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).
@@ -3928,23 +3922,6 @@ 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).
@@ -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<void>;
+
+  /**
+   * 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<Locator>;
+
   /**
    * Starts capturing screencast frames. Frames are emitted as
    * [inspector.on('screencastframe')](https://playwright.dev/docs/api/class-inspector#inspector-event-screencast-frame)

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<Locator> {
+    const { selector } = await this._page._channel.pickLocator({});
+    return this._page.locator(selector);
+  }
+
+  async cancelPickLocator(): Promise<void> {
+    await this._page._channel.cancelPickLocator({});
+  }
+
   async startScreencast(options: { size?: { width: number, height: number } } = {}): Promise<void> {
     await this._page._channel.startScreencast(options);
   }

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

@@ -826,15 +826,6 @@ 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 cancelPickLocator(): Promise<void> {
-    await this._channel.cancelPickLocator({});
-  }
-
   async pdf(options: PDFOptions = {}): Promise<Buffer> {
     const transportOptions: channels.PagePdfParams = { ...options } as channels.PagePdfParams;
     if (transportOptions.margin)

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

@@ -2187,12 +2187,6 @@ 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).
@@ -3928,23 +3922,6 @@ 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).
@@ -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<void>;
+
+  /**
+   * 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<Locator>;
+
   /**
    * Starts capturing screencast frames. Frames are emitted as
    * [inspector.on('screencastframe')](https://playwright.dev/docs/api/class-inspector#inspector-event-screencast-frame)

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(`<button>Submit</button>`);
 
   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(`<button>Submit</button>`);
 
   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'),
   ]);
 });