feat: implement Locator.prototype.waitHandle (#10650)

docs/api/puppeteer.locator.md

@@ -42,3 +42,4 @@ export declare abstract class Locator<T> extends EventEmitter
 | [setWaitForEnabled(this, value)](./puppeteer.locator.setwaitforenabled.md)                             |                     |                                                                                                                                                                                                                                          |
 | [setWaitForStableBoundingBox(this, value)](./puppeteer.locator.setwaitforstableboundingbox.md)         |                     |                                                                                                                                                                                                                                          |
 | [wait(options)](./puppeteer.locator.wait.md)                                                           |                     | <p>Waits for the locator to get the serialized value from the page.</p><p>Note this requires the value to be JSON-serializable.</p>                                                                                                      |
+| [waitHandle(options)](./puppeteer.locator.waithandle.md)                                               |                     | Waits for the locator to get a handle from the page.                                                                                                                                                                                     |

docs/api/puppeteer.locator.waithandle.md

@@ -0,0 +1,25 @@
+---
+sidebar_label: Locator.waitHandle
+---
+
+# Locator.waitHandle() method
+
+Waits for the locator to get a handle from the page.
+
+#### Signature:
+
+```typescript
+class Locator {
+  waitHandle(options?: Readonly<ActionOptions>): Promise<HandleFor<T>>;
+}
+```
+
+## Parameters
+
+| Parameter | Type                                                          | Description  |
+| --------- | ------------------------------------------------------------- | ------------ |
+| options   | Readonly&lt;[ActionOptions](./puppeteer.actionoptions.md)&gt; | _(Optional)_ |
+
+**Returns:**
+
+Promise&lt;[HandleFor](./puppeteer.handlefor.md)&lt;T&gt;&gt;

packages/puppeteer-core/src/api/locators/Locator.ts

@@ -667,6 +667,19 @@ export abstract class Locator<T> extends EventEmitter {
     return this._clone();
   }
 
+  /**
+   * Waits for the locator to get a handle from the page.
+   *
+   * @public
+   */
+  async waitHandle(options?: Readonly<ActionOptions>): Promise<HandleFor<T>> {
+    return await firstValueFrom(
+      this._wait(options).pipe(
+        this.operators.retryAndRaceWithSignalAndTimer(options?.signal)
+      )
+    );
+  }
+
   /**
    * Waits for the locator to get the serialized value from the page.
    *
@@ -675,11 +688,7 @@ export abstract class Locator<T> extends EventEmitter {
    * @public
    */
   async wait(options?: Readonly<ActionOptions>): Promise<T> {
-    const handle = await firstValueFrom(
+    const handle = await this.waitHandle(options);
-      this._wait(options).pipe(
-        this.operators.retryAndRaceWithSignalAndTimer(options?.signal)
-      )
-    );
     try {
       return await handle.jsonValue();
     } finally {

test/src/locator.spec.ts

@@ -648,6 +648,22 @@ describe('Locator', function () {
     });
   });
 
+  describe('Locator.prototype.waitHandle', () => {
+    it('should work', async () => {
+      const {page} = await getTestState();
+      page.setContent(`
+        <script>
+          setTimeout(() => {
+            const element = document.createElement("div");
+            element.innerText = "test2"
+            document.body.append(element);
+          }, 50);
+        </script>
+      `);
+      await expect(page.locator('div').waitHandle()).resolves.toBeDefined();
+    });
+  });
+
   describe('Locator.prototype.clone', () => {
     it('should work', async () => {
       const {page} = await getTestState();