diff --git a/docs/api/index.md b/docs/api/index.md index 0d2f5cf4..f4472822 100644 --- a/docs/api/index.md +++ b/docs/api/index.md @@ -29,7 +29,7 @@ sidebar_label: API | [JSCoverage](./puppeteer.jscoverage.md) | | | [JSHandle](./puppeteer.jshandle.md) |

Represents a reference to a JavaScript object. Instances can be created using [Page.evaluateHandle()](./puppeteer.page.evaluatehandle.md).

Handles prevent the referenced JavaScript object from being garbage-collected unless the handle is purposely [disposed](./puppeteer.jshandle.dispose.md). JSHandles are auto-disposed when their associated frame is navigated away or the parent context gets destroyed.

Handles can be used as arguments for any evaluation function such as [Page.$eval()](./puppeteer.page._eval.md), [Page.evaluate()](./puppeteer.page.evaluate.md), and [Page.evaluateHandle()](./puppeteer.page.evaluatehandle.md). They are resolved to their referenced object.

| | [Keyboard](./puppeteer.keyboard.md) | Keyboard provides an api for managing a virtual keyboard. The high level api is [Keyboard.type()](./puppeteer.keyboard.type.md), which takes raw characters and generates proper keydown, keypress/input, and keyup events on your page. | -| [Locator](./puppeteer.locator.md) | Locators describe a strategy of locating elements and performing an action on them. If the action fails because the element is not ready for the action, the whole operation is retried. Various preconditions for a successful action are checked automatically. | +| [Locator](./puppeteer.locator.md) | Locators describe a strategy of locating objects and performing an action on them. If the action fails because the object is not ready for the action, the whole operation is retried. Various preconditions for a successful action are checked automatically. | | [Mouse](./puppeteer.mouse.md) | The Mouse class operates in main-frame CSS pixels relative to the top-left corner of the viewport. | | [Page](./puppeteer.page.md) |

Page provides methods to interact with a single tab or [extension background page](https://developer.chrome.com/extensions/background_pages) in the browser.

:::note

One Browser instance might have multiple Page instances.

:::

| | [ProductLauncher](./puppeteer.productlauncher.md) | Describes a launcher - a class that is able to create and launch a browser instance. | diff --git a/docs/api/puppeteer.frame.locator.md b/docs/api/puppeteer.frame.locator.md index eb19c571..f2eb7fbe 100644 --- a/docs/api/puppeteer.frame.locator.md +++ b/docs/api/puppeteer.frame.locator.md @@ -4,7 +4,7 @@ sidebar_label: Frame.locator # Frame.locator() method -Creates a locator for the provided `selector`. See [Locator](./puppeteer.locator.md) for details and supported actions. +Creates a locator for the provided selector. See [Locator](./puppeteer.locator.md) for details and supported actions. #### Signature: diff --git a/docs/api/puppeteer.frame.locator_1.md b/docs/api/puppeteer.frame.locator_1.md new file mode 100644 index 00000000..a52a1c58 --- /dev/null +++ b/docs/api/puppeteer.frame.locator_1.md @@ -0,0 +1,29 @@ +--- +sidebar_label: Frame.locator_1 +--- + +# Frame.locator() method + +Creates a locator for the provided function. See [Locator](./puppeteer.locator.md) for details and supported actions. + +#### Signature: + +```typescript +class Frame { + locator(func: () => Awaitable): Locator; +} +``` + +## Parameters + +| Parameter | Type | Description | +| --------- | --------------------------------------------------------- | ----------- | +| func | () => [Awaitable](./puppeteer.awaitable.md)<Ret> | | + +**Returns:** + +[Locator](./puppeteer.locator.md)<Ret> + +## Remarks + +Locators API is experimental and we will not follow semver for breaking change in the Locators API. diff --git a/docs/api/puppeteer.frame.md b/docs/api/puppeteer.frame.md index 574284b3..79bfcadd 100644 --- a/docs/api/puppeteer.frame.md +++ b/docs/api/puppeteer.frame.md @@ -81,7 +81,8 @@ console.log(text); | [hover(selector)](./puppeteer.frame.hover.md) | | Hovers the pointer over the center of the first element that matches the selector. | | [isDetached()](./puppeteer.frame.isdetached.md) | | Istrue if the frame has been detached. Otherwise, false. | | [isOOPFrame()](./puppeteer.frame.isoopframe.md) | | Is true if the frame is an out-of-process (OOP) frame. Otherwise, false. | -| [locator(selector)](./puppeteer.frame.locator.md) | | Creates a locator for the provided selector. See [Locator](./puppeteer.locator.md) for details and supported actions. | +| [locator(selector)](./puppeteer.frame.locator.md) | | Creates a locator for the provided selector. See [Locator](./puppeteer.locator.md) for details and supported actions. | +| [locator(func)](./puppeteer.frame.locator_1.md) | | Creates a locator for the provided function. See [Locator](./puppeteer.locator.md) for details and supported actions. | | [name()](./puppeteer.frame.name.md) | | The frame's name attribute as specified in the tag. | | [page()](./puppeteer.frame.page.md) | | The page associated with the frame. | | [parentFrame()](./puppeteer.frame.parentframe.md) | | The parent frame, if any. Detached and main frames return null. | diff --git a/docs/api/puppeteer.locator.md b/docs/api/puppeteer.locator.md index 86a6312b..9bfb137a 100644 --- a/docs/api/puppeteer.locator.md +++ b/docs/api/puppeteer.locator.md @@ -4,7 +4,7 @@ sidebar_label: Locator # Locator class -Locators describe a strategy of locating elements and performing an action on them. If the action fails because the element is not ready for the action, the whole operation is retried. Various preconditions for a successful action are checked automatically. +Locators describe a strategy of locating objects and performing an action on them. If the action fails because the object is not ready for the action, the whole operation is retried. Various preconditions for a successful action are checked automatically. #### Signature: diff --git a/docs/api/puppeteer.page.locator.md b/docs/api/puppeteer.page.locator.md index ffb81c69..62ebcbfe 100644 --- a/docs/api/puppeteer.page.locator.md +++ b/docs/api/puppeteer.page.locator.md @@ -4,7 +4,7 @@ sidebar_label: Page.locator # Page.locator() method -Creates a locator for the provided `selector`. See [Locator](./puppeteer.locator.md) for details and supported actions. +Creates a locator for the provided selector. See [Locator](./puppeteer.locator.md) for details and supported actions. #### Signature: diff --git a/docs/api/puppeteer.page.locator_1.md b/docs/api/puppeteer.page.locator_1.md new file mode 100644 index 00000000..72c3f30f --- /dev/null +++ b/docs/api/puppeteer.page.locator_1.md @@ -0,0 +1,29 @@ +--- +sidebar_label: Page.locator_1 +--- + +# Page.locator() method + +Creates a locator for the provided function. See [Locator](./puppeteer.locator.md) for details and supported actions. + +#### Signature: + +```typescript +class Page { + locator(func: () => Awaitable): Locator; +} +``` + +## Parameters + +| Parameter | Type | Description | +| --------- | --------------------------------------------------------- | ----------- | +| func | () => [Awaitable](./puppeteer.awaitable.md)<Ret> | | + +**Returns:** + +[Locator](./puppeteer.locator.md)<Ret> + +## Remarks + +Locators API is experimental and we will not follow semver for breaking change in the Locators API. diff --git a/docs/api/puppeteer.page.md b/docs/api/puppeteer.page.md index 29549dc8..b1351eb0 100644 --- a/docs/api/puppeteer.page.md +++ b/docs/api/puppeteer.page.md @@ -118,7 +118,8 @@ page.off('request', logRequest); | [isDragInterceptionEnabled()](./puppeteer.page.isdraginterceptionenabled.md) | | true if drag events are being intercepted, false otherwise. | | [isJavaScriptEnabled()](./puppeteer.page.isjavascriptenabled.md) | | true if the page has JavaScript enabled, false otherwise. | | [isServiceWorkerBypassed()](./puppeteer.page.isserviceworkerbypassed.md) | | true if the service worker are being bypassed, false otherwise. | -| [locator(selector)](./puppeteer.page.locator.md) | | Creates a locator for the provided selector. See [Locator](./puppeteer.locator.md) for details and supported actions. | +| [locator(selector)](./puppeteer.page.locator.md) | | Creates a locator for the provided selector. See [Locator](./puppeteer.locator.md) for details and supported actions. | +| [locator(func)](./puppeteer.page.locator_1.md) | | Creates a locator for the provided function. See [Locator](./puppeteer.locator.md) for details and supported actions. | | [mainFrame()](./puppeteer.page.mainframe.md) | | The page's main frame. | | [metrics()](./puppeteer.page.metrics.md) | | Object containing metrics as key/value pairs. | | [off(eventName, handler)](./puppeteer.page.off.md) | | | diff --git a/docs/guides/locators.md b/docs/guides/locators.md index 0985a28d..9f707f43 100644 --- a/docs/guides/locators.md +++ b/docs/guides/locators.md @@ -1,9 +1,9 @@ # Locators -Locators is a new experimental API that combines `waitForSelector` and element -actions in a single unit. In combination with additional precondition checks -this allows locators to retry failed actions automatically leading to less flaky -automation scripts. +Locators is a new, experimental API that combines the functionalities of +waiting and actions. With additional precondition checks, it +enables automatic retries for failed actions, resulting in more reliable and +less flaky automation scripts. :::note @@ -12,7 +12,42 @@ in the Locators API. ::: -## Clicking an element +## Use cases + +### Waiting for an element + +```ts +await page.locator('button').wait(); +``` + +The following preconditions are automatically checked: + +- Waits for the element to become + [visible](https://pptr.dev/api/puppeteer.elementhandle.isvisible/) or hidden. + +### Waiting for a function + +```ts +await page + .locator(() => { + let resolve!: (node: HTMLCanvasElement) => void; + const promise = new Promise(res => { + return (resolve = res); + }); + const observer = new MutationObserver(records => { + for (const record of records) { + if (record.target instanceof HTMLCanvasElement) { + resolve(record.target); + } + } + }); + observer.observe(document); + return promise; + }) + .wait(); +``` + +### Clicking an element ```ts await page.locator('button').click(); @@ -27,7 +62,25 @@ The following preconditions are automatically checked: - Waits for the element to have a stable bounding box over two consecutive animation frames. -## Filling out an input +### Clicking an element matching a criteria + +```ts +await page + .locator('button') + .filter(button => !button.disabled) + .click(); +``` + +The following preconditions are automatically checked: + +- Ensures the element is in the viewport. +- Waits for the element to become + [visible](https://pptr.dev/api/puppeteer.elementhandle.isvisible/) or hidden. +- Waits for the element to become enabled. +- Waits for the element to have a stable bounding box over two consecutive + animation frames. + +### Filling out an input ```ts await page.locator('input').fill('value'); @@ -44,7 +97,16 @@ The following preconditions are automatically checked: - Waits for the element to have a stable bounding box over two consecutive animation frames. -## Hover over an element +### Retrieving an element property + +```ts +const enabled = await page + .locator('button') + .map(button => !button.disabled) + .wait(); +``` + +### Hover over an element ```ts await page.locator('div').hover(); @@ -58,7 +120,7 @@ The following preconditions are automatically checked: - Waits for the element to have a stable bounding box over two consecutive animation frames. -## Scroll an element +### Scroll an element ```ts await page.locator('div').scroll({ diff --git a/packages/puppeteer-core/src/api/Frame.ts b/packages/puppeteer-core/src/api/Frame.ts index c5e56872..ed105935 100644 --- a/packages/puppeteer-core/src/api/Frame.ts +++ b/packages/puppeteer-core/src/api/Frame.ts @@ -28,6 +28,7 @@ import { import {LazyArg} from '../common/LazyArg.js'; import {PuppeteerLifeCycleEvent} from '../common/LifecycleWatcher.js'; import { + Awaitable, EvaluateFunc, EvaluateFuncWith, HandleFor, @@ -39,7 +40,7 @@ import {TaskManager} from '../common/WaitTask.js'; import {KeyboardTypeOptions} from './Input.js'; import {JSHandle} from './JSHandle.js'; -import {Locator, NodeLocator} from './locators/locators.js'; +import {Locator, FunctionLocator, NodeLocator} from './locators/locators.js'; /** * @internal @@ -417,7 +418,7 @@ export class Frame { } /** - * Creates a locator for the provided `selector`. See {@link Locator} for + * Creates a locator for the provided selector. See {@link Locator} for * details and supported actions. * * @remarks @@ -426,10 +427,26 @@ export class Frame { */ locator( selector: Selector - ): Locator> { - return NodeLocator.create(this, selector); - } + ): Locator>; + /** + * Creates a locator for the provided function. See {@link Locator} for + * details and supported actions. + * + * @remarks + * Locators API is experimental and we will not follow semver for breaking + * change in the Locators API. + */ + locator(func: () => Awaitable): Locator; + locator( + selectorOrFunc: Selector | (() => Awaitable) + ): Locator> | Locator { + if (typeof selectorOrFunc === 'string') { + return NodeLocator.create(this, selectorOrFunc); + } else { + return FunctionLocator.create(this, selectorOrFunc); + } + } /** * Queries the frame for an element matching the given selector. * diff --git a/packages/puppeteer-core/src/api/Page.ts b/packages/puppeteer-core/src/api/Page.ts index 9629210a..0fd73b3b 100644 --- a/packages/puppeteer-core/src/api/Page.ts +++ b/packages/puppeteer-core/src/api/Page.ts @@ -46,6 +46,7 @@ import { import type {Viewport} from '../common/PuppeteerViewport.js'; import type {Tracing} from '../common/Tracing.js'; import type { + Awaitable, EvaluateFunc, EvaluateFuncWith, HandleFor, @@ -73,7 +74,12 @@ import type { } from './Frame.js'; import {Keyboard, KeyboardTypeOptions, Mouse, Touchscreen} from './Input.js'; import type {JSHandle} from './JSHandle.js'; -import {AwaitedLocator, Locator, NodeLocator} from './locators/locators.js'; +import { + AwaitedLocator, + FunctionLocator, + Locator, + NodeLocator, +} from './locators/locators.js'; import type {Target} from './Target.js'; /** @@ -832,7 +838,7 @@ export class Page extends EventEmitter { } /** - * Creates a locator for the provided `selector`. See {@link Locator} for + * Creates a locator for the provided selector. See {@link Locator} for * details and supported actions. * * @remarks @@ -841,8 +847,25 @@ export class Page extends EventEmitter { */ locator( selector: Selector - ): Locator> { - return NodeLocator.create(this, selector); + ): Locator>; + + /** + * Creates a locator for the provided function. See {@link Locator} for + * details and supported actions. + * + * @remarks + * Locators API is experimental and we will not follow semver for breaking + * change in the Locators API. + */ + locator(func: () => Awaitable): Locator; + locator( + selectorOrFunc: Selector | (() => Awaitable) + ): Locator> | Locator { + if (typeof selectorOrFunc === 'string') { + return NodeLocator.create(this, selectorOrFunc); + } else { + return FunctionLocator.create(this, selectorOrFunc); + } } /** diff --git a/packages/puppeteer-core/src/api/locators/FunctionLocator.ts b/packages/puppeteer-core/src/api/locators/FunctionLocator.ts new file mode 100644 index 00000000..eed04109 --- /dev/null +++ b/packages/puppeteer-core/src/api/locators/FunctionLocator.ts @@ -0,0 +1,69 @@ +/** + * Copyright 2023 Google Inc. All rights reserved. + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +import { + Observable, + defer, + from, + throwIfEmpty, +} from '../../../third_party/rxjs/rxjs.js'; +import {Awaitable, HandleFor} from '../../common/types.js'; +import {Frame} from '../Frame.js'; +import {Page} from '../Page.js'; + +import {ActionOptions, Locator} from './locators.js'; + +/** + * @internal + */ +export class FunctionLocator extends Locator { + static create( + pageOrFrame: Page | Frame, + func: () => Awaitable + ): Locator { + return new FunctionLocator(pageOrFrame, func).setTimeout( + 'getDefaultTimeout' in pageOrFrame + ? pageOrFrame.getDefaultTimeout() + : pageOrFrame.page().getDefaultTimeout() + ); + } + + #pageOrFrame: Page | Frame; + #func: () => Awaitable; + + private constructor(pageOrFrame: Page | Frame, func: () => Awaitable) { + super(); + + this.#pageOrFrame = pageOrFrame; + this.#func = func; + } + + override _clone(): FunctionLocator { + return new FunctionLocator(this.#pageOrFrame, this.#func); + } + + _wait(options?: Readonly): Observable> { + const signal = options?.signal; + return defer(() => { + return from( + this.#pageOrFrame.waitForFunction(this.#func, { + timeout: this.timeout, + signal, + }) + ); + }).pipe(throwIfEmpty()); + } +} diff --git a/packages/puppeteer-core/src/api/locators/Locator.ts b/packages/puppeteer-core/src/api/locators/Locator.ts index 6e710675..010c8a7e 100644 --- a/packages/puppeteer-core/src/api/locators/Locator.ts +++ b/packages/puppeteer-core/src/api/locators/Locator.ts @@ -146,10 +146,10 @@ export interface LocatorEventObject { } /** - * Locators describe a strategy of locating elements and performing an action on - * them. If the action fails because the element is not ready for the action, - * the whole operation is retried. Various preconditions for a successful action - * are checked automatically. + * Locators describe a strategy of locating objects and performing an action on + * them. If the action fails because the object is not ready for the action, the + * whole operation is retried. Various preconditions for a successful action are + * checked automatically. * * @public */ diff --git a/packages/puppeteer-core/src/api/locators/locators.ts b/packages/puppeteer-core/src/api/locators/locators.ts index c71400f4..7270bd35 100644 --- a/packages/puppeteer-core/src/api/locators/locators.ts +++ b/packages/puppeteer-core/src/api/locators/locators.ts @@ -20,3 +20,4 @@ export * from './FilteredLocator.js'; export * from './RaceLocator.js'; export * from './DelegatedLocator.js'; export * from './MappedLocator.js'; +export * from './FunctionLocator.js'; diff --git a/test/src/locator.spec.ts b/test/src/locator.spec.ts index d6511c1f..f58306b3 100644 --- a/test/src/locator.spec.ts +++ b/test/src/locator.spec.ts @@ -672,4 +672,34 @@ describe('Locator', function () { } }); }); + + describe('FunctionLocator', () => { + it('should work', async () => { + const {page} = await getTestState(); + const result = page + .locator(() => { + return new Promise(resolve => { + return setTimeout(() => { + return resolve(true); + }, 100); + }); + }) + .wait(); + await expect(result).resolves.toEqual(true); + }); + it('should work with actions', async () => { + const {page} = await getTestState(); + await page.setContent(`
test
`); + await page + .locator(() => { + return document.getElementsByTagName('div')[0] as HTMLDivElement; + }) + .click(); + await expect( + page.evaluate(() => { + return (window as unknown as {clicked: boolean}).clicked; + }) + ).resolves.toEqual(true); + }); + }); });