diff --git a/package-lock.json b/package-lock.json index eb0399a9cb..70fcacf837 100644 --- a/package-lock.json +++ b/package-lock.json @@ -1576,6 +1576,10 @@ "resolved": "packages/playwright-browser-webkit", "link": true }, + "node_modules/@playwright/client": { + "resolved": "packages/playwright-client", + "link": true + }, "node_modules/@playwright/experimental-ct-core": { "resolved": "packages/playwright-ct-core", "link": true @@ -8932,6 +8936,17 @@ "node": ">=18" } }, + "packages/playwright-client": { + "name": "@playwright/client", + "version": "1.51.0-next", + "license": "Apache-2.0", + "dependencies": { + "playwright-core": "1.51.0-next" + }, + "engines": { + "node": ">=18" + } + }, "packages/playwright-core": { "version": "1.51.0-next", "license": "Apache-2.0", diff --git a/packages/playwright-core/src/client/clientBundle.ts b/packages/playwright-client/index.d.ts similarity index 59% rename from packages/playwright-core/src/client/clientBundle.ts rename to packages/playwright-client/index.d.ts index 99df031213..74906f0947 100644 --- a/packages/playwright-core/src/client/clientBundle.ts +++ b/packages/playwright-client/index.d.ts @@ -1,7 +1,7 @@ /** * Copyright (c) Microsoft Corporation. * - * Licensed under the Apache License, Version 2.0 (the 'License"); + * 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 * @@ -14,12 +14,12 @@ * limitations under the License. */ -import { Connection } from './connection'; -import { setPlatformForSelectors } from './selectors'; +import type { Browser } from './types/types'; -import type { Platform } from './platform'; +export * from './types/types'; -export function createConnectionFactory(platform: Platform): () => Connection { - setPlatformForSelectors(platform); - return () => new Connection(platform); -} +export type Options = { + headless?: boolean; +}; + +export const connect: (wsEndpoint: string, browserName: string, options: Options) => Promise; diff --git a/packages/playwright-client/index.js b/packages/playwright-client/index.js new file mode 100644 index 0000000000..227eee0fde --- /dev/null +++ b/packages/playwright-client/index.js @@ -0,0 +1,17 @@ +/** + * 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. + */ + +module.exports = require('./lib/index'); diff --git a/packages/playwright-client/index.mjs b/packages/playwright-client/index.mjs new file mode 100644 index 0000000000..0332e50157 --- /dev/null +++ b/packages/playwright-client/index.mjs @@ -0,0 +1,17 @@ +/** + * 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. + */ + +export { connect } from './index.js'; diff --git a/packages/playwright-client/package.json b/packages/playwright-client/package.json new file mode 100644 index 0000000000..57cfa8375a --- /dev/null +++ b/packages/playwright-client/package.json @@ -0,0 +1,34 @@ +{ + "name": "@playwright/client", + "private": true, + "version": "1.51.0-next", + "description": "A thin client for Playwright", + "repository": { + "type": "git", + "url": "git+https://github.com/microsoft/playwright.git" + }, + "homepage": "https://playwright.dev", + "engines": { + "node": ">=18" + }, + "author": { + "name": "Microsoft Corporation" + }, + "license": "Apache-2.0", + "exports": { + ".": { + "types": "./index.d.ts", + "import": "./index.mjs", + "require": "./index.js", + "default": "./index.js" + }, + "./package.json": "./package.json" + }, + "scripts": { + "build": "esbuild ./src/index.ts --outdir=lib --format=cjs --bundle --platform=node --target=ES2019", + "watch": "esbuild ./src/index.ts --outdir=lib --format=cjs --bundle --platform=node --target=ES2019 --watch" + }, + "dependencies": { + "playwright-core": "1.51.0-next" + } +} diff --git a/packages/playwright-client/src/index.ts b/packages/playwright-client/src/index.ts new file mode 100644 index 0000000000..48762e4e81 --- /dev/null +++ b/packages/playwright-client/src/index.ts @@ -0,0 +1,40 @@ +/** + * 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 { Connection } from '../../playwright-core/src/client/connection'; +import { webPlatform } from './webPlatform'; + +import type { Browser } from '../../playwright-core/src/client/browser'; + +export type Options = { + headless?: boolean; +}; + +export async function connect(wsEndpoint: string, browserName: string, options: Options): Promise { + const ws = new WebSocket(`${wsEndpoint}?browser=${browserName}&launch-options=${JSON.stringify(options)}`); + await new Promise((f, r) => { + ws.addEventListener('open', f); + ws.addEventListener('error', r); + }); + + const connection = new Connection(webPlatform); + connection.onmessage = message => ws.send(JSON.stringify(message)); + ws.addEventListener('message', message => connection.dispatch(JSON.parse(message.data))); + ws.addEventListener('close', () => connection.close()); + + const playwright = await connection.initializePlaywright(); + return playwright._preLaunchedBrowser(); +} diff --git a/packages/playwright-client/src/webPlatform.ts b/packages/playwright-client/src/webPlatform.ts new file mode 100644 index 0000000000..e7d64817ec --- /dev/null +++ b/packages/playwright-client/src/webPlatform.ts @@ -0,0 +1,48 @@ +/* eslint-disable no-console */ +/** + * 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 { emptyPlatform } from '../../playwright-core/src/client/platform'; + +import type { Platform } from '../../playwright-core/src/client/platform'; + +export const webPlatform: Platform = { + ...emptyPlatform, + + name: 'web', + + boxedStackPrefixes: () => [], + + calculateSha1: async (text: string) => { + const bytes = new TextEncoder().encode(text); + const hashBuffer = await window.crypto.subtle.digest('SHA-1', bytes); + return Array.from(new Uint8Array(hashBuffer), b => b.toString(16).padStart(2, '0')).join(''); + }, + + createGuid: () => { + return Array.from(window.crypto.getRandomValues(new Uint8Array(16)), b => b.toString(16).padStart(2, '0')).join(''); + }, + + isLogEnabled(name: 'api' | 'channel') { + return true; + }, + + log(name: 'api' | 'channel', message: string | Error | object) { + console.debug(name, message); + }, + + showInternalStackFrames: () => true, +}; diff --git a/packages/playwright-client/types/types.d.ts b/packages/playwright-client/types/types.d.ts new file mode 100644 index 0000000000..65907853f4 --- /dev/null +++ b/packages/playwright-client/types/types.d.ts @@ -0,0 +1,22974 @@ +// This file is generated by /utils/generate_types/index.js +/** + * 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 { ChildProcess } from 'child_process'; +import { Readable } from 'stream'; +import { ReadStream } from 'fs'; +import { Protocol } from './protocol'; +import { Serializable, EvaluationArgument, PageFunction, PageFunctionOn, SmartHandle, ElementHandleForTag, BindingSource } from './structs'; + +type PageWaitForSelectorOptionsNotHidden = PageWaitForSelectorOptions & { + state?: 'visible'|'attached'; +}; +type ElementHandleWaitForSelectorOptionsNotHidden = ElementHandleWaitForSelectorOptions & { + state?: 'visible'|'attached'; +}; + +/** + * Page provides methods to interact with a single tab in a [Browser](https://playwright.dev/docs/api/class-browser), + * or an [extension background page](https://developer.chrome.com/extensions/background_pages) in Chromium. One + * [Browser](https://playwright.dev/docs/api/class-browser) instance might have multiple + * [Page](https://playwright.dev/docs/api/class-page) instances. + * + * This example creates a page, navigates it to a URL, and then saves a screenshot: + * + * ```js + * const { webkit } = require('playwright'); // Or 'chromium' or 'firefox'. + * + * (async () => { + * const browser = await webkit.launch(); + * const context = await browser.newContext(); + * const page = await context.newPage(); + * await page.goto('https://example.com'); + * await page.screenshot({ path: 'screenshot.png' }); + * await browser.close(); + * })(); + * ``` + * + * The Page class emits various events (described below) which can be handled using any of Node's native + * [`EventEmitter`](https://nodejs.org/api/events.html#events_class_eventemitter) methods, such as `on`, `once` or + * `removeListener`. + * + * This example logs a message for a single page `load` event: + * + * ```js + * page.once('load', () => console.log('Page loaded!')); + * ``` + * + * To unsubscribe from events use the `removeListener` method: + * + * ```js + * function logRequest(interceptedRequest) { + * console.log('A request was made:', interceptedRequest.url()); + * } + * page.on('request', logRequest); + * // Sometime later... + * page.removeListener('request', logRequest); + * ``` + * + */ +export interface Page { + /** + * Returns the value of the + * [`pageFunction`](https://playwright.dev/docs/api/class-page#page-evaluate-option-expression) invocation. + * + * If the function passed to the + * [page.evaluate(pageFunction[, arg])](https://playwright.dev/docs/api/class-page#page-evaluate) returns a [Promise], + * then [page.evaluate(pageFunction[, arg])](https://playwright.dev/docs/api/class-page#page-evaluate) would wait for + * the promise to resolve and return its value. + * + * If the function passed to the + * [page.evaluate(pageFunction[, arg])](https://playwright.dev/docs/api/class-page#page-evaluate) returns a + * non-[Serializable] value, then + * [page.evaluate(pageFunction[, arg])](https://playwright.dev/docs/api/class-page#page-evaluate) resolves to + * `undefined`. Playwright also supports transferring some additional values that are not serializable by `JSON`: + * `-0`, `NaN`, `Infinity`, `-Infinity`. + * + * **Usage** + * + * Passing argument to [`pageFunction`](https://playwright.dev/docs/api/class-page#page-evaluate-option-expression): + * + * ```js + * const result = await page.evaluate(([x, y]) => { + * return Promise.resolve(x * y); + * }, [7, 8]); + * console.log(result); // prints "56" + * ``` + * + * A string can also be passed in instead of a function: + * + * ```js + * console.log(await page.evaluate('1 + 2')); // prints "3" + * const x = 10; + * console.log(await page.evaluate(`1 + ${x}`)); // prints "11" + * ``` + * + * [ElementHandle](https://playwright.dev/docs/api/class-elementhandle) instances can be passed as an argument to the + * [page.evaluate(pageFunction[, arg])](https://playwright.dev/docs/api/class-page#page-evaluate): + * + * ```js + * const bodyHandle = await page.evaluate('document.body'); + * const html = await page.evaluate(([body, suffix]) => + * body.innerHTML + suffix, [bodyHandle, 'hello'] + * ); + * await bodyHandle.dispose(); + * ``` + * + * @param pageFunction Function to be evaluated in the page context. + * @param arg Optional argument to pass to + * [`pageFunction`](https://playwright.dev/docs/api/class-page#page-evaluate-option-expression). + */ + evaluate(pageFunction: PageFunction, arg: Arg): Promise; + /** + * Returns the value of the + * [`pageFunction`](https://playwright.dev/docs/api/class-page#page-evaluate-option-expression) invocation. + * + * If the function passed to the + * [page.evaluate(pageFunction[, arg])](https://playwright.dev/docs/api/class-page#page-evaluate) returns a [Promise], + * then [page.evaluate(pageFunction[, arg])](https://playwright.dev/docs/api/class-page#page-evaluate) would wait for + * the promise to resolve and return its value. + * + * If the function passed to the + * [page.evaluate(pageFunction[, arg])](https://playwright.dev/docs/api/class-page#page-evaluate) returns a + * non-[Serializable] value, then + * [page.evaluate(pageFunction[, arg])](https://playwright.dev/docs/api/class-page#page-evaluate) resolves to + * `undefined`. Playwright also supports transferring some additional values that are not serializable by `JSON`: + * `-0`, `NaN`, `Infinity`, `-Infinity`. + * + * **Usage** + * + * Passing argument to [`pageFunction`](https://playwright.dev/docs/api/class-page#page-evaluate-option-expression): + * + * ```js + * const result = await page.evaluate(([x, y]) => { + * return Promise.resolve(x * y); + * }, [7, 8]); + * console.log(result); // prints "56" + * ``` + * + * A string can also be passed in instead of a function: + * + * ```js + * console.log(await page.evaluate('1 + 2')); // prints "3" + * const x = 10; + * console.log(await page.evaluate(`1 + ${x}`)); // prints "11" + * ``` + * + * [ElementHandle](https://playwright.dev/docs/api/class-elementhandle) instances can be passed as an argument to the + * [page.evaluate(pageFunction[, arg])](https://playwright.dev/docs/api/class-page#page-evaluate): + * + * ```js + * const bodyHandle = await page.evaluate('document.body'); + * const html = await page.evaluate(([body, suffix]) => + * body.innerHTML + suffix, [bodyHandle, 'hello'] + * ); + * await bodyHandle.dispose(); + * ``` + * + * @param pageFunction Function to be evaluated in the page context. + * @param arg Optional argument to pass to + * [`pageFunction`](https://playwright.dev/docs/api/class-page#page-evaluate-option-expression). + */ + evaluate(pageFunction: PageFunction, arg?: any): Promise; + + /** + * Returns the value of the + * [`pageFunction`](https://playwright.dev/docs/api/class-page#page-evaluate-handle-option-expression) invocation as a + * [JSHandle](https://playwright.dev/docs/api/class-jshandle). + * + * The only difference between + * [page.evaluate(pageFunction[, arg])](https://playwright.dev/docs/api/class-page#page-evaluate) and + * [page.evaluateHandle(pageFunction[, arg])](https://playwright.dev/docs/api/class-page#page-evaluate-handle) is that + * [page.evaluateHandle(pageFunction[, arg])](https://playwright.dev/docs/api/class-page#page-evaluate-handle) returns + * [JSHandle](https://playwright.dev/docs/api/class-jshandle). + * + * If the function passed to the + * [page.evaluateHandle(pageFunction[, arg])](https://playwright.dev/docs/api/class-page#page-evaluate-handle) returns + * a [Promise], then + * [page.evaluateHandle(pageFunction[, arg])](https://playwright.dev/docs/api/class-page#page-evaluate-handle) would + * wait for the promise to resolve and return its value. + * + * **Usage** + * + * ```js + * // Handle for the window object. + * const aWindowHandle = await page.evaluateHandle(() => Promise.resolve(window)); + * ``` + * + * A string can also be passed in instead of a function: + * + * ```js + * const aHandle = await page.evaluateHandle('document'); // Handle for the 'document' + * ``` + * + * [JSHandle](https://playwright.dev/docs/api/class-jshandle) instances can be passed as an argument to the + * [page.evaluateHandle(pageFunction[, arg])](https://playwright.dev/docs/api/class-page#page-evaluate-handle): + * + * ```js + * const aHandle = await page.evaluateHandle(() => document.body); + * const resultHandle = await page.evaluateHandle(body => body.innerHTML, aHandle); + * console.log(await resultHandle.jsonValue()); + * await resultHandle.dispose(); + * ``` + * + * @param pageFunction Function to be evaluated in the page context. + * @param arg Optional argument to pass to + * [`pageFunction`](https://playwright.dev/docs/api/class-page#page-evaluate-handle-option-expression). + */ + evaluateHandle(pageFunction: PageFunction, arg: Arg): Promise>; + /** + * Returns the value of the + * [`pageFunction`](https://playwright.dev/docs/api/class-page#page-evaluate-handle-option-expression) invocation as a + * [JSHandle](https://playwright.dev/docs/api/class-jshandle). + * + * The only difference between + * [page.evaluate(pageFunction[, arg])](https://playwright.dev/docs/api/class-page#page-evaluate) and + * [page.evaluateHandle(pageFunction[, arg])](https://playwright.dev/docs/api/class-page#page-evaluate-handle) is that + * [page.evaluateHandle(pageFunction[, arg])](https://playwright.dev/docs/api/class-page#page-evaluate-handle) returns + * [JSHandle](https://playwright.dev/docs/api/class-jshandle). + * + * If the function passed to the + * [page.evaluateHandle(pageFunction[, arg])](https://playwright.dev/docs/api/class-page#page-evaluate-handle) returns + * a [Promise], then + * [page.evaluateHandle(pageFunction[, arg])](https://playwright.dev/docs/api/class-page#page-evaluate-handle) would + * wait for the promise to resolve and return its value. + * + * **Usage** + * + * ```js + * // Handle for the window object. + * const aWindowHandle = await page.evaluateHandle(() => Promise.resolve(window)); + * ``` + * + * A string can also be passed in instead of a function: + * + * ```js + * const aHandle = await page.evaluateHandle('document'); // Handle for the 'document' + * ``` + * + * [JSHandle](https://playwright.dev/docs/api/class-jshandle) instances can be passed as an argument to the + * [page.evaluateHandle(pageFunction[, arg])](https://playwright.dev/docs/api/class-page#page-evaluate-handle): + * + * ```js + * const aHandle = await page.evaluateHandle(() => document.body); + * const resultHandle = await page.evaluateHandle(body => body.innerHTML, aHandle); + * console.log(await resultHandle.jsonValue()); + * await resultHandle.dispose(); + * ``` + * + * @param pageFunction Function to be evaluated in the page context. + * @param arg Optional argument to pass to + * [`pageFunction`](https://playwright.dev/docs/api/class-page#page-evaluate-handle-option-expression). + */ + evaluateHandle(pageFunction: PageFunction, arg?: any): Promise>; + + /** + * Adds a script which would be evaluated in one of the following scenarios: + * - Whenever the page is navigated. + * - Whenever the child frame is attached or navigated. In this case, the script is evaluated in the context of the + * newly attached frame. + * + * The script is evaluated after the document was created but before any of its scripts were run. This is useful to + * amend the JavaScript environment, e.g. to seed `Math.random`. + * + * **Usage** + * + * An example of overriding `Math.random` before the page loads: + * + * ```js + * // preload.js + * Math.random = () => 42; + * ``` + * + * ```js + * // In your playwright script, assuming the preload.js file is in same directory + * await page.addInitScript({ path: './preload.js' }); + * ``` + * + * ```js + * await page.addInitScript(mock => { + * window.mock = mock; + * }, mock); + * ``` + * + * **NOTE** The order of evaluation of multiple scripts installed via + * [browserContext.addInitScript(script[, arg])](https://playwright.dev/docs/api/class-browsercontext#browser-context-add-init-script) + * and [page.addInitScript(script[, arg])](https://playwright.dev/docs/api/class-page#page-add-init-script) is not + * defined. + * + * @param script Script to be evaluated in the page. + * @param arg Optional argument to pass to + * [`script`](https://playwright.dev/docs/api/class-page#page-add-init-script-option-script) (only supported when + * passing a function). + */ + addInitScript(script: PageFunction | { path?: string, content?: string }, arg?: Arg): Promise; + + /** + * **NOTE** Use locator-based [page.locator(selector[, options])](https://playwright.dev/docs/api/class-page#page-locator) + * instead. Read more about [locators](https://playwright.dev/docs/locators). + * + * The method finds an element matching the specified selector within the page. If no elements match the selector, the + * return value resolves to `null`. To wait for an element on the page, use + * [locator.waitFor([options])](https://playwright.dev/docs/api/class-locator#locator-wait-for). + * @param selector A selector to query for. + * @param options + */ + $(selector: K, options?: { strict: boolean }): Promise | null>; + /** + * **NOTE** Use locator-based [page.locator(selector[, options])](https://playwright.dev/docs/api/class-page#page-locator) + * instead. Read more about [locators](https://playwright.dev/docs/locators). + * + * The method finds an element matching the specified selector within the page. If no elements match the selector, the + * return value resolves to `null`. To wait for an element on the page, use + * [locator.waitFor([options])](https://playwright.dev/docs/api/class-locator#locator-wait-for). + * @param selector A selector to query for. + * @param options + */ + $(selector: string, options?: { strict: boolean }): Promise | null>; + + /** + * **NOTE** Use locator-based [page.locator(selector[, options])](https://playwright.dev/docs/api/class-page#page-locator) + * instead. Read more about [locators](https://playwright.dev/docs/locators). + * + * The method finds all elements matching the specified selector within the page. If no elements match the selector, + * the return value resolves to `[]`. + * @param selector A selector to query for. + */ + $$(selector: K): Promise[]>; + /** + * **NOTE** Use locator-based [page.locator(selector[, options])](https://playwright.dev/docs/api/class-page#page-locator) + * instead. Read more about [locators](https://playwright.dev/docs/locators). + * + * The method finds all elements matching the specified selector within the page. If no elements match the selector, + * the return value resolves to `[]`. + * @param selector A selector to query for. + */ + $$(selector: string): Promise[]>; + + /** + * **NOTE** This method does not wait for the element to pass actionability checks and therefore can lead to the flaky tests. + * Use + * [locator.evaluate(pageFunction[, arg, options])](https://playwright.dev/docs/api/class-locator#locator-evaluate), + * other [Locator](https://playwright.dev/docs/api/class-locator) helper methods or web-first assertions instead. + * + * The method finds an element matching the specified selector within the page and passes it as a first argument to + * [`pageFunction`](https://playwright.dev/docs/api/class-page#page-eval-on-selector-option-expression). If no + * elements match the selector, the method throws an error. Returns the value of + * [`pageFunction`](https://playwright.dev/docs/api/class-page#page-eval-on-selector-option-expression). + * + * If [`pageFunction`](https://playwright.dev/docs/api/class-page#page-eval-on-selector-option-expression) returns a + * [Promise], then + * [page.$eval(selector, pageFunction[, arg, options])](https://playwright.dev/docs/api/class-page#page-eval-on-selector) + * would wait for the promise to resolve and return its value. + * + * **Usage** + * + * ```js + * const searchValue = await page.$eval('#search', el => el.value); + * const preloadHref = await page.$eval('link[rel=preload]', el => el.href); + * const html = await page.$eval('.main-container', (e, suffix) => e.outerHTML + suffix, 'hello'); + * // In TypeScript, this example requires an explicit type annotation (HTMLLinkElement) on el: + * const preloadHrefTS = await page.$eval('link[rel=preload]', (el: HTMLLinkElement) => el.href); + * ``` + * + * @param selector A selector to query for. + * @param pageFunction Function to be evaluated in the page context. + * @param arg Optional argument to pass to + * [`pageFunction`](https://playwright.dev/docs/api/class-page#page-eval-on-selector-option-expression). + * @param options + */ + $eval(selector: K, pageFunction: PageFunctionOn, arg: Arg): Promise; + /** + * **NOTE** This method does not wait for the element to pass actionability checks and therefore can lead to the flaky tests. + * Use + * [locator.evaluate(pageFunction[, arg, options])](https://playwright.dev/docs/api/class-locator#locator-evaluate), + * other [Locator](https://playwright.dev/docs/api/class-locator) helper methods or web-first assertions instead. + * + * The method finds an element matching the specified selector within the page and passes it as a first argument to + * [`pageFunction`](https://playwright.dev/docs/api/class-page#page-eval-on-selector-option-expression). If no + * elements match the selector, the method throws an error. Returns the value of + * [`pageFunction`](https://playwright.dev/docs/api/class-page#page-eval-on-selector-option-expression). + * + * If [`pageFunction`](https://playwright.dev/docs/api/class-page#page-eval-on-selector-option-expression) returns a + * [Promise], then + * [page.$eval(selector, pageFunction[, arg, options])](https://playwright.dev/docs/api/class-page#page-eval-on-selector) + * would wait for the promise to resolve and return its value. + * + * **Usage** + * + * ```js + * const searchValue = await page.$eval('#search', el => el.value); + * const preloadHref = await page.$eval('link[rel=preload]', el => el.href); + * const html = await page.$eval('.main-container', (e, suffix) => e.outerHTML + suffix, 'hello'); + * // In TypeScript, this example requires an explicit type annotation (HTMLLinkElement) on el: + * const preloadHrefTS = await page.$eval('link[rel=preload]', (el: HTMLLinkElement) => el.href); + * ``` + * + * @param selector A selector to query for. + * @param pageFunction Function to be evaluated in the page context. + * @param arg Optional argument to pass to + * [`pageFunction`](https://playwright.dev/docs/api/class-page#page-eval-on-selector-option-expression). + * @param options + */ + $eval(selector: string, pageFunction: PageFunctionOn, arg: Arg): Promise; + /** + * **NOTE** This method does not wait for the element to pass actionability checks and therefore can lead to the flaky tests. + * Use + * [locator.evaluate(pageFunction[, arg, options])](https://playwright.dev/docs/api/class-locator#locator-evaluate), + * other [Locator](https://playwright.dev/docs/api/class-locator) helper methods or web-first assertions instead. + * + * The method finds an element matching the specified selector within the page and passes it as a first argument to + * [`pageFunction`](https://playwright.dev/docs/api/class-page#page-eval-on-selector-option-expression). If no + * elements match the selector, the method throws an error. Returns the value of + * [`pageFunction`](https://playwright.dev/docs/api/class-page#page-eval-on-selector-option-expression). + * + * If [`pageFunction`](https://playwright.dev/docs/api/class-page#page-eval-on-selector-option-expression) returns a + * [Promise], then + * [page.$eval(selector, pageFunction[, arg, options])](https://playwright.dev/docs/api/class-page#page-eval-on-selector) + * would wait for the promise to resolve and return its value. + * + * **Usage** + * + * ```js + * const searchValue = await page.$eval('#search', el => el.value); + * const preloadHref = await page.$eval('link[rel=preload]', el => el.href); + * const html = await page.$eval('.main-container', (e, suffix) => e.outerHTML + suffix, 'hello'); + * // In TypeScript, this example requires an explicit type annotation (HTMLLinkElement) on el: + * const preloadHrefTS = await page.$eval('link[rel=preload]', (el: HTMLLinkElement) => el.href); + * ``` + * + * @param selector A selector to query for. + * @param pageFunction Function to be evaluated in the page context. + * @param arg Optional argument to pass to + * [`pageFunction`](https://playwright.dev/docs/api/class-page#page-eval-on-selector-option-expression). + * @param options + */ + $eval(selector: K, pageFunction: PageFunctionOn, arg?: any): Promise; + /** + * **NOTE** This method does not wait for the element to pass actionability checks and therefore can lead to the flaky tests. + * Use + * [locator.evaluate(pageFunction[, arg, options])](https://playwright.dev/docs/api/class-locator#locator-evaluate), + * other [Locator](https://playwright.dev/docs/api/class-locator) helper methods or web-first assertions instead. + * + * The method finds an element matching the specified selector within the page and passes it as a first argument to + * [`pageFunction`](https://playwright.dev/docs/api/class-page#page-eval-on-selector-option-expression). If no + * elements match the selector, the method throws an error. Returns the value of + * [`pageFunction`](https://playwright.dev/docs/api/class-page#page-eval-on-selector-option-expression). + * + * If [`pageFunction`](https://playwright.dev/docs/api/class-page#page-eval-on-selector-option-expression) returns a + * [Promise], then + * [page.$eval(selector, pageFunction[, arg, options])](https://playwright.dev/docs/api/class-page#page-eval-on-selector) + * would wait for the promise to resolve and return its value. + * + * **Usage** + * + * ```js + * const searchValue = await page.$eval('#search', el => el.value); + * const preloadHref = await page.$eval('link[rel=preload]', el => el.href); + * const html = await page.$eval('.main-container', (e, suffix) => e.outerHTML + suffix, 'hello'); + * // In TypeScript, this example requires an explicit type annotation (HTMLLinkElement) on el: + * const preloadHrefTS = await page.$eval('link[rel=preload]', (el: HTMLLinkElement) => el.href); + * ``` + * + * @param selector A selector to query for. + * @param pageFunction Function to be evaluated in the page context. + * @param arg Optional argument to pass to + * [`pageFunction`](https://playwright.dev/docs/api/class-page#page-eval-on-selector-option-expression). + * @param options + */ + $eval(selector: string, pageFunction: PageFunctionOn, arg?: any): Promise; + + /** + * **NOTE** In most cases, + * [locator.evaluateAll(pageFunction[, arg])](https://playwright.dev/docs/api/class-locator#locator-evaluate-all), + * other [Locator](https://playwright.dev/docs/api/class-locator) helper methods and web-first assertions do a better + * job. + * + * The method finds all elements matching the specified selector within the page and passes an array of matched + * elements as a first argument to + * [`pageFunction`](https://playwright.dev/docs/api/class-page#page-eval-on-selector-all-option-expression). Returns + * the result of + * [`pageFunction`](https://playwright.dev/docs/api/class-page#page-eval-on-selector-all-option-expression) + * invocation. + * + * If [`pageFunction`](https://playwright.dev/docs/api/class-page#page-eval-on-selector-all-option-expression) returns + * a [Promise], then + * [page.$$eval(selector, pageFunction[, arg])](https://playwright.dev/docs/api/class-page#page-eval-on-selector-all) + * would wait for the promise to resolve and return its value. + * + * **Usage** + * + * ```js + * const divCounts = await page.$$eval('div', (divs, min) => divs.length >= min, 10); + * ``` + * + * @param selector A selector to query for. + * @param pageFunction Function to be evaluated in the page context. + * @param arg Optional argument to pass to + * [`pageFunction`](https://playwright.dev/docs/api/class-page#page-eval-on-selector-all-option-expression). + */ + $$eval(selector: K, pageFunction: PageFunctionOn, arg: Arg): Promise; + /** + * **NOTE** In most cases, + * [locator.evaluateAll(pageFunction[, arg])](https://playwright.dev/docs/api/class-locator#locator-evaluate-all), + * other [Locator](https://playwright.dev/docs/api/class-locator) helper methods and web-first assertions do a better + * job. + * + * The method finds all elements matching the specified selector within the page and passes an array of matched + * elements as a first argument to + * [`pageFunction`](https://playwright.dev/docs/api/class-page#page-eval-on-selector-all-option-expression). Returns + * the result of + * [`pageFunction`](https://playwright.dev/docs/api/class-page#page-eval-on-selector-all-option-expression) + * invocation. + * + * If [`pageFunction`](https://playwright.dev/docs/api/class-page#page-eval-on-selector-all-option-expression) returns + * a [Promise], then + * [page.$$eval(selector, pageFunction[, arg])](https://playwright.dev/docs/api/class-page#page-eval-on-selector-all) + * would wait for the promise to resolve and return its value. + * + * **Usage** + * + * ```js + * const divCounts = await page.$$eval('div', (divs, min) => divs.length >= min, 10); + * ``` + * + * @param selector A selector to query for. + * @param pageFunction Function to be evaluated in the page context. + * @param arg Optional argument to pass to + * [`pageFunction`](https://playwright.dev/docs/api/class-page#page-eval-on-selector-all-option-expression). + */ + $$eval(selector: string, pageFunction: PageFunctionOn, arg: Arg): Promise; + /** + * **NOTE** In most cases, + * [locator.evaluateAll(pageFunction[, arg])](https://playwright.dev/docs/api/class-locator#locator-evaluate-all), + * other [Locator](https://playwright.dev/docs/api/class-locator) helper methods and web-first assertions do a better + * job. + * + * The method finds all elements matching the specified selector within the page and passes an array of matched + * elements as a first argument to + * [`pageFunction`](https://playwright.dev/docs/api/class-page#page-eval-on-selector-all-option-expression). Returns + * the result of + * [`pageFunction`](https://playwright.dev/docs/api/class-page#page-eval-on-selector-all-option-expression) + * invocation. + * + * If [`pageFunction`](https://playwright.dev/docs/api/class-page#page-eval-on-selector-all-option-expression) returns + * a [Promise], then + * [page.$$eval(selector, pageFunction[, arg])](https://playwright.dev/docs/api/class-page#page-eval-on-selector-all) + * would wait for the promise to resolve and return its value. + * + * **Usage** + * + * ```js + * const divCounts = await page.$$eval('div', (divs, min) => divs.length >= min, 10); + * ``` + * + * @param selector A selector to query for. + * @param pageFunction Function to be evaluated in the page context. + * @param arg Optional argument to pass to + * [`pageFunction`](https://playwright.dev/docs/api/class-page#page-eval-on-selector-all-option-expression). + */ + $$eval(selector: K, pageFunction: PageFunctionOn, arg?: any): Promise; + /** + * **NOTE** In most cases, + * [locator.evaluateAll(pageFunction[, arg])](https://playwright.dev/docs/api/class-locator#locator-evaluate-all), + * other [Locator](https://playwright.dev/docs/api/class-locator) helper methods and web-first assertions do a better + * job. + * + * The method finds all elements matching the specified selector within the page and passes an array of matched + * elements as a first argument to + * [`pageFunction`](https://playwright.dev/docs/api/class-page#page-eval-on-selector-all-option-expression). Returns + * the result of + * [`pageFunction`](https://playwright.dev/docs/api/class-page#page-eval-on-selector-all-option-expression) + * invocation. + * + * If [`pageFunction`](https://playwright.dev/docs/api/class-page#page-eval-on-selector-all-option-expression) returns + * a [Promise], then + * [page.$$eval(selector, pageFunction[, arg])](https://playwright.dev/docs/api/class-page#page-eval-on-selector-all) + * would wait for the promise to resolve and return its value. + * + * **Usage** + * + * ```js + * const divCounts = await page.$$eval('div', (divs, min) => divs.length >= min, 10); + * ``` + * + * @param selector A selector to query for. + * @param pageFunction Function to be evaluated in the page context. + * @param arg Optional argument to pass to + * [`pageFunction`](https://playwright.dev/docs/api/class-page#page-eval-on-selector-all-option-expression). + */ + $$eval(selector: string, pageFunction: PageFunctionOn, arg?: any): Promise; + + /** + * Returns when the + * [`pageFunction`](https://playwright.dev/docs/api/class-page#page-wait-for-function-option-expression) returns a + * truthy value. It resolves to a JSHandle of the truthy value. + * + * **Usage** + * + * The + * [page.waitForFunction(pageFunction[, arg, options])](https://playwright.dev/docs/api/class-page#page-wait-for-function) + * can be used to observe viewport size change: + * + * ```js + * const { webkit } = require('playwright'); // Or 'chromium' or 'firefox'. + * + * (async () => { + * const browser = await webkit.launch(); + * const page = await browser.newPage(); + * const watchDog = page.waitForFunction(() => window.innerWidth < 100); + * await page.setViewportSize({ width: 50, height: 50 }); + * await watchDog; + * await browser.close(); + * })(); + * ``` + * + * To pass an argument to the predicate of + * [page.waitForFunction(pageFunction[, arg, options])](https://playwright.dev/docs/api/class-page#page-wait-for-function) + * function: + * + * ```js + * const selector = '.foo'; + * await page.waitForFunction(selector => !!document.querySelector(selector), selector); + * ``` + * + * @param pageFunction Function to be evaluated in the page context. + * @param arg Optional argument to pass to + * [`pageFunction`](https://playwright.dev/docs/api/class-page#page-wait-for-function-option-expression). + * @param options + */ + waitForFunction(pageFunction: PageFunction, arg: Arg, options?: PageWaitForFunctionOptions): Promise>; + /** + * Returns when the + * [`pageFunction`](https://playwright.dev/docs/api/class-page#page-wait-for-function-option-expression) returns a + * truthy value. It resolves to a JSHandle of the truthy value. + * + * **Usage** + * + * The + * [page.waitForFunction(pageFunction[, arg, options])](https://playwright.dev/docs/api/class-page#page-wait-for-function) + * can be used to observe viewport size change: + * + * ```js + * const { webkit } = require('playwright'); // Or 'chromium' or 'firefox'. + * + * (async () => { + * const browser = await webkit.launch(); + * const page = await browser.newPage(); + * const watchDog = page.waitForFunction(() => window.innerWidth < 100); + * await page.setViewportSize({ width: 50, height: 50 }); + * await watchDog; + * await browser.close(); + * })(); + * ``` + * + * To pass an argument to the predicate of + * [page.waitForFunction(pageFunction[, arg, options])](https://playwright.dev/docs/api/class-page#page-wait-for-function) + * function: + * + * ```js + * const selector = '.foo'; + * await page.waitForFunction(selector => !!document.querySelector(selector), selector); + * ``` + * + * @param pageFunction Function to be evaluated in the page context. + * @param arg Optional argument to pass to + * [`pageFunction`](https://playwright.dev/docs/api/class-page#page-wait-for-function-option-expression). + * @param options + */ + waitForFunction(pageFunction: PageFunction, arg?: any, options?: PageWaitForFunctionOptions): Promise>; + + /** + * **NOTE** Use web assertions that assert visibility or a locator-based + * [locator.waitFor([options])](https://playwright.dev/docs/api/class-locator#locator-wait-for) instead. Read more + * about [locators](https://playwright.dev/docs/locators). + * + * Returns when element specified by selector satisfies + * [`state`](https://playwright.dev/docs/api/class-page#page-wait-for-selector-option-state) option. Returns `null` if + * waiting for `hidden` or `detached`. + * + * **NOTE** Playwright automatically waits for element to be ready before performing an action. Using + * [Locator](https://playwright.dev/docs/api/class-locator) objects and web-first assertions makes the code + * wait-for-selector-free. + * + * Wait for the [`selector`](https://playwright.dev/docs/api/class-page#page-wait-for-selector-option-selector) to + * satisfy [`state`](https://playwright.dev/docs/api/class-page#page-wait-for-selector-option-state) option (either + * appear/disappear from dom, or become visible/hidden). If at the moment of calling the method + * [`selector`](https://playwright.dev/docs/api/class-page#page-wait-for-selector-option-selector) already satisfies + * the condition, the method will return immediately. If the selector doesn't satisfy the condition for the + * [`timeout`](https://playwright.dev/docs/api/class-page#page-wait-for-selector-option-timeout) milliseconds, the + * function will throw. + * + * **Usage** + * + * This method works across navigations: + * + * ```js + * const { chromium } = require('playwright'); // Or 'firefox' or 'webkit'. + * + * (async () => { + * const browser = await chromium.launch(); + * const page = await browser.newPage(); + * for (const currentURL of ['https://google.com', 'https://bbc.com']) { + * await page.goto(currentURL); + * const element = await page.waitForSelector('img'); + * console.log('Loaded image: ' + await element.getAttribute('src')); + * } + * await browser.close(); + * })(); + * ``` + * + * @param selector A selector to query for. + * @param options + */ + waitForSelector(selector: K, options?: PageWaitForSelectorOptionsNotHidden): Promise>; + /** + * **NOTE** Use web assertions that assert visibility or a locator-based + * [locator.waitFor([options])](https://playwright.dev/docs/api/class-locator#locator-wait-for) instead. Read more + * about [locators](https://playwright.dev/docs/locators). + * + * Returns when element specified by selector satisfies + * [`state`](https://playwright.dev/docs/api/class-page#page-wait-for-selector-option-state) option. Returns `null` if + * waiting for `hidden` or `detached`. + * + * **NOTE** Playwright automatically waits for element to be ready before performing an action. Using + * [Locator](https://playwright.dev/docs/api/class-locator) objects and web-first assertions makes the code + * wait-for-selector-free. + * + * Wait for the [`selector`](https://playwright.dev/docs/api/class-page#page-wait-for-selector-option-selector) to + * satisfy [`state`](https://playwright.dev/docs/api/class-page#page-wait-for-selector-option-state) option (either + * appear/disappear from dom, or become visible/hidden). If at the moment of calling the method + * [`selector`](https://playwright.dev/docs/api/class-page#page-wait-for-selector-option-selector) already satisfies + * the condition, the method will return immediately. If the selector doesn't satisfy the condition for the + * [`timeout`](https://playwright.dev/docs/api/class-page#page-wait-for-selector-option-timeout) milliseconds, the + * function will throw. + * + * **Usage** + * + * This method works across navigations: + * + * ```js + * const { chromium } = require('playwright'); // Or 'firefox' or 'webkit'. + * + * (async () => { + * const browser = await chromium.launch(); + * const page = await browser.newPage(); + * for (const currentURL of ['https://google.com', 'https://bbc.com']) { + * await page.goto(currentURL); + * const element = await page.waitForSelector('img'); + * console.log('Loaded image: ' + await element.getAttribute('src')); + * } + * await browser.close(); + * })(); + * ``` + * + * @param selector A selector to query for. + * @param options + */ + waitForSelector(selector: string, options?: PageWaitForSelectorOptionsNotHidden): Promise>; + /** + * **NOTE** Use web assertions that assert visibility or a locator-based + * [locator.waitFor([options])](https://playwright.dev/docs/api/class-locator#locator-wait-for) instead. Read more + * about [locators](https://playwright.dev/docs/locators). + * + * Returns when element specified by selector satisfies + * [`state`](https://playwright.dev/docs/api/class-page#page-wait-for-selector-option-state) option. Returns `null` if + * waiting for `hidden` or `detached`. + * + * **NOTE** Playwright automatically waits for element to be ready before performing an action. Using + * [Locator](https://playwright.dev/docs/api/class-locator) objects and web-first assertions makes the code + * wait-for-selector-free. + * + * Wait for the [`selector`](https://playwright.dev/docs/api/class-page#page-wait-for-selector-option-selector) to + * satisfy [`state`](https://playwright.dev/docs/api/class-page#page-wait-for-selector-option-state) option (either + * appear/disappear from dom, or become visible/hidden). If at the moment of calling the method + * [`selector`](https://playwright.dev/docs/api/class-page#page-wait-for-selector-option-selector) already satisfies + * the condition, the method will return immediately. If the selector doesn't satisfy the condition for the + * [`timeout`](https://playwright.dev/docs/api/class-page#page-wait-for-selector-option-timeout) milliseconds, the + * function will throw. + * + * **Usage** + * + * This method works across navigations: + * + * ```js + * const { chromium } = require('playwright'); // Or 'firefox' or 'webkit'. + * + * (async () => { + * const browser = await chromium.launch(); + * const page = await browser.newPage(); + * for (const currentURL of ['https://google.com', 'https://bbc.com']) { + * await page.goto(currentURL); + * const element = await page.waitForSelector('img'); + * console.log('Loaded image: ' + await element.getAttribute('src')); + * } + * await browser.close(); + * })(); + * ``` + * + * @param selector A selector to query for. + * @param options + */ + waitForSelector(selector: K, options: PageWaitForSelectorOptions): Promise | null>; + /** + * **NOTE** Use web assertions that assert visibility or a locator-based + * [locator.waitFor([options])](https://playwright.dev/docs/api/class-locator#locator-wait-for) instead. Read more + * about [locators](https://playwright.dev/docs/locators). + * + * Returns when element specified by selector satisfies + * [`state`](https://playwright.dev/docs/api/class-page#page-wait-for-selector-option-state) option. Returns `null` if + * waiting for `hidden` or `detached`. + * + * **NOTE** Playwright automatically waits for element to be ready before performing an action. Using + * [Locator](https://playwright.dev/docs/api/class-locator) objects and web-first assertions makes the code + * wait-for-selector-free. + * + * Wait for the [`selector`](https://playwright.dev/docs/api/class-page#page-wait-for-selector-option-selector) to + * satisfy [`state`](https://playwright.dev/docs/api/class-page#page-wait-for-selector-option-state) option (either + * appear/disappear from dom, or become visible/hidden). If at the moment of calling the method + * [`selector`](https://playwright.dev/docs/api/class-page#page-wait-for-selector-option-selector) already satisfies + * the condition, the method will return immediately. If the selector doesn't satisfy the condition for the + * [`timeout`](https://playwright.dev/docs/api/class-page#page-wait-for-selector-option-timeout) milliseconds, the + * function will throw. + * + * **Usage** + * + * This method works across navigations: + * + * ```js + * const { chromium } = require('playwright'); // Or 'firefox' or 'webkit'. + * + * (async () => { + * const browser = await chromium.launch(); + * const page = await browser.newPage(); + * for (const currentURL of ['https://google.com', 'https://bbc.com']) { + * await page.goto(currentURL); + * const element = await page.waitForSelector('img'); + * console.log('Loaded image: ' + await element.getAttribute('src')); + * } + * await browser.close(); + * })(); + * ``` + * + * @param selector A selector to query for. + * @param options + */ + waitForSelector(selector: string, options: PageWaitForSelectorOptions): Promise>; + + /** + * The method adds a function called + * [`name`](https://playwright.dev/docs/api/class-page#page-expose-binding-option-name) on the `window` object of + * every frame in this page. When called, the function executes + * [`callback`](https://playwright.dev/docs/api/class-page#page-expose-binding-option-callback) and returns a + * [Promise] which resolves to the return value of + * [`callback`](https://playwright.dev/docs/api/class-page#page-expose-binding-option-callback). If the + * [`callback`](https://playwright.dev/docs/api/class-page#page-expose-binding-option-callback) returns a [Promise], + * it will be awaited. + * + * The first argument of the + * [`callback`](https://playwright.dev/docs/api/class-page#page-expose-binding-option-callback) function contains + * information about the caller: `{ browserContext: BrowserContext, page: Page, frame: Frame }`. + * + * See + * [browserContext.exposeBinding(name, callback[, options])](https://playwright.dev/docs/api/class-browsercontext#browser-context-expose-binding) + * for the context-wide version. + * + * **NOTE** Functions installed via + * [page.exposeBinding(name, callback[, options])](https://playwright.dev/docs/api/class-page#page-expose-binding) + * survive navigations. + * + * **Usage** + * + * An example of exposing page URL to all frames in a page: + * + * ```js + * const { webkit } = require('playwright'); // Or 'chromium' or 'firefox'. + * + * (async () => { + * const browser = await webkit.launch({ headless: false }); + * const context = await browser.newContext(); + * const page = await context.newPage(); + * await page.exposeBinding('pageURL', ({ page }) => page.url()); + * await page.setContent(` + * + * + *
+ * `); + * await page.click('button'); + * })(); + * ``` + * + * @param name Name of the function on the window object. + * @param callback Callback function that will be called in the Playwright's context. + * @param options + */ + exposeBinding(name: string, playwrightBinding: (source: BindingSource, arg: JSHandle) => any, options: { handle: true }): Promise; + /** + * The method adds a function called + * [`name`](https://playwright.dev/docs/api/class-page#page-expose-binding-option-name) on the `window` object of + * every frame in this page. When called, the function executes + * [`callback`](https://playwright.dev/docs/api/class-page#page-expose-binding-option-callback) and returns a + * [Promise] which resolves to the return value of + * [`callback`](https://playwright.dev/docs/api/class-page#page-expose-binding-option-callback). If the + * [`callback`](https://playwright.dev/docs/api/class-page#page-expose-binding-option-callback) returns a [Promise], + * it will be awaited. + * + * The first argument of the + * [`callback`](https://playwright.dev/docs/api/class-page#page-expose-binding-option-callback) function contains + * information about the caller: `{ browserContext: BrowserContext, page: Page, frame: Frame }`. + * + * See + * [browserContext.exposeBinding(name, callback[, options])](https://playwright.dev/docs/api/class-browsercontext#browser-context-expose-binding) + * for the context-wide version. + * + * **NOTE** Functions installed via + * [page.exposeBinding(name, callback[, options])](https://playwright.dev/docs/api/class-page#page-expose-binding) + * survive navigations. + * + * **Usage** + * + * An example of exposing page URL to all frames in a page: + * + * ```js + * const { webkit } = require('playwright'); // Or 'chromium' or 'firefox'. + * + * (async () => { + * const browser = await webkit.launch({ headless: false }); + * const context = await browser.newContext(); + * const page = await context.newPage(); + * await page.exposeBinding('pageURL', ({ page }) => page.url()); + * await page.setContent(` + * + * + *
+ * `); + * await page.click('button'); + * })(); + * ``` + * + * @param name Name of the function on the window object. + * @param callback Callback function that will be called in the Playwright's context. + * @param options + */ + exposeBinding(name: string, playwrightBinding: (source: BindingSource, ...args: any[]) => any, options?: { handle?: boolean }): Promise; + + /** + * Removes all the listeners of the given type (or all registered listeners if no type given). Allows to wait for + * async listeners to complete or to ignore subsequent errors from these listeners. + * + * **Usage** + * + * ```js + * page.on('request', async request => { + * const response = await request.response(); + * const body = await response.body(); + * console.log(body.byteLength); + * }); + * await page.goto('https://playwright.dev', { waitUntil: 'domcontentloaded' }); + * // Waits for all the reported 'request' events to resolve. + * await page.removeAllListeners('request', { behavior: 'wait' }); + * ``` + * + * @param type + * @param options + */ + removeAllListeners(type?: string): this; + /** + * Removes all the listeners of the given type (or all registered listeners if no type given). Allows to wait for + * async listeners to complete or to ignore subsequent errors from these listeners. + * + * **Usage** + * + * ```js + * page.on('request', async request => { + * const response = await request.response(); + * const body = await response.body(); + * console.log(body.byteLength); + * }); + * await page.goto('https://playwright.dev', { waitUntil: 'domcontentloaded' }); + * // Waits for all the reported 'request' events to resolve. + * await page.removeAllListeners('request', { behavior: 'wait' }); + * ``` + * + * @param type + * @param options + */ + removeAllListeners(type: string | undefined, options: { + /** + * Specifies whether to wait for already running listeners and what to do if they throw errors: + * - `'default'` - do not wait for current listener calls (if any) to finish, if the listener throws, it may result in unhandled error + * - `'wait'` - wait for current listener calls (if any) to finish + * - `'ignoreErrors'` - do not wait for current listener calls (if any) to finish, all errors thrown by the listeners after removal are silently caught + */ + behavior?: 'wait'|'ignoreErrors'|'default' + }): Promise; + /** + * Emitted when the page closes. + */ + on(event: 'close', listener: (page: Page) => any): this; + + /** + * Emitted when JavaScript within the page calls one of console API methods, e.g. `console.log` or `console.dir`. + * + * The arguments passed into `console.log` are available on the + * [ConsoleMessage](https://playwright.dev/docs/api/class-consolemessage) event handler argument. + * + * **Usage** + * + * ```js + * page.on('console', async msg => { + * const values = []; + * for (const arg of msg.args()) + * values.push(await arg.jsonValue()); + * console.log(...values); + * }); + * await page.evaluate(() => console.log('hello', 5, { foo: 'bar' })); + * ``` + * + */ + on(event: 'console', listener: (consoleMessage: ConsoleMessage) => any): this; + + /** + * Emitted when the page crashes. Browser pages might crash if they try to allocate too much memory. When the page + * crashes, ongoing and subsequent operations will throw. + * + * The most common way to deal with crashes is to catch an exception: + * + * ```js + * try { + * // Crash might happen during a click. + * await page.click('button'); + * // Or while waiting for an event. + * await page.waitForEvent('popup'); + * } catch (e) { + * // When the page crashes, exception message contains 'crash'. + * } + * ``` + * + */ + on(event: 'crash', listener: (page: Page) => any): this; + + /** + * Emitted when a JavaScript dialog appears, such as `alert`, `prompt`, `confirm` or `beforeunload`. Listener **must** + * either [dialog.accept([promptText])](https://playwright.dev/docs/api/class-dialog#dialog-accept) or + * [dialog.dismiss()](https://playwright.dev/docs/api/class-dialog#dialog-dismiss) the dialog - otherwise the page + * will [freeze](https://developer.mozilla.org/en-US/docs/Web/JavaScript/EventLoop#never_blocking) waiting for the + * dialog, and actions like click will never finish. + * + * **Usage** + * + * ```js + * page.on('dialog', dialog => dialog.accept()); + * ``` + * + * **NOTE** When no [page.on('dialog')](https://playwright.dev/docs/api/class-page#page-event-dialog) or + * [browserContext.on('dialog')](https://playwright.dev/docs/api/class-browsercontext#browser-context-event-dialog) + * listeners are present, all dialogs are automatically dismissed. + * + */ + on(event: 'dialog', listener: (dialog: Dialog) => any): this; + + /** + * Emitted when the JavaScript + * [`DOMContentLoaded`](https://developer.mozilla.org/en-US/docs/Web/Events/DOMContentLoaded) event is dispatched. + */ + on(event: 'domcontentloaded', listener: (page: Page) => any): this; + + /** + * Emitted when attachment download started. User can access basic file operations on downloaded content via the + * passed [Download](https://playwright.dev/docs/api/class-download) instance. + */ + on(event: 'download', listener: (download: Download) => any): this; + + /** + * Emitted when a file chooser is supposed to appear, such as after clicking the ``. Playwright can + * respond to it via setting the input files using + * [fileChooser.setFiles(files[, options])](https://playwright.dev/docs/api/class-filechooser#file-chooser-set-files) + * that can be uploaded after that. + * + * ```js + * page.on('filechooser', async fileChooser => { + * await fileChooser.setFiles(path.join(__dirname, '/tmp/myfile.pdf')); + * }); + * ``` + * + */ + on(event: 'filechooser', listener: (fileChooser: FileChooser) => any): this; + + /** + * Emitted when a frame is attached. + */ + on(event: 'frameattached', listener: (frame: Frame) => any): this; + + /** + * Emitted when a frame is detached. + */ + on(event: 'framedetached', listener: (frame: Frame) => any): this; + + /** + * Emitted when a frame is navigated to a new url. + */ + on(event: 'framenavigated', listener: (frame: Frame) => any): this; + + /** + * Emitted when the JavaScript [`load`](https://developer.mozilla.org/en-US/docs/Web/Events/load) event is dispatched. + */ + on(event: 'load', listener: (page: Page) => any): this; + + /** + * Emitted when an uncaught exception happens within the page. + * + * ```js + * // Log all uncaught errors to the terminal + * page.on('pageerror', exception => { + * console.log(`Uncaught exception: "${exception}"`); + * }); + * + * // Navigate to a page with an exception. + * await page.goto('data:text/html,'); + * ``` + * + */ + on(event: 'pageerror', listener: (error: Error) => any): this; + + /** + * Emitted when the page opens a new tab or window. This event is emitted in addition to the + * [browserContext.on('page')](https://playwright.dev/docs/api/class-browsercontext#browser-context-event-page), but + * only for popups relevant to this page. + * + * The earliest moment that page is available is when it has navigated to the initial url. For example, when opening a + * popup with `window.open('http://example.com')`, this event will fire when the network request to + * "http://example.com" is done and its response has started loading in the popup. If you would like to route/listen + * to this network request, use + * [browserContext.route(url, handler[, options])](https://playwright.dev/docs/api/class-browsercontext#browser-context-route) + * and + * [browserContext.on('request')](https://playwright.dev/docs/api/class-browsercontext#browser-context-event-request) + * respectively instead of similar methods on the [Page](https://playwright.dev/docs/api/class-page). + * + * ```js + * // Start waiting for popup before clicking. Note no await. + * const popupPromise = page.waitForEvent('popup'); + * await page.getByText('open the popup').click(); + * const popup = await popupPromise; + * console.log(await popup.evaluate('location.href')); + * ``` + * + * **NOTE** Use + * [page.waitForLoadState([state, options])](https://playwright.dev/docs/api/class-page#page-wait-for-load-state) to + * wait until the page gets to a particular state (you should not need it in most cases). + * + */ + on(event: 'popup', listener: (page: Page) => any): this; + + /** + * Emitted when a page issues a request. The [request] object is read-only. In order to intercept and mutate requests, + * see [page.route(url, handler[, options])](https://playwright.dev/docs/api/class-page#page-route) or + * [browserContext.route(url, handler[, options])](https://playwright.dev/docs/api/class-browsercontext#browser-context-route). + */ + on(event: 'request', listener: (request: Request) => any): this; + + /** + * Emitted when a request fails, for example by timing out. + * + * ```js + * page.on('requestfailed', request => { + * console.log(request.url() + ' ' + request.failure().errorText); + * }); + * ``` + * + * **NOTE** HTTP Error responses, such as 404 or 503, are still successful responses from HTTP standpoint, so request + * will complete with + * [page.on('requestfinished')](https://playwright.dev/docs/api/class-page#page-event-request-finished) event and not + * with [page.on('requestfailed')](https://playwright.dev/docs/api/class-page#page-event-request-failed). A request + * will only be considered failed when the client cannot get an HTTP response from the server, e.g. due to network + * error net::ERR_FAILED. + * + */ + on(event: 'requestfailed', listener: (request: Request) => any): this; + + /** + * Emitted when a request finishes successfully after downloading the response body. For a successful response, the + * sequence of events is `request`, `response` and `requestfinished`. + */ + on(event: 'requestfinished', listener: (request: Request) => any): this; + + /** + * Emitted when [response] status and headers are received for a request. For a successful response, the sequence of + * events is `request`, `response` and `requestfinished`. + */ + on(event: 'response', listener: (response: Response) => any): this; + + /** + * Emitted when [WebSocket](https://playwright.dev/docs/api/class-websocket) request is sent. + */ + on(event: 'websocket', listener: (webSocket: WebSocket) => any): this; + + /** + * Emitted when a dedicated [WebWorker](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API) is spawned + * by the page. + */ + on(event: 'worker', listener: (worker: Worker) => any): this; + + /** + * Adds an event listener that will be automatically removed after it is triggered once. See `addListener` for more information about this event. + */ + once(event: 'close', listener: (page: Page) => any): this; + + /** + * Adds an event listener that will be automatically removed after it is triggered once. See `addListener` for more information about this event. + */ + once(event: 'console', listener: (consoleMessage: ConsoleMessage) => any): this; + + /** + * Adds an event listener that will be automatically removed after it is triggered once. See `addListener` for more information about this event. + */ + once(event: 'crash', listener: (page: Page) => any): this; + + /** + * Adds an event listener that will be automatically removed after it is triggered once. See `addListener` for more information about this event. + */ + once(event: 'dialog', listener: (dialog: Dialog) => any): this; + + /** + * Adds an event listener that will be automatically removed after it is triggered once. See `addListener` for more information about this event. + */ + once(event: 'domcontentloaded', listener: (page: Page) => any): this; + + /** + * Adds an event listener that will be automatically removed after it is triggered once. See `addListener` for more information about this event. + */ + once(event: 'download', listener: (download: Download) => any): this; + + /** + * Adds an event listener that will be automatically removed after it is triggered once. See `addListener` for more information about this event. + */ + once(event: 'filechooser', listener: (fileChooser: FileChooser) => any): this; + + /** + * Adds an event listener that will be automatically removed after it is triggered once. See `addListener` for more information about this event. + */ + once(event: 'frameattached', listener: (frame: Frame) => any): this; + + /** + * Adds an event listener that will be automatically removed after it is triggered once. See `addListener` for more information about this event. + */ + once(event: 'framedetached', listener: (frame: Frame) => any): this; + + /** + * Adds an event listener that will be automatically removed after it is triggered once. See `addListener` for more information about this event. + */ + once(event: 'framenavigated', listener: (frame: Frame) => any): this; + + /** + * Adds an event listener that will be automatically removed after it is triggered once. See `addListener` for more information about this event. + */ + once(event: 'load', listener: (page: Page) => any): this; + + /** + * Adds an event listener that will be automatically removed after it is triggered once. See `addListener` for more information about this event. + */ + once(event: 'pageerror', listener: (error: Error) => any): this; + + /** + * Adds an event listener that will be automatically removed after it is triggered once. See `addListener` for more information about this event. + */ + once(event: 'popup', listener: (page: Page) => any): this; + + /** + * Adds an event listener that will be automatically removed after it is triggered once. See `addListener` for more information about this event. + */ + once(event: 'request', listener: (request: Request) => any): this; + + /** + * Adds an event listener that will be automatically removed after it is triggered once. See `addListener` for more information about this event. + */ + once(event: 'requestfailed', listener: (request: Request) => any): this; + + /** + * Adds an event listener that will be automatically removed after it is triggered once. See `addListener` for more information about this event. + */ + once(event: 'requestfinished', listener: (request: Request) => any): this; + + /** + * Adds an event listener that will be automatically removed after it is triggered once. See `addListener` for more information about this event. + */ + once(event: 'response', listener: (response: Response) => any): this; + + /** + * Adds an event listener that will be automatically removed after it is triggered once. See `addListener` for more information about this event. + */ + once(event: 'websocket', listener: (webSocket: WebSocket) => any): this; + + /** + * Adds an event listener that will be automatically removed after it is triggered once. See `addListener` for more information about this event. + */ + once(event: 'worker', listener: (worker: Worker) => any): this; + + /** + * Emitted when the page closes. + */ + addListener(event: 'close', listener: (page: Page) => any): this; + + /** + * Emitted when JavaScript within the page calls one of console API methods, e.g. `console.log` or `console.dir`. + * + * The arguments passed into `console.log` are available on the + * [ConsoleMessage](https://playwright.dev/docs/api/class-consolemessage) event handler argument. + * + * **Usage** + * + * ```js + * page.on('console', async msg => { + * const values = []; + * for (const arg of msg.args()) + * values.push(await arg.jsonValue()); + * console.log(...values); + * }); + * await page.evaluate(() => console.log('hello', 5, { foo: 'bar' })); + * ``` + * + */ + addListener(event: 'console', listener: (consoleMessage: ConsoleMessage) => any): this; + + /** + * Emitted when the page crashes. Browser pages might crash if they try to allocate too much memory. When the page + * crashes, ongoing and subsequent operations will throw. + * + * The most common way to deal with crashes is to catch an exception: + * + * ```js + * try { + * // Crash might happen during a click. + * await page.click('button'); + * // Or while waiting for an event. + * await page.waitForEvent('popup'); + * } catch (e) { + * // When the page crashes, exception message contains 'crash'. + * } + * ``` + * + */ + addListener(event: 'crash', listener: (page: Page) => any): this; + + /** + * Emitted when a JavaScript dialog appears, such as `alert`, `prompt`, `confirm` or `beforeunload`. Listener **must** + * either [dialog.accept([promptText])](https://playwright.dev/docs/api/class-dialog#dialog-accept) or + * [dialog.dismiss()](https://playwright.dev/docs/api/class-dialog#dialog-dismiss) the dialog - otherwise the page + * will [freeze](https://developer.mozilla.org/en-US/docs/Web/JavaScript/EventLoop#never_blocking) waiting for the + * dialog, and actions like click will never finish. + * + * **Usage** + * + * ```js + * page.on('dialog', dialog => dialog.accept()); + * ``` + * + * **NOTE** When no [page.on('dialog')](https://playwright.dev/docs/api/class-page#page-event-dialog) or + * [browserContext.on('dialog')](https://playwright.dev/docs/api/class-browsercontext#browser-context-event-dialog) + * listeners are present, all dialogs are automatically dismissed. + * + */ + addListener(event: 'dialog', listener: (dialog: Dialog) => any): this; + + /** + * Emitted when the JavaScript + * [`DOMContentLoaded`](https://developer.mozilla.org/en-US/docs/Web/Events/DOMContentLoaded) event is dispatched. + */ + addListener(event: 'domcontentloaded', listener: (page: Page) => any): this; + + /** + * Emitted when attachment download started. User can access basic file operations on downloaded content via the + * passed [Download](https://playwright.dev/docs/api/class-download) instance. + */ + addListener(event: 'download', listener: (download: Download) => any): this; + + /** + * Emitted when a file chooser is supposed to appear, such as after clicking the ``. Playwright can + * respond to it via setting the input files using + * [fileChooser.setFiles(files[, options])](https://playwright.dev/docs/api/class-filechooser#file-chooser-set-files) + * that can be uploaded after that. + * + * ```js + * page.on('filechooser', async fileChooser => { + * await fileChooser.setFiles(path.join(__dirname, '/tmp/myfile.pdf')); + * }); + * ``` + * + */ + addListener(event: 'filechooser', listener: (fileChooser: FileChooser) => any): this; + + /** + * Emitted when a frame is attached. + */ + addListener(event: 'frameattached', listener: (frame: Frame) => any): this; + + /** + * Emitted when a frame is detached. + */ + addListener(event: 'framedetached', listener: (frame: Frame) => any): this; + + /** + * Emitted when a frame is navigated to a new url. + */ + addListener(event: 'framenavigated', listener: (frame: Frame) => any): this; + + /** + * Emitted when the JavaScript [`load`](https://developer.mozilla.org/en-US/docs/Web/Events/load) event is dispatched. + */ + addListener(event: 'load', listener: (page: Page) => any): this; + + /** + * Emitted when an uncaught exception happens within the page. + * + * ```js + * // Log all uncaught errors to the terminal + * page.on('pageerror', exception => { + * console.log(`Uncaught exception: "${exception}"`); + * }); + * + * // Navigate to a page with an exception. + * await page.goto('data:text/html,'); + * ``` + * + */ + addListener(event: 'pageerror', listener: (error: Error) => any): this; + + /** + * Emitted when the page opens a new tab or window. This event is emitted in addition to the + * [browserContext.on('page')](https://playwright.dev/docs/api/class-browsercontext#browser-context-event-page), but + * only for popups relevant to this page. + * + * The earliest moment that page is available is when it has navigated to the initial url. For example, when opening a + * popup with `window.open('http://example.com')`, this event will fire when the network request to + * "http://example.com" is done and its response has started loading in the popup. If you would like to route/listen + * to this network request, use + * [browserContext.route(url, handler[, options])](https://playwright.dev/docs/api/class-browsercontext#browser-context-route) + * and + * [browserContext.on('request')](https://playwright.dev/docs/api/class-browsercontext#browser-context-event-request) + * respectively instead of similar methods on the [Page](https://playwright.dev/docs/api/class-page). + * + * ```js + * // Start waiting for popup before clicking. Note no await. + * const popupPromise = page.waitForEvent('popup'); + * await page.getByText('open the popup').click(); + * const popup = await popupPromise; + * console.log(await popup.evaluate('location.href')); + * ``` + * + * **NOTE** Use + * [page.waitForLoadState([state, options])](https://playwright.dev/docs/api/class-page#page-wait-for-load-state) to + * wait until the page gets to a particular state (you should not need it in most cases). + * + */ + addListener(event: 'popup', listener: (page: Page) => any): this; + + /** + * Emitted when a page issues a request. The [request] object is read-only. In order to intercept and mutate requests, + * see [page.route(url, handler[, options])](https://playwright.dev/docs/api/class-page#page-route) or + * [browserContext.route(url, handler[, options])](https://playwright.dev/docs/api/class-browsercontext#browser-context-route). + */ + addListener(event: 'request', listener: (request: Request) => any): this; + + /** + * Emitted when a request fails, for example by timing out. + * + * ```js + * page.on('requestfailed', request => { + * console.log(request.url() + ' ' + request.failure().errorText); + * }); + * ``` + * + * **NOTE** HTTP Error responses, such as 404 or 503, are still successful responses from HTTP standpoint, so request + * will complete with + * [page.on('requestfinished')](https://playwright.dev/docs/api/class-page#page-event-request-finished) event and not + * with [page.on('requestfailed')](https://playwright.dev/docs/api/class-page#page-event-request-failed). A request + * will only be considered failed when the client cannot get an HTTP response from the server, e.g. due to network + * error net::ERR_FAILED. + * + */ + addListener(event: 'requestfailed', listener: (request: Request) => any): this; + + /** + * Emitted when a request finishes successfully after downloading the response body. For a successful response, the + * sequence of events is `request`, `response` and `requestfinished`. + */ + addListener(event: 'requestfinished', listener: (request: Request) => any): this; + + /** + * Emitted when [response] status and headers are received for a request. For a successful response, the sequence of + * events is `request`, `response` and `requestfinished`. + */ + addListener(event: 'response', listener: (response: Response) => any): this; + + /** + * Emitted when [WebSocket](https://playwright.dev/docs/api/class-websocket) request is sent. + */ + addListener(event: 'websocket', listener: (webSocket: WebSocket) => any): this; + + /** + * Emitted when a dedicated [WebWorker](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API) is spawned + * by the page. + */ + addListener(event: 'worker', listener: (worker: Worker) => any): this; + + /** + * Removes an event listener added by `on` or `addListener`. + */ + removeListener(event: 'close', listener: (page: Page) => any): this; + + /** + * Removes an event listener added by `on` or `addListener`. + */ + removeListener(event: 'console', listener: (consoleMessage: ConsoleMessage) => any): this; + + /** + * Removes an event listener added by `on` or `addListener`. + */ + removeListener(event: 'crash', listener: (page: Page) => any): this; + + /** + * Removes an event listener added by `on` or `addListener`. + */ + removeListener(event: 'dialog', listener: (dialog: Dialog) => any): this; + + /** + * Removes an event listener added by `on` or `addListener`. + */ + removeListener(event: 'domcontentloaded', listener: (page: Page) => any): this; + + /** + * Removes an event listener added by `on` or `addListener`. + */ + removeListener(event: 'download', listener: (download: Download) => any): this; + + /** + * Removes an event listener added by `on` or `addListener`. + */ + removeListener(event: 'filechooser', listener: (fileChooser: FileChooser) => any): this; + + /** + * Removes an event listener added by `on` or `addListener`. + */ + removeListener(event: 'frameattached', listener: (frame: Frame) => any): this; + + /** + * Removes an event listener added by `on` or `addListener`. + */ + removeListener(event: 'framedetached', listener: (frame: Frame) => any): this; + + /** + * Removes an event listener added by `on` or `addListener`. + */ + removeListener(event: 'framenavigated', listener: (frame: Frame) => any): this; + + /** + * Removes an event listener added by `on` or `addListener`. + */ + removeListener(event: 'load', listener: (page: Page) => any): this; + + /** + * Removes an event listener added by `on` or `addListener`. + */ + removeListener(event: 'pageerror', listener: (error: Error) => any): this; + + /** + * Removes an event listener added by `on` or `addListener`. + */ + removeListener(event: 'popup', listener: (page: Page) => any): this; + + /** + * Removes an event listener added by `on` or `addListener`. + */ + removeListener(event: 'request', listener: (request: Request) => any): this; + + /** + * Removes an event listener added by `on` or `addListener`. + */ + removeListener(event: 'requestfailed', listener: (request: Request) => any): this; + + /** + * Removes an event listener added by `on` or `addListener`. + */ + removeListener(event: 'requestfinished', listener: (request: Request) => any): this; + + /** + * Removes an event listener added by `on` or `addListener`. + */ + removeListener(event: 'response', listener: (response: Response) => any): this; + + /** + * Removes an event listener added by `on` or `addListener`. + */ + removeListener(event: 'websocket', listener: (webSocket: WebSocket) => any): this; + + /** + * Removes an event listener added by `on` or `addListener`. + */ + removeListener(event: 'worker', listener: (worker: Worker) => any): this; + + /** + * Removes an event listener added by `on` or `addListener`. + */ + off(event: 'close', listener: (page: Page) => any): this; + + /** + * Removes an event listener added by `on` or `addListener`. + */ + off(event: 'console', listener: (consoleMessage: ConsoleMessage) => any): this; + + /** + * Removes an event listener added by `on` or `addListener`. + */ + off(event: 'crash', listener: (page: Page) => any): this; + + /** + * Removes an event listener added by `on` or `addListener`. + */ + off(event: 'dialog', listener: (dialog: Dialog) => any): this; + + /** + * Removes an event listener added by `on` or `addListener`. + */ + off(event: 'domcontentloaded', listener: (page: Page) => any): this; + + /** + * Removes an event listener added by `on` or `addListener`. + */ + off(event: 'download', listener: (download: Download) => any): this; + + /** + * Removes an event listener added by `on` or `addListener`. + */ + off(event: 'filechooser', listener: (fileChooser: FileChooser) => any): this; + + /** + * Removes an event listener added by `on` or `addListener`. + */ + off(event: 'frameattached', listener: (frame: Frame) => any): this; + + /** + * Removes an event listener added by `on` or `addListener`. + */ + off(event: 'framedetached', listener: (frame: Frame) => any): this; + + /** + * Removes an event listener added by `on` or `addListener`. + */ + off(event: 'framenavigated', listener: (frame: Frame) => any): this; + + /** + * Removes an event listener added by `on` or `addListener`. + */ + off(event: 'load', listener: (page: Page) => any): this; + + /** + * Removes an event listener added by `on` or `addListener`. + */ + off(event: 'pageerror', listener: (error: Error) => any): this; + + /** + * Removes an event listener added by `on` or `addListener`. + */ + off(event: 'popup', listener: (page: Page) => any): this; + + /** + * Removes an event listener added by `on` or `addListener`. + */ + off(event: 'request', listener: (request: Request) => any): this; + + /** + * Removes an event listener added by `on` or `addListener`. + */ + off(event: 'requestfailed', listener: (request: Request) => any): this; + + /** + * Removes an event listener added by `on` or `addListener`. + */ + off(event: 'requestfinished', listener: (request: Request) => any): this; + + /** + * Removes an event listener added by `on` or `addListener`. + */ + off(event: 'response', listener: (response: Response) => any): this; + + /** + * Removes an event listener added by `on` or `addListener`. + */ + off(event: 'websocket', listener: (webSocket: WebSocket) => any): this; + + /** + * Removes an event listener added by `on` or `addListener`. + */ + off(event: 'worker', listener: (worker: Worker) => any): this; + + /** + * Emitted when the page closes. + */ + prependListener(event: 'close', listener: (page: Page) => any): this; + + /** + * Emitted when JavaScript within the page calls one of console API methods, e.g. `console.log` or `console.dir`. + * + * The arguments passed into `console.log` are available on the + * [ConsoleMessage](https://playwright.dev/docs/api/class-consolemessage) event handler argument. + * + * **Usage** + * + * ```js + * page.on('console', async msg => { + * const values = []; + * for (const arg of msg.args()) + * values.push(await arg.jsonValue()); + * console.log(...values); + * }); + * await page.evaluate(() => console.log('hello', 5, { foo: 'bar' })); + * ``` + * + */ + prependListener(event: 'console', listener: (consoleMessage: ConsoleMessage) => any): this; + + /** + * Emitted when the page crashes. Browser pages might crash if they try to allocate too much memory. When the page + * crashes, ongoing and subsequent operations will throw. + * + * The most common way to deal with crashes is to catch an exception: + * + * ```js + * try { + * // Crash might happen during a click. + * await page.click('button'); + * // Or while waiting for an event. + * await page.waitForEvent('popup'); + * } catch (e) { + * // When the page crashes, exception message contains 'crash'. + * } + * ``` + * + */ + prependListener(event: 'crash', listener: (page: Page) => any): this; + + /** + * Emitted when a JavaScript dialog appears, such as `alert`, `prompt`, `confirm` or `beforeunload`. Listener **must** + * either [dialog.accept([promptText])](https://playwright.dev/docs/api/class-dialog#dialog-accept) or + * [dialog.dismiss()](https://playwright.dev/docs/api/class-dialog#dialog-dismiss) the dialog - otherwise the page + * will [freeze](https://developer.mozilla.org/en-US/docs/Web/JavaScript/EventLoop#never_blocking) waiting for the + * dialog, and actions like click will never finish. + * + * **Usage** + * + * ```js + * page.on('dialog', dialog => dialog.accept()); + * ``` + * + * **NOTE** When no [page.on('dialog')](https://playwright.dev/docs/api/class-page#page-event-dialog) or + * [browserContext.on('dialog')](https://playwright.dev/docs/api/class-browsercontext#browser-context-event-dialog) + * listeners are present, all dialogs are automatically dismissed. + * + */ + prependListener(event: 'dialog', listener: (dialog: Dialog) => any): this; + + /** + * Emitted when the JavaScript + * [`DOMContentLoaded`](https://developer.mozilla.org/en-US/docs/Web/Events/DOMContentLoaded) event is dispatched. + */ + prependListener(event: 'domcontentloaded', listener: (page: Page) => any): this; + + /** + * Emitted when attachment download started. User can access basic file operations on downloaded content via the + * passed [Download](https://playwright.dev/docs/api/class-download) instance. + */ + prependListener(event: 'download', listener: (download: Download) => any): this; + + /** + * Emitted when a file chooser is supposed to appear, such as after clicking the ``. Playwright can + * respond to it via setting the input files using + * [fileChooser.setFiles(files[, options])](https://playwright.dev/docs/api/class-filechooser#file-chooser-set-files) + * that can be uploaded after that. + * + * ```js + * page.on('filechooser', async fileChooser => { + * await fileChooser.setFiles(path.join(__dirname, '/tmp/myfile.pdf')); + * }); + * ``` + * + */ + prependListener(event: 'filechooser', listener: (fileChooser: FileChooser) => any): this; + + /** + * Emitted when a frame is attached. + */ + prependListener(event: 'frameattached', listener: (frame: Frame) => any): this; + + /** + * Emitted when a frame is detached. + */ + prependListener(event: 'framedetached', listener: (frame: Frame) => any): this; + + /** + * Emitted when a frame is navigated to a new url. + */ + prependListener(event: 'framenavigated', listener: (frame: Frame) => any): this; + + /** + * Emitted when the JavaScript [`load`](https://developer.mozilla.org/en-US/docs/Web/Events/load) event is dispatched. + */ + prependListener(event: 'load', listener: (page: Page) => any): this; + + /** + * Emitted when an uncaught exception happens within the page. + * + * ```js + * // Log all uncaught errors to the terminal + * page.on('pageerror', exception => { + * console.log(`Uncaught exception: "${exception}"`); + * }); + * + * // Navigate to a page with an exception. + * await page.goto('data:text/html,'); + * ``` + * + */ + prependListener(event: 'pageerror', listener: (error: Error) => any): this; + + /** + * Emitted when the page opens a new tab or window. This event is emitted in addition to the + * [browserContext.on('page')](https://playwright.dev/docs/api/class-browsercontext#browser-context-event-page), but + * only for popups relevant to this page. + * + * The earliest moment that page is available is when it has navigated to the initial url. For example, when opening a + * popup with `window.open('http://example.com')`, this event will fire when the network request to + * "http://example.com" is done and its response has started loading in the popup. If you would like to route/listen + * to this network request, use + * [browserContext.route(url, handler[, options])](https://playwright.dev/docs/api/class-browsercontext#browser-context-route) + * and + * [browserContext.on('request')](https://playwright.dev/docs/api/class-browsercontext#browser-context-event-request) + * respectively instead of similar methods on the [Page](https://playwright.dev/docs/api/class-page). + * + * ```js + * // Start waiting for popup before clicking. Note no await. + * const popupPromise = page.waitForEvent('popup'); + * await page.getByText('open the popup').click(); + * const popup = await popupPromise; + * console.log(await popup.evaluate('location.href')); + * ``` + * + * **NOTE** Use + * [page.waitForLoadState([state, options])](https://playwright.dev/docs/api/class-page#page-wait-for-load-state) to + * wait until the page gets to a particular state (you should not need it in most cases). + * + */ + prependListener(event: 'popup', listener: (page: Page) => any): this; + + /** + * Emitted when a page issues a request. The [request] object is read-only. In order to intercept and mutate requests, + * see [page.route(url, handler[, options])](https://playwright.dev/docs/api/class-page#page-route) or + * [browserContext.route(url, handler[, options])](https://playwright.dev/docs/api/class-browsercontext#browser-context-route). + */ + prependListener(event: 'request', listener: (request: Request) => any): this; + + /** + * Emitted when a request fails, for example by timing out. + * + * ```js + * page.on('requestfailed', request => { + * console.log(request.url() + ' ' + request.failure().errorText); + * }); + * ``` + * + * **NOTE** HTTP Error responses, such as 404 or 503, are still successful responses from HTTP standpoint, so request + * will complete with + * [page.on('requestfinished')](https://playwright.dev/docs/api/class-page#page-event-request-finished) event and not + * with [page.on('requestfailed')](https://playwright.dev/docs/api/class-page#page-event-request-failed). A request + * will only be considered failed when the client cannot get an HTTP response from the server, e.g. due to network + * error net::ERR_FAILED. + * + */ + prependListener(event: 'requestfailed', listener: (request: Request) => any): this; + + /** + * Emitted when a request finishes successfully after downloading the response body. For a successful response, the + * sequence of events is `request`, `response` and `requestfinished`. + */ + prependListener(event: 'requestfinished', listener: (request: Request) => any): this; + + /** + * Emitted when [response] status and headers are received for a request. For a successful response, the sequence of + * events is `request`, `response` and `requestfinished`. + */ + prependListener(event: 'response', listener: (response: Response) => any): this; + + /** + * Emitted when [WebSocket](https://playwright.dev/docs/api/class-websocket) request is sent. + */ + prependListener(event: 'websocket', listener: (webSocket: WebSocket) => any): this; + + /** + * Emitted when a dedicated [WebWorker](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API) is spawned + * by the page. + */ + prependListener(event: 'worker', listener: (worker: Worker) => any): this; + + /** + * When testing a web page, sometimes unexpected overlays like a "Sign up" dialog appear and block actions you want to + * automate, e.g. clicking a button. These overlays don't always show up in the same way or at the same time, making + * them tricky to handle in automated tests. + * + * This method lets you set up a special function, called a handler, that activates when it detects that overlay is + * visible. The handler's job is to remove the overlay, allowing your test to continue as if the overlay wasn't there. + * + * Things to keep in mind: + * - When an overlay is shown predictably, we recommend explicitly waiting for it in your test and dismissing it as + * a part of your normal test flow, instead of using + * [page.addLocatorHandler(locator, handler[, options])](https://playwright.dev/docs/api/class-page#page-add-locator-handler). + * - Playwright checks for the overlay every time before executing or retrying an action that requires an + * [actionability check](https://playwright.dev/docs/actionability), or before performing an auto-waiting assertion check. When overlay + * is visible, Playwright calls the handler first, and then proceeds with the action/assertion. Note that the + * handler is only called when you perform an action/assertion - if the overlay becomes visible but you don't + * perform any actions, the handler will not be triggered. + * - After executing the handler, Playwright will ensure that overlay that triggered the handler is not visible + * anymore. You can opt-out of this behavior with + * [`noWaitAfter`](https://playwright.dev/docs/api/class-page#page-add-locator-handler-option-no-wait-after). + * - The execution time of the handler counts towards the timeout of the action/assertion that executed the handler. + * If your handler takes too long, it might cause timeouts. + * - You can register multiple handlers. However, only a single handler will be running at a time. Make sure the + * actions within a handler don't depend on another handler. + * + * **NOTE** Running the handler will alter your page state mid-test. For example it will change the currently focused + * element and move the mouse. Make sure that actions that run after the handler are self-contained and do not rely on + * the focus and mouse state being unchanged. + * + * For example, consider a test that calls + * [locator.focus([options])](https://playwright.dev/docs/api/class-locator#locator-focus) followed by + * [keyboard.press(key[, options])](https://playwright.dev/docs/api/class-keyboard#keyboard-press). If your handler + * clicks a button between these two actions, the focused element most likely will be wrong, and key press will happen + * on the unexpected element. Use + * [locator.press(key[, options])](https://playwright.dev/docs/api/class-locator#locator-press) instead to avoid this + * problem. + * + * Another example is a series of mouse actions, where + * [mouse.move(x, y[, options])](https://playwright.dev/docs/api/class-mouse#mouse-move) is followed by + * [mouse.down([options])](https://playwright.dev/docs/api/class-mouse#mouse-down). Again, when the handler runs + * between these two actions, the mouse position will be wrong during the mouse down. Prefer self-contained actions + * like [locator.click([options])](https://playwright.dev/docs/api/class-locator#locator-click) that do not rely on + * the state being unchanged by a handler. + * + * **Usage** + * + * An example that closes a "Sign up to the newsletter" dialog when it appears: + * + * ```js + * // Setup the handler. + * await page.addLocatorHandler(page.getByText('Sign up to the newsletter'), async () => { + * await page.getByRole('button', { name: 'No thanks' }).click(); + * }); + * + * // Write the test as usual. + * await page.goto('https://example.com'); + * await page.getByRole('button', { name: 'Start here' }).click(); + * ``` + * + * An example that skips the "Confirm your security details" page when it is shown: + * + * ```js + * // Setup the handler. + * await page.addLocatorHandler(page.getByText('Confirm your security details'), async () => { + * await page.getByRole('button', { name: 'Remind me later' }).click(); + * }); + * + * // Write the test as usual. + * await page.goto('https://example.com'); + * await page.getByRole('button', { name: 'Start here' }).click(); + * ``` + * + * An example with a custom callback on every actionability check. It uses a `` locator that is always visible, + * so the handler is called before every actionability check. It is important to specify + * [`noWaitAfter`](https://playwright.dev/docs/api/class-page#page-add-locator-handler-option-no-wait-after), because + * the handler does not hide the `` element. + * + * ```js + * // Setup the handler. + * await page.addLocatorHandler(page.locator('body'), async () => { + * await page.evaluate(() => window.removeObstructionsForTestIfNeeded()); + * }, { noWaitAfter: true }); + * + * // Write the test as usual. + * await page.goto('https://example.com'); + * await page.getByRole('button', { name: 'Start here' }).click(); + * ``` + * + * Handler takes the original locator as an argument. You can also automatically remove the handler after a number of + * invocations by setting [`times`](https://playwright.dev/docs/api/class-page#page-add-locator-handler-option-times): + * + * ```js + * await page.addLocatorHandler(page.getByLabel('Close'), async locator => { + * await locator.click(); + * }, { times: 1 }); + * ``` + * + * @param locator Locator that triggers the handler. + * @param handler Function that should be run once + * [`locator`](https://playwright.dev/docs/api/class-page#page-add-locator-handler-option-locator) appears. This + * function should get rid of the element that blocks actions like click. + * @param options + */ + addLocatorHandler(locator: Locator, handler: ((locator: Locator) => Promise), options?: { + /** + * By default, after calling the handler Playwright will wait until the overlay becomes hidden, and only then + * Playwright will continue with the action/assertion that triggered the handler. This option allows to opt-out of + * this behavior, so that overlay can stay visible after the handler has run. + */ + noWaitAfter?: boolean; + + /** + * Specifies the maximum number of times this handler should be called. Unlimited by default. + */ + times?: number; + }): Promise; + + /** + * Adds a ` + * + *
+ * `); + * await page.click('button'); + * })(); + * ``` + * + * @param name Name of the function on the window object + * @param callback Callback function which will be called in Playwright's context. + */ + exposeFunction(name: string, callback: Function): Promise; + + /** + * **NOTE** Use locator-based [locator.fill(value[, options])](https://playwright.dev/docs/api/class-locator#locator-fill) + * instead. Read more about [locators](https://playwright.dev/docs/locators). + * + * This method waits for an element matching + * [`selector`](https://playwright.dev/docs/api/class-page#page-fill-option-selector), waits for + * [actionability](https://playwright.dev/docs/actionability) checks, focuses the element, fills it and triggers an `input` event after + * filling. Note that you can pass an empty string to clear the input field. + * + * If the target element is not an ``, `