feat: support locators from element handles (#14147)

OrKoN · web-flow · commit f2608d018260 · 2025-08-29T09:40:20.000Z
diff --git a/docs/api/puppeteer.frame.locator.md b/docs/api/puppeteer.frame.locator.md
@@ -95,3 +95,47 @@ func
 **Returns:**
 
 [Locator](./puppeteer.locator.md)&lt;Ret&gt;
+
+<h2 id="locator-2">locator(): Locator&lt;T&gt;</h2>
+
+Creates a locator based on an ElementHandle. This would not allow refreshing the element handle if it is stale but it allows re-using other locator pre-conditions.
+
+### Signature
+
+```typescript
+class Frame {
+  locator<T extends Node>(handle: ElementHandle<T>): Locator<T>;
+}
+```
+
+## Parameters
+
+<table><thead><tr><th>
+
+Parameter
+
+</th><th>
+
+Type
+
+</th><th>
+
+Description
+
+</th></tr></thead>
+<tbody><tr><td>
+
+handle
+
+</td><td>
+
+[ElementHandle](./puppeteer.elementhandle.md)&lt;T&gt;
+
+</td><td>
+
+</td></tr>
+</tbody></table>
+
+**Returns:**
+
+[Locator](./puppeteer.locator.md)&lt;T&gt;
diff --git a/docs/api/puppeteer.frame.md b/docs/api/puppeteer.frame.md
@@ -371,6 +371,17 @@ Creates a locator for the provided function. See [Locator](./puppeteer.locator.m
 </td></tr>
 <tr><td>
 
+<span id="locator">[locator(handle)](./puppeteer.frame.locator.md)</span>
+
+</td><td>
+
+</td><td>
+
+Creates a locator based on an ElementHandle. This would not allow refreshing the element handle if it is stale but it allows re-using other locator pre-conditions.
+
+</td></tr>
+<tr><td>
+
 <span id="name">[name()](./puppeteer.frame.name.md)</span>
 
 </td><td>
diff --git a/docs/api/puppeteer.page.locator.md b/docs/api/puppeteer.page.locator.md
@@ -95,3 +95,47 @@ func
 **Returns:**
 
 [Locator](./puppeteer.locator.md)&lt;Ret&gt;
+
+<h2 id="locator-2">locator(): Locator&lt;T&gt;</h2>
+
+Creates a locator based on an ElementHandle. This would not allow refreshing the element handle if it is stale but it allows re-using other locator pre-conditions.
+
+### Signature
+
+```typescript
+class Page {
+  locator<T extends Node>(handle: ElementHandle<T>): Locator<T>;
+}
+```
+
+## Parameters
+
+<table><thead><tr><th>
+
+Parameter
+
+</th><th>
+
+Type
+
+</th><th>
+
+Description
+
+</th></tr></thead>
+<tbody><tr><td>
+
+handle
+
+</td><td>
+
+[ElementHandle](./puppeteer.elementhandle.md)&lt;T&gt;
+
+</td><td>
+
+</td></tr>
+</tbody></table>
+
+**Returns:**
+
+[Locator](./puppeteer.locator.md)&lt;T&gt;
diff --git a/docs/api/puppeteer.page.md b/docs/api/puppeteer.page.md
@@ -832,6 +832,17 @@ Creates a locator for the provided function. See [Locator](./puppeteer.locator.m
 </td></tr>
 <tr><td>
 
+<span id="locator">[locator(handle)](./puppeteer.page.locator.md)</span>
+
+</td><td>
+
+</td><td>
+
+Creates a locator based on an ElementHandle. This would not allow refreshing the element handle if it is stale but it allows re-using other locator pre-conditions.
+
+</td></tr>
+<tr><td>
+
 <span id="mainframe">[mainFrame()](./puppeteer.page.mainframe.md)</span>
 
 </td><td>
diff --git a/packages/puppeteer-core/src/api/Frame.ts b/packages/puppeteer-core/src/api/Frame.ts
@@ -520,17 +520,26 @@ export abstract class Frame extends EventEmitter<FrameEvents> {
    */
   locator<Ret>(func: () => Awaitable<Ret>): Locator<Ret>;
 
+  /**
+   * Creates a locator based on an ElementHandle. This would not allow
+   * refreshing the element handle if it is stale but it allows re-using other
+   * locator pre-conditions.
+   */
+  locator<T extends Node>(handle: ElementHandle<T>): Locator<T>;
+
   /**
    * @internal
    */
   @throwIfDetached
-  locator<Selector extends string, Ret>(
-    selectorOrFunc: Selector | (() => Awaitable<Ret>),
-  ): Locator<NodeFor<Selector>> | Locator<Ret> {
-    if (typeof selectorOrFunc === 'string') {
-      return NodeLocator.create(this, selectorOrFunc);
+  locator<Selector extends string, Ret, T extends Node>(
+    input: Selector | (() => Awaitable<Ret>) | ElementHandle<T>,
+  ): Locator<NodeFor<Selector>> | Locator<Ret> | Locator<T> {
+    if (typeof input === 'string') {
+      return NodeLocator.create(this, input);
+    } else if (typeof input === 'function') {
+      return FunctionLocator.create(this, input);
     } else {
-      return FunctionLocator.create(this, selectorOrFunc);
+      return NodeLocator.createFromHandle(this, input);
     }
   }
   /**
diff --git a/packages/puppeteer-core/src/api/Page.ts b/packages/puppeteer-core/src/api/Page.ts
@@ -1105,13 +1105,22 @@ export abstract class Page extends EventEmitter<PageEvents> {
    * {@link https://pptr.dev/guides/page-interactions#prefixed-selector-syntax | prefix}.
    */
   locator<Ret>(func: () => Awaitable<Ret>): Locator<Ret>;
-  locator<Selector extends string, Ret>(
-    selectorOrFunc: Selector | (() => Awaitable<Ret>),
-  ): Locator<NodeFor<Selector>> | Locator<Ret> {
-    if (typeof selectorOrFunc === 'string') {
-      return NodeLocator.create(this, selectorOrFunc);
+
+  /**
+   * Creates a locator based on an ElementHandle. This would not allow
+   * refreshing the element handle if it is stale but it allows re-using other
+   * locator pre-conditions.
+   */
+  locator<T extends Node>(handle: ElementHandle<T>): Locator<T>;
+  locator<Selector extends string, Ret, T extends Node>(
+    input: Selector | (() => Awaitable<Ret>) | ElementHandle<T>,
+  ): Locator<NodeFor<Selector>> | Locator<Ret> | Locator<T> {
+    if (typeof input === 'string') {
+      return NodeLocator.create(this, input);
+    } else if (typeof input === 'function') {
+      return FunctionLocator.create(this, input);
     } else {
-      return FunctionLocator.create(this, selectorOrFunc);
+      return NodeLocator.createFromHandle(this, input);
     }
   }
 
diff --git a/packages/puppeteer-core/src/api/locators/locators.ts b/packages/puppeteer-core/src/api/locators/locators.ts
@@ -22,6 +22,7 @@ import {
   merge,
   mergeMap,
   noop,
+  of,
   pipe,
   race,
   raceWith,
@@ -973,14 +974,29 @@ export class NodeLocator<T extends Node> extends Locator<T> {
     );
   }
 
+  static createFromHandle<T extends Node>(
+    pageOrFrame: Page | Frame,
+    handle: ElementHandle<T>,
+  ): Locator<T> {
+    return new NodeLocator<T>(pageOrFrame, handle).setTimeout(
+      'getDefaultTimeout' in pageOrFrame
+        ? pageOrFrame.getDefaultTimeout()
+        : pageOrFrame.page().getDefaultTimeout(),
+    );
+  }
+
   #pageOrFrame: Page | Frame;
-  #selector: string;
+  #selectorOrHandle: string | ElementHandle<T>;
 
-  private constructor(pageOrFrame: Page | Frame, selector: string) {
+  private constructor(pageOrFrame: Page | Frame, selector: string);
+  private constructor(pageOrFrame: Page | Frame, handle: ElementHandle<T>);
+  private constructor(
+    pageOrFrame: Page | Frame,
+    selectorOrHandle: string | ElementHandle<T>,
+  ) {
     super();
-
     this.#pageOrFrame = pageOrFrame;
-    this.#selector = selector;
+    this.#selectorOrHandle = selectorOrHandle;
   }
 
   /**
@@ -1009,21 +1025,27 @@ export class NodeLocator<T extends Node> extends Locator<T> {
   };
 
   override _clone(): NodeLocator<T> {
-    return new NodeLocator<T>(this.#pageOrFrame, this.#selector).copyOptions(
-      this,
-    );
+    return new NodeLocator<T>(
+      this.#pageOrFrame,
+      // @ts-expect-error TSC does cannot parse private overloads.
+      this.#selectorOrHandle,
+    ).copyOptions(this);
   }
 
   override _wait(options?: Readonly<ActionOptions>): Observable<HandleFor<T>> {
     const signal = options?.signal;
     return defer(() => {
-      return from(
-        this.#pageOrFrame.waitForSelector(this.#selector, {
-          visible: false,
-          timeout: this._timeout,
-          signal,
-        }) as Promise<HandleFor<T> | null>,
-      );
+      if (typeof this.#selectorOrHandle === 'string') {
+        return from(
+          this.#pageOrFrame.waitForSelector(this.#selectorOrHandle, {
+            visible: false,
+            timeout: this._timeout,
+            signal,
+          }) as Promise<HandleFor<T> | null>,
+        );
+      } else {
+        return of(this.#selectorOrHandle as HandleFor<T>);
+      }
     }).pipe(
       filter((value): value is NonNullable<typeof value> => {
         return value !== null;
diff --git a/test/src/locator.spec.ts b/test/src/locator.spec.ts
@@ -127,6 +127,24 @@ describe('Locator', function () {
       expect(text).toBe('clicked');
     });
 
+    it('should work with element handles', async () => {
+      const {page} = await getTestState();
+
+      await page.setViewport({width: 500, height: 500});
+      await page.setContent(`
+        <button style="margin-top: 600px;" onclick="this.innerText = 'clicked';">test</button>
+    `);
+      using button = await page.$('button');
+      if (!button) {
+        throw new Error('button not found');
+      }
+      await page.locator(button).click();
+      const text = await button?.evaluate(el => {
+        return el.innerText;
+      });
+      expect(text).toBe('clicked');
+    });
+
     it('should work if the element becomes visible later', async () => {
       const {page} = await getTestState();
 
