Playwright is a framework for Web Testing and Automation. It allows testing Chromium, Firefox and WebKit with a single API.
TypeScript automationchromechromiume2e-testingelectronend-to-end-testingfirefoxjavascriptplaywrighttesttest-automationtestingtesting-toolswebwebkit
feat(locator): introduce Locator.waitForFunction() (#41380)
Dmitry Gozmanb5a45d98118a
diff --git a/docs/src/api/class-locator.md b/docs/src/api/class-locator.mdindex 7bbff0ce32..a7f1fbd9f1 100644--- a/docs/src/api/class-locator.md+++ b/docs/src/api/class-locator.md@@ -2796,3 +2796,50 @@ orderSent.WaitForAsync();### option: Locator.waitFor.timeout = %%-input-timeout-js-%%* since: v1.16++## async method: Locator.waitForFunction+* since: v1.62++Returns when [`param: expression`] returns a truthy value, called with the matching element as a first argument, and [`param: arg`] as a second argument.++This is a generic way to wait for an element to reach a custom condition without asserting it. The locator is re-resolved on each retry, so it tolerates the element being re-rendered while waiting.++If [`param: expression`] returns a [Promise], this method will wait for the promise to resolve before checking its value.++If [`param: expression`] throws or rejects, this method throws.++**Usage**++Wait for an attribute to appear:++```js+const toggle = page.getByRole('button', { name: 'Menu' });+await toggle.click();+await toggle.waitForFunction(element => element.hasAttribute('aria-expanded'));+```++Passing argument to [`param: expression`]:++```js+await page.getByTestId('status').waitForFunction((element, value) => {+ return element.textContent === value;+}, 'Ready');+```++### param: Locator.waitForFunction.expression = %%-evaluate-expression-%%+* since: v1.62++### param: Locator.waitForFunction.expression = %%-js-evaluate-pagefunction-%%+* since: v1.62++### param: Locator.waitForFunction.arg+* since: v1.62+- `arg` ?<[EvaluationArgument]>++Optional argument to pass to [`param: expression`].++### option: Locator.waitForFunction.timeout = %%-wait-for-function-timeout-%%+* since: v1.62++### option: Locator.waitForFunction.timeout = %%-wait-for-function-timeout-js-%%+* since: v1.62diff --git a/packages/playwright-client/types/types.d.ts b/packages/playwright-client/types/types.d.tsindex 4f4e40c7cd..5f01196f87 100644--- a/packages/playwright-client/types/types.d.ts+++ b/packages/playwright-client/types/types.d.ts@@ -12852,78 +12852,7 @@ export interface Locator {* [`pageFunction`](https://playwright.dev/docs/api/class-locator#locator-evaluate-option-expression).* @param options*/- evaluate<R, Arg, E extends SVGElement | HTMLElement = SVGElement | HTMLElement>(pageFunction: PageFunctionOn<E, Arg, R>, arg: Arg, options?: {- timeout?: number;- }): Promise<R>;- /**- * Execute JavaScript code in the page, taking the matching element as an argument.- *- * **Details**- *- * Returns the return value of- * [`pageFunction`](https://playwright.dev/docs/api/class-locator#locator-evaluate-option-expression), called with the- * matching element as a first argument, and- * [`arg`](https://playwright.dev/docs/api/class-locator#locator-evaluate-option-arg) as a second argument.- *- * If [`pageFunction`](https://playwright.dev/docs/api/class-locator#locator-evaluate-option-expression) returns a- * [Promise], this method will wait for the promise to resolve and return its value.- *- * If [`pageFunction`](https://playwright.dev/docs/api/class-locator#locator-evaluate-option-expression) throws or- * rejects, this method throws.- *- * **Usage**- *- * Passing argument to- * [`pageFunction`](https://playwright.dev/docs/api/class-locator#locator-evaluate-option-expression):- *- * ```js- * const result = await page.getByTestId('myId').evaluate((element, [x, y]) => {- * return element.textContent + ' ' + x * y;- * }, [7, 8]);- * console.log(result); // prints "myId text 56"- * ```- *- * @param pageFunction Function to be evaluated in the page context.- * @param arg Optional argument to pass to- * [`pageFunction`](https://playwright.dev/docs/api/class-locator#locator-evaluate-option-expression).- * @param options- */- evaluate<R, E extends SVGElement | HTMLElement = SVGElement | HTMLElement>(pageFunction: PageFunctionOn<E, void, R>, options?: {- timeout?: number;- }): Promise<R>;- /**- * Execute JavaScript code in the page, taking the matching element as an argument, and return a- * [JSHandle](https://playwright.dev/docs/api/class-jshandle) with the result.- *- * **Details**- *- * Returns the return value of- * [`pageFunction`](https://playwright.dev/docs/api/class-locator#locator-evaluate-handle-option-expression) as- * a[JSHandle](https://playwright.dev/docs/api/class-jshandle), called with the matching element as a first argument,- * and [`arg`](https://playwright.dev/docs/api/class-locator#locator-evaluate-handle-option-arg) as a second argument.- *- * The only difference between- * [locator.evaluate(pageFunction[, arg, options])](https://playwright.dev/docs/api/class-locator#locator-evaluate)- * and- * [locator.evaluateHandle(pageFunction[, arg, options])](https://playwright.dev/docs/api/class-locator#locator-evaluate-handle)- * is that- * [locator.evaluateHandle(pageFunction[, arg, options])](https://playwright.dev/docs/api/class-locator#locator-evaluate-handle)- * returns [JSHandle](https://playwright.dev/docs/api/class-jshandle).- *- * If [`pageFunction`](https://playwright.dev/docs/api/class-locator#locator-evaluate-handle-option-expression)- * returns a [Promise], this method will wait for the promise to resolve and return its value.- *- * If [`pageFunction`](https://playwright.dev/docs/api/class-locator#locator-evaluate-handle-option-expression) throws- * or rejects, this method throws.- *- * See [page.evaluateHandle(pageFunction[, arg])](https://playwright.dev/docs/api/class-page#page-evaluate-handle) for- * more details.- * @param pageFunction Function to be evaluated in the page context.- * @param arg Optional argument to pass to- * [`pageFunction`](https://playwright.dev/docs/api/class-locator#locator-evaluate-handle-option-expression).- * @param options- */- evaluateHandle<R, Arg, E extends SVGElement | HTMLElement = SVGElement | HTMLElement>(pageFunction: PageFunctionOn<E, Arg, R>, arg: Arg): Promise<SmartHandle<R>>;+ evaluate<R, Arg, E extends SVGElement | HTMLElement = SVGElement | HTMLElement>(pageFunction: PageFunctionOn<E, Arg, R>, arg?: Arg, options?: { timeout?: number }): Promise<R>;/*** Execute JavaScript code in the page, taking the matching element as an argument, and return a* [JSHandle](https://playwright.dev/docs/api/class-jshandle) with the result.@@ -12956,7 +12885,7 @@ export interface Locator {* [`pageFunction`](https://playwright.dev/docs/api/class-locator#locator-evaluate-handle-option-expression).* @param options*/- evaluateHandle<R, E extends SVGElement | HTMLElement = SVGElement | HTMLElement>(pageFunction: PageFunctionOn<E, void, R>): Promise<SmartHandle<R>>;+ evaluateHandle<R, Arg, E extends SVGElement | HTMLElement = SVGElement | HTMLElement>(pageFunction: PageFunctionOn<E, Arg, R>, arg?: Arg, options?: { timeout?: number }): Promise<SmartHandle<R>>;/*** Execute JavaScript code in the page, taking all matching elements as an argument.*@@ -12984,35 +12913,47 @@ export interface Locator {* @param arg Optional argument to pass to* [`pageFunction`](https://playwright.dev/docs/api/class-locator#locator-evaluate-all-option-expression).*/- evaluateAll<R, Arg, E extends SVGElement | HTMLElement = SVGElement | HTMLElement>(pageFunction: PageFunctionOn<E[], Arg, R>, arg: Arg): Promise<R>;+ evaluateAll<R, Arg, E extends SVGElement | HTMLElement = SVGElement | HTMLElement>(pageFunction: PageFunctionOn<E[], Arg, R>, arg?: Arg): Promise<R>;/**- * Execute JavaScript code in the page, taking all matching elements as an argument.+ * Returns when+ * [`pageFunction`](https://playwright.dev/docs/api/class-locator#locator-wait-for-function-option-expression) returns+ * a truthy value, called with the matching element as a first argument, and+ * [`arg`](https://playwright.dev/docs/api/class-locator#locator-wait-for-function-option-arg) as a second argument.*- * **Details**+ * This is a generic way to wait for an element to reach a custom condition without asserting it. The locator is+ * re-resolved on each retry, so it tolerates the element being re-rendered while waiting.*- * Returns the return value of- * [`pageFunction`](https://playwright.dev/docs/api/class-locator#locator-evaluate-all-option-expression), called with- * an array of all matching elements as a first argument, and- * [`arg`](https://playwright.dev/docs/api/class-locator#locator-evaluate-all-option-arg) as a second argument.+ * If [`pageFunction`](https://playwright.dev/docs/api/class-locator#locator-wait-for-function-option-expression)+ * returns a [Promise], this method will wait for the promise to resolve before checking its value.*- * If [`pageFunction`](https://playwright.dev/docs/api/class-locator#locator-evaluate-all-option-expression) returns a- * [Promise], this method will wait for the promise to resolve and return its value.- *- * If [`pageFunction`](https://playwright.dev/docs/api/class-locator#locator-evaluate-all-option-expression) throws or- * rejects, this method throws.+ * If [`pageFunction`](https://playwright.dev/docs/api/class-locator#locator-wait-for-function-option-expression)+ * throws or rejects, this method throws.** **Usage***+ * Wait for an attribute to appear:+ ** ```js- * const locator = page.locator('div');- * const moreThanTen = await locator.evaluateAll((divs, min) => divs.length > min, 10);+ * const toggle = page.getByRole('button', { name: 'Menu' });+ * await toggle.click();+ * await toggle.waitForFunction(element => element.hasAttribute('aria-expanded'));+ * ```+ *+ * Passing argument to+ * [`pageFunction`](https://playwright.dev/docs/api/class-locator#locator-wait-for-function-option-expression):+ *+ * ```js+ * await page.getByTestId('status').waitForFunction((element, value) => {+ * return element.textContent === value;+ * }, 'Ready');* ```** @param pageFunction Function to be evaluated in the page context.* @param arg Optional argument to pass to- * [`pageFunction`](https://playwright.dev/docs/api/class-locator#locator-evaluate-all-option-expression).+ * [`pageFunction`](https://playwright.dev/docs/api/class-locator#locator-wait-for-function-option-expression).+ * @param options*/- evaluateAll<R, E extends SVGElement | HTMLElement = SVGElement | HTMLElement>(pageFunction: PageFunctionOn<E[], void, R>): Promise<R>;+ waitForFunction<Arg, E extends SVGElement | HTMLElement = SVGElement | HTMLElement>(pageFunction: PageFunctionOn<E, Arg, any>, arg?: Arg, options?: { timeout?: number }): Promise<void>;/*** **NOTE** Always prefer using [Locator](https://playwright.dev/docs/api/class-locator)s and web assertions over* [ElementHandle](https://playwright.dev/docs/api/class-elementhandle)s because latter are inherently racy.@@ -13021,17 +12962,13 @@ export interface Locator {* multiple elements match the locator, throws.* @param options*/- elementHandle(options?: {- timeout?: number;- }): Promise<null|ElementHandle<SVGElement | HTMLElement>>;+ elementHandle(options?: { timeout?: number }): Promise<ElementHandle<SVGElement | HTMLElement>>;/*** Highlight the corresponding element(s) on the screen. Useful for debugging, don't commit the code that uses* [locator.highlight([options])](https://playwright.dev/docs/api/class-locator#locator-highlight).* @param options*/- highlight(options?: {- style?: string | { [key: string]: string | number };- }): Promise<Disposable>;+ highlight(options?: { style?: string | { [key: string]: string | number } }): Promise<Disposable>;/*** Returns a human-readable representation of the locator, using the* [locator.description()](https://playwright.dev/docs/api/class-locator#locator-description) if one exists;diff --git a/packages/playwright-core/src/client/channels.d.ts b/packages/playwright-core/src/client/channels.d.tsindex 3387f0c599..ea59dfbb58 100644--- a/packages/playwright-core/src/client/channels.d.ts+++ b/packages/playwright-core/src/client/channels.d.ts@@ -2981,13 +2981,17 @@ export type FrameWaitForFunctionParams = {arg: SerializedArgument,timeout: number,pollingInterval?: number,+ selector?: string,+ strict?: boolean,};export type FrameWaitForFunctionOptions = {isFunction?: boolean,pollingInterval?: number,+ selector?: string,+ strict?: boolean,};export type FrameWaitForFunctionResult = {- handle: JSHandleChannel,+ handle?: JSHandleChannel,};export type FrameWaitForSelectorParams = {selector: string,diff --git a/packages/playwright-core/src/client/frame.ts b/packages/playwright-core/src/client/frame.tsindex c6b9695ff9..5699713a6b 100644--- a/packages/playwright-core/src/client/frame.ts+++ b/packages/playwright-core/src/client/frame.ts@@ -484,7 +484,7 @@ export class Frame extends ChannelOwner<channels.FrameChannel> implements api.Frarg: serializeArgument(arg),timeout: this._timeout(options),});- return JSHandle.from(result.handle) as any as structs.SmartHandle<R>;+ return JSHandle.from(result.handle!) as any as structs.SmartHandle<R>;}async title(): Promise<string> {diff --git a/packages/playwright-core/src/client/locator.ts b/packages/playwright-core/src/client/locator.tsindex 89c892c540..297b2e6c5c 100644--- a/packages/playwright-core/src/client/locator.ts+++ b/packages/playwright-core/src/client/locator.ts@@ -20,6 +20,7 @@ import { escapeForTextSelector } from '@isomorphic/stringUtils';import { isString } from '@isomorphic/rtti';import { monotonicTime } from '@isomorphic/time';import { ElementHandle } from './elementHandle';+import { serializeArgument } from './jsHandle';import { DisposableStub } from './disposable';import type { ExpectResult, Frame } from './frame';@@ -390,6 +391,18 @@ export class Locator implements api.Locator {await this._frame._channel.waitForSelector({ selector: this._selector, strict: true, omitReturnValue: true, ...options, timeout: this._frame._timeout(options) });}+ async waitForFunction<R, Arg>(pageFunction: structs.PageFunctionOn<SVGElement | HTMLElement, Arg, R>, arg?: Arg, options?: TimeoutOptions): Promise<void> {+ await this._frame._channel.waitForFunction({+ selector: this._selector,+ strict: true,+ expression: String(pageFunction),+ isFunction: typeof pageFunction === 'function',+ arg: serializeArgument(arg),+ timeout: this._frame._timeout(options),+ pollingInterval: 100,+ });+ }+async _expect(expression: string, options: FrameExpectParams): Promise<ExpectResult> {return this._frame._expect(expression, {diff --git a/packages/playwright-core/src/protocol/validator.ts b/packages/playwright-core/src/protocol/validator.tsindex e001312d87..5fe1cce5d2 100644--- a/packages/playwright-core/src/protocol/validator.ts+++ b/packages/playwright-core/src/protocol/validator.ts@@ -1632,9 +1632,11 @@ scheme.FrameWaitForFunctionParams = tObject({arg: tType('SerializedArgument'),timeout: tFloat,pollingInterval: tOptional(tFloat),+ selector: tOptional(tString),+ strict: tOptional(tBoolean),});scheme.FrameWaitForFunctionResult = tObject({- handle: tChannel(['ElementHandle', 'JSHandle']),+ handle: tOptional(tChannel(['ElementHandle', 'JSHandle'])),});scheme.FrameWaitForSelectorParams = tObject({selector: tString,diff --git a/packages/playwright-core/src/server/channels.d.ts b/packages/playwright-core/src/server/channels.d.tsindex e70d98db23..e8c7c0ddc8 100644--- a/packages/playwright-core/src/server/channels.d.ts+++ b/packages/playwright-core/src/server/channels.d.ts@@ -2984,13 +2984,17 @@ export type FrameWaitForFunctionParams = {arg: SerializedArgument,timeout: number,pollingInterval?: number,+ selector?: string,+ strict?: boolean,};export type FrameWaitForFunctionOptions = {isFunction?: boolean,pollingInterval?: number,+ selector?: string,+ strict?: boolean,};export type FrameWaitForFunctionResult = {- handle: JSHandleChannel,+ handle?: JSHandleChannel,};export type FrameWaitForSelectorParams = {selector: string,diff --git a/packages/playwright-core/src/server/dispatchers/frameDispatcher.ts b/packages/playwright-core/src/server/dispatchers/frameDispatcher.tsindex f8b58d74ed..9ae0d8ffbe 100644--- a/packages/playwright-core/src/server/dispatchers/frameDispatcher.ts+++ b/packages/playwright-core/src/server/dispatchers/frameDispatcher.ts@@ -255,7 +255,12 @@ export class FrameDispatcher extends Dispatcher<Frame, channels.FrameChannel, Br}async waitForFunction(params: channels.FrameWaitForFunctionParams, progress: Progress): Promise<channels.FrameWaitForFunctionResult> {- return { handle: ElementHandleDispatcher.fromJSOrElementHandle(this, await this._frame.waitForFunctionExpression(progress, params.expression, params.isFunction, parseArgument(params.arg), params)) };+ const handle = await this._frame.waitForFunctionExpression(progress, params.expression, params.isFunction, parseArgument(params.arg), params);+ if (params.selector !== undefined) {+ handle.dispose();+ return {};+ }+ return { handle: ElementHandleDispatcher.fromJSOrElementHandle(this, handle) };}async title(params: channels.FrameTitleParams, progress: Progress): Promise<channels.FrameTitleResult> {diff --git a/packages/playwright-core/src/server/frames.ts b/packages/playwright-core/src/server/frames.tsindex 392fe5203f..dc8e86ef84 100644--- a/packages/playwright-core/src/server/frames.ts+++ b/packages/playwright-core/src/server/frames.ts@@ -1599,30 +1599,49 @@ export class Frame extends SdkObject<FrameEventMap> {return { matches, received };}- async waitForFunctionExpression<R>(progress: Progress, expression: string, isFunction: boolean | undefined, arg: any, options: { pollingInterval?: number }, world: types.World = 'main'): Promise<js.SmartHandle<R>> {+ async waitForFunctionExpression<R>(progress: Progress, expression: string, isFunction: boolean | undefined, arg: any, options: { pollingInterval?: number, selector?: string, strict?: boolean }, world: types.World = 'main'): Promise<js.SmartHandle<R>> {if (typeof options.pollingInterval === 'number')assert(options.pollingInterval > 0, 'Cannot poll with non-positive interval: ' + options.pollingInterval);expression = js.normalizeEvaluationExpression(expression, isFunction);- return this.retryWithProgressAndTimeouts(progress, [100], async () => {- const context = world === 'main' ? await progress.race(this.mainContext()) : await progress.race(this.utilityContext());- const injectedScript = await progress.race(context.injectedScript());- const handle = await progress.race(injectedScript.evaluateHandle((injected, { expression, isFunction, polling, arg }) => {+ if (options.selector !== undefined)+ progress.log(`waiting for ${this._asLocator(options.selector)}`);+ return this.retryWithProgressAndBackoff(progress, async (progress, continuePolling) => {+ let injectedScript: js.JSHandle<InjectedScript>;+ let info: SelectorInfo | undefined;+ if (options.selector !== undefined) {+ const resolved = await progress.race(this.selectors.resolveInjectedForSelector(options.selector, { strict: options.strict, mainWorld: true }));+ if (!resolved)+ return continuePolling;+ injectedScript = resolved.injected;+ info = resolved.info;+ } else {+ const context = world === 'main' ? await progress.race(this.mainContext()) : await progress.race(this.utilityContext());+ injectedScript = await progress.race(context.injectedScript());+ }+ const handle = await progress.race(injectedScript.evaluateHandle((injected, { info, expression, isFunction, polling, arg }) => {let evaledExpression: any;const predicate = (): R => {+ const args = [arg];+ if (info) {+ const element = injected.querySelector(info.parsed, document, info.strict);+ if (!element)+ return undefined as any;+ args.unshift(element);+ }// NOTE: make sure to use `globalThis.eval` instead of `self.eval` due to a bug with sandbox isolation// in firefox.// See https://bugzilla.mozilla.org/show_bug.cgi?id=1814898let result = evaledExpression ?? globalThis.eval(expression);if (isFunction === true) {evaledExpression = result;- result = result(arg);+ result = result(...args);} else if (isFunction === false) {result = result;} else {// auto detect.if (typeof result === 'function') {evaledExpression = result;- result = result(arg);+ result = result(...args);}}return result;@@ -1653,12 +1672,14 @@ export class Frame extends SdkObject<FrameEventMap> {next();return { result, abort: () => aborted = true };- }, { expression, isFunction, polling: options.pollingInterval, arg }));+ }, { info, expression, isFunction, polling: options.pollingInterval, arg }));try {return await progress.race(handle.evaluateHandle(h => h.result));} catch (error) {// Note: it is important to await "abort()" to prevent any side effects- // after this method returns.+ // after this method returns. We intentionally do not race against progress+ // here - it is already resolved/aborted, and the abort must run to completion.+ // eslint-disable-next-line progress/await-must-use-progressawait handle.evaluate(h => h.abort()).catch(() => {});throw error;} finally {diff --git a/packages/playwright-core/types/types.d.ts b/packages/playwright-core/types/types.d.tsindex 4f4e40c7cd..5f01196f87 100644--- a/packages/playwright-core/types/types.d.ts+++ b/packages/playwright-core/types/types.d.ts@@ -12852,78 +12852,7 @@ export interface Locator {* [`pageFunction`](https://playwright.dev/docs/api/class-locator#locator-evaluate-option-expression).* @param options*/- evaluate<R, Arg, E extends SVGElement | HTMLElement = SVGElement | HTMLElement>(pageFunction: PageFunctionOn<E, Arg, R>, arg: Arg, options?: {- timeout?: number;- }): Promise<R>;- /**- * Execute JavaScript code in the page, taking the matching element as an argument.- *- * **Details**- *- * Returns the return value of- * [`pageFunction`](https://playwright.dev/docs/api/class-locator#locator-evaluate-option-expression), called with the- * matching element as a first argument, and- * [`arg`](https://playwright.dev/docs/api/class-locator#locator-evaluate-option-arg) as a second argument.- *- * If [`pageFunction`](https://playwright.dev/docs/api/class-locator#locator-evaluate-option-expression) returns a- * [Promise], this method will wait for the promise to resolve and return its value.- *- * If [`pageFunction`](https://playwright.dev/docs/api/class-locator#locator-evaluate-option-expression) throws or- * rejects, this method throws.- *- * **Usage**- *- * Passing argument to- * [`pageFunction`](https://playwright.dev/docs/api/class-locator#locator-evaluate-option-expression):- *- * ```js- * const result = await page.getByTestId('myId').evaluate((element, [x, y]) => {- * return element.textContent + ' ' + x * y;- * }, [7, 8]);- * console.log(result); // prints "myId text 56"- * ```- *- * @param pageFunction Function to be evaluated in the page context.- * @param arg Optional argument to pass to- * [`pageFunction`](https://playwright.dev/docs/api/class-locator#locator-evaluate-option-expression).- * @param options- */- evaluate<R, E extends SVGElement | HTMLElement = SVGElement | HTMLElement>(pageFunction: PageFunctionOn<E, void, R>, options?: {- timeout?: number;- }): Promise<R>;- /**- * Execute JavaScript code in the page, taking the matching element as an argument, and return a- * [JSHandle](https://playwright.dev/docs/api/class-jshandle) with the result.- *- * **Details**- *- * Returns the return value of- * [`pageFunction`](https://playwright.dev/docs/api/class-locator#locator-evaluate-handle-option-expression) as- * a[JSHandle](https://playwright.dev/docs/api/class-jshandle), called with the matching element as a first argument,- * and [`arg`](https://playwright.dev/docs/api/class-locator#locator-evaluate-handle-option-arg) as a second argument.- *- * The only difference between- * [locator.evaluate(pageFunction[, arg, options])](https://playwright.dev/docs/api/class-locator#locator-evaluate)- * and- * [locator.evaluateHandle(pageFunction[, arg, options])](https://playwright.dev/docs/api/class-locator#locator-evaluate-handle)- * is that- * [locator.evaluateHandle(pageFunction[, arg, options])](https://playwright.dev/docs/api/class-locator#locator-evaluate-handle)- * returns [JSHandle](https://playwright.dev/docs/api/class-jshandle).- *- * If [`pageFunction`](https://playwright.dev/docs/api/class-locator#locator-evaluate-handle-option-expression)- * returns a [Promise], this method will wait for the promise to resolve and return its value.- *- * If [`pageFunction`](https://playwright.dev/docs/api/class-locator#locator-evaluate-handle-option-expression) throws- * or rejects, this method throws.- *- * See [page.evaluateHandle(pageFunction[, arg])](https://playwright.dev/docs/api/class-page#page-evaluate-handle) for- * more details.- * @param pageFunction Function to be evaluated in the page context.- * @param arg Optional argument to pass to- * [`pageFunction`](https://playwright.dev/docs/api/class-locator#locator-evaluate-handle-option-expression).- * @param options- */- evaluateHandle<R, Arg, E extends SVGElement | HTMLElement = SVGElement | HTMLElement>(pageFunction: PageFunctionOn<E, Arg, R>, arg: Arg): Promise<SmartHandle<R>>;+ evaluate<R, Arg, E extends SVGElement | HTMLElement = SVGElement | HTMLElement>(pageFunction: PageFunctionOn<E, Arg, R>, arg?: Arg, options?: { timeout?: number }): Promise<R>;/*** Execute JavaScript code in the page, taking the matching element as an argument, and return a* [JSHandle](https://playwright.dev/docs/api/class-jshandle) with the result.@@ -12956,7 +12885,7 @@ export interface Locator {* [`pageFunction`](https://playwright.dev/docs/api/class-locator#locator-evaluate-handle-option-expression).* @param options*/- evaluateHandle<R, E extends SVGElement | HTMLElement = SVGElement | HTMLElement>(pageFunction: PageFunctionOn<E, void, R>): Promise<SmartHandle<R>>;+ evaluateHandle<R, Arg, E extends SVGElement | HTMLElement = SVGElement | HTMLElement>(pageFunction: PageFunctionOn<E, Arg, R>, arg?: Arg, options?: { timeout?: number }): Promise<SmartHandle<R>>;/*** Execute JavaScript code in the page, taking all matching elements as an argument.*@@ -12984,35 +12913,47 @@ export interface Locator {* @param arg Optional argument to pass to* [`pageFunction`](https://playwright.dev/docs/api/class-locator#locator-evaluate-all-option-expression).*/- evaluateAll<R, Arg, E extends SVGElement | HTMLElement = SVGElement | HTMLElement>(pageFunction: PageFunctionOn<E[], Arg, R>, arg: Arg): Promise<R>;+ evaluateAll<R, Arg, E extends SVGElement | HTMLElement = SVGElement | HTMLElement>(pageFunction: PageFunctionOn<E[], Arg, R>, arg?: Arg): Promise<R>;/**- * Execute JavaScript code in the page, taking all matching elements as an argument.+ * Returns when+ * [`pageFunction`](https://playwright.dev/docs/api/class-locator#locator-wait-for-function-option-expression) returns+ * a truthy value, called with the matching element as a first argument, and+ * [`arg`](https://playwright.dev/docs/api/class-locator#locator-wait-for-function-option-arg) as a second argument.*- * **Details**+ * This is a generic way to wait for an element to reach a custom condition without asserting it. The locator is+ * re-resolved on each retry, so it tolerates the element being re-rendered while waiting.*- * Returns the return value of- * [`pageFunction`](https://playwright.dev/docs/api/class-locator#locator-evaluate-all-option-expression), called with- * an array of all matching elements as a first argument, and- * [`arg`](https://playwright.dev/docs/api/class-locator#locator-evaluate-all-option-arg) as a second argument.+ * If [`pageFunction`](https://playwright.dev/docs/api/class-locator#locator-wait-for-function-option-expression)+ * returns a [Promise], this method will wait for the promise to resolve before checking its value.*- * If [`pageFunction`](https://playwright.dev/docs/api/class-locator#locator-evaluate-all-option-expression) returns a- * [Promise], this method will wait for the promise to resolve and return its value.- *- * If [`pageFunction`](https://playwright.dev/docs/api/class-locator#locator-evaluate-all-option-expression) throws or- * rejects, this method throws.+ * If [`pageFunction`](https://playwright.dev/docs/api/class-locator#locator-wait-for-function-option-expression)+ * throws or rejects, this method throws.** **Usage***+ * Wait for an attribute to appear:+ ** ```js- * const locator = page.locator('div');- * const moreThanTen = await locator.evaluateAll((divs, min) => divs.length > min, 10);+ * const toggle = page.getByRole('button', { name: 'Menu' });+ * await toggle.click();+ * await toggle.waitForFunction(element => element.hasAttribute('aria-expanded'));+ * ```+ *+ * Passing argument to+ * [`pageFunction`](https://playwright.dev/docs/api/class-locator#locator-wait-for-function-option-expression):+ *+ * ```js+ * await page.getByTestId('status').waitForFunction((element, value) => {+ * return element.textContent === value;+ * }, 'Ready');* ```** @param pageFunction Function to be evaluated in the page context.* @param arg Optional argument to pass to- * [`pageFunction`](https://playwright.dev/docs/api/class-locator#locator-evaluate-all-option-expression).+ * [`pageFunction`](https://playwright.dev/docs/api/class-locator#locator-wait-for-function-option-expression).+ * @param options*/- evaluateAll<R, E extends SVGElement | HTMLElement = SVGElement | HTMLElement>(pageFunction: PageFunctionOn<E[], void, R>): Promise<R>;+ waitForFunction<Arg, E extends SVGElement | HTMLElement = SVGElement | HTMLElement>(pageFunction: PageFunctionOn<E, Arg, any>, arg?: Arg, options?: { timeout?: number }): Promise<void>;/*** **NOTE** Always prefer using [Locator](https://playwright.dev/docs/api/class-locator)s and web assertions over* [ElementHandle](https://playwright.dev/docs/api/class-elementhandle)s because latter are inherently racy.@@ -13021,17 +12962,13 @@ export interface Locator {* multiple elements match the locator, throws.* @param options*/- elementHandle(options?: {- timeout?: number;- }): Promise<null|ElementHandle<SVGElement | HTMLElement>>;+ elementHandle(options?: { timeout?: number }): Promise<ElementHandle<SVGElement | HTMLElement>>;/*** Highlight the corresponding element(s) on the screen. Useful for debugging, don't commit the code that uses* [locator.highlight([options])](https://playwright.dev/docs/api/class-locator#locator-highlight).* @param options*/- highlight(options?: {- style?: string | { [key: string]: string | number };- }): Promise<Disposable>;+ highlight(options?: { style?: string | { [key: string]: string | number } }): Promise<Disposable>;/*** Returns a human-readable representation of the locator, using the* [locator.description()](https://playwright.dev/docs/api/class-locator#locator-description) if one exists;diff --git a/packages/protocol/spec/frame.yml b/packages/protocol/spec/frame.ymlindex eb0917e05e..2ff4909e77 100644--- a/packages/protocol/spec/frame.yml+++ b/packages/protocol/spec/frame.yml@@ -720,8 +720,12 @@ Frame:timeout: float# When present, polls on interval. Otherwise, polls on raf.pollingInterval: float?+ # When present, first argument is the matched element.+ selector: string?+ strict: boolean?returns:- handle: JSHandle+ # Missing when "selector" is present.+ handle: JSHandle?flags:snapshot: truepause: truediff --git a/tests/library/inspector/cli-codegen-1.spec.ts b/tests/library/inspector/cli-codegen-1.spec.tsindex 97929c01ae..d793079e48 100644--- a/tests/library/inspector/cli-codegen-1.spec.ts+++ b/tests/library/inspector/cli-codegen-1.spec.ts@@ -402,7 +402,7 @@ await page.Locator("#input").FillAsync(\"てすと\");`);const { page, recorder } = await openRecorder();await recorder.setContentAndWait(`<textarea id="textarea"></textarea>`);const textarea = page.locator('textarea');- await textarea.evaluate<void, HTMLTextAreaElement>(e => e.addEventListener('input', () => (window as any).lastInputValue = e.value));+ await textarea.evaluate<void, void, HTMLTextAreaElement>(e => e.addEventListener('input', () => (window as any).lastInputValue = e.value));const waitForOutputPromise = recorder.waitForOutput('JavaScript', 'Hello\\n');await textarea.type('Hello\n');// Issue was that the input event was not fired for the last newline, so we check for that.diff --git a/tests/page/locator-wait-for-function.spec.ts b/tests/page/locator-wait-for-function.spec.tsnew file mode 100644index 0000000000..adce6bb11a--- /dev/null+++ b/tests/page/locator-wait-for-function.spec.ts@@ -0,0 +1,80 @@+/**+ * Copyright (c) Microsoft Corporation.+ *+ * 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 { test as it, expect } from './pageTest';++it('should wait for an attribute to appear', async ({ page }) => {+ await page.setContent('<button id=toggle>Menu</button>');+ await page.evaluate(() => window.builtins.setTimeout(() => document.querySelector('#toggle')!.setAttribute('aria-expanded', 'true'), 1000));+ await page.locator('#toggle').waitForFunction(element => element.hasAttribute('aria-expanded'));+});++it('should return immediately when already truthy', async ({ page }) => {+ await page.setContent('<div id=target>yes</div>');+ expect(await page.locator('#target').waitForFunction(element => element.textContent === 'yes')).toBe(undefined);+});++it('should accept ElementHandle arguments', async ({ page }) => {+ await page.setContent('<div id=a></div><div id=b>value</div>');+ const handle = await page.$('#b');+ await page.locator('#a').waitForFunction((element, other) => other.textContent === 'value', handle);+});++it('should accept string expression', async ({ page }) => {+ await page.setContent('<div id=target>yes</div>');+ await page.locator('#target').waitForFunction(`element => element.textContent === 'yes'`);+});++it('should resolve a promise returned by the predicate', async ({ page }) => {+ await page.setContent('<div id=target>yes</div>');+ await page.locator('#target').waitForFunction(async element => element.textContent === 'yes');+});++it('should wait for element to appear and survive rerender', async ({ page }) => {+ await page.setContent('<span>nothing here</span>');+ await page.evaluate(() => {+ let count = 0;+ let prev: Element | null = null;+ const tick = () => {+ ++count;+ const next = document.createElement('div');+ next.id = 'target';+ next.textContent = String(count);+ if (prev)+ prev.remove();+ document.body.appendChild(next);+ prev = next;+ if (count < 3)+ window.builtins.setTimeout(tick, 500);+ };+ window.builtins.setTimeout(tick, 500);+ });+ await page.locator('#target').waitForFunction(element => element.textContent === '3');+});++it('should throw when predicate throws', async ({ page }) => {+ await page.setContent('<div id=target>no</div>');+ const error = await page.locator('#target').waitForFunction(() => {+ throw new Error('oh my');+ }).catch(e => e);+ expect(error.message).toContain('oh my');+});++it('should throw on strict mode violation', async ({ page }) => {+ await page.setContent('<div class=x>1</div><div class=x>2</div>');+ const error = await page.locator('div.x').waitForFunction(() => true).catch(e => e);+ expect(error.message).toContain('strict mode violation');+});diff --git a/utils/generate_types/overrides.d.ts b/utils/generate_types/overrides.d.tsindex e2ec1db55e..ccfd73db92 100644--- a/utils/generate_types/overrides.d.ts+++ b/utils/generate_types/overrides.d.ts@@ -190,22 +190,12 @@ export interface ElementHandle<T=Node> extends JSHandle<T> {}export interface Locator {- evaluate<R, Arg, E extends SVGElement | HTMLElement = SVGElement | HTMLElement>(pageFunction: PageFunctionOn<E, Arg, R>, arg: Arg, options?: {- timeout?: number;- }): Promise<R>;- evaluate<R, E extends SVGElement | HTMLElement = SVGElement | HTMLElement>(pageFunction: PageFunctionOn<E, void, R>, options?: {- timeout?: number;- }): Promise<R>;- evaluateHandle<R, Arg, E extends SVGElement | HTMLElement = SVGElement | HTMLElement>(pageFunction: PageFunctionOn<E, Arg, R>, arg: Arg): Promise<SmartHandle<R>>;- evaluateHandle<R, E extends SVGElement | HTMLElement = SVGElement | HTMLElement>(pageFunction: PageFunctionOn<E, void, R>): Promise<SmartHandle<R>>;- evaluateAll<R, Arg, E extends SVGElement | HTMLElement = SVGElement | HTMLElement>(pageFunction: PageFunctionOn<E[], Arg, R>, arg: Arg): Promise<R>;- evaluateAll<R, E extends SVGElement | HTMLElement = SVGElement | HTMLElement>(pageFunction: PageFunctionOn<E[], void, R>): Promise<R>;- elementHandle(options?: {- timeout?: number;- }): Promise<null|ElementHandle<SVGElement | HTMLElement>>;- highlight(options?: {- style?: string | { [key: string]: string | number };- }): Promise<Disposable>;+ evaluate<R, Arg, E extends SVGElement | HTMLElement = SVGElement | HTMLElement>(pageFunction: PageFunctionOn<E, Arg, R>, arg?: Arg, options?: { timeout?: number }): Promise<R>;+ evaluateHandle<R, Arg, E extends SVGElement | HTMLElement = SVGElement | HTMLElement>(pageFunction: PageFunctionOn<E, Arg, R>, arg?: Arg, options?: { timeout?: number }): Promise<SmartHandle<R>>;+ evaluateAll<R, Arg, E extends SVGElement | HTMLElement = SVGElement | HTMLElement>(pageFunction: PageFunctionOn<E[], Arg, R>, arg?: Arg): Promise<R>;+ waitForFunction<Arg, E extends SVGElement | HTMLElement = SVGElement | HTMLElement>(pageFunction: PageFunctionOn<E, Arg, any>, arg?: Arg, options?: { timeout?: number }): Promise<void>;+ elementHandle(options?: { timeout?: number }): Promise<ElementHandle<SVGElement | HTMLElement>>;+ highlight(options?: { style?: string | { [key: string]: string | number } }): Promise<Disposable>;toString(): string;}