diff --git a/docs/api/puppeteer.locator.md b/docs/api/puppeteer.locator.md index 9bfb137a..823e30a6 100644 --- a/docs/api/puppeteer.locator.md +++ b/docs/api/puppeteer.locator.md @@ -42,3 +42,4 @@ export declare abstract class Locator extends EventEmitter | [setWaitForEnabled(this, value)](./puppeteer.locator.setwaitforenabled.md) | | | | [setWaitForStableBoundingBox(this, value)](./puppeteer.locator.setwaitforstableboundingbox.md) | | | | [wait(options)](./puppeteer.locator.wait.md) | |

Waits for the locator to get the serialized value from the page.

Note this requires the value to be JSON-serializable.

| +| [waitHandle(options)](./puppeteer.locator.waithandle.md) | | Waits for the locator to get a handle from the page. | diff --git a/docs/api/puppeteer.locator.waithandle.md b/docs/api/puppeteer.locator.waithandle.md new file mode 100644 index 00000000..45fb2956 --- /dev/null +++ b/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): Promise>; +} +``` + +## Parameters + +| Parameter | Type | Description | +| --------- | ------------------------------------------------------------- | ------------ | +| options | Readonly<[ActionOptions](./puppeteer.actionoptions.md)> | _(Optional)_ | + +**Returns:** + +Promise<[HandleFor](./puppeteer.handlefor.md)<T>> diff --git a/packages/puppeteer-core/src/api/locators/Locator.ts b/packages/puppeteer-core/src/api/locators/Locator.ts index ca5c8c65..8ff4c734 100644 --- a/packages/puppeteer-core/src/api/locators/Locator.ts +++ b/packages/puppeteer-core/src/api/locators/Locator.ts @@ -667,6 +667,19 @@ export abstract class Locator extends EventEmitter { return this._clone(); } + /** + * Waits for the locator to get a handle from the page. + * + * @public + */ + async waitHandle(options?: Readonly): Promise> { + 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 extends EventEmitter { * @public */ async wait(options?: Readonly): Promise { - const handle = await firstValueFrom( - this._wait(options).pipe( - this.operators.retryAndRaceWithSignalAndTimer(options?.signal) - ) - ); + const handle = await this.waitHandle(options); try { return await handle.jsonValue(); } finally { diff --git a/test/src/locator.spec.ts b/test/src/locator.spec.ts index f58306b3..d0288a43 100644 --- a/test/src/locator.spec.ts +++ b/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(` + + `); + await expect(page.locator('div').waitHandle()).resolves.toBeDefined(); + }); + }); + describe('Locator.prototype.clone', () => { it('should work', async () => { const {page} = await getTestState();