diff --git a/docs/src/api/params.md b/docs/src/api/params.md index 415a4faecc..cdc5cb9f0c 100644 --- a/docs/src/api/params.md +++ b/docs/src/api/params.md @@ -960,6 +960,8 @@ An object which specifies clipping of the resulting image. Should have the follo When set to `"css"`, screenshot will have a single pixel per each css pixel on the page. For high-dpi devices, this will keep screenshots small. Using `"device"` option will produce a single pixel per each device pixel, so screenhots of high-dpi devices will be twice as large or even larger. Defaults to `"device"`. ## screenshot-option-fonts +* langs: js +* experimental - `fonts` <[ScreenshotFonts]<"ready"|"nowait">> When set to `"ready"`, screenshot will wait for [`document.fonts.ready`](https://developer.mozilla.org/en-US/docs/Web/API/FontFaceSet/ready) promise to resolve in all frames. Defaults to `"nowait"`. @@ -975,6 +977,7 @@ When set to `"hide"`, screenshot will hide text caret. When set to `"initial"`, - %%-screenshot-option-quality-%% - %%-screenshot-option-path-%% - %%-screenshot-option-scale-%% +- %%-screenshot-option-fonts-%% - %%-screenshot-option-caret-%% - %%-screenshot-option-type-%% - %%-screenshot-option-mask-%% diff --git a/packages/playwright-core/package.json b/packages/playwright-core/package.json index bf1e7953b5..8176ffca81 100644 --- a/packages/playwright-core/package.json +++ b/packages/playwright-core/package.json @@ -36,7 +36,9 @@ "./lib/utils/timeoutRunner": "./lib/utils/timeoutRunner.js", "./lib/remote/playwrightServer": "./lib/remote/playwrightServer.js", "./lib/remote/playwrightClient": "./lib/remote/playwrightClient.js", - "./lib/server": "./lib/server/index.js" + "./lib/server": "./lib/server/index.js", + "./types/protocol": "./types/protocol.d.ts", + "./types/structs": "./types/structs.d.ts" }, "types": "types/types.d.ts", "bin": { diff --git a/packages/playwright-core/src/client/elementHandle.ts b/packages/playwright-core/src/client/elementHandle.ts index fc5fe7c8b8..e3be4dc5e6 100644 --- a/packages/playwright-core/src/client/elementHandle.ts +++ b/packages/playwright-core/src/client/elementHandle.ts @@ -201,7 +201,6 @@ export class ElementHandle extends JSHandle implements selector: locator._selector, })); } - copy.fonts = (options as any)._fonts; const result = await this._elementChannel.screenshot(copy); const buffer = Buffer.from(result.binary, 'base64'); if (options.path) { diff --git a/packages/playwright-core/src/client/page.ts b/packages/playwright-core/src/client/page.ts index 76d4053573..ad054decc9 100644 --- a/packages/playwright-core/src/client/page.ts +++ b/packages/playwright-core/src/client/page.ts @@ -492,7 +492,6 @@ export class Page extends ChannelOwner implements api.Page selector: locator._selector, })); } - copy.fonts = (options as any)._fonts; const result = await this._channel.screenshot(copy); const buffer = Buffer.from(result.binary, 'base64'); if (options.path) { diff --git a/packages/playwright-core/src/server/screenshotter.ts b/packages/playwright-core/src/server/screenshotter.ts index 22bb27466b..869e06b191 100644 --- a/packages/playwright-core/src/server/screenshotter.ts +++ b/packages/playwright-core/src/server/screenshotter.ts @@ -23,7 +23,7 @@ import type { Frame } from './frames'; import type { ParsedSelector } from './isomorphic/selectorParser'; import type * as types from './types'; import type { Progress } from './progress'; -import { assert } from '../utils'; +import { assert, experimentalFeaturesEnabled } from '../utils'; import { MultiMap } from '../utils/multimap'; declare global { @@ -322,6 +322,9 @@ function trimClipToSize(clip: types.Rect, size: types.Size): types.Rect { } function validateScreenshotOptions(options: ScreenshotOptions): 'png' | 'jpeg' { + if (options.fonts && !experimentalFeaturesEnabled()) + throw new Error(`To use the experimental option "fonts", set PLAYWRIGHT_EXPERIMENTAL_FEATURES=1 enviroment variable.`); + let format: 'png' | 'jpeg' | null = null; // options.type takes precedence over inferring the type from options.path // because it may be a 0-length file with no extension created beforehand (i.e. as a temp file). diff --git a/packages/playwright-core/types/structs.d.ts b/packages/playwright-core/types/structs.d.ts index 50232b91df..0f9afa5bdd 100644 --- a/packages/playwright-core/types/structs.d.ts +++ b/packages/playwright-core/types/structs.d.ts @@ -14,7 +14,7 @@ * limitations under the License. */ -import { JSHandle, ElementHandle, Frame, Page, BrowserContext, Locator } from './types'; +import { JSHandle, ElementHandle, Frame, Page, BrowserContext } from 'playwright-core'; /** * Can be converted to JSON diff --git a/packages/playwright-core/types/types.d.ts b/packages/playwright-core/types/types.d.ts index 1d2a22879f..babfb25cab 100644 --- a/packages/playwright-core/types/types.d.ts +++ b/packages/playwright-core/types/types.d.ts @@ -14,12 +14,12 @@ * See the License for the specific language governing permissions and * limitations under the License. */ -import { Protocol } from './protocol'; +import { Protocol } from 'playwright-core/types/protocol'; import { ChildProcess } from 'child_process'; import { EventEmitter } from 'events'; import { Readable } from 'stream'; import { ReadStream } from 'fs'; -import { Serializable, EvaluationArgument, PageFunction, PageFunctionOn, SmartHandle, ElementHandleForTag, BindingSource } from './structs'; +import { Serializable, EvaluationArgument, PageFunction, PageFunctionOn, SmartHandle, ElementHandleForTag, BindingSource } from 'playwright-core/types/structs'; type PageWaitForSelectorOptionsNotHidden = PageWaitForSelectorOptions & { state?: 'visible'|'attached'; diff --git a/packages/playwright-test/index.d.ts b/packages/playwright-test/index.d.ts index cc63b3ecde..4369d23a3c 100644 --- a/packages/playwright-test/index.d.ts +++ b/packages/playwright-test/index.d.ts @@ -14,6 +14,5 @@ * limitations under the License. */ -export * from 'playwright-core'; export * from './types/test'; export { default } from './types/test'; diff --git a/packages/playwright-test/src/matchers/toMatchSnapshot.ts b/packages/playwright-test/src/matchers/toMatchSnapshot.ts index f325590c4f..5205c7ce0c 100644 --- a/packages/playwright-test/src/matchers/toMatchSnapshot.ts +++ b/packages/playwright-test/src/matchers/toMatchSnapshot.ts @@ -308,7 +308,7 @@ export async function toHaveScreenshot( const [page, locator] = pageOrLocator.constructor.name === 'Page' ? [(pageOrLocator as PageEx), undefined] : [(pageOrLocator as Locator).page() as PageEx, pageOrLocator as LocatorEx]; const screenshotOptions = { animations: config?.animations ?? 'disabled', - _fonts: config?.fonts ?? 'ready', + fonts: process.env.PLAYWRIGHT_EXPERIMENTAL_FEATURES ? (config?.fonts ?? 'ready') : undefined, scale: config?.scale ?? 'css', caret: config?.caret ?? 'hide', ...helper.allOptions, diff --git a/packages/playwright-test/types/test.d.ts b/packages/playwright-test/types/test.d.ts index ccb922c017..c535dc8515 100644 --- a/packages/playwright-test/types/test.d.ts +++ b/packages/playwright-test/types/test.d.ts @@ -16,6 +16,7 @@ */ import type { APIRequestContext, Browser, BrowserContext, BrowserContextOptions, Page, LaunchOptions, ViewportSize, Geolocation, HTTPCredentials, Locator, APIResponse } from 'playwright-core'; +export * from 'playwright-core'; export type ReporterDescription = ['dot'] | @@ -2917,7 +2918,7 @@ type MakeMatchers = BaseMatchers & { ExtraMatchers & ExtraMatchers; -export declare type Expect = { +export type Expect = { (actual: T, messageOrOptions?: string | { message?: string }): MakeMatchers; soft: (actual: T, messageOrOptions?: string | { message?: string }) => MakeMatchers; poll: (actual: () => T | Promise, messageOrOptions?: string | { message?: string, timeout?: number }) => BaseMatchers, T> & { @@ -2996,12 +2997,14 @@ type SupportedExpectProperties = 'toThrow' | 'toThrowError' +// --- BEGINGLOBAL --- declare global { export namespace PlaywrightTest { export interface Matchers { } } } +// --- ENDGLOBAL --- /** * These tests are executed in Playwright environment that launches the browser diff --git a/packages/playwright-test/types/testReporter.d.ts b/packages/playwright-test/types/testReporter.d.ts index 57c16ad5fc..1c0e2e58fd 100644 --- a/packages/playwright-test/types/testReporter.d.ts +++ b/packages/playwright-test/types/testReporter.d.ts @@ -15,8 +15,8 @@ * limitations under the License. */ -import type { FullConfig, FullProject, TestStatus, TestError } from './test'; -export type { FullConfig, TestStatus, TestError } from './test'; +import type { FullConfig, FullProject, TestStatus, TestError } from '@playwright/test'; +export type { FullConfig, TestStatus, TestError } from '@playwright/test'; /** * `Suite` is a group of tests. All tests in Playwright Test form the following hierarchy: diff --git a/tests/config/commonFixtures.ts b/tests/config/commonFixtures.ts index e74a9cc6dd..90828a6aa2 100644 --- a/tests/config/commonFixtures.ts +++ b/tests/config/commonFixtures.ts @@ -14,6 +14,9 @@ * limitations under the License. */ +// eslint-disable-next-line spaced-comment +/// + import type { Fixtures } from '@playwright/test'; import type { ChildProcess } from 'child_process'; import { execSync, spawn } from 'child_process'; diff --git a/tests/config/experimental.d.ts b/tests/config/experimental.d.ts new file mode 100644 index 0000000000..13ee71086b --- /dev/null +++ b/tests/config/experimental.d.ts @@ -0,0 +1,20281 @@ +// This file is generated by /utils/generate_types/index.js +declare module 'playwright-core' { +// 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 { Protocol } from 'playwright-core/types/protocol'; +import { ChildProcess } from 'child_process'; +import { EventEmitter } from 'events'; +import { Readable } from 'stream'; +import { ReadStream } from 'fs'; +import { Serializable, EvaluationArgument, PageFunction, PageFunctionOn, SmartHandle, ElementHandleForTag, BindingSource } from 'playwright-core/types/structs'; + +type PageWaitForSelectorOptionsNotHidden = PageWaitForSelectorOptions & { + state?: 'visible'|'attached'; +}; +type ElementHandleWaitForSelectorOptionsNotHidden = ElementHandleWaitForSelectorOptions & { + state?: 'visible'|'attached'; +}; + +/** + * - extends: [EventEmitter] + * + * Page provides methods to interact with a single tab in a [Browser], or an + * [extension background page](https://developer.chrome.com/extensions/background_pages) in Chromium. One [Browser] + * instance might have multiple [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` 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`. + * + * Passing argument to `pageFunction`: + * + * ```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] 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(); + * ``` + * + * Shortcut for main frame's + * [frame.evaluate(pageFunction[, arg])](https://playwright.dev/docs/api/class-frame#frame-evaluate). + * @param pageFunction Function to be evaluated in the page context. + * @param arg Optional argument to pass to `pageFunction`. + */ + evaluate(pageFunction: PageFunction, arg: Arg): Promise; + /** + * Returns the value of the `pageFunction` 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`. + * + * Passing argument to `pageFunction`: + * + * ```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] 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(); + * ``` + * + * Shortcut for main frame's + * [frame.evaluate(pageFunction[, arg])](https://playwright.dev/docs/api/class-frame#frame-evaluate). + * @param pageFunction Function to be evaluated in the page context. + * @param arg Optional argument to pass to `pageFunction`. + */ + evaluate(pageFunction: PageFunction, arg?: any): Promise; + + /** + * Returns the value of the `pageFunction` invocation as a [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]. + * + * 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. + * + * ```js + * const aWindowHandle = await page.evaluateHandle(() => Promise.resolve(window)); + * aWindowHandle; // Handle for the window object. + * ``` + * + * A string can also be passed in instead of a function: + * + * ```js + * const aHandle = await page.evaluateHandle('document'); // Handle for the 'document' + * ``` + * + * [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`. + */ + evaluateHandle(pageFunction: PageFunction, arg: Arg): Promise>; + /** + * Returns the value of the `pageFunction` invocation as a [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]. + * + * 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. + * + * ```js + * const aWindowHandle = await page.evaluateHandle(() => Promise.resolve(window)); + * aWindowHandle; // Handle for the window object. + * ``` + * + * A string can also be passed in instead of a function: + * + * ```js + * const aHandle = await page.evaluateHandle('document'); // Handle for the 'document' + * ``` + * + * [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`. + */ + evaluateHandle(pageFunction: PageFunction, arg?: any): Promise>; + + /** + * > NOTE: The use of [ElementHandle] is discouraged, use [Locator] objects and web-first assertions instead. + * + * 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). + * + * Shortcut for main frame's + * [frame.$(selector[, options])](https://playwright.dev/docs/api/class-frame#frame-query-selector). + * @param selector A selector to query for. See [working with selectors](https://playwright.dev/docs/selectors) for more details. + * @param options + */ + $(selector: K, options?: { strict: boolean }): Promise | null>; + /** + * > NOTE: The use of [ElementHandle] is discouraged, use [Locator] objects and web-first assertions instead. + * + * 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). + * + * Shortcut for main frame's + * [frame.$(selector[, options])](https://playwright.dev/docs/api/class-frame#frame-query-selector). + * @param selector A selector to query for. See [working with selectors](https://playwright.dev/docs/selectors) for more details. + * @param options + */ + $(selector: string, options?: { strict: boolean }): Promise | null>; + + /** + * > NOTE: The use of [ElementHandle] is discouraged, use [Locator] objects and web-first assertions instead. + * + * The method finds all elements matching the specified selector within the page. If no elements match the selector, the + * return value resolves to `[]`. + * + * Shortcut for main frame's [frame.$$(selector)](https://playwright.dev/docs/api/class-frame#frame-query-selector-all). + * @param selector A selector to query for. See [working with selectors](https://playwright.dev/docs/selectors) for more details. + */ + $$(selector: K): Promise[]>; + /** + * > NOTE: The use of [ElementHandle] is discouraged, use [Locator] objects and web-first assertions instead. + * + * The method finds all elements matching the specified selector within the page. If no elements match the selector, the + * return value resolves to `[]`. + * + * Shortcut for main frame's [frame.$$(selector)](https://playwright.dev/docs/api/class-frame#frame-query-selector-all). + * @param selector A selector to query for. See [working with selectors](https://playwright.dev/docs/selectors) for more details. + */ + $$(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] 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`. If no elements match the selector, the method throws an error. Returns the value of `pageFunction`. + * + * If `pageFunction` 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. + * + * Examples: + * + * ```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); + * ``` + * + * Shortcut for main frame's + * [frame.$eval(selector, pageFunction[, arg, options])](https://playwright.dev/docs/api/class-frame#frame-eval-on-selector). + * @param selector A selector to query for. See [working with selectors](https://playwright.dev/docs/selectors) for more details. + * @param pageFunction Function to be evaluated in the page context. + * @param arg Optional argument to pass to `pageFunction`. + * @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] 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`. If no elements match the selector, the method throws an error. Returns the value of `pageFunction`. + * + * If `pageFunction` 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. + * + * Examples: + * + * ```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); + * ``` + * + * Shortcut for main frame's + * [frame.$eval(selector, pageFunction[, arg, options])](https://playwright.dev/docs/api/class-frame#frame-eval-on-selector). + * @param selector A selector to query for. See [working with selectors](https://playwright.dev/docs/selectors) for more details. + * @param pageFunction Function to be evaluated in the page context. + * @param arg Optional argument to pass to `pageFunction`. + * @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] 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`. If no elements match the selector, the method throws an error. Returns the value of `pageFunction`. + * + * If `pageFunction` 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. + * + * Examples: + * + * ```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); + * ``` + * + * Shortcut for main frame's + * [frame.$eval(selector, pageFunction[, arg, options])](https://playwright.dev/docs/api/class-frame#frame-eval-on-selector). + * @param selector A selector to query for. See [working with selectors](https://playwright.dev/docs/selectors) for more details. + * @param pageFunction Function to be evaluated in the page context. + * @param arg Optional argument to pass to `pageFunction`. + * @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] 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`. If no elements match the selector, the method throws an error. Returns the value of `pageFunction`. + * + * If `pageFunction` 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. + * + * Examples: + * + * ```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); + * ``` + * + * Shortcut for main frame's + * [frame.$eval(selector, pageFunction[, arg, options])](https://playwright.dev/docs/api/class-frame#frame-eval-on-selector). + * @param selector A selector to query for. See [working with selectors](https://playwright.dev/docs/selectors) for more details. + * @param pageFunction Function to be evaluated in the page context. + * @param arg Optional argument to pass to `pageFunction`. + * @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] 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`. Returns the result of `pageFunction` invocation. + * + * If `pageFunction` 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. + * + * Examples: + * + * ```js + * const divCounts = await page.$$eval('div', (divs, min) => divs.length >= min, 10); + * ``` + * + * @param selector A selector to query for. See [working with selectors](https://playwright.dev/docs/selectors) for more details. + * @param pageFunction Function to be evaluated in the page context. + * @param arg Optional argument to pass to `pageFunction`. + */ + $$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] 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`. Returns the result of `pageFunction` invocation. + * + * If `pageFunction` 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. + * + * Examples: + * + * ```js + * const divCounts = await page.$$eval('div', (divs, min) => divs.length >= min, 10); + * ``` + * + * @param selector A selector to query for. See [working with selectors](https://playwright.dev/docs/selectors) for more details. + * @param pageFunction Function to be evaluated in the page context. + * @param arg Optional argument to pass to `pageFunction`. + */ + $$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] 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`. Returns the result of `pageFunction` invocation. + * + * If `pageFunction` 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. + * + * Examples: + * + * ```js + * const divCounts = await page.$$eval('div', (divs, min) => divs.length >= min, 10); + * ``` + * + * @param selector A selector to query for. See [working with selectors](https://playwright.dev/docs/selectors) for more details. + * @param pageFunction Function to be evaluated in the page context. + * @param arg Optional argument to pass to `pageFunction`. + */ + $$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] 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`. Returns the result of `pageFunction` invocation. + * + * If `pageFunction` 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. + * + * Examples: + * + * ```js + * const divCounts = await page.$$eval('div', (divs, min) => divs.length >= min, 10); + * ``` + * + * @param selector A selector to query for. See [working with selectors](https://playwright.dev/docs/selectors) for more details. + * @param pageFunction Function to be evaluated in the page context. + * @param arg Optional argument to pass to `pageFunction`. + */ + $$eval(selector: string, pageFunction: PageFunctionOn, arg?: any): Promise; + + /** + * Returns when the `pageFunction` returns a truthy value. It resolves to a JSHandle of the truthy value. + * + * 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); + * ``` + * + * Shortcut for main frame's + * [frame.waitForFunction(pageFunction[, arg, options])](https://playwright.dev/docs/api/class-frame#frame-wait-for-function). + * @param pageFunction Function to be evaluated in the page context. + * @param arg Optional argument to pass to `pageFunction`. + * @param options + */ + waitForFunction(pageFunction: PageFunction, arg: Arg, options?: PageWaitForFunctionOptions): Promise>; + /** + * Returns when the `pageFunction` returns a truthy value. It resolves to a JSHandle of the truthy value. + * + * 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); + * ``` + * + * Shortcut for main frame's + * [frame.waitForFunction(pageFunction[, arg, options])](https://playwright.dev/docs/api/class-frame#frame-wait-for-function). + * @param pageFunction Function to be evaluated in the page context. + * @param arg Optional argument to pass to `pageFunction`. + * @param options + */ + waitForFunction(pageFunction: PageFunction, arg?: any, options?: PageWaitForFunctionOptions): Promise>; + + /** + * Returns when element specified by selector satisfies `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] objects and + * web-first assertions make the code wait-for-selector-free. + * + * Wait for the `selector` to satisfy `state` option (either appear/disappear from dom, or become visible/hidden). If at + * the moment of calling the method `selector` already satisfies the condition, the method will return immediately. If the + * selector doesn't satisfy the condition for the `timeout` milliseconds, the function will throw. + * + * 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 (let 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. See [working with selectors](https://playwright.dev/docs/selectors) for more details. + * @param options + */ + waitForSelector(selector: K, options?: PageWaitForSelectorOptionsNotHidden): Promise>; + /** + * Returns when element specified by selector satisfies `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] objects and + * web-first assertions make the code wait-for-selector-free. + * + * Wait for the `selector` to satisfy `state` option (either appear/disappear from dom, or become visible/hidden). If at + * the moment of calling the method `selector` already satisfies the condition, the method will return immediately. If the + * selector doesn't satisfy the condition for the `timeout` milliseconds, the function will throw. + * + * 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 (let 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. See [working with selectors](https://playwright.dev/docs/selectors) for more details. + * @param options + */ + waitForSelector(selector: string, options?: PageWaitForSelectorOptionsNotHidden): Promise>; + /** + * Returns when element specified by selector satisfies `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] objects and + * web-first assertions make the code wait-for-selector-free. + * + * Wait for the `selector` to satisfy `state` option (either appear/disappear from dom, or become visible/hidden). If at + * the moment of calling the method `selector` already satisfies the condition, the method will return immediately. If the + * selector doesn't satisfy the condition for the `timeout` milliseconds, the function will throw. + * + * 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 (let 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. See [working with selectors](https://playwright.dev/docs/selectors) for more details. + * @param options + */ + waitForSelector(selector: K, options: PageWaitForSelectorOptions): Promise | null>; + /** + * Returns when element specified by selector satisfies `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] objects and + * web-first assertions make the code wait-for-selector-free. + * + * Wait for the `selector` to satisfy `state` option (either appear/disappear from dom, or become visible/hidden). If at + * the moment of calling the method `selector` already satisfies the condition, the method will return immediately. If the + * selector doesn't satisfy the condition for the `timeout` milliseconds, the function will throw. + * + * 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 (let 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. See [working with selectors](https://playwright.dev/docs/selectors) for more details. + * @param options + */ + waitForSelector(selector: string, options: PageWaitForSelectorOptions): Promise>; + + /** + * The method adds a function called `name` on the `window` object of every frame in this page. When called, the function + * executes `callback` and returns a [Promise] which resolves to the return value of `callback`. If the `callback` returns + * a [Promise], it will be awaited. + * + * The first argument of the `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. + * + * 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'); + * })(); + * ``` + * + * An example of passing an element handle: + * + * ```js + * await page.exposeBinding('clicked', async (source, element) => { + * console.log(await element.textContent()); + * }, { handle: true }); + * await page.setContent(` + * + *
Click me
+ *
Or click me
+ * `); + * ``` + * + * @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` on the `window` object of every frame in this page. When called, the function + * executes `callback` and returns a [Promise] which resolves to the return value of `callback`. If the `callback` returns + * a [Promise], it will be awaited. + * + * The first argument of the `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. + * + * 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'); + * })(); + * ``` + * + * An example of passing an element handle: + * + * ```js + * await page.exposeBinding('clicked', async (source, element) => { + * console.log(await element.textContent()); + * }, { handle: true }); + * await page.setContent(` + * + *
Click me
+ *
Or click me
+ * `); + * ``` + * + * @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; + /** + * Emitted when the page closes. + */ + on(event: 'close', listener: (page: Page) => void): this; + + /** + * Emitted when JavaScript within the page calls one of console API methods, e.g. `console.log` or `console.dir`. Also + * emitted if the page throws an error or a warning. + * + * The arguments passed into `console.log` appear as arguments on the event handler. + * + * An example of handling `console` event: + * + * ```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) => void): 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) => void): 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. + * + * ```js + * page.on('dialog', dialog => { + * dialog.accept(); + * }); + * ``` + * + * > NOTE: When no [page.on('dialog')](https://playwright.dev/docs/api/class-page#page-event-dialog) listeners are present, + * all dialogs are automatically dismissed. + */ + on(event: 'dialog', listener: (dialog: Dialog) => void): 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) => void): this; + + /** + * Emitted when attachment download started. User can access basic file operations on downloaded content via the passed + * [Download] instance. + */ + on(event: 'download', listener: (download: Download) => void): 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('/tmp/myfile.pdf'); + * }); + * ``` + * + */ + on(event: 'filechooser', listener: (fileChooser: FileChooser) => void): this; + + /** + * Emitted when a frame is attached. + */ + on(event: 'frameattached', listener: (frame: Frame) => void): this; + + /** + * Emitted when a frame is detached. + */ + on(event: 'framedetached', listener: (frame: Frame) => void): this; + + /** + * Emitted when a frame is navigated to a new url. + */ + on(event: 'framenavigated', listener: (frame: Frame) => void): 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) => void): 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) => void): 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. + * + * ```js + * // Note that Promise.all prevents a race condition + * // between evaluating and waiting for the popup. + * const [popup] = await Promise.all([ + * // It is important to call waitForEvent first. + * page.waitForEvent('popup'), + * // Opens the popup. + * page.evaluate(() => window.open('https://example.com')), + * ]); + * 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) => void): 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) => void): 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) => void): 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) => void): 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) => void): this; + + /** + * Emitted when [WebSocket] request is sent. + */ + on(event: 'websocket', listener: (webSocket: WebSocket) => void): 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) => void): 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) => void): 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) => void): 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) => void): 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) => void): 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) => void): 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) => void): 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) => void): 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) => void): 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) => void): 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) => void): 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) => void): 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) => void): 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) => void): 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) => void): 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) => void): 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) => void): 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) => void): 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) => void): 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) => void): this; + + /** + * Emitted when the page closes. + */ + addListener(event: 'close', listener: (page: Page) => void): this; + + /** + * Emitted when JavaScript within the page calls one of console API methods, e.g. `console.log` or `console.dir`. Also + * emitted if the page throws an error or a warning. + * + * The arguments passed into `console.log` appear as arguments on the event handler. + * + * An example of handling `console` event: + * + * ```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) => void): 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) => void): 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. + * + * ```js + * page.on('dialog', dialog => { + * dialog.accept(); + * }); + * ``` + * + * > NOTE: When no [page.on('dialog')](https://playwright.dev/docs/api/class-page#page-event-dialog) listeners are present, + * all dialogs are automatically dismissed. + */ + addListener(event: 'dialog', listener: (dialog: Dialog) => void): 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) => void): this; + + /** + * Emitted when attachment download started. User can access basic file operations on downloaded content via the passed + * [Download] instance. + */ + addListener(event: 'download', listener: (download: Download) => void): 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('/tmp/myfile.pdf'); + * }); + * ``` + * + */ + addListener(event: 'filechooser', listener: (fileChooser: FileChooser) => void): this; + + /** + * Emitted when a frame is attached. + */ + addListener(event: 'frameattached', listener: (frame: Frame) => void): this; + + /** + * Emitted when a frame is detached. + */ + addListener(event: 'framedetached', listener: (frame: Frame) => void): this; + + /** + * Emitted when a frame is navigated to a new url. + */ + addListener(event: 'framenavigated', listener: (frame: Frame) => void): 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) => void): 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) => void): 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. + * + * ```js + * // Note that Promise.all prevents a race condition + * // between evaluating and waiting for the popup. + * const [popup] = await Promise.all([ + * // It is important to call waitForEvent first. + * page.waitForEvent('popup'), + * // Opens the popup. + * page.evaluate(() => window.open('https://example.com')), + * ]); + * 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) => void): 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) => void): 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) => void): 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) => void): 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) => void): this; + + /** + * Emitted when [WebSocket] request is sent. + */ + addListener(event: 'websocket', listener: (webSocket: WebSocket) => void): 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) => void): this; + + /** + * Removes an event listener added by `on` or `addListener`. + */ + removeListener(event: 'close', listener: (page: Page) => void): this; + + /** + * Removes an event listener added by `on` or `addListener`. + */ + removeListener(event: 'console', listener: (consoleMessage: ConsoleMessage) => void): this; + + /** + * Removes an event listener added by `on` or `addListener`. + */ + removeListener(event: 'crash', listener: (page: Page) => void): this; + + /** + * Removes an event listener added by `on` or `addListener`. + */ + removeListener(event: 'dialog', listener: (dialog: Dialog) => void): this; + + /** + * Removes an event listener added by `on` or `addListener`. + */ + removeListener(event: 'domcontentloaded', listener: (page: Page) => void): this; + + /** + * Removes an event listener added by `on` or `addListener`. + */ + removeListener(event: 'download', listener: (download: Download) => void): this; + + /** + * Removes an event listener added by `on` or `addListener`. + */ + removeListener(event: 'filechooser', listener: (fileChooser: FileChooser) => void): this; + + /** + * Removes an event listener added by `on` or `addListener`. + */ + removeListener(event: 'frameattached', listener: (frame: Frame) => void): this; + + /** + * Removes an event listener added by `on` or `addListener`. + */ + removeListener(event: 'framedetached', listener: (frame: Frame) => void): this; + + /** + * Removes an event listener added by `on` or `addListener`. + */ + removeListener(event: 'framenavigated', listener: (frame: Frame) => void): this; + + /** + * Removes an event listener added by `on` or `addListener`. + */ + removeListener(event: 'load', listener: (page: Page) => void): this; + + /** + * Removes an event listener added by `on` or `addListener`. + */ + removeListener(event: 'pageerror', listener: (error: Error) => void): this; + + /** + * Removes an event listener added by `on` or `addListener`. + */ + removeListener(event: 'popup', listener: (page: Page) => void): this; + + /** + * Removes an event listener added by `on` or `addListener`. + */ + removeListener(event: 'request', listener: (request: Request) => void): this; + + /** + * Removes an event listener added by `on` or `addListener`. + */ + removeListener(event: 'requestfailed', listener: (request: Request) => void): this; + + /** + * Removes an event listener added by `on` or `addListener`. + */ + removeListener(event: 'requestfinished', listener: (request: Request) => void): this; + + /** + * Removes an event listener added by `on` or `addListener`. + */ + removeListener(event: 'response', listener: (response: Response) => void): this; + + /** + * Removes an event listener added by `on` or `addListener`. + */ + removeListener(event: 'websocket', listener: (webSocket: WebSocket) => void): this; + + /** + * Removes an event listener added by `on` or `addListener`. + */ + removeListener(event: 'worker', listener: (worker: Worker) => void): this; + + /** + * Removes an event listener added by `on` or `addListener`. + */ + off(event: 'close', listener: (page: Page) => void): this; + + /** + * Removes an event listener added by `on` or `addListener`. + */ + off(event: 'console', listener: (consoleMessage: ConsoleMessage) => void): this; + + /** + * Removes an event listener added by `on` or `addListener`. + */ + off(event: 'crash', listener: (page: Page) => void): this; + + /** + * Removes an event listener added by `on` or `addListener`. + */ + off(event: 'dialog', listener: (dialog: Dialog) => void): this; + + /** + * Removes an event listener added by `on` or `addListener`. + */ + off(event: 'domcontentloaded', listener: (page: Page) => void): this; + + /** + * Removes an event listener added by `on` or `addListener`. + */ + off(event: 'download', listener: (download: Download) => void): this; + + /** + * Removes an event listener added by `on` or `addListener`. + */ + off(event: 'filechooser', listener: (fileChooser: FileChooser) => void): this; + + /** + * Removes an event listener added by `on` or `addListener`. + */ + off(event: 'frameattached', listener: (frame: Frame) => void): this; + + /** + * Removes an event listener added by `on` or `addListener`. + */ + off(event: 'framedetached', listener: (frame: Frame) => void): this; + + /** + * Removes an event listener added by `on` or `addListener`. + */ + off(event: 'framenavigated', listener: (frame: Frame) => void): this; + + /** + * Removes an event listener added by `on` or `addListener`. + */ + off(event: 'load', listener: (page: Page) => void): this; + + /** + * Removes an event listener added by `on` or `addListener`. + */ + off(event: 'pageerror', listener: (error: Error) => void): this; + + /** + * Removes an event listener added by `on` or `addListener`. + */ + off(event: 'popup', listener: (page: Page) => void): this; + + /** + * Removes an event listener added by `on` or `addListener`. + */ + off(event: 'request', listener: (request: Request) => void): this; + + /** + * Removes an event listener added by `on` or `addListener`. + */ + off(event: 'requestfailed', listener: (request: Request) => void): this; + + /** + * Removes an event listener added by `on` or `addListener`. + */ + off(event: 'requestfinished', listener: (request: Request) => void): this; + + /** + * Removes an event listener added by `on` or `addListener`. + */ + off(event: 'response', listener: (response: Response) => void): this; + + /** + * Removes an event listener added by `on` or `addListener`. + */ + off(event: 'websocket', listener: (webSocket: WebSocket) => void): this; + + /** + * Removes an event listener added by `on` or `addListener`. + */ + off(event: 'worker', listener: (worker: Worker) => void): this; + + accessibility: Accessibility; + + /** + * 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`. + * + * An example of overriding `Math.random` before the page loads: + * + * ```js browser + * // 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' }); + * ``` + * + * > 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` (only supported when passing a function). + */ + addInitScript(script: Function|string|{ + /** + * Path to the JavaScript file. If `path` is a relative path, then it is resolved relative to the current working + * directory. Optional. + */ + path?: string; + + /** + * Raw script content. Optional. + */ + content?: string; + }, arg?: Serializable): 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; + + /** + * This method waits for an element matching `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 ``, `