diff --git a/packages/playwright-client/types/types.d.ts b/packages/playwright-client/types/types.d.ts index 637fa2b03196f..10fe15bf27f77 100644 --- a/packages/playwright-client/types/types.d.ts +++ b/packages/playwright-client/types/types.d.ts @@ -80,6 +80,7 @@ type InferZodSchema = T extends z3.ZodTypeAny ? z3.infer * page.removeListener('request', logRequest); * ``` * + * @since v1.8 */ export interface Page { /** @@ -128,6 +129,7 @@ export interface Page { * await bodyHandle.dispose(); * ``` * + * @since v1.8 * @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). @@ -179,6 +181,7 @@ export interface Page { * await bodyHandle.dispose(); * ``` * + * @since v1.8 * @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). @@ -225,6 +228,7 @@ export interface Page { * await resultHandle.dispose(); * ``` * + * @since v1.8 * @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). @@ -270,6 +274,7 @@ export interface Page { * await resultHandle.dispose(); * ``` * + * @since v1.8 * @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). @@ -310,6 +315,7 @@ export interface Page { * and [page.addInitScript(script[, arg])](https://playwright.dev/docs/api/class-page#page-add-init-script) is not * defined. * + * @since v1.8 * @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 @@ -324,6 +330,7 @@ export interface Page { * 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). + * @since v1.9 * @param selector A selector to query for. * @param options */ @@ -335,6 +342,7 @@ export interface Page { * 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). + * @since v1.9 * @param selector A selector to query for. * @param options */ @@ -346,6 +354,7 @@ export interface Page { * * The method finds all elements matching the specified selector within the page. If no elements match the selector, * the return value resolves to `[]`. + * @since v1.9 * @param selector A selector to query for. */ $$(selector: K): Promise[]>; @@ -355,6 +364,7 @@ export interface Page { * * The method finds all elements matching the specified selector within the page. If no elements match the selector, * the return value resolves to `[]`. + * @since v1.9 * @param selector A selector to query for. */ $$(selector: string): Promise[]>; @@ -385,6 +395,7 @@ export interface Page { * const preloadHrefTS = await page.$eval('link[rel=preload]', (el: HTMLLinkElement) => el.href); * ``` * + * @since v1.9 * @param selector A selector to query for. * @param pageFunction Function to be evaluated in the page context. * @param arg Optional argument to pass to @@ -418,6 +429,7 @@ export interface Page { * const preloadHrefTS = await page.$eval('link[rel=preload]', (el: HTMLLinkElement) => el.href); * ``` * + * @since v1.9 * @param selector A selector to query for. * @param pageFunction Function to be evaluated in the page context. * @param arg Optional argument to pass to @@ -451,6 +463,7 @@ export interface Page { * const preloadHrefTS = await page.$eval('link[rel=preload]', (el: HTMLLinkElement) => el.href); * ``` * + * @since v1.9 * @param selector A selector to query for. * @param pageFunction Function to be evaluated in the page context. * @param arg Optional argument to pass to @@ -484,6 +497,7 @@ export interface Page { * const preloadHrefTS = await page.$eval('link[rel=preload]', (el: HTMLLinkElement) => el.href); * ``` * + * @since v1.9 * @param selector A selector to query for. * @param pageFunction Function to be evaluated in the page context. * @param arg Optional argument to pass to @@ -516,6 +530,7 @@ export interface Page { * const divCounts = await page.$$eval('div', (divs, min) => divs.length >= min, 10); * ``` * + * @since v1.9 * @param selector A selector to query for. * @param pageFunction Function to be evaluated in the page context. * @param arg Optional argument to pass to @@ -546,6 +561,7 @@ export interface Page { * const divCounts = await page.$$eval('div', (divs, min) => divs.length >= min, 10); * ``` * + * @since v1.9 * @param selector A selector to query for. * @param pageFunction Function to be evaluated in the page context. * @param arg Optional argument to pass to @@ -576,6 +592,7 @@ export interface Page { * const divCounts = await page.$$eval('div', (divs, min) => divs.length >= min, 10); * ``` * + * @since v1.9 * @param selector A selector to query for. * @param pageFunction Function to be evaluated in the page context. * @param arg Optional argument to pass to @@ -606,6 +623,7 @@ export interface Page { * const divCounts = await page.$$eval('div', (divs, min) => divs.length >= min, 10); * ``` * + * @since v1.9 * @param selector A selector to query for. * @param pageFunction Function to be evaluated in the page context. * @param arg Optional argument to pass to @@ -646,6 +664,7 @@ export interface Page { * await page.waitForFunction(selector => !!document.querySelector(selector), selector); * ``` * + * @since v1.8 * @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). @@ -685,6 +704,7 @@ export interface Page { * await page.waitForFunction(selector => !!document.querySelector(selector), selector); * ``` * + * @since v1.8 * @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). @@ -732,6 +752,7 @@ export interface Page { * })(); * ``` * + * @since v1.8 * @param selector A selector to query for. * @param options */ @@ -776,6 +797,7 @@ export interface Page { * })(); * ``` * + * @since v1.8 * @param selector A selector to query for. * @param options */ @@ -820,6 +842,7 @@ export interface Page { * })(); * ``` * + * @since v1.8 * @param selector A selector to query for. * @param options */ @@ -864,6 +887,7 @@ export interface Page { * })(); * ``` * + * @since v1.8 * @param selector A selector to query for. * @param options */ @@ -916,6 +940,7 @@ export interface Page { * })(); * ``` * + * @since v1.8 * @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 @@ -968,6 +993,7 @@ export interface Page { * })(); * ``` * + * @since v1.8 * @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 @@ -991,6 +1017,7 @@ export interface Page { * await page.removeAllListeners('request', { behavior: 'wait' }); * ``` * + * @since v1.47 * @param type * @param options */ @@ -1012,6 +1039,7 @@ export interface Page { * await page.removeAllListeners('request', { behavior: 'wait' }); * ``` * + * @since v1.47 * @param type * @param options */ @@ -2027,6 +2055,7 @@ export interface Page { * }, { times: 1 }); * ``` * + * @since v1.42 * @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 @@ -2038,11 +2067,13 @@ export interface Page { * 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. + * @since v1.44 */ noWaitAfter?: boolean; /** * Specifies the maximum number of times this handler should be called. Unlimited by default. + * @since v1.44 */ times?: number; }): Promise; @@ -2050,28 +2081,33 @@ export interface Page { /** * Adds a `'); * ``` * + * @since v1.38 */ export interface WebError { /** * Unhandled error that was thrown. + * @since v1.38 */ error(): Error; /** * The page that produced this unhandled exception, if any. + * @since v1.38 */ page(): null|Page; } @@ -22202,6 +24625,7 @@ export interface WebError { * * If you want to intercept or modify WebSocket frames, consider using * [WebSocketRoute](https://playwright.dev/docs/api/class-websocketroute). + * @since v1.8 */ export interface WebSocket { /** @@ -22215,6 +24639,7 @@ export interface WebSocket { on(event: 'framereceived', listener: (data: { /** * frame payload + * @since v1.9 */ payload: string|Buffer; }) => any): this; @@ -22225,6 +24650,7 @@ export interface WebSocket { on(event: 'framesent', listener: (data: { /** * frame payload + * @since v1.9 */ payload: string|Buffer; }) => any): this; @@ -22245,6 +24671,7 @@ export interface WebSocket { once(event: 'framereceived', listener: (data: { /** * frame payload + * @since v1.9 */ payload: string|Buffer; }) => any): this; @@ -22255,6 +24682,7 @@ export interface WebSocket { once(event: 'framesent', listener: (data: { /** * frame payload + * @since v1.9 */ payload: string|Buffer; }) => any): this; @@ -22275,6 +24703,7 @@ export interface WebSocket { addListener(event: 'framereceived', listener: (data: { /** * frame payload + * @since v1.9 */ payload: string|Buffer; }) => any): this; @@ -22285,6 +24714,7 @@ export interface WebSocket { addListener(event: 'framesent', listener: (data: { /** * frame payload + * @since v1.9 */ payload: string|Buffer; }) => any): this; @@ -22305,6 +24735,7 @@ export interface WebSocket { removeListener(event: 'framereceived', listener: (data: { /** * frame payload + * @since v1.9 */ payload: string|Buffer; }) => any): this; @@ -22315,6 +24746,7 @@ export interface WebSocket { removeListener(event: 'framesent', listener: (data: { /** * frame payload + * @since v1.9 */ payload: string|Buffer; }) => any): this; @@ -22335,6 +24767,7 @@ export interface WebSocket { off(event: 'framereceived', listener: (data: { /** * frame payload + * @since v1.9 */ payload: string|Buffer; }) => any): this; @@ -22345,6 +24778,7 @@ export interface WebSocket { off(event: 'framesent', listener: (data: { /** * frame payload + * @since v1.9 */ payload: string|Buffer; }) => any): this; @@ -22365,6 +24799,7 @@ export interface WebSocket { prependListener(event: 'framereceived', listener: (data: { /** * frame payload + * @since v1.9 */ payload: string|Buffer; }) => any): this; @@ -22375,6 +24810,7 @@ export interface WebSocket { prependListener(event: 'framesent', listener: (data: { /** * frame payload + * @since v1.9 */ payload: string|Buffer; }) => any): this; @@ -22386,11 +24822,13 @@ export interface WebSocket { /** * Indicates that the web socket has been closed. + * @since v1.8 */ isClosed(): boolean; /** * Contains the URL of the WebSocket. + * @since v1.8 */ url(): string; @@ -22405,16 +24843,19 @@ export interface WebSocket { waitForEvent(event: 'framereceived', optionsOrPredicate?: { predicate?: (data: { /** * frame payload + * @since v1.9 */ payload: string|Buffer; }) => boolean | Promise, timeout?: number } | ((data: { /** * frame payload + * @since v1.9 */ payload: string|Buffer; }) => boolean | Promise)): Promise<{ /** * frame payload + * @since v1.9 */ payload: string|Buffer; }>; @@ -22425,16 +24866,19 @@ export interface WebSocket { waitForEvent(event: 'framesent', optionsOrPredicate?: { predicate?: (data: { /** * frame payload + * @since v1.9 */ payload: string|Buffer; }) => boolean | Promise, timeout?: number } | ((data: { /** * frame payload + * @since v1.9 */ payload: string|Buffer; }) => boolean | Promise)): Promise<{ /** * frame payload + * @since v1.9 */ payload: string|Buffer; }>; @@ -22452,6 +24896,7 @@ export interface LaunchOptions { * * Additional arguments to pass to the browser instance. The list of Chromium flags can be found * [here](https://peter.sh/experiments/chromium-command-line-switches/). + * @since v1.8 */ args?: Array; @@ -22459,6 +24904,7 @@ export interface LaunchOptions { * If specified, artifacts (traces, videos, downloads, HAR files, etc.) are saved into this directory. The directory * is not cleaned up when the browser closes. If not specified, a temporary directory is used and cleaned up when the * browser closes. + * @since v1.8 */ artifactsDir?: string; @@ -22469,11 +24915,13 @@ export interface LaunchOptions { * * Use "chrome", "chrome-beta", "chrome-dev", "chrome-canary", "msedge", "msedge-beta", "msedge-dev", or * "msedge-canary" to use branded [Google Chrome and Microsoft Edge](https://playwright.dev/docs/browsers#google-chrome--microsoft-edge). + * @since v1.8 */ channel?: string; /** * Enable Chromium sandboxing. Defaults to `false`. + * @since v1.8 */ chromiumSandbox?: boolean; @@ -22481,9 +24929,13 @@ export interface LaunchOptions { * If specified, accepted downloads are downloaded into this directory. Otherwise, temporary directory is created and * is deleted when browser is closed. In either case, the downloads are deleted when the browser context they were * created in is closed. + * @since v1.8 */ downloadsPath?: string; + /** + * @since v1.8 + */ env?: { [key: string]: string|undefined; }; /** @@ -22491,6 +24943,7 @@ export interface LaunchOptions { * [`executablePath`](https://playwright.dev/docs/api/class-browsertype#browser-type-launch-option-executable-path) is * a relative path, then it is resolved relative to the current working directory. Note that Playwright only works * with the bundled Chromium, Firefox or WebKit, use at your own risk. + * @since v1.8 */ executablePath?: string; @@ -22500,21 +24953,25 @@ export interface LaunchOptions { * * You can also provide a path to a custom [`policies.json` file](https://mozilla.github.io/policy-templates/) via * `PLAYWRIGHT_FIREFOX_POLICIES_JSON` environment variable. + * @since v1.8 */ firefoxUserPrefs?: { [key: string]: string|number|boolean; }; /** * Close the browser process on SIGHUP. Defaults to `true`. + * @since v1.8 */ handleSIGHUP?: boolean; /** * Close the browser process on Ctrl-C. Defaults to `true`. + * @since v1.8 */ handleSIGINT?: boolean; /** * Close the browser process on SIGTERM. Defaults to `true`. + * @since v1.8 */ handleSIGTERM?: boolean; @@ -22522,6 +24979,7 @@ export interface LaunchOptions { * Whether to run browser in headless mode. More details for * [Chromium](https://developers.google.com/web/updates/2017/04/headless-chrome) and * [Firefox](https://hacks.mozilla.org/2017/12/using-headless-mode-in-firefox/). Defaults to `true`. + * @since v1.8 */ headless?: boolean; @@ -22529,37 +24987,44 @@ export interface LaunchOptions { * If `true`, Playwright does not pass its own configurations args and only uses the ones from * [`args`](https://playwright.dev/docs/api/class-browsertype#browser-type-launch-option-args). If an array is given, * then filters out the given default arguments. Dangerous option; use with care. Defaults to `false`. + * @since v1.8 */ ignoreDefaultArgs?: boolean|Array; /** * Logger sink for Playwright logging. * @deprecated The logs received by the logger are incomplete. Please use tracing instead. + * @since v1.8 */ logger?: Logger; /** * Network proxy settings. + * @since v1.8 */ proxy?: { /** * Proxy to be used for all requests. HTTP and SOCKS proxies are supported, for example `http://myproxy.com:3128` or * `socks5://myproxy.com:3128`. Short form `myproxy.com:3128` is considered an HTTP proxy. + * @since v1.8 */ server: string; /** * Optional comma-separated domains to bypass proxy, for example `".com, chromium.org, .domain.com"`. + * @since v1.8 */ bypass?: string; /** * Optional username to use if HTTP proxy requires authentication. + * @since v1.8 */ username?: string; /** * Optional password to use if HTTP proxy requires authentication. + * @since v1.8 */ password?: string; }; @@ -22567,17 +25032,20 @@ export interface LaunchOptions { /** * Slows down Playwright operations by the specified amount of milliseconds. Useful so that you can see what is going * on. + * @since v1.8 */ slowMo?: number; /** * Maximum time in milliseconds to wait for the browser instance to start. Defaults to `30000` (30 seconds). Pass `0` * to disable timeout. + * @since v1.8 */ timeout?: number; /** * If specified, traces are saved into this directory. + * @since v1.8 */ tracesDir?: string; } @@ -22585,35 +25053,41 @@ export interface LaunchOptions { export interface ConnectOverCDPOptions { /** * @deprecated Use the first argument instead. + * @since v1.14 */ endpointURL?: string; /** * Additional HTTP headers to be sent with connect request. Optional. + * @since v1.11 */ headers?: { [key: string]: string; }; /** * Tells Playwright that it runs on the same host as the CDP server. It will enable certain optimizations that rely * upon the file system being the same between Playwright and the Browser. + * @since v1.58 */ isLocal?: boolean; /** * Logger sink for Playwright logging. Optional. * @deprecated The logs received by the logger are incomplete. Please use tracing instead. + * @since v1.14 */ logger?: Logger; /** * Slows down Playwright operations by the specified amount of milliseconds. Useful so that you can see what is going * on. Defaults to 0. + * @since v1.11 */ slowMo?: number; /** * Maximum time in milliseconds to wait for the connection to be established. Defaults to `30000` (30 seconds). Pass * `0` to disable timeout. + * @since v1.11 */ timeout?: number; } @@ -22633,28 +25107,33 @@ export interface ConnectOptions { * 1. `""` to expose localhost network. * 1. `"*.test.internal-domain,*.staging.internal-domain,"` to expose test/staging deployments and * localhost. + * @since v1.37 */ exposeNetwork?: string; /** * Additional HTTP headers to be sent with web socket connect request. Optional. + * @since v1.11 */ headers?: { [key: string]: string; }; /** * Logger sink for Playwright logging. Optional. * @deprecated The logs received by the logger are incomplete. Please use tracing instead. + * @since v1.14 */ logger?: Logger; /** * Slows down Playwright operations by the specified amount of milliseconds. Useful so that you can see what is going * on. Defaults to 0. + * @since v1.10 */ slowMo?: number; /** * Maximum time in milliseconds to wait for the connection to be established. Defaults to `0` (no timeout). + * @since v1.10 */ timeout?: number; } @@ -22667,12 +25146,14 @@ export interface LocatorScreenshotOptions { * - infinite animations are canceled to initial state, and then played over after the screenshot. * * Defaults to `"allow"` that leaves animations untouched. + * @since v1.14 */ animations?: "disabled"|"allow"; /** * When set to `"hide"`, screenshot will hide text caret. When set to `"initial"`, text caret behavior will not be * changed. Defaults to `"hide"`. + * @since v1.14 */ caret?: "hide"|"initial"; @@ -22682,18 +25163,21 @@ export interface LocatorScreenshotOptions { * [`maskColor`](https://playwright.dev/docs/api/class-locator#locator-screenshot-option-mask-color)) that completely * covers its bounding box. The mask is also applied to invisible elements, see * [Matching only visible elements](https://playwright.dev/docs/locators#matching-only-visible-elements) to disable that. + * @since v1.14 */ mask?: Array; /** * Specify the color of the overlay box for masked elements, in * [CSS color format](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value). Default color is pink `#FF00FF`. + * @since v1.35 */ maskColor?: string; /** * Hides default white background and allows capturing screenshots with transparency. Not applicable to `jpeg` images. * Defaults to `false`. + * @since v1.14 */ omitBackground?: boolean; @@ -22702,11 +25186,13 @@ export interface LocatorScreenshotOptions { * [`path`](https://playwright.dev/docs/api/class-locator#locator-screenshot-option-path) is a relative path, then it * is resolved relative to the current working directory. If no path is provided, the image won't be saved to the * disk. + * @since v1.14 */ path?: string; /** * The quality of the image, between 0-100. Not applicable to `png` images. + * @since v1.14 */ quality?: number; @@ -22716,6 +25202,7 @@ export interface LocatorScreenshotOptions { * screenshots of high-dpi devices will be twice as large or even larger. * * Defaults to `"device"`. + * @since v1.14 */ scale?: "css"|"device"; @@ -22723,6 +25210,7 @@ export interface LocatorScreenshotOptions { * Text of the stylesheet to apply while making the screenshot. This is where you can hide dynamic elements, make * elements invisible or change their properties to help you creating repeatable screenshots. This stylesheet pierces * the Shadow DOM and applies to the inner frames. + * @since v1.41 */ style?: string; @@ -22731,11 +25219,13 @@ export interface LocatorScreenshotOptions { * option in the config, or by using the * [browserContext.setDefaultTimeout(timeout)](https://playwright.dev/docs/api/class-browsercontext#browser-context-set-default-timeout) * or [page.setDefaultTimeout(timeout)](https://playwright.dev/docs/api/class-page#page-set-default-timeout) methods. + * @since v1.14 */ timeout?: number; /** * Specify screenshot type, defaults to `png`. + * @since v1.14 */ type?: "png"|"jpeg"; } @@ -22749,12 +25239,14 @@ interface ElementHandleWaitForSelectorOptions { * without any content or with `display:none` has an empty bounding box and is not considered visible. * - `'hidden'` - wait for element to be either detached from DOM, or have an empty bounding box or * `visibility:hidden`. This is opposite to the `'visible'` option. + * @since v1.8 */ state?: "attached"|"detached"|"visible"|"hidden"; /** * When true, the call requires selector to resolve to a single element. If given selector resolves to more than one * element, the call throws an exception. + * @since v1.15 */ strict?: boolean; @@ -22763,6 +25255,7 @@ interface ElementHandleWaitForSelectorOptions { * option in the config, or by using the * [browserContext.setDefaultTimeout(timeout)](https://playwright.dev/docs/api/class-browsercontext#browser-context-set-default-timeout) * or [page.setDefaultTimeout(timeout)](https://playwright.dev/docs/api/class-page#page-set-default-timeout) methods. + * @since v1.8 */ timeout?: number; } @@ -22770,6 +25263,7 @@ interface ElementHandleWaitForSelectorOptions { export interface BrowserContextOptions { /** * Whether to automatically download all the attachments. Defaults to `true` where all the downloads are accepted. + * @since v1.8 */ acceptDownloads?: boolean; @@ -22788,11 +25282,13 @@ export interface BrowserContextOptions { * `http://localhost:3000/foo/bar.html` * - baseURL: `http://localhost:3000/foo` (without trailing slash) and navigating to `./bar.html` results in * `http://localhost:3000/bar.html` + * @since v1.8 */ baseURL?: string; /** * Toggles bypassing page's Content-Security-Policy. Defaults to `false`. + * @since v1.8 */ bypassCSP?: boolean; @@ -22813,45 +25309,54 @@ export interface BrowserContextOptions { * **NOTE** When using WebKit on macOS, accessing `localhost` will not pick up client certificates. You can make it * work by replacing `localhost` with `local.playwright`. * + * @since 1.46 */ clientCertificates?: Array<{ /** * Exact origin that the certificate is valid for. Origin includes `https` protocol, a hostname and optionally a port. + * @since 1.46 */ origin: string; /** * Path to the file with the certificate in PEM format. + * @since 1.46 */ certPath?: string; /** * Direct value of the certificate in PEM format. + * @since 1.46 */ cert?: Buffer; /** * Path to the file with the private key in PEM format. + * @since 1.46 */ keyPath?: string; /** * Direct value of the private key in PEM format. + * @since 1.46 */ key?: Buffer; /** * Path to the PFX or PKCS12 encoded private key and certificate chain. + * @since 1.46 */ pfxPath?: string; /** * Direct value of the PFX or PKCS12 encoded private key and certificate chain. + * @since 1.46 */ pfx?: Buffer; /** * Passphrase for the private key (PEM or PFX). + * @since 1.46 */ passphrase?: string; }>; @@ -22861,6 +25366,7 @@ export interface BrowserContextOptions { * media feature, supported values are `'light'` and `'dark'`. See * [page.emulateMedia([options])](https://playwright.dev/docs/api/class-page#page-emulate-media) for more details. * Passing `null` resets emulation to system defaults. Defaults to `'light'`. + * @since v1.8 */ colorScheme?: null|"light"|"dark"|"no-preference"; @@ -22868,17 +25374,20 @@ export interface BrowserContextOptions { * Emulates `'prefers-contrast'` media feature, supported values are `'no-preference'`, `'more'`. See * [page.emulateMedia([options])](https://playwright.dev/docs/api/class-page#page-emulate-media) for more details. * Passing `null` resets emulation to system defaults. Defaults to `'no-preference'`. + * @since v1.8 */ contrast?: null|"no-preference"|"more"; /** * Specify device scale factor (can be thought of as dpr). Defaults to `1`. Learn more about * [emulating devices with device scale factor](https://playwright.dev/docs/emulation#devices). + * @since v1.8 */ deviceScaleFactor?: number; /** * An object containing additional HTTP headers to be sent with every request. Defaults to none. + * @since v1.8 */ extraHTTPHeaders?: { [key: string]: string; }; @@ -22886,25 +25395,32 @@ export interface BrowserContextOptions { * Emulates `'forced-colors'` media feature, supported values are `'active'`, `'none'`. See * [page.emulateMedia([options])](https://playwright.dev/docs/api/class-page#page-emulate-media) for more details. * Passing `null` resets emulation to system defaults. Defaults to `'none'`. + * @since v1.8 */ forcedColors?: null|"active"|"none"; + /** + * @since v1.8 + */ geolocation?: Geolocation; /** * Specifies if viewport supports touch events. Defaults to false. Learn more about * [mobile emulation](https://playwright.dev/docs/emulation#devices). + * @since v1.8 */ hasTouch?: boolean; /** * Credentials for [HTTP authentication](https://developer.mozilla.org/en-US/docs/Web/HTTP/Authentication). If no * origin is specified, the username and password are sent to any servers upon unauthorized responses. + * @since v1.8 */ httpCredentials?: HTTPCredentials; /** * Whether to ignore HTTPS errors when sending network requests. Defaults to `false`. + * @since v1.8 */ ignoreHTTPSErrors?: boolean; @@ -22912,12 +25428,14 @@ export interface BrowserContextOptions { * Whether the `meta viewport` tag is taken into account and touch events are enabled. isMobile is a part of device, * so you don't actually need to set it manually. Defaults to `false` and is not supported in Firefox. Learn more * about [mobile emulation](https://playwright.dev/docs/emulation#ismobile). + * @since v1.8 */ isMobile?: boolean; /** * Whether or not to enable JavaScript in the context. Defaults to `true`. Learn more about * [disabling JavaScript](https://playwright.dev/docs/emulation#javascript-enabled). + * @since v1.8 */ javaScriptEnabled?: boolean; @@ -22925,18 +25443,21 @@ export interface BrowserContextOptions { * Specify user locale, for example `en-GB`, `de-DE`, etc. Locale will affect `navigator.language` value, * `Accept-Language` request header value as well as number and date formatting rules. Defaults to the system default * locale. Learn more about emulation in our [emulation guide](https://playwright.dev/docs/emulation#locale--timezone). + * @since v1.8 */ locale?: string; /** * Logger sink for Playwright logging. * @deprecated The logs received by the logger are incomplete. Please use tracing instead. + * @since v1.8 */ logger?: Logger; /** * Whether to emulate network being offline. Defaults to `false`. Learn more about * [network emulation](https://playwright.dev/docs/emulation#offline). + * @since v1.8 */ offline?: boolean; @@ -22944,31 +25465,37 @@ export interface BrowserContextOptions { * A list of permissions to grant to all pages in this context. See * [browserContext.grantPermissions(permissions[, options])](https://playwright.dev/docs/api/class-browsercontext#browser-context-grant-permissions) * for more details. Defaults to none. + * @since v1.8 */ permissions?: Array; /** * Network proxy settings to use with this context. Defaults to none. + * @since v1.8 */ proxy?: { /** * Proxy to be used for all requests. HTTP and SOCKS proxies are supported, for example `http://myproxy.com:3128` or * `socks5://myproxy.com:3128`. Short form `myproxy.com:3128` is considered an HTTP proxy. + * @since v1.8 */ server: string; /** * Optional comma-separated domains to bypass proxy, for example `".com, chromium.org, .domain.com"`. + * @since v1.8 */ bypass?: string; /** * Optional username to use if HTTP proxy requires authentication. + * @since v1.8 */ username?: string; /** * Optional password to use if HTTP proxy requires authentication. + * @since v1.8 */ password?: string; }; @@ -22978,11 +25505,13 @@ export interface BrowserContextOptions { * If not specified, the HAR is not recorded. Make sure to await * [browserContext.close([options])](https://playwright.dev/docs/api/class-browsercontext#browser-context-close) for * the HAR to be saved. + * @since v1.8 */ recordHar?: { /** * Optional setting to control whether to omit request content from the HAR. Defaults to `false`. Deprecated, use * `content` policy instead. + * @since v1.8 */ omitContent?: boolean; @@ -22991,18 +25520,21 @@ export interface BrowserContextOptions { * `attach` is specified, resources are persisted as separate files or entries in the ZIP archive. If `embed` is * specified, content is stored inline the HAR file as per HAR specification. Defaults to `attach` for `.zip` output * files and to `embed` for all other file extensions. + * @since v1.8 */ content?: "omit"|"embed"|"attach"; /** * Path on the filesystem to write the HAR file to. If the file name ends with `.zip`, `content: 'attach'` is used by * default. + * @since v1.8 */ path: string; /** * When set to `minimal`, only record information necessary for routing from HAR. This omits sizes, timing, page, * cookies, security and other types of HAR information that are not used when replaying from HAR. Defaults to `full`. + * @since v1.8 */ mode?: "full"|"minimal"; @@ -23011,6 +25543,7 @@ export interface BrowserContextOptions { * [`baseURL`](https://playwright.dev/docs/api/class-browser#browser-new-context-option-base-url) via the context * options was provided and the passed URL is a path, it gets merged via the * [`new URL()`](https://developer.mozilla.org/en-US/docs/Web/API/URL/URL) constructor. Defaults to none. + * @since v1.8 */ urlFilter?: string|RegExp; }; @@ -23020,11 +25553,13 @@ export interface BrowserContextOptions { * Make sure to await * [browserContext.close([options])](https://playwright.dev/docs/api/class-browsercontext#browser-context-close) for * videos to be saved. + * @since v1.8 */ recordVideo?: { /** * Path to the directory to put videos into. If not specified, the videos will be stored in `artifactsDir` (see * [browserType.launch([options])](https://playwright.dev/docs/api/class-browsertype#browser-type-launch) options). + * @since v1.8 */ dir?: string; @@ -23032,35 +25567,42 @@ export interface BrowserContextOptions { * Optional dimensions of the recorded videos. If not specified the size will be equal to `viewport` scaled down to * fit into 800x800. If `viewport` is not configured explicitly the video size defaults to 800x450. Actual picture of * each page will be scaled down if necessary to fit the specified size. + * @since v1.8 */ size?: { /** * Video frame width. + * @since v1.8 */ width: number; /** * Video frame height. + * @since v1.8 */ height: number; }; /** * If specified, enables visual annotations on interacted elements during video recording. + * @since v1.8 */ showActions?: { /** * How long each annotation is displayed in milliseconds. Defaults to `500`. + * @since v1.8 */ duration?: number; /** * Position of the action title overlay. Defaults to `"top-right"`. + * @since v1.8 */ position?: "top-left"|"top"|"top-right"|"bottom-left"|"bottom"|"bottom-right"; /** * Font size of the action title in pixels. Defaults to `24`. + * @since v1.8 */ fontSize?: number; }; @@ -23070,21 +25612,25 @@ export interface BrowserContextOptions { * Emulates `'prefers-reduced-motion'` media feature, supported values are `'reduce'`, `'no-preference'`. See * [page.emulateMedia([options])](https://playwright.dev/docs/api/class-page#page-emulate-media) for more details. * Passing `null` resets emulation to system defaults. Defaults to `'no-preference'`. + * @since v1.8 */ reducedMotion?: null|"reduce"|"no-preference"; /** * Emulates consistent window screen size available inside web page via `window.screen`. Is only used when the * [`viewport`](https://playwright.dev/docs/api/class-browser#browser-new-context-option-viewport) is set. + * @since v1.8 */ screen?: { /** * page width in pixels. + * @since v1.8 */ width: number; /** * page height in pixels. + * @since v1.8 */ height: number; }; @@ -23094,6 +25640,7 @@ export interface BrowserContextOptions { * - `'allow'`: [Service Workers](https://developer.mozilla.org/en-US/docs/Web/API/Service_Worker_API) can be * registered. * - `'block'`: Playwright will block all registration of Service Workers. + * @since v1.8 */ serviceWorkers?: "allow"|"block"; @@ -23103,51 +25650,82 @@ export interface BrowserContextOptions { * Populates context with given storage state. This option can be used to initialize context with logged-in * information obtained via * [browserContext.storageState([options])](https://playwright.dev/docs/api/class-browsercontext#browser-context-storage-state). + * @since v1.8 */ storageState?: string|{ /** * Cookies to set for context + * @since v1.8 */ cookies: Array<{ + /** + * @since v1.8 + */ name: string; + /** + * @since v1.8 + */ value: string; /** * Domain and path are required. For the cookie to apply to all subdomains as well, prefix domain with a dot, like * this: ".example.com" + * @since v1.8 */ domain: string; /** * Domain and path are required + * @since v1.8 */ path: string; /** * Unix time in seconds. + * @since v1.8 */ expires: number; + /** + * @since v1.8 + */ httpOnly: boolean; + /** + * @since v1.8 + */ secure: boolean; /** * sameSite flag + * @since v1.8 */ sameSite: "Strict"|"Lax"|"None"; }>; + /** + * @since v1.8 + */ origins: Array<{ + /** + * @since v1.8 + */ origin: string; /** * localStorage to set for context + * @since v1.8 */ localStorage: Array<{ + /** + * @since v1.8 + */ name: string; + /** + * @since v1.8 + */ value: string; }>; }>; @@ -23158,6 +25736,7 @@ export interface BrowserContextOptions { * selectors that imply single target DOM element will throw when more than one element matches the selector. This * option does not affect any Locator APIs (Locators are always strict). Defaults to `false`. See * [Locator](https://playwright.dev/docs/api/class-locator) to learn more about the strict mode. + * @since v1.8 */ strictSelectors?: boolean; @@ -23165,31 +25744,37 @@ export interface BrowserContextOptions { * Changes the timezone of the context. See * [ICU's metaZones.txt](https://cs.chromium.org/chromium/src/third_party/icu/source/data/misc/metaZones.txt?rcl=faee8bc70570192d82d2978a71e2a615788597d1) * for a list of supported timezone IDs. Defaults to the system timezone. + * @since v1.8 */ timezoneId?: string; /** * Specific user agent to use in this context. + * @since v1.8 */ userAgent?: string; /** * @deprecated Use [`recordVideo`](https://playwright.dev/docs/api/class-browser#browser-new-context-option-record-video) instead. + * @since v1.8 */ videoSize?: { /** * Video frame width. + * @since v1.8 */ width: number; /** * Video frame height. + * @since v1.8 */ height: number; }; /** * @deprecated Use [`recordVideo`](https://playwright.dev/docs/api/class-browser#browser-new-context-option-record-video) instead. + * @since v1.8 */ videosPath?: string; @@ -23200,6 +25785,7 @@ export interface BrowserContextOptions { * **NOTE** The `null` value opts out from the default presets, makes viewport depend on the host window size defined * by the operating system. It makes the execution of the tests non-deterministic. * + * @since v1.8 */ viewport?: null|ViewportSize; } @@ -23207,22 +25793,31 @@ export interface BrowserContextOptions { export interface ViewportSize { /** * page width in pixels. + * @since v1.8 */ width: number; /** * page height in pixels. + * @since v1.8 */ height: number; } export interface HTTPCredentials { + /** + * @since v1.8 + */ username: string; + /** + * @since v1.8 + */ password: string; /** * Restrain sending http credentials on specific origin (scheme://host:port). + * @since v1.8 */ origin?: string; @@ -23232,6 +25827,7 @@ export interface HTTPCredentials { * the browser. `'always'` - `Authorization` header with basic authentication credentials will be sent with the each * API request. `'unauthorized` - the credentials are only sent when 401 (Unauthorized) response with * `WWW-Authenticate` header is received. Defaults to `'unauthorized'`. + * @since v1.8 */ send?: "unauthorized"|"always"; } @@ -23239,40 +25835,68 @@ export interface HTTPCredentials { export interface Geolocation { /** * Latitude between -90 and 90. + * @since v1.8 */ latitude: number; /** * Longitude between -180 and 180. + * @since v1.8 */ longitude: number; /** * Non-negative accuracy value. Defaults to `0`. + * @since v1.8 */ accuracy?: number; } export interface Cookie { + /** + * @since v1.8 + */ name: string; + /** + * @since v1.8 + */ value: string; + /** + * @since v1.8 + */ domain: string; + /** + * @since v1.8 + */ path: string; /** * Unix time in seconds. + * @since v1.8 */ expires: number; + /** + * @since v1.8 + */ httpOnly: boolean; + /** + * @since v1.8 + */ secure: boolean; + /** + * @since v1.8 + */ sameSite: "Strict"|"Lax"|"None"; + /** + * @since v1.8 + */ partitionKey?: string; } @@ -23285,12 +25909,14 @@ interface PageWaitForSelectorOptions { * without any content or with `display:none` has an empty bounding box and is not considered visible. * - `'hidden'` - wait for element to be either detached from DOM, or have an empty bounding box or * `visibility:hidden`. This is opposite to the `'visible'` option. + * @since v1.8 */ state?: "attached"|"detached"|"visible"|"hidden"; /** * When true, the call requires selector to resolve to a single element. If given selector resolves to more than one * element, the call throws an exception. + * @since v1.14 */ strict?: boolean; @@ -23299,6 +25925,7 @@ interface PageWaitForSelectorOptions { * option in the config, or by using the * [browserContext.setDefaultTimeout(timeout)](https://playwright.dev/docs/api/class-browsercontext#browser-context-set-default-timeout) * or [page.setDefaultTimeout(timeout)](https://playwright.dev/docs/api/class-page#page-set-default-timeout) methods. + * @since v1.8 */ timeout?: number; } @@ -23310,6 +25937,7 @@ interface PageWaitForFunctionOptions { * executed in `requestAnimationFrame` callback. If * [`polling`](https://playwright.dev/docs/api/class-page#page-wait-for-function-option-polling) is a number, then it * is treated as an interval in milliseconds at which the function would be executed. Defaults to `raf`. + * @since v1.8 */ polling?: number|"raf"; @@ -23318,6 +25946,7 @@ interface PageWaitForFunctionOptions { * `actionTimeout` option in the config, or by using the * [browserContext.setDefaultTimeout(timeout)](https://playwright.dev/docs/api/class-browsercontext#browser-context-set-default-timeout) * or [page.setDefaultTimeout(timeout)](https://playwright.dev/docs/api/class-page#page-set-default-timeout) methods. + * @since v1.8 */ timeout?: number; } @@ -23330,36 +25959,43 @@ export interface PageScreenshotOptions { * - infinite animations are canceled to initial state, and then played over after the screenshot. * * Defaults to `"allow"` that leaves animations untouched. + * @since v1.8 */ animations?: "disabled"|"allow"; /** * When set to `"hide"`, screenshot will hide text caret. When set to `"initial"`, text caret behavior will not be * changed. Defaults to `"hide"`. + * @since v1.8 */ caret?: "hide"|"initial"; /** * An object which specifies clipping of the resulting image. + * @since v1.8 */ clip?: { /** * x-coordinate of top-left corner of clip area + * @since v1.8 */ x: number; /** * y-coordinate of top-left corner of clip area + * @since v1.8 */ y: number; /** * width of clipping area + * @since v1.8 */ width: number; /** * height of clipping area + * @since v1.8 */ height: number; }; @@ -23367,6 +26003,7 @@ export interface PageScreenshotOptions { /** * When true, takes a screenshot of the full scrollable page, instead of the currently visible viewport. Defaults to * `false`. + * @since v1.8 */ fullPage?: boolean; @@ -23376,18 +26013,21 @@ export interface PageScreenshotOptions { * [`maskColor`](https://playwright.dev/docs/api/class-page#page-screenshot-option-mask-color)) that completely covers * its bounding box. The mask is also applied to invisible elements, see * [Matching only visible elements](https://playwright.dev/docs/locators#matching-only-visible-elements) to disable that. + * @since v1.8 */ mask?: Array; /** * Specify the color of the overlay box for masked elements, in * [CSS color format](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value). Default color is pink `#FF00FF`. + * @since v1.35 */ maskColor?: string; /** * Hides default white background and allows capturing screenshots with transparency. Not applicable to `jpeg` images. * Defaults to `false`. + * @since v1.8 */ omitBackground?: boolean; @@ -23395,11 +26035,13 @@ export interface PageScreenshotOptions { * The file path to save the image to. The screenshot type will be inferred from file extension. If * [`path`](https://playwright.dev/docs/api/class-page#page-screenshot-option-path) is a relative path, then it is * resolved relative to the current working directory. If no path is provided, the image won't be saved to the disk. + * @since v1.8 */ path?: string; /** * The quality of the image, between 0-100. Not applicable to `png` images. + * @since v1.8 */ quality?: number; @@ -23409,6 +26051,7 @@ export interface PageScreenshotOptions { * screenshots of high-dpi devices will be twice as large or even larger. * * Defaults to `"device"`. + * @since v1.8 */ scale?: "css"|"device"; @@ -23416,6 +26059,7 @@ export interface PageScreenshotOptions { * Text of the stylesheet to apply while making the screenshot. This is where you can hide dynamic elements, make * elements invisible or change their properties to help you creating repeatable screenshots. This stylesheet pierces * the Shadow DOM and applies to the inner frames. + * @since v1.41 */ style?: string; @@ -23424,11 +26068,13 @@ export interface PageScreenshotOptions { * option in the config, or by using the * [browserContext.setDefaultTimeout(timeout)](https://playwright.dev/docs/api/class-browsercontext#browser-context-set-default-timeout) * or [page.setDefaultTimeout(timeout)](https://playwright.dev/docs/api/class-page#page-set-default-timeout) methods. + * @since v1.8 */ timeout?: number; /** * Specify screenshot type, defaults to `png`. + * @since v1.8 */ type?: "png"|"jpeg"; } diff --git a/packages/playwright-core/types/types.d.ts b/packages/playwright-core/types/types.d.ts index 637fa2b03196f..10fe15bf27f77 100644 --- a/packages/playwright-core/types/types.d.ts +++ b/packages/playwright-core/types/types.d.ts @@ -80,6 +80,7 @@ type InferZodSchema = T extends z3.ZodTypeAny ? z3.infer * page.removeListener('request', logRequest); * ``` * + * @since v1.8 */ export interface Page { /** @@ -128,6 +129,7 @@ export interface Page { * await bodyHandle.dispose(); * ``` * + * @since v1.8 * @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). @@ -179,6 +181,7 @@ export interface Page { * await bodyHandle.dispose(); * ``` * + * @since v1.8 * @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). @@ -225,6 +228,7 @@ export interface Page { * await resultHandle.dispose(); * ``` * + * @since v1.8 * @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). @@ -270,6 +274,7 @@ export interface Page { * await resultHandle.dispose(); * ``` * + * @since v1.8 * @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). @@ -310,6 +315,7 @@ export interface Page { * and [page.addInitScript(script[, arg])](https://playwright.dev/docs/api/class-page#page-add-init-script) is not * defined. * + * @since v1.8 * @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 @@ -324,6 +330,7 @@ export interface Page { * 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). + * @since v1.9 * @param selector A selector to query for. * @param options */ @@ -335,6 +342,7 @@ export interface Page { * 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). + * @since v1.9 * @param selector A selector to query for. * @param options */ @@ -346,6 +354,7 @@ export interface Page { * * The method finds all elements matching the specified selector within the page. If no elements match the selector, * the return value resolves to `[]`. + * @since v1.9 * @param selector A selector to query for. */ $$(selector: K): Promise[]>; @@ -355,6 +364,7 @@ export interface Page { * * The method finds all elements matching the specified selector within the page. If no elements match the selector, * the return value resolves to `[]`. + * @since v1.9 * @param selector A selector to query for. */ $$(selector: string): Promise[]>; @@ -385,6 +395,7 @@ export interface Page { * const preloadHrefTS = await page.$eval('link[rel=preload]', (el: HTMLLinkElement) => el.href); * ``` * + * @since v1.9 * @param selector A selector to query for. * @param pageFunction Function to be evaluated in the page context. * @param arg Optional argument to pass to @@ -418,6 +429,7 @@ export interface Page { * const preloadHrefTS = await page.$eval('link[rel=preload]', (el: HTMLLinkElement) => el.href); * ``` * + * @since v1.9 * @param selector A selector to query for. * @param pageFunction Function to be evaluated in the page context. * @param arg Optional argument to pass to @@ -451,6 +463,7 @@ export interface Page { * const preloadHrefTS = await page.$eval('link[rel=preload]', (el: HTMLLinkElement) => el.href); * ``` * + * @since v1.9 * @param selector A selector to query for. * @param pageFunction Function to be evaluated in the page context. * @param arg Optional argument to pass to @@ -484,6 +497,7 @@ export interface Page { * const preloadHrefTS = await page.$eval('link[rel=preload]', (el: HTMLLinkElement) => el.href); * ``` * + * @since v1.9 * @param selector A selector to query for. * @param pageFunction Function to be evaluated in the page context. * @param arg Optional argument to pass to @@ -516,6 +530,7 @@ export interface Page { * const divCounts = await page.$$eval('div', (divs, min) => divs.length >= min, 10); * ``` * + * @since v1.9 * @param selector A selector to query for. * @param pageFunction Function to be evaluated in the page context. * @param arg Optional argument to pass to @@ -546,6 +561,7 @@ export interface Page { * const divCounts = await page.$$eval('div', (divs, min) => divs.length >= min, 10); * ``` * + * @since v1.9 * @param selector A selector to query for. * @param pageFunction Function to be evaluated in the page context. * @param arg Optional argument to pass to @@ -576,6 +592,7 @@ export interface Page { * const divCounts = await page.$$eval('div', (divs, min) => divs.length >= min, 10); * ``` * + * @since v1.9 * @param selector A selector to query for. * @param pageFunction Function to be evaluated in the page context. * @param arg Optional argument to pass to @@ -606,6 +623,7 @@ export interface Page { * const divCounts = await page.$$eval('div', (divs, min) => divs.length >= min, 10); * ``` * + * @since v1.9 * @param selector A selector to query for. * @param pageFunction Function to be evaluated in the page context. * @param arg Optional argument to pass to @@ -646,6 +664,7 @@ export interface Page { * await page.waitForFunction(selector => !!document.querySelector(selector), selector); * ``` * + * @since v1.8 * @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). @@ -685,6 +704,7 @@ export interface Page { * await page.waitForFunction(selector => !!document.querySelector(selector), selector); * ``` * + * @since v1.8 * @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). @@ -732,6 +752,7 @@ export interface Page { * })(); * ``` * + * @since v1.8 * @param selector A selector to query for. * @param options */ @@ -776,6 +797,7 @@ export interface Page { * })(); * ``` * + * @since v1.8 * @param selector A selector to query for. * @param options */ @@ -820,6 +842,7 @@ export interface Page { * })(); * ``` * + * @since v1.8 * @param selector A selector to query for. * @param options */ @@ -864,6 +887,7 @@ export interface Page { * })(); * ``` * + * @since v1.8 * @param selector A selector to query for. * @param options */ @@ -916,6 +940,7 @@ export interface Page { * })(); * ``` * + * @since v1.8 * @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 @@ -968,6 +993,7 @@ export interface Page { * })(); * ``` * + * @since v1.8 * @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 @@ -991,6 +1017,7 @@ export interface Page { * await page.removeAllListeners('request', { behavior: 'wait' }); * ``` * + * @since v1.47 * @param type * @param options */ @@ -1012,6 +1039,7 @@ export interface Page { * await page.removeAllListeners('request', { behavior: 'wait' }); * ``` * + * @since v1.47 * @param type * @param options */ @@ -2027,6 +2055,7 @@ export interface Page { * }, { times: 1 }); * ``` * + * @since v1.42 * @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 @@ -2038,11 +2067,13 @@ export interface Page { * 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. + * @since v1.44 */ noWaitAfter?: boolean; /** * Specifies the maximum number of times this handler should be called. Unlimited by default. + * @since v1.44 */ times?: number; }): Promise; @@ -2050,28 +2081,33 @@ export interface Page { /** * Adds a `'); * ``` * + * @since v1.38 */ export interface WebError { /** * Unhandled error that was thrown. + * @since v1.38 */ error(): Error; /** * The page that produced this unhandled exception, if any. + * @since v1.38 */ page(): null|Page; } @@ -22202,6 +24625,7 @@ export interface WebError { * * If you want to intercept or modify WebSocket frames, consider using * [WebSocketRoute](https://playwright.dev/docs/api/class-websocketroute). + * @since v1.8 */ export interface WebSocket { /** @@ -22215,6 +24639,7 @@ export interface WebSocket { on(event: 'framereceived', listener: (data: { /** * frame payload + * @since v1.9 */ payload: string|Buffer; }) => any): this; @@ -22225,6 +24650,7 @@ export interface WebSocket { on(event: 'framesent', listener: (data: { /** * frame payload + * @since v1.9 */ payload: string|Buffer; }) => any): this; @@ -22245,6 +24671,7 @@ export interface WebSocket { once(event: 'framereceived', listener: (data: { /** * frame payload + * @since v1.9 */ payload: string|Buffer; }) => any): this; @@ -22255,6 +24682,7 @@ export interface WebSocket { once(event: 'framesent', listener: (data: { /** * frame payload + * @since v1.9 */ payload: string|Buffer; }) => any): this; @@ -22275,6 +24703,7 @@ export interface WebSocket { addListener(event: 'framereceived', listener: (data: { /** * frame payload + * @since v1.9 */ payload: string|Buffer; }) => any): this; @@ -22285,6 +24714,7 @@ export interface WebSocket { addListener(event: 'framesent', listener: (data: { /** * frame payload + * @since v1.9 */ payload: string|Buffer; }) => any): this; @@ -22305,6 +24735,7 @@ export interface WebSocket { removeListener(event: 'framereceived', listener: (data: { /** * frame payload + * @since v1.9 */ payload: string|Buffer; }) => any): this; @@ -22315,6 +24746,7 @@ export interface WebSocket { removeListener(event: 'framesent', listener: (data: { /** * frame payload + * @since v1.9 */ payload: string|Buffer; }) => any): this; @@ -22335,6 +24767,7 @@ export interface WebSocket { off(event: 'framereceived', listener: (data: { /** * frame payload + * @since v1.9 */ payload: string|Buffer; }) => any): this; @@ -22345,6 +24778,7 @@ export interface WebSocket { off(event: 'framesent', listener: (data: { /** * frame payload + * @since v1.9 */ payload: string|Buffer; }) => any): this; @@ -22365,6 +24799,7 @@ export interface WebSocket { prependListener(event: 'framereceived', listener: (data: { /** * frame payload + * @since v1.9 */ payload: string|Buffer; }) => any): this; @@ -22375,6 +24810,7 @@ export interface WebSocket { prependListener(event: 'framesent', listener: (data: { /** * frame payload + * @since v1.9 */ payload: string|Buffer; }) => any): this; @@ -22386,11 +24822,13 @@ export interface WebSocket { /** * Indicates that the web socket has been closed. + * @since v1.8 */ isClosed(): boolean; /** * Contains the URL of the WebSocket. + * @since v1.8 */ url(): string; @@ -22405,16 +24843,19 @@ export interface WebSocket { waitForEvent(event: 'framereceived', optionsOrPredicate?: { predicate?: (data: { /** * frame payload + * @since v1.9 */ payload: string|Buffer; }) => boolean | Promise, timeout?: number } | ((data: { /** * frame payload + * @since v1.9 */ payload: string|Buffer; }) => boolean | Promise)): Promise<{ /** * frame payload + * @since v1.9 */ payload: string|Buffer; }>; @@ -22425,16 +24866,19 @@ export interface WebSocket { waitForEvent(event: 'framesent', optionsOrPredicate?: { predicate?: (data: { /** * frame payload + * @since v1.9 */ payload: string|Buffer; }) => boolean | Promise, timeout?: number } | ((data: { /** * frame payload + * @since v1.9 */ payload: string|Buffer; }) => boolean | Promise)): Promise<{ /** * frame payload + * @since v1.9 */ payload: string|Buffer; }>; @@ -22452,6 +24896,7 @@ export interface LaunchOptions { * * Additional arguments to pass to the browser instance. The list of Chromium flags can be found * [here](https://peter.sh/experiments/chromium-command-line-switches/). + * @since v1.8 */ args?: Array; @@ -22459,6 +24904,7 @@ export interface LaunchOptions { * If specified, artifacts (traces, videos, downloads, HAR files, etc.) are saved into this directory. The directory * is not cleaned up when the browser closes. If not specified, a temporary directory is used and cleaned up when the * browser closes. + * @since v1.8 */ artifactsDir?: string; @@ -22469,11 +24915,13 @@ export interface LaunchOptions { * * Use "chrome", "chrome-beta", "chrome-dev", "chrome-canary", "msedge", "msedge-beta", "msedge-dev", or * "msedge-canary" to use branded [Google Chrome and Microsoft Edge](https://playwright.dev/docs/browsers#google-chrome--microsoft-edge). + * @since v1.8 */ channel?: string; /** * Enable Chromium sandboxing. Defaults to `false`. + * @since v1.8 */ chromiumSandbox?: boolean; @@ -22481,9 +24929,13 @@ export interface LaunchOptions { * If specified, accepted downloads are downloaded into this directory. Otherwise, temporary directory is created and * is deleted when browser is closed. In either case, the downloads are deleted when the browser context they were * created in is closed. + * @since v1.8 */ downloadsPath?: string; + /** + * @since v1.8 + */ env?: { [key: string]: string|undefined; }; /** @@ -22491,6 +24943,7 @@ export interface LaunchOptions { * [`executablePath`](https://playwright.dev/docs/api/class-browsertype#browser-type-launch-option-executable-path) is * a relative path, then it is resolved relative to the current working directory. Note that Playwright only works * with the bundled Chromium, Firefox or WebKit, use at your own risk. + * @since v1.8 */ executablePath?: string; @@ -22500,21 +24953,25 @@ export interface LaunchOptions { * * You can also provide a path to a custom [`policies.json` file](https://mozilla.github.io/policy-templates/) via * `PLAYWRIGHT_FIREFOX_POLICIES_JSON` environment variable. + * @since v1.8 */ firefoxUserPrefs?: { [key: string]: string|number|boolean; }; /** * Close the browser process on SIGHUP. Defaults to `true`. + * @since v1.8 */ handleSIGHUP?: boolean; /** * Close the browser process on Ctrl-C. Defaults to `true`. + * @since v1.8 */ handleSIGINT?: boolean; /** * Close the browser process on SIGTERM. Defaults to `true`. + * @since v1.8 */ handleSIGTERM?: boolean; @@ -22522,6 +24979,7 @@ export interface LaunchOptions { * Whether to run browser in headless mode. More details for * [Chromium](https://developers.google.com/web/updates/2017/04/headless-chrome) and * [Firefox](https://hacks.mozilla.org/2017/12/using-headless-mode-in-firefox/). Defaults to `true`. + * @since v1.8 */ headless?: boolean; @@ -22529,37 +24987,44 @@ export interface LaunchOptions { * If `true`, Playwright does not pass its own configurations args and only uses the ones from * [`args`](https://playwright.dev/docs/api/class-browsertype#browser-type-launch-option-args). If an array is given, * then filters out the given default arguments. Dangerous option; use with care. Defaults to `false`. + * @since v1.8 */ ignoreDefaultArgs?: boolean|Array; /** * Logger sink for Playwright logging. * @deprecated The logs received by the logger are incomplete. Please use tracing instead. + * @since v1.8 */ logger?: Logger; /** * Network proxy settings. + * @since v1.8 */ proxy?: { /** * Proxy to be used for all requests. HTTP and SOCKS proxies are supported, for example `http://myproxy.com:3128` or * `socks5://myproxy.com:3128`. Short form `myproxy.com:3128` is considered an HTTP proxy. + * @since v1.8 */ server: string; /** * Optional comma-separated domains to bypass proxy, for example `".com, chromium.org, .domain.com"`. + * @since v1.8 */ bypass?: string; /** * Optional username to use if HTTP proxy requires authentication. + * @since v1.8 */ username?: string; /** * Optional password to use if HTTP proxy requires authentication. + * @since v1.8 */ password?: string; }; @@ -22567,17 +25032,20 @@ export interface LaunchOptions { /** * Slows down Playwright operations by the specified amount of milliseconds. Useful so that you can see what is going * on. + * @since v1.8 */ slowMo?: number; /** * Maximum time in milliseconds to wait for the browser instance to start. Defaults to `30000` (30 seconds). Pass `0` * to disable timeout. + * @since v1.8 */ timeout?: number; /** * If specified, traces are saved into this directory. + * @since v1.8 */ tracesDir?: string; } @@ -22585,35 +25053,41 @@ export interface LaunchOptions { export interface ConnectOverCDPOptions { /** * @deprecated Use the first argument instead. + * @since v1.14 */ endpointURL?: string; /** * Additional HTTP headers to be sent with connect request. Optional. + * @since v1.11 */ headers?: { [key: string]: string; }; /** * Tells Playwright that it runs on the same host as the CDP server. It will enable certain optimizations that rely * upon the file system being the same between Playwright and the Browser. + * @since v1.58 */ isLocal?: boolean; /** * Logger sink for Playwright logging. Optional. * @deprecated The logs received by the logger are incomplete. Please use tracing instead. + * @since v1.14 */ logger?: Logger; /** * Slows down Playwright operations by the specified amount of milliseconds. Useful so that you can see what is going * on. Defaults to 0. + * @since v1.11 */ slowMo?: number; /** * Maximum time in milliseconds to wait for the connection to be established. Defaults to `30000` (30 seconds). Pass * `0` to disable timeout. + * @since v1.11 */ timeout?: number; } @@ -22633,28 +25107,33 @@ export interface ConnectOptions { * 1. `""` to expose localhost network. * 1. `"*.test.internal-domain,*.staging.internal-domain,"` to expose test/staging deployments and * localhost. + * @since v1.37 */ exposeNetwork?: string; /** * Additional HTTP headers to be sent with web socket connect request. Optional. + * @since v1.11 */ headers?: { [key: string]: string; }; /** * Logger sink for Playwright logging. Optional. * @deprecated The logs received by the logger are incomplete. Please use tracing instead. + * @since v1.14 */ logger?: Logger; /** * Slows down Playwright operations by the specified amount of milliseconds. Useful so that you can see what is going * on. Defaults to 0. + * @since v1.10 */ slowMo?: number; /** * Maximum time in milliseconds to wait for the connection to be established. Defaults to `0` (no timeout). + * @since v1.10 */ timeout?: number; } @@ -22667,12 +25146,14 @@ export interface LocatorScreenshotOptions { * - infinite animations are canceled to initial state, and then played over after the screenshot. * * Defaults to `"allow"` that leaves animations untouched. + * @since v1.14 */ animations?: "disabled"|"allow"; /** * When set to `"hide"`, screenshot will hide text caret. When set to `"initial"`, text caret behavior will not be * changed. Defaults to `"hide"`. + * @since v1.14 */ caret?: "hide"|"initial"; @@ -22682,18 +25163,21 @@ export interface LocatorScreenshotOptions { * [`maskColor`](https://playwright.dev/docs/api/class-locator#locator-screenshot-option-mask-color)) that completely * covers its bounding box. The mask is also applied to invisible elements, see * [Matching only visible elements](https://playwright.dev/docs/locators#matching-only-visible-elements) to disable that. + * @since v1.14 */ mask?: Array; /** * Specify the color of the overlay box for masked elements, in * [CSS color format](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value). Default color is pink `#FF00FF`. + * @since v1.35 */ maskColor?: string; /** * Hides default white background and allows capturing screenshots with transparency. Not applicable to `jpeg` images. * Defaults to `false`. + * @since v1.14 */ omitBackground?: boolean; @@ -22702,11 +25186,13 @@ export interface LocatorScreenshotOptions { * [`path`](https://playwright.dev/docs/api/class-locator#locator-screenshot-option-path) is a relative path, then it * is resolved relative to the current working directory. If no path is provided, the image won't be saved to the * disk. + * @since v1.14 */ path?: string; /** * The quality of the image, between 0-100. Not applicable to `png` images. + * @since v1.14 */ quality?: number; @@ -22716,6 +25202,7 @@ export interface LocatorScreenshotOptions { * screenshots of high-dpi devices will be twice as large or even larger. * * Defaults to `"device"`. + * @since v1.14 */ scale?: "css"|"device"; @@ -22723,6 +25210,7 @@ export interface LocatorScreenshotOptions { * Text of the stylesheet to apply while making the screenshot. This is where you can hide dynamic elements, make * elements invisible or change their properties to help you creating repeatable screenshots. This stylesheet pierces * the Shadow DOM and applies to the inner frames. + * @since v1.41 */ style?: string; @@ -22731,11 +25219,13 @@ export interface LocatorScreenshotOptions { * option in the config, or by using the * [browserContext.setDefaultTimeout(timeout)](https://playwright.dev/docs/api/class-browsercontext#browser-context-set-default-timeout) * or [page.setDefaultTimeout(timeout)](https://playwright.dev/docs/api/class-page#page-set-default-timeout) methods. + * @since v1.14 */ timeout?: number; /** * Specify screenshot type, defaults to `png`. + * @since v1.14 */ type?: "png"|"jpeg"; } @@ -22749,12 +25239,14 @@ interface ElementHandleWaitForSelectorOptions { * without any content or with `display:none` has an empty bounding box and is not considered visible. * - `'hidden'` - wait for element to be either detached from DOM, or have an empty bounding box or * `visibility:hidden`. This is opposite to the `'visible'` option. + * @since v1.8 */ state?: "attached"|"detached"|"visible"|"hidden"; /** * When true, the call requires selector to resolve to a single element. If given selector resolves to more than one * element, the call throws an exception. + * @since v1.15 */ strict?: boolean; @@ -22763,6 +25255,7 @@ interface ElementHandleWaitForSelectorOptions { * option in the config, or by using the * [browserContext.setDefaultTimeout(timeout)](https://playwright.dev/docs/api/class-browsercontext#browser-context-set-default-timeout) * or [page.setDefaultTimeout(timeout)](https://playwright.dev/docs/api/class-page#page-set-default-timeout) methods. + * @since v1.8 */ timeout?: number; } @@ -22770,6 +25263,7 @@ interface ElementHandleWaitForSelectorOptions { export interface BrowserContextOptions { /** * Whether to automatically download all the attachments. Defaults to `true` where all the downloads are accepted. + * @since v1.8 */ acceptDownloads?: boolean; @@ -22788,11 +25282,13 @@ export interface BrowserContextOptions { * `http://localhost:3000/foo/bar.html` * - baseURL: `http://localhost:3000/foo` (without trailing slash) and navigating to `./bar.html` results in * `http://localhost:3000/bar.html` + * @since v1.8 */ baseURL?: string; /** * Toggles bypassing page's Content-Security-Policy. Defaults to `false`. + * @since v1.8 */ bypassCSP?: boolean; @@ -22813,45 +25309,54 @@ export interface BrowserContextOptions { * **NOTE** When using WebKit on macOS, accessing `localhost` will not pick up client certificates. You can make it * work by replacing `localhost` with `local.playwright`. * + * @since 1.46 */ clientCertificates?: Array<{ /** * Exact origin that the certificate is valid for. Origin includes `https` protocol, a hostname and optionally a port. + * @since 1.46 */ origin: string; /** * Path to the file with the certificate in PEM format. + * @since 1.46 */ certPath?: string; /** * Direct value of the certificate in PEM format. + * @since 1.46 */ cert?: Buffer; /** * Path to the file with the private key in PEM format. + * @since 1.46 */ keyPath?: string; /** * Direct value of the private key in PEM format. + * @since 1.46 */ key?: Buffer; /** * Path to the PFX or PKCS12 encoded private key and certificate chain. + * @since 1.46 */ pfxPath?: string; /** * Direct value of the PFX or PKCS12 encoded private key and certificate chain. + * @since 1.46 */ pfx?: Buffer; /** * Passphrase for the private key (PEM or PFX). + * @since 1.46 */ passphrase?: string; }>; @@ -22861,6 +25366,7 @@ export interface BrowserContextOptions { * media feature, supported values are `'light'` and `'dark'`. See * [page.emulateMedia([options])](https://playwright.dev/docs/api/class-page#page-emulate-media) for more details. * Passing `null` resets emulation to system defaults. Defaults to `'light'`. + * @since v1.8 */ colorScheme?: null|"light"|"dark"|"no-preference"; @@ -22868,17 +25374,20 @@ export interface BrowserContextOptions { * Emulates `'prefers-contrast'` media feature, supported values are `'no-preference'`, `'more'`. See * [page.emulateMedia([options])](https://playwright.dev/docs/api/class-page#page-emulate-media) for more details. * Passing `null` resets emulation to system defaults. Defaults to `'no-preference'`. + * @since v1.8 */ contrast?: null|"no-preference"|"more"; /** * Specify device scale factor (can be thought of as dpr). Defaults to `1`. Learn more about * [emulating devices with device scale factor](https://playwright.dev/docs/emulation#devices). + * @since v1.8 */ deviceScaleFactor?: number; /** * An object containing additional HTTP headers to be sent with every request. Defaults to none. + * @since v1.8 */ extraHTTPHeaders?: { [key: string]: string; }; @@ -22886,25 +25395,32 @@ export interface BrowserContextOptions { * Emulates `'forced-colors'` media feature, supported values are `'active'`, `'none'`. See * [page.emulateMedia([options])](https://playwright.dev/docs/api/class-page#page-emulate-media) for more details. * Passing `null` resets emulation to system defaults. Defaults to `'none'`. + * @since v1.8 */ forcedColors?: null|"active"|"none"; + /** + * @since v1.8 + */ geolocation?: Geolocation; /** * Specifies if viewport supports touch events. Defaults to false. Learn more about * [mobile emulation](https://playwright.dev/docs/emulation#devices). + * @since v1.8 */ hasTouch?: boolean; /** * Credentials for [HTTP authentication](https://developer.mozilla.org/en-US/docs/Web/HTTP/Authentication). If no * origin is specified, the username and password are sent to any servers upon unauthorized responses. + * @since v1.8 */ httpCredentials?: HTTPCredentials; /** * Whether to ignore HTTPS errors when sending network requests. Defaults to `false`. + * @since v1.8 */ ignoreHTTPSErrors?: boolean; @@ -22912,12 +25428,14 @@ export interface BrowserContextOptions { * Whether the `meta viewport` tag is taken into account and touch events are enabled. isMobile is a part of device, * so you don't actually need to set it manually. Defaults to `false` and is not supported in Firefox. Learn more * about [mobile emulation](https://playwright.dev/docs/emulation#ismobile). + * @since v1.8 */ isMobile?: boolean; /** * Whether or not to enable JavaScript in the context. Defaults to `true`. Learn more about * [disabling JavaScript](https://playwright.dev/docs/emulation#javascript-enabled). + * @since v1.8 */ javaScriptEnabled?: boolean; @@ -22925,18 +25443,21 @@ export interface BrowserContextOptions { * Specify user locale, for example `en-GB`, `de-DE`, etc. Locale will affect `navigator.language` value, * `Accept-Language` request header value as well as number and date formatting rules. Defaults to the system default * locale. Learn more about emulation in our [emulation guide](https://playwright.dev/docs/emulation#locale--timezone). + * @since v1.8 */ locale?: string; /** * Logger sink for Playwright logging. * @deprecated The logs received by the logger are incomplete. Please use tracing instead. + * @since v1.8 */ logger?: Logger; /** * Whether to emulate network being offline. Defaults to `false`. Learn more about * [network emulation](https://playwright.dev/docs/emulation#offline). + * @since v1.8 */ offline?: boolean; @@ -22944,31 +25465,37 @@ export interface BrowserContextOptions { * A list of permissions to grant to all pages in this context. See * [browserContext.grantPermissions(permissions[, options])](https://playwright.dev/docs/api/class-browsercontext#browser-context-grant-permissions) * for more details. Defaults to none. + * @since v1.8 */ permissions?: Array; /** * Network proxy settings to use with this context. Defaults to none. + * @since v1.8 */ proxy?: { /** * Proxy to be used for all requests. HTTP and SOCKS proxies are supported, for example `http://myproxy.com:3128` or * `socks5://myproxy.com:3128`. Short form `myproxy.com:3128` is considered an HTTP proxy. + * @since v1.8 */ server: string; /** * Optional comma-separated domains to bypass proxy, for example `".com, chromium.org, .domain.com"`. + * @since v1.8 */ bypass?: string; /** * Optional username to use if HTTP proxy requires authentication. + * @since v1.8 */ username?: string; /** * Optional password to use if HTTP proxy requires authentication. + * @since v1.8 */ password?: string; }; @@ -22978,11 +25505,13 @@ export interface BrowserContextOptions { * If not specified, the HAR is not recorded. Make sure to await * [browserContext.close([options])](https://playwright.dev/docs/api/class-browsercontext#browser-context-close) for * the HAR to be saved. + * @since v1.8 */ recordHar?: { /** * Optional setting to control whether to omit request content from the HAR. Defaults to `false`. Deprecated, use * `content` policy instead. + * @since v1.8 */ omitContent?: boolean; @@ -22991,18 +25520,21 @@ export interface BrowserContextOptions { * `attach` is specified, resources are persisted as separate files or entries in the ZIP archive. If `embed` is * specified, content is stored inline the HAR file as per HAR specification. Defaults to `attach` for `.zip` output * files and to `embed` for all other file extensions. + * @since v1.8 */ content?: "omit"|"embed"|"attach"; /** * Path on the filesystem to write the HAR file to. If the file name ends with `.zip`, `content: 'attach'` is used by * default. + * @since v1.8 */ path: string; /** * When set to `minimal`, only record information necessary for routing from HAR. This omits sizes, timing, page, * cookies, security and other types of HAR information that are not used when replaying from HAR. Defaults to `full`. + * @since v1.8 */ mode?: "full"|"minimal"; @@ -23011,6 +25543,7 @@ export interface BrowserContextOptions { * [`baseURL`](https://playwright.dev/docs/api/class-browser#browser-new-context-option-base-url) via the context * options was provided and the passed URL is a path, it gets merged via the * [`new URL()`](https://developer.mozilla.org/en-US/docs/Web/API/URL/URL) constructor. Defaults to none. + * @since v1.8 */ urlFilter?: string|RegExp; }; @@ -23020,11 +25553,13 @@ export interface BrowserContextOptions { * Make sure to await * [browserContext.close([options])](https://playwright.dev/docs/api/class-browsercontext#browser-context-close) for * videos to be saved. + * @since v1.8 */ recordVideo?: { /** * Path to the directory to put videos into. If not specified, the videos will be stored in `artifactsDir` (see * [browserType.launch([options])](https://playwright.dev/docs/api/class-browsertype#browser-type-launch) options). + * @since v1.8 */ dir?: string; @@ -23032,35 +25567,42 @@ export interface BrowserContextOptions { * Optional dimensions of the recorded videos. If not specified the size will be equal to `viewport` scaled down to * fit into 800x800. If `viewport` is not configured explicitly the video size defaults to 800x450. Actual picture of * each page will be scaled down if necessary to fit the specified size. + * @since v1.8 */ size?: { /** * Video frame width. + * @since v1.8 */ width: number; /** * Video frame height. + * @since v1.8 */ height: number; }; /** * If specified, enables visual annotations on interacted elements during video recording. + * @since v1.8 */ showActions?: { /** * How long each annotation is displayed in milliseconds. Defaults to `500`. + * @since v1.8 */ duration?: number; /** * Position of the action title overlay. Defaults to `"top-right"`. + * @since v1.8 */ position?: "top-left"|"top"|"top-right"|"bottom-left"|"bottom"|"bottom-right"; /** * Font size of the action title in pixels. Defaults to `24`. + * @since v1.8 */ fontSize?: number; }; @@ -23070,21 +25612,25 @@ export interface BrowserContextOptions { * Emulates `'prefers-reduced-motion'` media feature, supported values are `'reduce'`, `'no-preference'`. See * [page.emulateMedia([options])](https://playwright.dev/docs/api/class-page#page-emulate-media) for more details. * Passing `null` resets emulation to system defaults. Defaults to `'no-preference'`. + * @since v1.8 */ reducedMotion?: null|"reduce"|"no-preference"; /** * Emulates consistent window screen size available inside web page via `window.screen`. Is only used when the * [`viewport`](https://playwright.dev/docs/api/class-browser#browser-new-context-option-viewport) is set. + * @since v1.8 */ screen?: { /** * page width in pixels. + * @since v1.8 */ width: number; /** * page height in pixels. + * @since v1.8 */ height: number; }; @@ -23094,6 +25640,7 @@ export interface BrowserContextOptions { * - `'allow'`: [Service Workers](https://developer.mozilla.org/en-US/docs/Web/API/Service_Worker_API) can be * registered. * - `'block'`: Playwright will block all registration of Service Workers. + * @since v1.8 */ serviceWorkers?: "allow"|"block"; @@ -23103,51 +25650,82 @@ export interface BrowserContextOptions { * Populates context with given storage state. This option can be used to initialize context with logged-in * information obtained via * [browserContext.storageState([options])](https://playwright.dev/docs/api/class-browsercontext#browser-context-storage-state). + * @since v1.8 */ storageState?: string|{ /** * Cookies to set for context + * @since v1.8 */ cookies: Array<{ + /** + * @since v1.8 + */ name: string; + /** + * @since v1.8 + */ value: string; /** * Domain and path are required. For the cookie to apply to all subdomains as well, prefix domain with a dot, like * this: ".example.com" + * @since v1.8 */ domain: string; /** * Domain and path are required + * @since v1.8 */ path: string; /** * Unix time in seconds. + * @since v1.8 */ expires: number; + /** + * @since v1.8 + */ httpOnly: boolean; + /** + * @since v1.8 + */ secure: boolean; /** * sameSite flag + * @since v1.8 */ sameSite: "Strict"|"Lax"|"None"; }>; + /** + * @since v1.8 + */ origins: Array<{ + /** + * @since v1.8 + */ origin: string; /** * localStorage to set for context + * @since v1.8 */ localStorage: Array<{ + /** + * @since v1.8 + */ name: string; + /** + * @since v1.8 + */ value: string; }>; }>; @@ -23158,6 +25736,7 @@ export interface BrowserContextOptions { * selectors that imply single target DOM element will throw when more than one element matches the selector. This * option does not affect any Locator APIs (Locators are always strict). Defaults to `false`. See * [Locator](https://playwright.dev/docs/api/class-locator) to learn more about the strict mode. + * @since v1.8 */ strictSelectors?: boolean; @@ -23165,31 +25744,37 @@ export interface BrowserContextOptions { * Changes the timezone of the context. See * [ICU's metaZones.txt](https://cs.chromium.org/chromium/src/third_party/icu/source/data/misc/metaZones.txt?rcl=faee8bc70570192d82d2978a71e2a615788597d1) * for a list of supported timezone IDs. Defaults to the system timezone. + * @since v1.8 */ timezoneId?: string; /** * Specific user agent to use in this context. + * @since v1.8 */ userAgent?: string; /** * @deprecated Use [`recordVideo`](https://playwright.dev/docs/api/class-browser#browser-new-context-option-record-video) instead. + * @since v1.8 */ videoSize?: { /** * Video frame width. + * @since v1.8 */ width: number; /** * Video frame height. + * @since v1.8 */ height: number; }; /** * @deprecated Use [`recordVideo`](https://playwright.dev/docs/api/class-browser#browser-new-context-option-record-video) instead. + * @since v1.8 */ videosPath?: string; @@ -23200,6 +25785,7 @@ export interface BrowserContextOptions { * **NOTE** The `null` value opts out from the default presets, makes viewport depend on the host window size defined * by the operating system. It makes the execution of the tests non-deterministic. * + * @since v1.8 */ viewport?: null|ViewportSize; } @@ -23207,22 +25793,31 @@ export interface BrowserContextOptions { export interface ViewportSize { /** * page width in pixels. + * @since v1.8 */ width: number; /** * page height in pixels. + * @since v1.8 */ height: number; } export interface HTTPCredentials { + /** + * @since v1.8 + */ username: string; + /** + * @since v1.8 + */ password: string; /** * Restrain sending http credentials on specific origin (scheme://host:port). + * @since v1.8 */ origin?: string; @@ -23232,6 +25827,7 @@ export interface HTTPCredentials { * the browser. `'always'` - `Authorization` header with basic authentication credentials will be sent with the each * API request. `'unauthorized` - the credentials are only sent when 401 (Unauthorized) response with * `WWW-Authenticate` header is received. Defaults to `'unauthorized'`. + * @since v1.8 */ send?: "unauthorized"|"always"; } @@ -23239,40 +25835,68 @@ export interface HTTPCredentials { export interface Geolocation { /** * Latitude between -90 and 90. + * @since v1.8 */ latitude: number; /** * Longitude between -180 and 180. + * @since v1.8 */ longitude: number; /** * Non-negative accuracy value. Defaults to `0`. + * @since v1.8 */ accuracy?: number; } export interface Cookie { + /** + * @since v1.8 + */ name: string; + /** + * @since v1.8 + */ value: string; + /** + * @since v1.8 + */ domain: string; + /** + * @since v1.8 + */ path: string; /** * Unix time in seconds. + * @since v1.8 */ expires: number; + /** + * @since v1.8 + */ httpOnly: boolean; + /** + * @since v1.8 + */ secure: boolean; + /** + * @since v1.8 + */ sameSite: "Strict"|"Lax"|"None"; + /** + * @since v1.8 + */ partitionKey?: string; } @@ -23285,12 +25909,14 @@ interface PageWaitForSelectorOptions { * without any content or with `display:none` has an empty bounding box and is not considered visible. * - `'hidden'` - wait for element to be either detached from DOM, or have an empty bounding box or * `visibility:hidden`. This is opposite to the `'visible'` option. + * @since v1.8 */ state?: "attached"|"detached"|"visible"|"hidden"; /** * When true, the call requires selector to resolve to a single element. If given selector resolves to more than one * element, the call throws an exception. + * @since v1.14 */ strict?: boolean; @@ -23299,6 +25925,7 @@ interface PageWaitForSelectorOptions { * option in the config, or by using the * [browserContext.setDefaultTimeout(timeout)](https://playwright.dev/docs/api/class-browsercontext#browser-context-set-default-timeout) * or [page.setDefaultTimeout(timeout)](https://playwright.dev/docs/api/class-page#page-set-default-timeout) methods. + * @since v1.8 */ timeout?: number; } @@ -23310,6 +25937,7 @@ interface PageWaitForFunctionOptions { * executed in `requestAnimationFrame` callback. If * [`polling`](https://playwright.dev/docs/api/class-page#page-wait-for-function-option-polling) is a number, then it * is treated as an interval in milliseconds at which the function would be executed. Defaults to `raf`. + * @since v1.8 */ polling?: number|"raf"; @@ -23318,6 +25946,7 @@ interface PageWaitForFunctionOptions { * `actionTimeout` option in the config, or by using the * [browserContext.setDefaultTimeout(timeout)](https://playwright.dev/docs/api/class-browsercontext#browser-context-set-default-timeout) * or [page.setDefaultTimeout(timeout)](https://playwright.dev/docs/api/class-page#page-set-default-timeout) methods. + * @since v1.8 */ timeout?: number; } @@ -23330,36 +25959,43 @@ export interface PageScreenshotOptions { * - infinite animations are canceled to initial state, and then played over after the screenshot. * * Defaults to `"allow"` that leaves animations untouched. + * @since v1.8 */ animations?: "disabled"|"allow"; /** * When set to `"hide"`, screenshot will hide text caret. When set to `"initial"`, text caret behavior will not be * changed. Defaults to `"hide"`. + * @since v1.8 */ caret?: "hide"|"initial"; /** * An object which specifies clipping of the resulting image. + * @since v1.8 */ clip?: { /** * x-coordinate of top-left corner of clip area + * @since v1.8 */ x: number; /** * y-coordinate of top-left corner of clip area + * @since v1.8 */ y: number; /** * width of clipping area + * @since v1.8 */ width: number; /** * height of clipping area + * @since v1.8 */ height: number; }; @@ -23367,6 +26003,7 @@ export interface PageScreenshotOptions { /** * When true, takes a screenshot of the full scrollable page, instead of the currently visible viewport. Defaults to * `false`. + * @since v1.8 */ fullPage?: boolean; @@ -23376,18 +26013,21 @@ export interface PageScreenshotOptions { * [`maskColor`](https://playwright.dev/docs/api/class-page#page-screenshot-option-mask-color)) that completely covers * its bounding box. The mask is also applied to invisible elements, see * [Matching only visible elements](https://playwright.dev/docs/locators#matching-only-visible-elements) to disable that. + * @since v1.8 */ mask?: Array; /** * Specify the color of the overlay box for masked elements, in * [CSS color format](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value). Default color is pink `#FF00FF`. + * @since v1.35 */ maskColor?: string; /** * Hides default white background and allows capturing screenshots with transparency. Not applicable to `jpeg` images. * Defaults to `false`. + * @since v1.8 */ omitBackground?: boolean; @@ -23395,11 +26035,13 @@ export interface PageScreenshotOptions { * The file path to save the image to. The screenshot type will be inferred from file extension. If * [`path`](https://playwright.dev/docs/api/class-page#page-screenshot-option-path) is a relative path, then it is * resolved relative to the current working directory. If no path is provided, the image won't be saved to the disk. + * @since v1.8 */ path?: string; /** * The quality of the image, between 0-100. Not applicable to `png` images. + * @since v1.8 */ quality?: number; @@ -23409,6 +26051,7 @@ export interface PageScreenshotOptions { * screenshots of high-dpi devices will be twice as large or even larger. * * Defaults to `"device"`. + * @since v1.8 */ scale?: "css"|"device"; @@ -23416,6 +26059,7 @@ export interface PageScreenshotOptions { * Text of the stylesheet to apply while making the screenshot. This is where you can hide dynamic elements, make * elements invisible or change their properties to help you creating repeatable screenshots. This stylesheet pierces * the Shadow DOM and applies to the inner frames. + * @since v1.41 */ style?: string; @@ -23424,11 +26068,13 @@ export interface PageScreenshotOptions { * option in the config, or by using the * [browserContext.setDefaultTimeout(timeout)](https://playwright.dev/docs/api/class-browsercontext#browser-context-set-default-timeout) * or [page.setDefaultTimeout(timeout)](https://playwright.dev/docs/api/class-page#page-set-default-timeout) methods. + * @since v1.8 */ timeout?: number; /** * Specify screenshot type, defaults to `png`. + * @since v1.8 */ type?: "png"|"jpeg"; } diff --git a/packages/playwright/types/test.d.ts b/packages/playwright/types/test.d.ts index 23e7e12e030b4..0608c064cc453 100644 --- a/packages/playwright/types/test.d.ts +++ b/packages/playwright/types/test.d.ts @@ -101,6 +101,7 @@ type UseOptions = Partial & Partial; * }); * ``` * + * @since v1.10 */ interface TestProject { /** @@ -127,6 +128,7 @@ interface TestProject { * * Use [testConfig.use](https://playwright.dev/docs/api/class-testconfig#test-config-use) to change this option for * all projects. + * @since v1.10 */ use?: UseOptions; /** @@ -168,6 +170,7 @@ interface TestProject { * }); * ``` * + * @since v1.31 */ dependencies?: Array; @@ -176,10 +179,12 @@ interface TestProject { * * Use [testConfig.expect](https://playwright.dev/docs/api/class-testconfig#test-config-expect) to change this option * for all projects. + * @since v1.10 */ expect?: { /** * Default timeout for async expect matchers in milliseconds, defaults to 5000ms. + * @since v1.10 */ timeout?: number; @@ -187,47 +192,55 @@ interface TestProject { * Configuration for the * [expect(page).toHaveScreenshot(name[, options])](https://playwright.dev/docs/api/class-pageassertions#page-assertions-to-have-screenshot-1) * method. + * @since v1.10 */ toHaveScreenshot?: { /** * an acceptable perceived color difference between the same pixel in compared images, ranging from `0` (strict) and * `1` (lax). `"pixelmatch"` comparator computes color difference in * [YIQ color space](https://en.wikipedia.org/wiki/YIQ) and defaults `threshold` value to `0.2`. + * @since v1.10 */ threshold?: number; /** * an acceptable amount of pixels that could be different, unset by default. + * @since v1.10 */ maxDiffPixels?: number; /** * an acceptable ratio of pixels that are different to the total amount of pixels, between `0` and `1` , unset by * default. + * @since v1.10 */ maxDiffPixelRatio?: number; /** * See [`animations`](https://playwright.dev/docs/api/class-page#page-screenshot-option-animations) in * [page.screenshot([options])](https://playwright.dev/docs/api/class-page#page-screenshot). Defaults to `"disabled"`. + * @since v1.10 */ animations?: "allow"|"disabled"; /** * See [`caret`](https://playwright.dev/docs/api/class-page#page-screenshot-option-caret) in * [page.screenshot([options])](https://playwright.dev/docs/api/class-page#page-screenshot). Defaults to `"hide"`. + * @since v1.10 */ caret?: "hide"|"initial"; /** * See [`scale`](https://playwright.dev/docs/api/class-page#page-screenshot-option-scale) in * [page.screenshot([options])](https://playwright.dev/docs/api/class-page#page-screenshot). Defaults to `"css"`. + * @since v1.10 */ scale?: "css"|"device"; /** * See [`style`](https://playwright.dev/docs/api/class-page#page-screenshot-option-style) in * [page.screenshot([options])](https://playwright.dev/docs/api/class-page#page-screenshot). + * @since v1.10 */ stylePath?: string|Array; @@ -235,6 +248,7 @@ interface TestProject { * A template controlling location of the screenshots. See * [testProject.snapshotPathTemplate](https://playwright.dev/docs/api/class-testproject#test-project-snapshot-path-template) * for details. + * @since v1.10 */ pathTemplate?: string; }; @@ -243,12 +257,14 @@ interface TestProject { * Configuration for the * [expect(locator).toMatchAriaSnapshot([options])](https://playwright.dev/docs/api/class-locatorassertions#locator-assertions-to-match-aria-snapshot-2) * method. + * @since v1.10 */ toMatchAriaSnapshot?: { /** * A template controlling location of the aria snapshots. See * [testProject.snapshotPathTemplate](https://playwright.dev/docs/api/class-testproject#test-project-snapshot-path-template) * for details. + * @since v1.10 */ pathTemplate?: string; @@ -256,6 +272,7 @@ interface TestProject { * Controls how children of the snapshot root are matched against the actual accessibility tree. This is equivalent to * adding a `/children` property at the top of every aria snapshot template. Individual snapshots can override this by * including an explicit `/children` property. + * @since v1.10 */ children?: "contain"|"equal"|"deep-equal"; }; @@ -264,38 +281,45 @@ interface TestProject { * Configuration for the * [expect(value).toMatchSnapshot(name[, options])](https://playwright.dev/docs/api/class-snapshotassertions#snapshot-assertions-to-match-snapshot-1) * method. + * @since v1.10 */ toMatchSnapshot?: { /** * an acceptable perceived color difference between the same pixel in compared images, ranging from `0` (strict) and * `1` (lax). `"pixelmatch"` comparator computes color difference in * [YIQ color space](https://en.wikipedia.org/wiki/YIQ) and defaults `threshold` value to `0.2`. + * @since v1.10 */ threshold?: number; /** * an acceptable amount of pixels that could be different, unset by default. + * @since v1.10 */ maxDiffPixels?: number; /** * an acceptable ratio of pixels that are different to the total amount of pixels, between `0` and `1` , unset by * default. + * @since v1.10 */ maxDiffPixelRatio?: number; }; /** * Configuration for the [expect(value).toPass()](https://playwright.dev/docs/test-assertions) method. + * @since v1.10 */ toPass?: { /** * timeout for toPass method in milliseconds. + * @since v1.10 */ timeout?: number; /** * probe intervals for toPass method in milliseconds. + * @since v1.10 */ intervals?: Array; }; @@ -307,6 +331,7 @@ interface TestProject { * worker process. * * You can configure entire test project to concurrently run all tests in all files using this option. + * @since v1.10 */ fullyParallel?: boolean; @@ -318,6 +343,7 @@ interface TestProject { * my-test.spec.ts my-suite my-test`. * * `grep` option is also useful for [tagging tests](https://playwright.dev/docs/test-annotations#tag-tests). + * @since v1.10 */ grep?: RegExp|Array; @@ -327,6 +353,7 @@ interface TestProject { * and in the [command line](https://playwright.dev/docs/test-cli) with the `--grep-invert` option. * * `grepInvert` option is also useful for [tagging tests](https://playwright.dev/docs/test-annotations#tag-tests). + * @since v1.10 */ grepInvert?: RegExp|Array; @@ -362,11 +389,13 @@ interface TestProject { * }); * ``` * + * @since v1.44 */ ignoreSnapshots?: boolean; /** * Metadata that will be put directly to the test report serialized as JSON. + * @since v1.10 */ metadata?: Metadata; @@ -376,6 +405,7 @@ interface TestProject { * **NOTE** Playwright executes the configuration file multiple times. Do not dynamically produce non-stable values in * your configuration. * + * @since v1.10 */ name?: string; @@ -404,6 +434,7 @@ interface TestProject { * * Use [testConfig.outputDir](https://playwright.dev/docs/api/class-testconfig#test-config-output-dir) to change this * option for all projects. + * @since v1.10 */ outputDir?: string; @@ -412,6 +443,7 @@ interface TestProject { * * Use [testConfig.repeatEach](https://playwright.dev/docs/api/class-testconfig#test-config-repeat-each) to change * this option for all projects. + * @since v1.10 */ repeatEach?: number; @@ -421,6 +453,7 @@ interface TestProject { * [testProject.testDir](https://playwright.dev/docs/api/class-testproject#test-project-test-dir) are explicitly * specified, Playwright will ignore any test files matching `.gitignore` entries. This option allows to override that * behavior. + * @since v1.45 */ respectGitIgnore?: boolean; @@ -433,6 +466,7 @@ interface TestProject { * * Use [testConfig.retries](https://playwright.dev/docs/api/class-testconfig#test-config-retries) to change this * option for all projects. + * @since v1.10 */ retries?: number; @@ -447,6 +481,7 @@ interface TestProject { * This path will serve as the base directory for each test file snapshot directory. Setting `snapshotDir` to * `'snapshots'`, the [testInfo.snapshotDir](https://playwright.dev/docs/api/class-testinfo#test-info-snapshot-dir) * would resolve to `snapshots/a.spec.js-snapshots`. + * @since v1.10 */ snapshotDir?: string; @@ -561,6 +596,7 @@ interface TestProject { * `/__screenshots__/chromium/example.spec.ts/..`. * 1. Since `snapshotPathTemplate` resolves to relative path, it will be resolved relative to `configDir`. * 1. Forward slashes `"/"` can be used as path separators on any platform. + * @since v1.28 */ snapshotPathTemplate?: string; @@ -610,6 +646,7 @@ interface TestProject { * }); * ``` * + * @since v1.34 */ teardown?: string; @@ -660,6 +697,7 @@ interface TestProject { * * Use [testConfig.testDir](https://playwright.dev/docs/api/class-testconfig#test-config-test-dir) to change this * option for all projects. + * @since v1.10 */ testDir?: string; @@ -671,6 +709,7 @@ interface TestProject { * * Use [testConfig.testIgnore](https://playwright.dev/docs/api/class-testconfig#test-config-test-ignore) to change * this option for all projects. + * @since v1.10 */ testIgnore?: string|RegExp|Array; @@ -684,6 +723,7 @@ interface TestProject { * * Use [testConfig.testMatch](https://playwright.dev/docs/api/class-testconfig#test-config-test-match) to change this * option for all projects. + * @since v1.10 */ testMatch?: string|RegExp|Array; @@ -697,6 +737,7 @@ interface TestProject { * * Use [testConfig.timeout](https://playwright.dev/docs/api/class-testconfig#test-config-timeout) to change this * option for all projects. + * @since v1.10 */ timeout?: number; @@ -738,6 +779,7 @@ interface TestProject { * }); * ``` * + * @since v1.52 */ workers?: number|string; } @@ -751,84 +793,101 @@ export interface Project extends TestProject { /** * See [testProject.use](https://playwright.dev/docs/api/class-testproject#test-project-use). + * @since v1.10 */ use: UseOptions; /** * See [testProject.dependencies](https://playwright.dev/docs/api/class-testproject#test-project-dependencies). + * @since v1.31 */ dependencies: Array; /** * See [testProject.grep](https://playwright.dev/docs/api/class-testproject#test-project-grep). + * @since v1.10 */ grep: RegExp|Array; /** * See [testProject.grepInvert](https://playwright.dev/docs/api/class-testproject#test-project-grep-invert). + * @since v1.10 */ grepInvert: null|RegExp|Array; /** * See [testProject.ignoreSnapshots](https://playwright.dev/docs/api/class-testproject#test-project-ignore-snapshots). + * @since v1.59 */ ignoreSnapshots: boolean; /** * See [testProject.metadata](https://playwright.dev/docs/api/class-testproject#test-project-metadata). + * @since v1.10 */ metadata: Metadata; /** * See [testProject.name](https://playwright.dev/docs/api/class-testproject#test-project-name). + * @since v1.10 */ name: string; /** * See [testProject.outputDir](https://playwright.dev/docs/api/class-testproject#test-project-output-dir). + * @since v1.10 */ outputDir: string; /** * See [testProject.repeatEach](https://playwright.dev/docs/api/class-testproject#test-project-repeat-each). + * @since v1.10 */ repeatEach: number; /** * See [testProject.retries](https://playwright.dev/docs/api/class-testproject#test-project-retries). + * @since v1.10 */ retries: number; /** * See [testProject.snapshotDir](https://playwright.dev/docs/api/class-testproject#test-project-snapshot-dir). + * @since v1.10 */ snapshotDir: string; /** * See [testProject.teardown](https://playwright.dev/docs/api/class-testproject#test-project-teardown). + * @since v1.34 */ teardown?: string; /** * See [testProject.testDir](https://playwright.dev/docs/api/class-testproject#test-project-test-dir). + * @since v1.10 */ testDir: string; /** * See [testProject.testIgnore](https://playwright.dev/docs/api/class-testproject#test-project-test-ignore). + * @since v1.10 */ testIgnore: string|RegExp|Array; /** * See [testProject.testMatch](https://playwright.dev/docs/api/class-testproject#test-project-test-match). + * @since v1.10 */ testMatch: string|RegExp|Array; /** * See [testProject.timeout](https://playwright.dev/docs/api/class-testproject#test-project-timeout). + * @since v1.10 */ timeout: number; } @@ -859,6 +918,7 @@ type LiteralUnion = T | (U & { zz_IGNORE_ME?: never }); * }); * ``` * + * @since v1.10 */ interface TestConfig { /** @@ -878,6 +938,7 @@ interface TestConfig { * }); * ``` * + * @since v1.10 */ projects?: Project[]; /** @@ -903,6 +964,7 @@ interface TestConfig { * }); * ``` * + * @since v1.10 */ reporter?: LiteralUnion<'list'|'dot'|'line'|'github'|'json'|'junit'|'null'|'html', string> | ReporterDescription[]; /** @@ -924,6 +986,7 @@ interface TestConfig { * }); * ``` * + * @since v1.10 */ use?: UseOptions; /** @@ -1030,6 +1093,7 @@ interface TestConfig { * }); * ``` * + * @since v1.10 */ webServer?: TestConfigWebServer | TestConfigWebServer[]; /** @@ -1048,11 +1112,13 @@ interface TestConfig { * }); * ``` * + * @since v1.35 */ build?: { /** * Paths to exclude from the transpilation expressed as a list of glob patterns. Typically heavy JS bundles that your * test uses are listed here. + * @since v1.35 */ external?: Array; }; @@ -1082,15 +1148,18 @@ interface TestConfig { * * **NOTE** The structure of the git commit metadata is subject to change. * + * @since v1.51 */ captureGitInfo?: { /** * Whether to capture commit and pull request information such as hash, author, timestamp. + * @since v1.51 */ commit?: boolean; /** * Whether to capture commit diff. + * @since v1.51 */ diff?: boolean; }; @@ -1114,10 +1183,12 @@ interface TestConfig { * }); * ``` * + * @since v1.10 */ expect?: { /** * Default timeout for async expect matchers in milliseconds, defaults to 5000ms. + * @since v1.10 */ timeout?: number; @@ -1125,40 +1196,47 @@ interface TestConfig { * Configuration for the * [expect(page).toHaveScreenshot(name[, options])](https://playwright.dev/docs/api/class-pageassertions#page-assertions-to-have-screenshot-1) * method. + * @since v1.10 */ toHaveScreenshot?: { /** * See [`animations`](https://playwright.dev/docs/api/class-page#page-screenshot-option-animations) in * [page.screenshot([options])](https://playwright.dev/docs/api/class-page#page-screenshot). Defaults to `"disabled"`. + * @since v1.10 */ animations?: "allow"|"disabled"; /** * See [`caret`](https://playwright.dev/docs/api/class-page#page-screenshot-option-caret) in * [page.screenshot([options])](https://playwright.dev/docs/api/class-page#page-screenshot). Defaults to `"hide"`. + * @since v1.10 */ caret?: "hide"|"initial"; /** * An acceptable amount of pixels that could be different, unset by default. + * @since v1.10 */ maxDiffPixels?: number; /** * An acceptable ratio of pixels that are different to the total amount of pixels, between `0` and `1` , unset by * default. + * @since v1.10 */ maxDiffPixelRatio?: number; /** * See [`scale`](https://playwright.dev/docs/api/class-page#page-screenshot-option-scale) in * [page.screenshot([options])](https://playwright.dev/docs/api/class-page#page-screenshot). Defaults to `"css"`. + * @since v1.10 */ scale?: "css"|"device"; /** * See [`style`](https://playwright.dev/docs/api/class-page#page-screenshot-option-style) in * [page.screenshot([options])](https://playwright.dev/docs/api/class-page#page-screenshot). + * @since v1.10 */ stylePath?: string|Array; @@ -1166,6 +1244,7 @@ interface TestConfig { * An acceptable perceived color difference between the same pixel in compared images, ranging from `0` (strict) and * `1` (lax). `"pixelmatch"` comparator computes color difference in * [YIQ color space](https://en.wikipedia.org/wiki/YIQ) and defaults `threshold` value to `0.2`. + * @since v1.10 */ threshold?: number; @@ -1173,6 +1252,7 @@ interface TestConfig { * A template controlling location of the screenshots. See * [testConfig.snapshotPathTemplate](https://playwright.dev/docs/api/class-testconfig#test-config-snapshot-path-template) * for details. + * @since v1.10 */ pathTemplate?: string; }; @@ -1181,12 +1261,14 @@ interface TestConfig { * Configuration for the * [expect(locator).toMatchAriaSnapshot([options])](https://playwright.dev/docs/api/class-locatorassertions#locator-assertions-to-match-aria-snapshot-2) * method. + * @since v1.10 */ toMatchAriaSnapshot?: { /** * A template controlling location of the aria snapshots. See * [testConfig.snapshotPathTemplate](https://playwright.dev/docs/api/class-testconfig#test-config-snapshot-path-template) * for details. + * @since v1.10 */ pathTemplate?: string; @@ -1194,6 +1276,7 @@ interface TestConfig { * Controls how children of the snapshot root are matched against the actual accessibility tree. This is equivalent to * adding a `/children` property at the top of every aria snapshot template. Individual snapshots can override this by * including an explicit `/children` property. + * @since v1.10 */ children?: "contain"|"equal"|"deep-equal"; }; @@ -1202,16 +1285,19 @@ interface TestConfig { * Configuration for the * [expect(value).toMatchSnapshot(name[, options])](https://playwright.dev/docs/api/class-snapshotassertions#snapshot-assertions-to-match-snapshot-1) * method. + * @since v1.10 */ toMatchSnapshot?: { /** * An acceptable amount of pixels that could be different, unset by default. + * @since v1.10 */ maxDiffPixels?: number; /** * An acceptable ratio of pixels that are different to the total amount of pixels, between `0` and `1` , unset by * default. + * @since v1.10 */ maxDiffPixelRatio?: number; @@ -1219,21 +1305,25 @@ interface TestConfig { * An acceptable perceived color difference between the same pixel in compared images, ranging from `0` (strict) and * `1` (lax). `"pixelmatch"` comparator computes color difference in * [YIQ color space](https://en.wikipedia.org/wiki/YIQ) and defaults `threshold` value to `0.2`. + * @since v1.10 */ threshold?: number; }; /** * Configuration for the [expect(value).toPass()](https://playwright.dev/docs/test-assertions#expecttopass) method. + * @since v1.10 */ toPass?: { /** * Probe intervals for toPass method in milliseconds. + * @since v1.10 */ intervals?: Array; /** * Timeout for toPass method in milliseconds. + * @since v1.10 */ timeout?: number; }; @@ -1255,6 +1345,7 @@ interface TestConfig { * }); * ``` * + * @since v1.52 */ failOnFlakyTests?: boolean; @@ -1275,6 +1366,7 @@ interface TestConfig { * }); * ``` * + * @since v1.10 */ forbidOnly?: boolean; @@ -1296,6 +1388,7 @@ interface TestConfig { * }); * ``` * + * @since v1.20 */ fullyParallel?: boolean; @@ -1317,6 +1410,7 @@ interface TestConfig { * }); * ``` * + * @since v1.10 */ globalSetup?: string|Array; @@ -1339,6 +1433,7 @@ interface TestConfig { * }); * ``` * + * @since v1.10 */ globalTeardown?: string|Array; @@ -1358,6 +1453,7 @@ interface TestConfig { * }); * ``` * + * @since v1.10 */ globalTimeout?: number; @@ -1381,6 +1477,7 @@ interface TestConfig { * }); * ``` * + * @since v1.10 */ grep?: RegExp|Array; @@ -1402,6 +1499,7 @@ interface TestConfig { * }); * ``` * + * @since v1.10 */ grepInvert?: RegExp|Array; @@ -1420,6 +1518,7 @@ interface TestConfig { * }); * ``` * + * @since v1.26 */ ignoreSnapshots?: boolean; @@ -1440,6 +1539,7 @@ interface TestConfig { * }); * ``` * + * @since v1.10 */ maxFailures?: number; @@ -1458,6 +1558,7 @@ interface TestConfig { * }); * ``` * + * @since v1.10 */ metadata?: Metadata; @@ -1476,6 +1577,7 @@ interface TestConfig { * }); * ``` * + * @since v1.10 */ name?: string; @@ -1515,6 +1617,7 @@ interface TestConfig { * }); * ``` * + * @since v1.10 */ outputDir?: string; @@ -1537,6 +1640,7 @@ interface TestConfig { * }); * ``` * + * @since v1.10 */ preserveOutput?: "always"|"never"|"failures-only"; @@ -1554,6 +1658,7 @@ interface TestConfig { * }); * ``` * + * @since v1.10 */ quiet?: boolean; @@ -1571,6 +1676,7 @@ interface TestConfig { * }); * ``` * + * @since v1.10 */ repeatEach?: number; @@ -1592,15 +1698,18 @@ interface TestConfig { * * Test files that took more than `threshold` milliseconds are considered slow, and the slowest ones are reported, no * more than `max` number of them. Passing zero as `max` reports all test files that exceed the threshold. + * @since v1.10 */ reportSlowTests?: null|{ /** * The maximum number of slow test files to report. Defaults to `5`. + * @since v1.10 */ max: number; /** * Test file duration in milliseconds that is considered slow. Defaults to 5 minutes. + * @since v1.10 */ threshold: number; }; @@ -1610,6 +1719,7 @@ interface TestConfig { * [testConfig.testDir](https://playwright.dev/docs/api/class-testconfig#test-config-test-dir) nor * [testProject.testDir](https://playwright.dev/docs/api/class-testproject#test-project-test-dir) are explicitly * specified, Playwright will ignore any test files matching `.gitignore` entries. + * @since v1.45 */ respectGitIgnore?: boolean; @@ -1628,6 +1738,7 @@ interface TestConfig { * }); * ``` * + * @since v1.10 */ retries?: number; @@ -1647,15 +1758,18 @@ interface TestConfig { * }); * ``` * + * @since v1.10 */ shard?: null|{ /** * The index of the shard to execute, one-based. + * @since v1.10 */ current: number; /** * The total number of shards. + * @since v1.10 */ total: number; }; @@ -1688,6 +1802,7 @@ interface TestConfig { * This path will serve as the base directory for each test file snapshot directory. Setting `snapshotDir` to * `'snapshots'`, the [testInfo.snapshotDir](https://playwright.dev/docs/api/class-testinfo#test-info-snapshot-dir) * would resolve to `snapshots/a.spec.js-snapshots`. + * @since v1.10 */ snapshotDir?: string; @@ -1802,6 +1917,7 @@ interface TestConfig { * `/__screenshots__/chromium/example.spec.ts/..`. * 1. Since `snapshotPathTemplate` resolves to relative path, it will be resolved relative to `configDir`. * 1. Forward slashes `"/"` can be used as path separators on any platform. + * @since v1.28 */ snapshotPathTemplate?: string; @@ -1822,6 +1938,7 @@ interface TestConfig { * }); * ``` * + * @since v1.57 */ tag?: string|Array; @@ -1839,6 +1956,7 @@ interface TestConfig { * }); * ``` * + * @since v1.10 */ testDir?: string; @@ -1859,6 +1977,7 @@ interface TestConfig { * }); * ``` * + * @since v1.10 */ testIgnore?: string|RegExp|Array; @@ -1881,6 +2000,7 @@ interface TestConfig { * }); * ``` * + * @since v1.10 */ testMatch?: string|RegExp|Array; @@ -1902,6 +2022,7 @@ interface TestConfig { * }); * ``` * + * @since v1.10 */ timeout?: number; @@ -1921,6 +2042,7 @@ interface TestConfig { * }); * ``` * + * @since v1.49 */ tsconfig?: string; @@ -1946,6 +2068,7 @@ interface TestConfig { * }); * ``` * + * @since v1.10 */ updateSnapshots?: "all"|"changed"|"missing"|"none"; @@ -1955,6 +2078,7 @@ interface TestConfig { * - `'3way'` - Generate merge conflict markers in source code. This allows user to manually pick relevant changes, * as if they are resolving a merge conflict in the IDE. * - `'overwrite'` - Overwrite the source code with the new snapshot values. + * @since v1.50 */ updateSourceMethod?: "overwrite"|"3way"|"patch"; @@ -1979,6 +2103,7 @@ interface TestConfig { * }); * ``` * + * @since v1.10 */ workers?: number|string; } @@ -1993,138 +2118,166 @@ export type Metadata = { [key: string]: any }; * [testInfo.config](https://playwright.dev/docs/api/class-testinfo#test-info-config) and is passed to the test * reporters. To see the format of Playwright configuration file, please see * [TestConfig](https://playwright.dev/docs/api/class-testconfig) instead. + * @since v1.10 */ export interface FullConfig { /** * List of resolved projects. + * @since v1.10 */ projects: FullProject[]; /** * See [testConfig.reporter](https://playwright.dev/docs/api/class-testconfig#test-config-reporter). + * @since v1.10 */ reporter: ReporterDescription[]; /** * See [testConfig.webServer](https://playwright.dev/docs/api/class-testconfig#test-config-web-server). + * @since v1.10 */ webServer: TestConfigWebServer | null; /** * Path to the configuration file used to run the tests. The value is an empty string if no config file was used. + * @since v1.20 */ configFile?: string; /** * See [testConfig.forbidOnly](https://playwright.dev/docs/api/class-testconfig#test-config-forbid-only). + * @since v1.10 */ forbidOnly: boolean; /** * See [testConfig.fullyParallel](https://playwright.dev/docs/api/class-testconfig#test-config-fully-parallel). + * @since v1.20 */ fullyParallel: boolean; /** * See [testConfig.globalSetup](https://playwright.dev/docs/api/class-testconfig#test-config-global-setup). + * @since v1.10 */ globalSetup: null|string; /** * See [testConfig.globalTeardown](https://playwright.dev/docs/api/class-testconfig#test-config-global-teardown). + * @since v1.10 */ globalTeardown: null|string; /** * See [testConfig.globalTimeout](https://playwright.dev/docs/api/class-testconfig#test-config-global-timeout). + * @since v1.10 */ globalTimeout: number; /** * See [testConfig.grep](https://playwright.dev/docs/api/class-testconfig#test-config-grep). + * @since v1.10 */ grep: RegExp|Array; /** * See [testConfig.grepInvert](https://playwright.dev/docs/api/class-testconfig#test-config-grep-invert). + * @since v1.10 */ grepInvert: null|RegExp|Array; /** * See [testConfig.maxFailures](https://playwright.dev/docs/api/class-testconfig#test-config-max-failures). + * @since v1.10 */ maxFailures: number; /** * See [testConfig.metadata](https://playwright.dev/docs/api/class-testconfig#test-config-metadata). + * @since v1.10 */ metadata: Metadata; /** * See [testConfig.preserveOutput](https://playwright.dev/docs/api/class-testconfig#test-config-preserve-output). + * @since v1.10 */ preserveOutput: "always"|"never"|"failures-only"; /** * See [testConfig.quiet](https://playwright.dev/docs/api/class-testconfig#test-config-quiet). + * @since v1.10 */ quiet: boolean; /** * See [testConfig.reportSlowTests](https://playwright.dev/docs/api/class-testconfig#test-config-report-slow-tests). + * @since v1.10 */ reportSlowTests: null|{ /** * The maximum number of slow test files to report. + * @since v1.10 */ max: number; /** * Test file duration in milliseconds that is considered slow. + * @since v1.10 */ threshold: number; }; /** * Base directory for all relative paths used in the reporters. + * @since v1.20 */ rootDir: string; /** * See [testConfig.shard](https://playwright.dev/docs/api/class-testconfig#test-config-shard). + * @since v1.10 */ shard: null|{ /** * The total number of shards. + * @since v1.10 */ total: number; /** * The index of the shard to execute, one-based. + * @since v1.10 */ current: number; }; /** * Resolved global tags. See [testConfig.tag](https://playwright.dev/docs/api/class-testconfig#test-config-tag). + * @since v1.57 */ tags: Array; /** * See [testConfig.updateSnapshots](https://playwright.dev/docs/api/class-testconfig#test-config-update-snapshots). + * @since v1.10 */ updateSnapshots: "all"|"changed"|"missing"|"none"; /** * See * [testConfig.updateSourceMethod](https://playwright.dev/docs/api/class-testconfig#test-config-update-source-method). + * @since v1.50 */ updateSourceMethod: "overwrite"|"3way"|"patch"; /** * Playwright version. + * @since v1.20 */ version: string; /** * See [testConfig.workers](https://playwright.dev/docs/api/class-testconfig#test-config-workers). + * @since v1.10 */ workers: number; } @@ -2147,6 +2300,7 @@ export interface FullConfig { * }); * ``` * + * @since v1.10 */ export interface TestInfo { /** @@ -2180,6 +2334,7 @@ export interface TestInfo { * const nestedPath = test.info().snapshotPath('dir', 'subdir', 'snapshot.txt'); * ``` * + * @since v1.10 * @param name The name of the snapshot or the path segments to define the snapshot file path. Snapshots with the same name in the * same test file are expected to be the same. * @@ -2219,6 +2374,7 @@ export interface TestInfo { * const nestedPath = test.info().snapshotPath('dir', 'subdir', 'snapshot.txt'); * ``` * + * @since v1.10 * @param name The name of the snapshot or the path segments to define the snapshot file path. Snapshots with the same name in the * same test file are expected to be the same. * @@ -2261,6 +2417,7 @@ export interface TestInfo { * automatically takes care of copying attached files to a location that is accessible to reporters. You can safely * remove the attachment after awaiting the attach call. * + * @since v1.10 * @param name Attachment name. The name will also be sanitized and used as the prefix of file name when saving to disk. * @param options */ @@ -2268,6 +2425,7 @@ export interface TestInfo { /** * Attachment body. Mutually exclusive with * [`path`](https://playwright.dev/docs/api/class-testinfo#test-info-attach-option-path). + * @since v1.10 */ body?: string|Buffer; @@ -2276,12 +2434,14 @@ export interface TestInfo { * `'image/png'`. If omitted, content type is inferred based on the * [`path`](https://playwright.dev/docs/api/class-testinfo#test-info-attach-option-path), or defaults to `text/plain` * for [string] attachments and `application/octet-stream` for [Buffer] attachments. + * @since v1.10 */ contentType?: string; /** * Path on the filesystem to the attached file. Mutually exclusive with * [`body`](https://playwright.dev/docs/api/class-testinfo#test-info-attach-option-body). + * @since v1.10 */ path?: string; }): Promise; @@ -2291,12 +2451,14 @@ export interface TestInfo { * failing. This is useful for documentation purposes to acknowledge that some functionality is broken until it is * fixed. This is similar to * [test.fail([title, details, body, condition, callback, description])](https://playwright.dev/docs/api/class-test#test-fail). + * @since v1.10 */ fail(): void; /** * Conditionally mark the currently running test as "should fail" with an optional description. This is similar to * [test.fail([title, details, body, condition, callback, description])](https://playwright.dev/docs/api/class-test#test-fail). + * @since v1.10 * @param condition Test is marked as "should fail" when the condition is `true`. * @param description Optional description that will be reflected in a test report. */ @@ -2305,12 +2467,14 @@ export interface TestInfo { /** * Mark a test as "fixme", with the intention to fix it. Test is immediately aborted. This is similar to * [test.fixme([title, details, body, condition, callback, description])](https://playwright.dev/docs/api/class-test#test-fixme). + * @since v1.10 */ fixme(): void; /** * Conditionally mark the currently running test as "fixme" with an optional description. This is similar to * [test.fixme([title, details, body, condition, callback, description])](https://playwright.dev/docs/api/class-test#test-fixme). + * @since v1.10 * @param condition Test is marked as "fixme" when the condition is `true`. * @param description Optional description that will be reflected in a test report. */ @@ -2336,6 +2500,7 @@ export interface TestInfo { * > However, this path must stay within the * [testInfo.outputDir](https://playwright.dev/docs/api/class-testinfo#test-info-output-dir) directory for each test * (i.e. `test-results/a-test-title`), otherwise it will throw. + * @since v1.10 * @param pathSegments Path segments to append at the end of the resulting path. */ outputPath(...pathSegments: ReadonlyArray): string; @@ -2356,6 +2521,7 @@ export interface TestInfo { * }); * ``` * + * @since v1.10 * @param timeout Timeout in milliseconds. */ setTimeout(timeout: number): void; @@ -2363,12 +2529,14 @@ export interface TestInfo { /** * Unconditionally skip the currently running test. Test is immediately aborted. This is similar to * [test.skip([title, details, body, condition, callback, description])](https://playwright.dev/docs/api/class-test#test-skip). + * @since v1.10 */ skip(): void; /** * Conditionally skips the currently running test with an optional description. This is similar to * [test.skip([title, details, body, condition, callback, description])](https://playwright.dev/docs/api/class-test#test-skip). + * @since v1.10 * @param condition A skip condition. Test is skipped when the condition is `true`. * @param description Optional description that will be reflected in a test report. */ @@ -2377,6 +2545,7 @@ export interface TestInfo { /** * Marks the currently running test as "slow", giving it triple the default timeout. This is similar to * [test.slow([condition, callback, description])](https://playwright.dev/docs/api/class-test#test-slow). + * @since v1.10 */ slow(): void; @@ -2384,6 +2553,7 @@ export interface TestInfo { * Conditionally mark the currently running test as "slow" with an optional description, giving it triple the default * timeout. This is similar to * [test.slow([condition, callback, description])](https://playwright.dev/docs/api/class-test#test-slow). + * @since v1.10 * @param condition Test is marked as "slow" when the condition is `true`. * @param description Optional description that will be reflected in a test report. */ @@ -2395,20 +2565,24 @@ export interface TestInfo { * test belongs to and file-level annotations for the test file. * * Learn more about [test annotations](https://playwright.dev/docs/test-annotations). + * @since v1.10 */ annotations: Array<{ /** * Annotation type, for example `'skip'` or `'fail'`. + * @since v1.10 */ type: string; /** * Optional description. + * @since v1.10 */ description?: string; /** * Optional location in the source where the annotation is added. + * @since v1.10 */ location?: Location; }>; @@ -2419,37 +2593,44 @@ export interface TestInfo { * To add an attachment, use * [testInfo.attach(name[, options])](https://playwright.dev/docs/api/class-testinfo#test-info-attach) instead of * directly pushing onto this array. + * @since v1.10 */ attachments: Array<{ /** * Attachment name. + * @since v1.10 */ name: string; /** * Content type of this attachment to properly present in the report, for example `'application/json'` or * `'image/png'`. + * @since v1.10 */ contentType: string; /** * Optional path on the filesystem to the attached file. + * @since v1.10 */ path?: string; /** * Optional attachment body used instead of a file. + * @since v1.10 */ body?: Buffer; }>; /** * Column number where the currently running test is declared. + * @since v1.10 */ column: number; /** * Processed configuration from the [configuration file](https://playwright.dev/docs/test-configuration). + * @since v1.10 */ config: FullConfig; @@ -2457,17 +2638,20 @@ export interface TestInfo { * The number of milliseconds the test took to finish. Always zero before the test finishes, either successfully or * not. Can be used in * [test.afterEach([title, hookFunction])](https://playwright.dev/docs/api/class-test#test-after-each) hook. + * @since v1.10 */ duration: number; /** * First error thrown during test execution, if any. This is equal to the first element in * [testInfo.errors](https://playwright.dev/docs/api/class-testinfo#test-info-errors). + * @since v1.10 */ error?: TestInfoError; /** * Errors thrown during test execution, if any. + * @since v1.10 */ errors: Array; @@ -2490,27 +2674,32 @@ export interface TestInfo { * }); * ``` * + * @since v1.10 */ expectedStatus: "passed"|"failed"|"timedOut"|"skipped"|"interrupted"; /** * Absolute path to a file where the currently running test is declared. + * @since v1.10 */ file: string; /** * Test function as passed to `test(title, testFunction)`. + * @since v1.10 */ fn: Function; /** * Line number where the currently running test is declared. + * @since v1.10 */ line: number; /** * Absolute path to the output directory for this specific test run. Each test run gets its own directory so they * cannot conflict. + * @since v1.10 */ outputDir: string; @@ -2521,17 +2710,20 @@ export interface TestInfo { * * Also available as `process.env.TEST_PARALLEL_INDEX`. Learn more about * [parallelism and sharding](https://playwright.dev/docs/test-parallel) with Playwright Test. + * @since v1.10 */ parallelIndex: number; /** * Processed project configuration from the [configuration file](https://playwright.dev/docs/test-configuration). + * @since v1.10 */ project: FullProject; /** * Specifies a unique repeat index when running in "repeat each" mode. This mode is enabled by passing `--repeat-each` * to the [command line](https://playwright.dev/docs/test-cli). + * @since v1.10 */ repeatEachIndex: number; @@ -2557,6 +2749,7 @@ export interface TestInfo { * }); * ``` * + * @since v1.10 */ retry: number; @@ -2567,6 +2760,7 @@ export interface TestInfo { * This property does not account for the * [testProject.snapshotPathTemplate](https://playwright.dev/docs/api/class-testproject#test-project-snapshot-path-template) * configuration. + * @since v1.10 */ snapshotDir: string; @@ -2580,6 +2774,7 @@ export interface TestInfo { * the platform, you can set `testInfo.snapshotSuffix` equal to `process.platform`. In this case * `expect(value).toMatchSnapshot(snapshotName)` will use different snapshots depending on the platform. Learn more * about [snapshots](https://playwright.dev/docs/test-snapshots). + * @since v1.10 */ snapshotSuffix: string; @@ -2600,6 +2795,7 @@ export interface TestInfo { * }); * ``` * + * @since v1.10 */ status?: "passed"|"failed"|"timedOut"|"skipped"|"interrupted"; @@ -2608,11 +2804,13 @@ export interface TestInfo { * * **NOTE** Any changes made to this list while the test is running will not be visible to test reporters. * + * @since v1.43 */ tags: Array; /** * Test id matching the test case id in the reporter API. + * @since v1.32 */ testId: string; @@ -2631,16 +2829,19 @@ export interface TestInfo { * }); * ``` * + * @since v1.10 */ timeout: number; /** * The title of the currently running test as passed to `test(title, testFunction)`. + * @since v1.10 */ title: string; /** * The full title path starting with the test file name. + * @since v1.10 */ titlePath: Array; @@ -2650,6 +2851,7 @@ export interface TestInfo { * * Also available as `process.env.TEST_WORKER_INDEX`. Learn more about [parallelism and sharding](https://playwright.dev/docs/test-parallel) * with Playwright Test. + * @since v1.10 */ workerIndex: number; } @@ -2686,6 +2888,7 @@ type ConditionBody = (args: TestArgs) => boolean; * }); * ``` * + * @since v1.10 */ export interface TestType { /** @@ -2759,6 +2962,7 @@ export interface TestType { * [testInfo.annotations](https://playwright.dev/docs/api/class-testinfo#test-info-annotations). * * Learn more about [test annotations](https://playwright.dev/docs/test-annotations). + * @since v1.10 * @param title Test title. * @param details Additional test details. * @param body Test body that takes one or two arguments: an object with fixtures and optional @@ -2836,6 +3040,7 @@ export interface TestType { * [testInfo.annotations](https://playwright.dev/docs/api/class-testinfo#test-info-annotations). * * Learn more about [test annotations](https://playwright.dev/docs/test-annotations). + * @since v1.10 * @param title Test title. * @param details Additional test details. * @param body Test body that takes one or two arguments: an object with fixtures and optional @@ -2856,6 +3061,7 @@ export interface TestType { * }); * ``` * + * @since v1.10 * @param title Test title. * @param details See [test.(call)(title[, details, body])](https://playwright.dev/docs/api/class-test#test-call) for test details * description. @@ -2876,6 +3082,7 @@ export interface TestType { * }); * ``` * + * @since v1.10 * @param title Test title. * @param details See [test.(call)(title[, details, body])](https://playwright.dev/docs/api/class-test#test-call) for test details * description. @@ -2972,6 +3179,7 @@ export interface TestType { * ``` * * Learn more about [test annotations](https://playwright.dev/docs/test-annotations). + * @since v1.10 * @param title Group title. * @param details Additional details for all tests in the group. * @param callback A callback that is run immediately when calling @@ -3067,6 +3275,7 @@ export interface TestType { * ``` * * Learn more about [test annotations](https://playwright.dev/docs/test-annotations). + * @since v1.10 * @param title Group title. * @param details Additional details for all tests in the group. * @param callback A callback that is run immediately when calling @@ -3162,6 +3371,7 @@ export interface TestType { * ``` * * Learn more about [test annotations](https://playwright.dev/docs/test-annotations). + * @since v1.10 * @param title Group title. * @param details Additional details for all tests in the group. * @param callback A callback that is run immediately when calling @@ -3257,6 +3467,7 @@ export interface TestType { * ``` * * Learn more about [test annotations](https://playwright.dev/docs/test-annotations). + * @since v1.10 * @param title Group title. * @param details Additional details for all tests in the group. * @param callback A callback that is run immediately when calling @@ -3293,6 +3504,7 @@ export interface TestType { * }); * ``` * + * @since v1.10 * @param title Group title. * @param details See [test.describe([title, details, callback])](https://playwright.dev/docs/api/class-test#test-describe) for * details description. @@ -3329,6 +3541,7 @@ export interface TestType { * }); * ``` * + * @since v1.10 * @param title Group title. * @param details See [test.describe([title, details, callback])](https://playwright.dev/docs/api/class-test#test-describe) for * details description. @@ -3365,6 +3578,7 @@ export interface TestType { * }); * ``` * + * @since v1.10 * @param title Group title. * @param details See [test.describe([title, details, callback])](https://playwright.dev/docs/api/class-test#test-describe) for * details description. @@ -3400,6 +3614,7 @@ export interface TestType { * }); * ``` * + * @since v1.10 * @param title Group title. * @param details See [test.describe([title, details, callback])](https://playwright.dev/docs/api/class-test#test-describe) for * details description. @@ -3434,6 +3649,7 @@ export interface TestType { * }); * ``` * + * @since v1.10 * @param title Group title. * @param details See [test.describe([title, details, callback])](https://playwright.dev/docs/api/class-test#test-describe) for * details description. @@ -3468,6 +3684,7 @@ export interface TestType { * }); * ``` * + * @since v1.10 * @param title Group title. * @param details See [test.describe([title, details, callback])](https://playwright.dev/docs/api/class-test#test-describe) for * details description. @@ -3503,6 +3720,7 @@ export interface TestType { * }); * ``` * + * @since v1.25 * @param title Group title. * @param details See [test.describe([title, details, callback])](https://playwright.dev/docs/api/class-test#test-describe) for * details description. @@ -3537,6 +3755,7 @@ export interface TestType { * }); * ``` * + * @since v1.25 * @param title Group title. * @param details See [test.describe([title, details, callback])](https://playwright.dev/docs/api/class-test#test-describe) for * details description. @@ -3571,6 +3790,7 @@ export interface TestType { * }); * ``` * + * @since v1.25 * @param title Group title. * @param details See [test.describe([title, details, callback])](https://playwright.dev/docs/api/class-test#test-describe) for * details description. @@ -3611,6 +3831,7 @@ export interface TestType { * }); * ``` * + * @since v1.10 * @param title Group title. * @param details See [test.describe([title, details, callback])](https://playwright.dev/docs/api/class-test#test-describe) for * details description. @@ -3650,6 +3871,7 @@ export interface TestType { * }); * ``` * + * @since v1.10 * @param title Group title. * @param details See [test.describe([title, details, callback])](https://playwright.dev/docs/api/class-test#test-describe) for * details description. @@ -3689,6 +3911,7 @@ export interface TestType { * }); * ``` * + * @since v1.10 * @param title Group title. * @param details See [test.describe([title, details, callback])](https://playwright.dev/docs/api/class-test#test-describe) for * details description. @@ -3728,6 +3951,7 @@ export interface TestType { * }); * ``` * + * @since v1.10 * @param title Group title. * @param details See [test.describe([title, details, callback])](https://playwright.dev/docs/api/class-test#test-describe) for * details description. @@ -3771,6 +3995,7 @@ export interface TestType { * }); * ``` * + * @since v1.10 * @param title Group title. * @param details See [test.describe([title, details, callback])](https://playwright.dev/docs/api/class-test#test-describe) for * details description. @@ -3813,6 +4038,7 @@ export interface TestType { * }); * ``` * + * @since v1.10 * @param title Group title. * @param details See [test.describe([title, details, callback])](https://playwright.dev/docs/api/class-test#test-describe) for * details description. @@ -3855,6 +4081,7 @@ export interface TestType { * }); * ``` * + * @since v1.10 * @param title Group title. * @param details See [test.describe([title, details, callback])](https://playwright.dev/docs/api/class-test#test-describe) for * details description. @@ -3897,6 +4124,7 @@ export interface TestType { * }); * ``` * + * @since v1.10 * @param title Group title. * @param details See [test.describe([title, details, callback])](https://playwright.dev/docs/api/class-test#test-describe) for * details description. @@ -3937,6 +4165,7 @@ export interface TestType { * }); * ``` * + * @since v1.10 * @param title Group title. * @param details See [test.describe([title, details, callback])](https://playwright.dev/docs/api/class-test#test-describe) for * details description. @@ -3977,6 +4206,7 @@ export interface TestType { * }); * ``` * + * @since v1.10 * @param title Group title. * @param details See [test.describe([title, details, callback])](https://playwright.dev/docs/api/class-test#test-describe) for * details description. @@ -4017,6 +4247,7 @@ export interface TestType { * }); * ``` * + * @since v1.10 * @param title Group title. * @param details See [test.describe([title, details, callback])](https://playwright.dev/docs/api/class-test#test-describe) for * details description. @@ -4054,6 +4285,7 @@ export interface TestType { * }); * ``` * + * @since v1.10 * @param title Group title. * @param details See [test.describe([title, details, callback])](https://playwright.dev/docs/api/class-test#test-describe) for * details description. @@ -4090,6 +4322,7 @@ export interface TestType { * }); * ``` * + * @since v1.10 * @param title Group title. * @param details See [test.describe([title, details, callback])](https://playwright.dev/docs/api/class-test#test-describe) for * details description. @@ -4126,6 +4359,7 @@ export interface TestType { * }); * ``` * + * @since v1.10 * @param title Group title. * @param details See [test.describe([title, details, callback])](https://playwright.dev/docs/api/class-test#test-describe) for * details description. @@ -4204,6 +4438,7 @@ export interface TestType { * }); * ``` * + * @since v1.10 * @param options */ configure: (options: { mode?: 'default' | 'parallel' | 'serial', retries?: number, timeout?: number }) => void; @@ -4279,6 +4514,7 @@ export interface TestType { * }); * ``` * + * @since v1.10 * @param title Test title. * @param details See [test.(call)(title[, details, body])](https://playwright.dev/docs/api/class-test#test-call) for test details * description. @@ -4360,6 +4596,7 @@ export interface TestType { * }); * ``` * + * @since v1.10 * @param title Test title. * @param details See [test.(call)(title[, details, body])](https://playwright.dev/docs/api/class-test#test-call) for test details * description. @@ -4441,6 +4678,7 @@ export interface TestType { * }); * ``` * + * @since v1.10 * @param title Test title. * @param details See [test.(call)(title[, details, body])](https://playwright.dev/docs/api/class-test#test-call) for test details * description. @@ -4522,6 +4760,7 @@ export interface TestType { * }); * ``` * + * @since v1.10 * @param title Test title. * @param details See [test.(call)(title[, details, body])](https://playwright.dev/docs/api/class-test#test-call) for test details * description. @@ -4603,6 +4842,7 @@ export interface TestType { * }); * ``` * + * @since v1.10 * @param title Test title. * @param details See [test.(call)(title[, details, body])](https://playwright.dev/docs/api/class-test#test-call) for test details * description. @@ -4682,6 +4922,7 @@ export interface TestType { * }); * ``` * + * @since v1.10 * @param title Test title. * @param details See [test.(call)(title[, details, body])](https://playwright.dev/docs/api/class-test#test-call) for test details * description. @@ -4760,6 +5001,7 @@ export interface TestType { * }); * ``` * + * @since v1.10 * @param title Test title. * @param details See [test.(call)(title[, details, body])](https://playwright.dev/docs/api/class-test#test-call) for test details * description. @@ -4838,6 +5080,7 @@ export interface TestType { * }); * ``` * + * @since v1.10 * @param title Test title. * @param details See [test.(call)(title[, details, body])](https://playwright.dev/docs/api/class-test#test-call) for test details * description. @@ -4916,6 +5159,7 @@ export interface TestType { * }); * ``` * + * @since v1.10 * @param title Test title. * @param details See [test.(call)(title[, details, body])](https://playwright.dev/docs/api/class-test#test-call) for test details * description. @@ -4994,6 +5238,7 @@ export interface TestType { * }); * ``` * + * @since v1.10 * @param title Test title. * @param details See [test.(call)(title[, details, body])](https://playwright.dev/docs/api/class-test#test-call) for test details * description. @@ -5072,6 +5317,7 @@ export interface TestType { * }); * ``` * + * @since v1.10 * @param title Test title. * @param details See [test.(call)(title[, details, body])](https://playwright.dev/docs/api/class-test#test-call) for test details * description. @@ -5149,6 +5395,7 @@ export interface TestType { * }); * ``` * + * @since v1.10 * @param title Test title. * @param details See [test.(call)(title[, details, body])](https://playwright.dev/docs/api/class-test#test-call) for test details * description. @@ -5226,6 +5473,7 @@ export interface TestType { * }); * ``` * + * @since v1.10 * @param title Test title. * @param details See [test.(call)(title[, details, body])](https://playwright.dev/docs/api/class-test#test-call) for test details * description. @@ -5303,6 +5551,7 @@ export interface TestType { * }); * ``` * + * @since v1.10 * @param title Test title. * @param details See [test.(call)(title[, details, body])](https://playwright.dev/docs/api/class-test#test-call) for test details * description. @@ -5380,6 +5629,7 @@ export interface TestType { * }); * ``` * + * @since v1.10 * @param title Test title. * @param details See [test.(call)(title[, details, body])](https://playwright.dev/docs/api/class-test#test-call) for test details * description. @@ -5457,6 +5707,7 @@ export interface TestType { * }); * ``` * + * @since v1.10 * @param title Test title. * @param details See [test.(call)(title[, details, body])](https://playwright.dev/docs/api/class-test#test-call) for test details * description. @@ -5492,6 +5743,7 @@ export interface TestType { * }); * ``` * + * @since v1.49 * @param title Test title. * @param details See [test.describe([title, details, callback])](https://playwright.dev/docs/api/class-test#test-describe) for test * details description. @@ -5522,6 +5774,7 @@ export interface TestType { * }); * ``` * + * @since v1.49 * @param title Test title. * @param details See [test.describe([title, details, callback])](https://playwright.dev/docs/api/class-test#test-describe) for test * details description. @@ -5583,6 +5836,7 @@ export interface TestType { * }); * ``` * + * @since v1.10 * @param condition Test is marked as "slow" when the condition is `true`. * @param callback A function that returns whether to mark as "slow", based on test fixtures. Test or tests are marked as "slow" when * the return value is `true`. @@ -5641,6 +5895,7 @@ export interface TestType { * }); * ``` * + * @since v1.10 * @param condition Test is marked as "slow" when the condition is `true`. * @param callback A function that returns whether to mark as "slow", based on test fixtures. Test or tests are marked as "slow" when * the return value is `true`. @@ -5699,6 +5954,7 @@ export interface TestType { * }); * ``` * + * @since v1.10 * @param condition Test is marked as "slow" when the condition is `true`. * @param callback A function that returns whether to mark as "slow", based on test fixtures. Test or tests are marked as "slow" when * the return value is `true`. @@ -5756,6 +6012,7 @@ export interface TestType { * }); * ``` * + * @since v1.10 * @param timeout Timeout in milliseconds. */ setTimeout(timeout: number): void; @@ -5807,6 +6064,7 @@ export interface TestType { * }); * ``` * + * @since v1.10 * @param title Hook title. * @param hookFunction Hook function that takes one or two arguments: an object with fixtures and optional * [TestInfo](https://playwright.dev/docs/api/class-testinfo). @@ -5860,6 +6118,7 @@ export interface TestType { * }); * ``` * + * @since v1.10 * @param title Hook title. * @param hookFunction Hook function that takes one or two arguments: an object with fixtures and optional * [TestInfo](https://playwright.dev/docs/api/class-testinfo). @@ -5912,6 +6171,7 @@ export interface TestType { * }); * ``` * + * @since v1.10 * @param title Hook title. * @param hookFunction Hook function that takes one or two arguments: an object with fixtures and optional * [TestInfo](https://playwright.dev/docs/api/class-testinfo). @@ -5964,6 +6224,7 @@ export interface TestType { * }); * ``` * + * @since v1.10 * @param title Hook title. * @param hookFunction Hook function that takes one or two arguments: an object with fixtures and optional * [TestInfo](https://playwright.dev/docs/api/class-testinfo). @@ -6018,6 +6279,7 @@ export interface TestType { * }); * ``` * + * @since v1.10 * @param title Hook title. * @param hookFunction Hook function that takes one or two arguments: an object with worker fixtures and optional * [TestInfo](https://playwright.dev/docs/api/class-testinfo). @@ -6072,6 +6334,7 @@ export interface TestType { * }); * ``` * + * @since v1.10 * @param title Hook title. * @param hookFunction Hook function that takes one or two arguments: an object with worker fixtures and optional * [TestInfo](https://playwright.dev/docs/api/class-testinfo). @@ -6113,6 +6376,7 @@ export interface TestType { * }); * ``` * + * @since v1.10 * @param title Hook title. * @param hookFunction Hook function that takes one or two arguments: an object with worker fixtures and optional * [TestInfo](https://playwright.dev/docs/api/class-testinfo). @@ -6154,6 +6418,7 @@ export interface TestType { * }); * ``` * + * @since v1.10 * @param title Hook title. * @param hookFunction Hook function that takes one or two arguments: an object with worker fixtures and optional * [TestInfo](https://playwright.dev/docs/api/class-testinfo). @@ -6199,6 +6464,7 @@ export interface TestType { * }); * ``` * + * @since v1.10 * @param options An object with local options. */ use(fixtures: Fixtures<{}, {}, TestArgs, WorkerArgs>): void; @@ -6356,6 +6622,7 @@ export interface TestType { * }); * ``` * + * @since v1.10 * @param title Step name. * @param body Step body. * @param options @@ -6515,6 +6782,7 @@ export interface TestType { * }); * ``` * + * @since v1.10 * @param title Step name. * @param body Step body. * @param options @@ -6543,6 +6811,7 @@ export interface TestType { * }); * ``` * + * @since v1.50 * @param title Step name. * @param body Step body. * @param options @@ -6560,6 +6829,7 @@ export interface TestType { * }); * ``` * + * @since v1.10 */ expect: Expect<{}>; /** @@ -6627,6 +6897,7 @@ export interface TestType { * ``` * * Learn more about [fixtures](https://playwright.dev/docs/test-fixtures) and [parametrizing tests](https://playwright.dev/docs/test-parameterize). + * @since v1.10 * @param fixtures An object containing fixtures and/or options. Learn more about [fixtures format](https://playwright.dev/docs/test-fixtures). */ extend(fixtures: Fixtures): TestType; @@ -6646,6 +6917,7 @@ export interface TestType { * }); * ``` * + * @since v1.10 */ info(): TestInfo; } @@ -6742,6 +7014,7 @@ type ConnectOptions = { * }); * ``` * + * @since v1.10 */ export interface PlaywrightWorkerOptions { /** @@ -6761,6 +7034,7 @@ export interface PlaywrightWorkerOptions { * }); * ``` * + * @since v1.10 */ browserName: BrowserName; defaultBrowserType: BrowserName; @@ -6782,6 +7056,7 @@ export interface PlaywrightWorkerOptions { * }); * ``` * + * @since v1.10 */ headless: boolean; /** @@ -6811,6 +7086,7 @@ export interface PlaywrightWorkerOptions { * }); * ``` * + * @since v1.10 */ channel: BrowserChannel | undefined; /** @@ -6843,6 +7119,7 @@ export interface PlaywrightWorkerOptions { * }); * ``` * + * @since v1.10 */ launchOptions: Omit; /** @@ -6868,6 +7145,7 @@ export interface PlaywrightWorkerOptions { * launching a browser locally, and any launch options like * [testOptions.headless](https://playwright.dev/docs/api/class-testoptions#test-options-headless) or * [testOptions.channel](https://playwright.dev/docs/api/class-testoptions#test-options-channel) are ignored. + * @since v1.10 */ connectOptions: ConnectOptions | undefined; /** @@ -6891,6 +7169,7 @@ export interface PlaywrightWorkerOptions { * ``` * * Learn more about [automatic screenshots](https://playwright.dev/docs/test-use-options#recording-options). + * @since v1.10 */ screenshot: ScreenshotMode | { mode: ScreenshotMode } & Pick; /** @@ -6920,6 +7199,7 @@ export interface PlaywrightWorkerOptions { * ``` * * Learn more about [recording trace](https://playwright.dev/docs/test-use-options#recording-options). + * @since v1.10 */ trace: TraceMode | /** deprecated */ 'retry-with-trace' | { mode: TraceMode, snapshots?: boolean, screenshots?: boolean, sources?: boolean, attachments?: boolean }; /** @@ -6952,6 +7232,7 @@ export interface PlaywrightWorkerOptions { * ``` * * Learn more about [recording video](https://playwright.dev/docs/test-use-options#recording-options). + * @since v1.10 */ video: VideoMode | /** deprecated */ 'retry-with-video' | { mode: VideoMode, size?: ViewportSize, show?: { actions?: { duration?: number, position?: 'top-left' | 'top' | 'top-right' | 'bottom-left' | 'bottom' | 'bottom-right', fontSize?: number }, test?: { level?: 'file' | 'title' | 'step', position?: 'top-left' | 'top' | 'top-right' | 'bottom-left' | 'bottom' | 'bottom-right', fontSize?: number } } }; } @@ -6996,6 +7277,7 @@ export type VideoMode = 'off' | 'on' | 'retain-on-failure' | 'on-first-retry'; * }); * ``` * + * @since v1.10 */ export interface PlaywrightTestOptions { /** @@ -7014,6 +7296,7 @@ export interface PlaywrightTestOptions { * }); * ``` * + * @since v1.10 */ acceptDownloads: boolean; /** @@ -7032,6 +7315,7 @@ export interface PlaywrightTestOptions { * }); * ``` * + * @since v1.10 */ bypassCSP: boolean; /** @@ -7053,6 +7337,7 @@ export interface PlaywrightTestOptions { * }); * ``` * + * @since v1.10 */ colorScheme: ColorScheme; /** @@ -7090,6 +7375,7 @@ export interface PlaywrightTestOptions { * }); * ``` * + * @since 1.46 */ clientCertificates: ClientCertificate[] | undefined; /** @@ -7110,6 +7396,7 @@ export interface PlaywrightTestOptions { * }); * ``` * + * @since v1.10 */ deviceScaleFactor: number | undefined; /** @@ -7130,6 +7417,7 @@ export interface PlaywrightTestOptions { * }); * ``` * + * @since v1.10 */ extraHTTPHeaders: ExtraHTTPHeaders | undefined; /** @@ -7147,6 +7435,7 @@ export interface PlaywrightTestOptions { * ``` * * Learn more about [geolocation](https://playwright.dev/docs/emulation#color-scheme-and-media). + * @since v1.10 */ geolocation: Geolocation | undefined; /** @@ -7166,6 +7455,7 @@ export interface PlaywrightTestOptions { * }); * ``` * + * @since v1.10 */ hasTouch: boolean; /** @@ -7188,6 +7478,7 @@ export interface PlaywrightTestOptions { * }); * ``` * + * @since v1.10 */ httpCredentials: HTTPCredentials | undefined; /** @@ -7206,6 +7497,7 @@ export interface PlaywrightTestOptions { * }); * ``` * + * @since v1.10 */ ignoreHTTPSErrors: boolean; /** @@ -7226,6 +7518,7 @@ export interface PlaywrightTestOptions { * }); * ``` * + * @since v1.10 */ isMobile: boolean; /** @@ -7245,6 +7538,7 @@ export interface PlaywrightTestOptions { * }); * ``` * + * @since v1.10 */ javaScriptEnabled: boolean; /** @@ -7265,6 +7559,7 @@ export interface PlaywrightTestOptions { * }); * ``` * + * @since v1.10 */ locale: string | undefined; /** @@ -7284,6 +7579,7 @@ export interface PlaywrightTestOptions { * }); * ``` * + * @since v1.10 */ offline: boolean; /** @@ -7304,6 +7600,7 @@ export interface PlaywrightTestOptions { * }); * ``` * + * @since v1.10 */ permissions: string[] | undefined; /** @@ -7325,6 +7622,7 @@ export interface PlaywrightTestOptions { * }); * ``` * + * @since v1.10 */ proxy: Proxy | undefined; /** @@ -7363,6 +7661,7 @@ export interface PlaywrightTestOptions { * }); * ``` * + * @since v1.10 */ storageState: StorageState | undefined; /** @@ -7383,6 +7682,7 @@ export interface PlaywrightTestOptions { * }); * ``` * + * @since v1.10 */ timezoneId: string | undefined; /** @@ -7401,6 +7701,7 @@ export interface PlaywrightTestOptions { * }); * ``` * + * @since v1.10 */ userAgent: string | undefined; /** @@ -7423,6 +7724,7 @@ export interface PlaywrightTestOptions { * }); * ``` * + * @since v1.10 */ viewport: ViewportSize | null; /** @@ -7454,6 +7756,7 @@ export interface PlaywrightTestOptions { * }); * ``` * + * @since v1.10 */ baseURL: string | undefined; /** @@ -7477,6 +7780,7 @@ export interface PlaywrightTestOptions { * }); * ``` * + * @since v1.10 */ contextOptions: BrowserContextOptions; /** @@ -7499,6 +7803,7 @@ export interface PlaywrightTestOptions { * ``` * * Learn more about [various timeouts](https://playwright.dev/docs/test-timeouts). + * @since v1.10 */ actionTimeout: number; /** @@ -7521,6 +7826,7 @@ export interface PlaywrightTestOptions { * ``` * * Learn more about [various timeouts](https://playwright.dev/docs/test-timeouts). + * @since v1.10 */ navigationTimeout: number; /** @@ -7542,6 +7848,7 @@ export interface PlaywrightTestOptions { * }); * ``` * + * @since v1.10 */ serviceWorkers: ServiceWorkerPolicy; /** @@ -7562,6 +7869,7 @@ export interface PlaywrightTestOptions { * }); * ``` * + * @since v1.27 */ testIdAttribute: string; } @@ -7592,6 +7900,7 @@ export interface PlaywrightTestOptions { * [fixtures.browser](https://playwright.dev/docs/api/class-fixtures#fixtures-browser), * [fixtures.context](https://playwright.dev/docs/api/class-fixtures#fixtures-context) and * [fixtures.page](https://playwright.dev/docs/api/class-fixtures#fixtures-page). + * @since v1.10 */ export interface PlaywrightWorkerArgs { playwright: typeof import('playwright-core'); @@ -7612,6 +7921,7 @@ export interface PlaywrightWorkerArgs { * }); * ``` * + * @since v1.10 */ browser: Browser; } @@ -7641,6 +7951,7 @@ export interface PlaywrightWorkerArgs { * [fixtures.browser](https://playwright.dev/docs/api/class-fixtures#fixtures-browser), * [fixtures.context](https://playwright.dev/docs/api/class-fixtures#fixtures-context) and * [fixtures.page](https://playwright.dev/docs/api/class-fixtures#fixtures-page). + * @since v1.10 */ export interface PlaywrightTestArgs { /** @@ -7662,6 +7973,7 @@ export interface PlaywrightTestArgs { * }); * ``` * + * @since v1.10 */ context: BrowserContext; /** @@ -7684,6 +7996,7 @@ export interface PlaywrightTestArgs { * }); * ``` * + * @since v1.10 */ page: Page; /** @@ -7705,6 +8018,7 @@ export interface PlaywrightTestArgs { * }); * ``` * + * @since v1.10 */ request: APIRequestContext; } @@ -7744,6 +8058,7 @@ interface AsymmetricMatchers { * expect('abc').toEqual(expect.any(String)); * ``` * + * @since v1.9 * @param constructor Constructor of the expected object like `ExampleClass`, or a primitive boxed type like `Number`. */ any(sample: unknown): AsymmetricMatcher; @@ -7760,6 +8075,7 @@ interface AsymmetricMatchers { * expect(value).not.toEqual({ otherProp: expect.anything() }); * ``` * + * @since v1.9 */ anything(): AsymmetricMatcher; /** @@ -7777,6 +8093,7 @@ interface AsymmetricMatchers { * expect([1, 2, 3]).not.toEqual(expect.arrayContaining([1, 4])); * ``` * + * @since v1.9 * @param expected Expected array that is a subset of the received value. */ arrayContaining(sample: Array): AsymmetricMatcher; @@ -7798,6 +8115,7 @@ interface AsymmetricMatchers { * expect(['a', 'b', 'c']).toEqual(expect.arrayOf(String)); * ``` * + * @since v1.57 * @param constructor Constructor of the expected object like `ExampleClass`, or a primitive boxed type like `Number`. */ arrayOf(sample: unknown): AsymmetricMatcher; @@ -7814,6 +8132,7 @@ interface AsymmetricMatchers { * expect({ prop: 0.1 + 0.2 }).toEqual({ prop: expect.closeTo(0.3, 5) }); * ``` * + * @since v1.9 * @param expected Expected value. * @param numDigits The number of decimal digits after the decimal point that must be equal. */ @@ -7846,6 +8165,7 @@ interface AsymmetricMatchers { * })); * ``` * + * @since v1.9 * @param expected Expected object pattern that contains a subset of the properties. */ objectContaining(sample: Record): AsymmetricMatcher; @@ -7860,6 +8180,7 @@ interface AsymmetricMatchers { * expect('Hello world!').toEqual(expect.stringContaining('Hello')); * ``` * + * @since v1.9 * @param expected Expected substring. */ stringContaining(sample: string): AsymmetricMatcher; @@ -7884,6 +8205,7 @@ interface AsymmetricMatchers { * }); * ``` * + * @since v1.9 * @param expected Pattern that expected string should match. */ stringMatching(sample: string | RegExp): AsymmetricMatcher; @@ -7904,6 +8226,7 @@ interface AsymmetricMatchers { * }); * ``` * + * @since v1.9 */ interface GenericAssertions { /** @@ -7918,6 +8241,7 @@ interface GenericAssertions { * expect(value).not.toBe(2); * ``` * + * @since v1.9 */ not: GenericAssertions; /** @@ -7932,6 +8256,7 @@ interface GenericAssertions { * }); * ``` * + * @since v1.9 */ resolves: GenericAssertions; /** @@ -7946,6 +8271,7 @@ interface GenericAssertions { * }); * ``` * + * @since v1.9 */ rejects: GenericAssertions; /** @@ -7963,6 +8289,7 @@ interface GenericAssertions { * expect(value.prop).toBe(1); * ``` * + * @since v1.9 * @param expected Expected value. */ toBe(expected: unknown): R; @@ -7978,6 +8305,7 @@ interface GenericAssertions { * expect(0.1 + 0.2).toBeCloseTo(0.3, 5); * ``` * + * @since v1.9 * @param expected Expected value. * @param numDigits The number of decimal digits after the decimal point that must be equal. */ @@ -7992,6 +8320,7 @@ interface GenericAssertions { * expect(value).toBeDefined(); * ``` * + * @since v1.9 */ toBeDefined(): R; /** @@ -8005,6 +8334,7 @@ interface GenericAssertions { * expect(value).toBeFalsy(); * ``` * + * @since v1.9 */ toBeFalsy(): R; /** @@ -8017,6 +8347,7 @@ interface GenericAssertions { * expect(value).toBeGreaterThan(1); * ``` * + * @since v1.9 * @param expected The value to compare to. */ toBeGreaterThan(expected: number | bigint): R; @@ -8030,6 +8361,7 @@ interface GenericAssertions { * expect(value).toBeGreaterThanOrEqual(42); * ``` * + * @since v1.9 * @param expected The value to compare to. */ toBeGreaterThanOrEqual(expected: number | bigint): R; @@ -8045,6 +8377,7 @@ interface GenericAssertions { * expect(new Example()).toBeInstanceOf(Example); * ``` * + * @since v1.9 * @param expected The class or constructor function. */ toBeInstanceOf(expected: Function): R; @@ -8058,6 +8391,7 @@ interface GenericAssertions { * expect(value).toBeLessThan(100); * ``` * + * @since v1.9 * @param expected The value to compare to. */ toBeLessThan(expected: number | bigint): R; @@ -8071,6 +8405,7 @@ interface GenericAssertions { * expect(value).toBeLessThanOrEqual(42); * ``` * + * @since v1.9 * @param expected The value to compare to. */ toBeLessThanOrEqual(expected: number | bigint): R; @@ -8084,6 +8419,7 @@ interface GenericAssertions { * expect(value).toBeNaN(); * ``` * + * @since v1.9 */ toBeNaN(): R; /** @@ -8096,6 +8432,7 @@ interface GenericAssertions { * expect(value).toBeNull(); * ``` * + * @since v1.9 */ toBeNull(): R; /** @@ -8109,6 +8446,7 @@ interface GenericAssertions { * expect(value).toBeTruthy(); * ``` * + * @since v1.9 */ toBeTruthy(): R; /** @@ -8121,6 +8459,7 @@ interface GenericAssertions { * expect(value).toBeUndefined(); * ``` * + * @since v1.9 */ toBeUndefined(): R; /** @@ -8134,6 +8473,7 @@ interface GenericAssertions { * expect(value).toContain(','); * ``` * + * @since v1.9 * @param expected Expected substring. */ toContain(expected: string): R; @@ -8148,6 +8488,7 @@ interface GenericAssertions { * expect(new Set(value)).toContain(2); * ``` * + * @since v1.9 * @param expected Expected value in the collection. */ toContain(expected: unknown): R; @@ -8173,6 +8514,7 @@ interface GenericAssertions { * expect(new Set(value)).toContainEqual({ another: 2 }); * ``` * + * @since v1.9 * @param expected Expected value in the collection. */ toContainEqual(expected: unknown): R; @@ -8235,6 +8577,7 @@ interface GenericAssertions { * })); * ``` * + * @since v1.9 * @param expected Expected value. */ toEqual(expected: unknown): R; @@ -8250,6 +8593,7 @@ interface GenericAssertions { * expect([1, 2, 3]).toHaveLength(3); * ``` * + * @since v1.9 * @param expected Expected length. */ toHaveLength(expected: number): R; @@ -8276,6 +8620,7 @@ interface GenericAssertions { * expect(value).toHaveProperty('c', true); * ``` * + * @since v1.9 * @param keyPath Path to the property. Use dot notation `a.b` to check nested properties and indexed `a[2]` notation to check nested * array items. * @param expected Optional expected value to compare the property to. @@ -8291,6 +8636,7 @@ interface GenericAssertions { * expect(value).toMatch(/Is \d+ enough/); * ``` * + * @since v1.9 * @param expected Regular expression to match against. */ toMatch(expected: RegExp | string): R; @@ -8317,6 +8663,7 @@ interface GenericAssertions { * expect([{ a: 1, b: 2 }]).toMatchObject([{ a: 1 }]); * ``` * + * @since v1.9 * @param expected The expected object value to match against. */ toMatchObject(expected: Record | Array): R; @@ -8339,6 +8686,7 @@ interface GenericAssertions { * expect(value).toStrictEqual({ prop: 1 }); * ``` * + * @since v1.9 * @param expected Expected value. */ toStrictEqual(expected: unknown): R; @@ -8369,6 +8717,7 @@ interface GenericAssertions { * }).toThrow(Error); * ``` * + * @since v1.9 * @param expected Expected error message or error object. */ toThrow(error?: unknown): R; @@ -8384,6 +8733,7 @@ interface GenericAssertions { * }).toThrowError(); * ``` * + * @since v1.9 * @param expected Expected error message or error object. */ toThrowError(error?: unknown): R; @@ -8586,6 +8936,7 @@ export { }; * }); * ``` * + * @since v1.18 */ interface APIResponseAssertions { /** @@ -8597,6 +8948,7 @@ interface APIResponseAssertions { * await expect(response).toBeOK(); * ``` * + * @since v1.18 */ toBeOK(): Promise; @@ -8611,6 +8963,7 @@ interface APIResponseAssertions { * await expect(response).not.toBeOK(); * ``` * + * @since v1.20 */ not: APIResponseAssertions; } @@ -8630,6 +8983,7 @@ interface APIResponseAssertions { * }); * ``` * + * @since v1.17 */ interface LocatorAssertions { /** @@ -8642,13 +8996,18 @@ interface LocatorAssertions { * await expect(page.getByText('Hidden text')).toBeAttached(); * ``` * + * @since v1.33 * @param options */ toBeAttached(options?: { + /** + * @since v1.33 + */ attached?: boolean; /** * Time to retry the assertion for in milliseconds. Defaults to `timeout` in `TestConfig.expect`. + * @since v1.33 */ timeout?: number; }): Promise; @@ -8663,6 +9022,7 @@ interface LocatorAssertions { * await expect(locator).toBeChecked(); * ``` * + * @since v1.20 * @param options */ toBeChecked(options?: { @@ -8670,6 +9030,7 @@ interface LocatorAssertions { * Provides state to assert for. Asserts for input to be checked by default. This option can't be used when * [`indeterminate`](https://playwright.dev/docs/api/class-locatorassertions#locator-assertions-to-be-checked-option-indeterminate) * is set to true. + * @since v1.18 */ checked?: boolean; @@ -8678,11 +9039,13 @@ interface LocatorAssertions { * This option can't be true when * [`checked`](https://playwright.dev/docs/api/class-locatorassertions#locator-assertions-to-be-checked-option-checked) * is provided. + * @since v1.50 */ indeterminate?: boolean; /** * Time to retry the assertion for in milliseconds. Defaults to `timeout` in `TestConfig.expect`. + * @since v1.18 */ timeout?: number; }): Promise; @@ -8701,11 +9064,13 @@ interface LocatorAssertions { * await expect(locator).toBeDisabled(); * ``` * + * @since v1.20 * @param options */ toBeDisabled(options?: { /** * Time to retry the assertion for in milliseconds. Defaults to `timeout` in `TestConfig.expect`. + * @since v1.18 */ timeout?: number; }): Promise; @@ -8720,13 +9085,18 @@ interface LocatorAssertions { * await expect(locator).toBeEditable(); * ``` * + * @since v1.20 * @param options */ toBeEditable(options?: { + /** + * @since v1.26 + */ editable?: boolean; /** * Time to retry the assertion for in milliseconds. Defaults to `timeout` in `TestConfig.expect`. + * @since v1.18 */ timeout?: number; }): Promise; @@ -8742,11 +9112,13 @@ interface LocatorAssertions { * await expect(locator).toBeEmpty(); * ``` * + * @since v1.20 * @param options */ toBeEmpty(options?: { /** * Time to retry the assertion for in milliseconds. Defaults to `timeout` in `TestConfig.expect`. + * @since v1.18 */ timeout?: number; }): Promise; @@ -8761,13 +9133,18 @@ interface LocatorAssertions { * await expect(locator).toBeEnabled(); * ``` * + * @since v1.20 * @param options */ toBeEnabled(options?: { + /** + * @since v1.26 + */ enabled?: boolean; /** * Time to retry the assertion for in milliseconds. Defaults to `timeout` in `TestConfig.expect`. + * @since v1.18 */ timeout?: number; }): Promise; @@ -8782,11 +9159,13 @@ interface LocatorAssertions { * await expect(locator).toBeFocused(); * ``` * + * @since v1.20 * @param options */ toBeFocused(options?: { /** * Time to retry the assertion for in milliseconds. Defaults to `timeout` in `TestConfig.expect`. + * @since v1.18 */ timeout?: number; }): Promise; @@ -8802,11 +9181,13 @@ interface LocatorAssertions { * await expect(locator).toBeHidden(); * ``` * + * @since v1.20 * @param options */ toBeHidden(options?: { /** * Time to retry the assertion for in milliseconds. Defaults to `timeout` in `TestConfig.expect`. + * @since v1.18 */ timeout?: number; }): Promise; @@ -8828,17 +9209,20 @@ interface LocatorAssertions { * await expect(locator).toBeInViewport({ ratio: 0.5 }); * ``` * + * @since v1.31 * @param options */ toBeInViewport(options?: { /** * The minimal ratio of the element to intersect viewport. If equals to `0`, then element should intersect viewport at * any positive ratio. Defaults to `0`. + * @since v1.31 */ ratio?: number; /** * Time to retry the assertion for in milliseconds. Defaults to `timeout` in `TestConfig.expect`. + * @since v1.31 */ timeout?: number; }): Promise; @@ -8867,14 +9251,19 @@ interface LocatorAssertions { * ).toBeVisible(); * ``` * + * @since v1.20 * @param options */ toBeVisible(options?: { /** * Time to retry the assertion for in milliseconds. Defaults to `timeout` in `TestConfig.expect`. + * @since v1.18 */ timeout?: number; + /** + * @since v1.26 + */ visible?: boolean; }): Promise; @@ -8912,6 +9301,7 @@ interface LocatorAssertions { * await expect(locator).toContainClass(['inactive', 'active', 'inactive']); * ``` * + * @since v1.52 * @param expected A string containing expected class names, separated by spaces, or a list of such strings to assert multiple * elements. * @param options @@ -8919,6 +9309,7 @@ interface LocatorAssertions { toContainClass(expected: string|ReadonlyArray, options?: { /** * Time to retry the assertion for in milliseconds. Defaults to `timeout` in `TestConfig.expect`. + * @since v1.52 */ timeout?: number; }): Promise; @@ -8973,6 +9364,7 @@ interface LocatorAssertions { * await expect(page.locator('ul')).toContainText(['Text 3']); * ``` * + * @since v1.20 * @param expected Expected substring or RegExp or a list of those. * @param options */ @@ -8981,16 +9373,19 @@ interface LocatorAssertions { * Whether to perform case-insensitive match. * [`ignoreCase`](https://playwright.dev/docs/api/class-locatorassertions#locator-assertions-to-contain-text-option-ignore-case) * option takes precedence over the corresponding regular expression flag if specified. + * @since v1.23 */ ignoreCase?: boolean; /** * Time to retry the assertion for in milliseconds. Defaults to `timeout` in `TestConfig.expect`. + * @since v1.18 */ timeout?: number; /** * Whether to use `element.innerText` instead of `element.textContent` when retrieving DOM node text. + * @since v1.18 */ useInnerText?: boolean; }): Promise; @@ -9006,6 +9401,7 @@ interface LocatorAssertions { * await expect(locator).toHaveAccessibleDescription('Save results to disk'); * ``` * + * @since v1.44 * @param description Expected accessible description. * @param options */ @@ -9014,11 +9410,13 @@ interface LocatorAssertions { * Whether to perform case-insensitive match. * [`ignoreCase`](https://playwright.dev/docs/api/class-locatorassertions#locator-assertions-to-have-accessible-description-option-ignore-case) * option takes precedence over the corresponding regular expression flag if specified. + * @since v1.44 */ ignoreCase?: boolean; /** * Time to retry the assertion for in milliseconds. Defaults to `timeout` in `TestConfig.expect`. + * @since v1.44 */ timeout?: number; }): Promise; @@ -9034,6 +9432,7 @@ interface LocatorAssertions { * await expect(locator).toHaveAccessibleErrorMessage('Username is required.'); * ``` * + * @since v1.50 * @param errorMessage Expected accessible error message. * @param options */ @@ -9042,11 +9441,13 @@ interface LocatorAssertions { * Whether to perform case-insensitive match. * [`ignoreCase`](https://playwright.dev/docs/api/class-locatorassertions#locator-assertions-to-have-accessible-error-message-option-ignore-case) * option takes precedence over the corresponding regular expression flag if specified. + * @since v1.50 */ ignoreCase?: boolean; /** * Time to retry the assertion for in milliseconds. Defaults to `timeout` in `TestConfig.expect`. + * @since v1.50 */ timeout?: number; }): Promise; @@ -9062,6 +9463,7 @@ interface LocatorAssertions { * await expect(locator).toHaveAccessibleName('Save to disk'); * ``` * + * @since v1.44 * @param name Expected accessible name. * @param options */ @@ -9070,11 +9472,13 @@ interface LocatorAssertions { * Whether to perform case-insensitive match. * [`ignoreCase`](https://playwright.dev/docs/api/class-locatorassertions#locator-assertions-to-have-accessible-name-option-ignore-case) * option takes precedence over the corresponding regular expression flag if specified. + * @since v1.44 */ ignoreCase?: boolean; /** * Time to retry the assertion for in milliseconds. Defaults to `timeout` in `TestConfig.expect`. + * @since v1.44 */ timeout?: number; }): Promise; @@ -9089,6 +9493,7 @@ interface LocatorAssertions { * await expect(locator).toHaveAttribute('type', 'text'); * ``` * + * @since v1.20 * @param name Attribute name. * @param value Expected attribute value. * @param options @@ -9098,11 +9503,13 @@ interface LocatorAssertions { * Whether to perform case-insensitive match. * [`ignoreCase`](https://playwright.dev/docs/api/class-locatorassertions#locator-assertions-to-have-attribute-option-ignore-case) * option takes precedence over the corresponding regular expression flag if specified. + * @since v1.40 */ ignoreCase?: boolean; /** * Time to retry the assertion for in milliseconds. Defaults to `timeout` in `TestConfig.expect`. + * @since v1.18 */ timeout?: number; }): Promise; @@ -9118,12 +9525,14 @@ interface LocatorAssertions { * await expect(locator).not.toHaveAttribute('open'); * ``` * + * @since v1.39 * @param name Attribute name. * @param options */ toHaveAttribute(name: string, options?: { /** * Time to retry the assertion for in milliseconds. Defaults to `timeout` in `TestConfig.expect`. + * @since v1.39 */ timeout?: number; }): Promise; @@ -9154,12 +9563,14 @@ interface LocatorAssertions { * await expect(locator).toHaveClass(['component', 'component selected', 'component']); * ``` * + * @since v1.20 * @param expected Expected class or RegExp or a list of those. * @param options */ toHaveClass(expected: string|RegExp|ReadonlyArray, options?: { /** * Time to retry the assertion for in milliseconds. Defaults to `timeout` in `TestConfig.expect`. + * @since v1.18 */ timeout?: number; }): Promise; @@ -9174,12 +9585,14 @@ interface LocatorAssertions { * await expect(list).toHaveCount(3); * ``` * + * @since v1.20 * @param count Expected count. * @param options */ toHaveCount(count: number, options?: { /** * Time to retry the assertion for in milliseconds. Defaults to `timeout` in `TestConfig.expect`. + * @since v1.18 */ timeout?: number; }): Promise; @@ -9195,6 +9608,7 @@ interface LocatorAssertions { * await expect(locator).toHaveCSS('display', 'flex'); * ``` * + * @since v1.20 * @param name CSS property name. * @param value CSS property value. * @param options @@ -9202,6 +9616,7 @@ interface LocatorAssertions { toHaveCSS(name: string, value: string|RegExp, options?: { /** * Time to retry the assertion for in milliseconds. Defaults to `timeout` in `TestConfig.expect`. + * @since v1.18 */ timeout?: number; }): Promise; @@ -9217,12 +9632,14 @@ interface LocatorAssertions { * await expect(locator).toHaveId('lastname'); * ``` * + * @since v1.20 * @param id Element id. * @param options */ toHaveId(id: string|RegExp, options?: { /** * Time to retry the assertion for in milliseconds. Defaults to `timeout` in `TestConfig.expect`. + * @since v1.18 */ timeout?: number; }): Promise; @@ -9238,6 +9655,7 @@ interface LocatorAssertions { * await expect(locator).toHaveJSProperty('loaded', true); * ``` * + * @since v1.20 * @param name Property name. * @param value Property value. * @param options @@ -9245,6 +9663,7 @@ interface LocatorAssertions { toHaveJSProperty(name: string, value: any, options?: { /** * Time to retry the assertion for in milliseconds. Defaults to `timeout` in `TestConfig.expect`. + * @since v1.18 */ timeout?: number; }): Promise; @@ -9263,12 +9682,14 @@ interface LocatorAssertions { * await expect(locator).toHaveRole('button'); * ``` * + * @since v1.44 * @param role Required aria role. * @param options */ toHaveRole(role: "alert"|"alertdialog"|"application"|"article"|"banner"|"blockquote"|"button"|"caption"|"cell"|"checkbox"|"code"|"columnheader"|"combobox"|"complementary"|"contentinfo"|"definition"|"deletion"|"dialog"|"directory"|"document"|"emphasis"|"feed"|"figure"|"form"|"generic"|"grid"|"gridcell"|"group"|"heading"|"img"|"insertion"|"link"|"list"|"listbox"|"listitem"|"log"|"main"|"marquee"|"math"|"meter"|"menu"|"menubar"|"menuitem"|"menuitemcheckbox"|"menuitemradio"|"navigation"|"none"|"note"|"option"|"paragraph"|"presentation"|"progressbar"|"radio"|"radiogroup"|"region"|"row"|"rowgroup"|"rowheader"|"scrollbar"|"search"|"searchbox"|"separator"|"slider"|"spinbutton"|"status"|"strong"|"subscript"|"superscript"|"switch"|"tab"|"table"|"tablist"|"tabpanel"|"term"|"textbox"|"time"|"timer"|"toolbar"|"tooltip"|"tree"|"treegrid"|"treeitem", options?: { /** * Time to retry the assertion for in milliseconds. Defaults to `timeout` in `TestConfig.expect`. + * @since v1.44 */ timeout?: number; }): Promise; @@ -9285,6 +9706,7 @@ interface LocatorAssertions { * ``` * * Note that screenshot assertions only work with Playwright test runner. + * @since v1.23 * @param name Snapshot name. * @param options */ @@ -9296,12 +9718,14 @@ interface LocatorAssertions { * - infinite animations are canceled to initial state, and then played over after the screenshot. * * Defaults to `"disabled"` that disables animations. + * @since v1.23 */ animations?: "disabled"|"allow"; /** * When set to `"hide"`, screenshot will hide text caret. When set to `"initial"`, text caret behavior will not be * changed. Defaults to `"hide"`. + * @since v1.23 */ caret?: "hide"|"initial"; @@ -9311,30 +9735,35 @@ interface LocatorAssertions { * [`maskColor`](https://playwright.dev/docs/api/class-locatorassertions#locator-assertions-to-have-screenshot-1-option-mask-color)) * that completely covers its bounding box. The mask is also applied to invisible elements, see * [Matching only visible elements](https://playwright.dev/docs/locators#matching-only-visible-elements) to disable that. + * @since v1.23 */ mask?: Array; /** * Specify the color of the overlay box for masked elements, in * [CSS color format](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value). Default color is pink `#FF00FF`. + * @since v1.35 */ maskColor?: string; /** * An acceptable ratio of pixels that are different to the total amount of pixels, between `0` and `1`. Default is * configurable with `TestConfig.expect`. Unset by default. + * @since v1.23 */ maxDiffPixelRatio?: number; /** * An acceptable amount of pixels that could be different. Default is configurable with `TestConfig.expect`. Unset by * default. + * @since v1.23 */ maxDiffPixels?: number; /** * Hides default white background and allows capturing screenshots with transparency. Not applicable to `jpeg` images. * Defaults to `false`. + * @since v1.23 */ omitBackground?: boolean; @@ -9344,6 +9773,7 @@ interface LocatorAssertions { * screenshots of high-dpi devices will be twice as large or even larger. * * Defaults to `"css"`. + * @since v1.23 */ scale?: "css"|"device"; @@ -9351,6 +9781,7 @@ interface LocatorAssertions { * File name containing the stylesheet to apply while making the screenshot. This is where you can hide dynamic * elements, make elements invisible or change their properties to help you creating repeatable screenshots. This * stylesheet pierces the Shadow DOM and applies to the inner frames. + * @since v1.41 */ stylePath?: string|Array; @@ -9358,11 +9789,13 @@ interface LocatorAssertions { * An acceptable perceived color difference in the [YIQ color space](https://en.wikipedia.org/wiki/YIQ) between the * same pixel in compared images, between zero (strict) and one (lax), default is configurable with * `TestConfig.expect`. Defaults to `0.2`. + * @since v1.23 */ threshold?: number; /** * Time to retry the assertion for in milliseconds. Defaults to `timeout` in `TestConfig.expect`. + * @since v1.23 */ timeout?: number; }): Promise; @@ -9379,6 +9812,7 @@ interface LocatorAssertions { * ``` * * Note that screenshot assertions only work with Playwright test runner. + * @since v1.23 * @param options */ toHaveScreenshot(options?: { @@ -9389,12 +9823,14 @@ interface LocatorAssertions { * - infinite animations are canceled to initial state, and then played over after the screenshot. * * Defaults to `"disabled"` that disables animations. + * @since v1.23 */ animations?: "disabled"|"allow"; /** * When set to `"hide"`, screenshot will hide text caret. When set to `"initial"`, text caret behavior will not be * changed. Defaults to `"hide"`. + * @since v1.23 */ caret?: "hide"|"initial"; @@ -9404,30 +9840,35 @@ interface LocatorAssertions { * [`maskColor`](https://playwright.dev/docs/api/class-locatorassertions#locator-assertions-to-have-screenshot-2-option-mask-color)) * that completely covers its bounding box. The mask is also applied to invisible elements, see * [Matching only visible elements](https://playwright.dev/docs/locators#matching-only-visible-elements) to disable that. + * @since v1.23 */ mask?: Array; /** * Specify the color of the overlay box for masked elements, in * [CSS color format](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value). Default color is pink `#FF00FF`. + * @since v1.35 */ maskColor?: string; /** * An acceptable ratio of pixels that are different to the total amount of pixels, between `0` and `1`. Default is * configurable with `TestConfig.expect`. Unset by default. + * @since v1.23 */ maxDiffPixelRatio?: number; /** * An acceptable amount of pixels that could be different. Default is configurable with `TestConfig.expect`. Unset by * default. + * @since v1.23 */ maxDiffPixels?: number; /** * Hides default white background and allows capturing screenshots with transparency. Not applicable to `jpeg` images. * Defaults to `false`. + * @since v1.23 */ omitBackground?: boolean; @@ -9437,6 +9878,7 @@ interface LocatorAssertions { * screenshots of high-dpi devices will be twice as large or even larger. * * Defaults to `"css"`. + * @since v1.23 */ scale?: "css"|"device"; @@ -9444,6 +9886,7 @@ interface LocatorAssertions { * File name containing the stylesheet to apply while making the screenshot. This is where you can hide dynamic * elements, make elements invisible or change their properties to help you creating repeatable screenshots. This * stylesheet pierces the Shadow DOM and applies to the inner frames. + * @since v1.41 */ stylePath?: string|Array; @@ -9451,11 +9894,13 @@ interface LocatorAssertions { * An acceptable perceived color difference in the [YIQ color space](https://en.wikipedia.org/wiki/YIQ) between the * same pixel in compared images, between zero (strict) and one (lax), default is configurable with * `TestConfig.expect`. Defaults to `0.2`. + * @since v1.23 */ threshold?: number; /** * Time to retry the assertion for in milliseconds. Defaults to `timeout` in `TestConfig.expect`. + * @since v1.23 */ timeout?: number; }): Promise; @@ -9509,6 +9954,7 @@ interface LocatorAssertions { * await expect(page.locator('ul')).toHaveText(['Text 1', 'Text 2', 'Text 3']); * ``` * + * @since v1.20 * @param expected Expected string or RegExp or a list of those. * @param options */ @@ -9517,16 +9963,19 @@ interface LocatorAssertions { * Whether to perform case-insensitive match. * [`ignoreCase`](https://playwright.dev/docs/api/class-locatorassertions#locator-assertions-to-have-text-option-ignore-case) * option takes precedence over the corresponding regular expression flag if specified. + * @since v1.23 */ ignoreCase?: boolean; /** * Time to retry the assertion for in milliseconds. Defaults to `timeout` in `TestConfig.expect`. + * @since v1.18 */ timeout?: number; /** * Whether to use `element.innerText` instead of `element.textContent` when retrieving DOM node text. + * @since v1.18 */ useInnerText?: boolean; }): Promise; @@ -9542,12 +9991,14 @@ interface LocatorAssertions { * await expect(locator).toHaveValue(/[0-9]/); * ``` * + * @since v1.20 * @param value Expected value. * @param options */ toHaveValue(value: string|RegExp, options?: { /** * Time to retry the assertion for in milliseconds. Defaults to `timeout` in `TestConfig.expect`. + * @since v1.18 */ timeout?: number; }): Promise; @@ -9574,12 +10025,14 @@ interface LocatorAssertions { * await expect(locator).toHaveValues([/R/, /G/]); * ``` * + * @since v1.23 * @param values Expected options currently selected. * @param options */ toHaveValues(values: ReadonlyArray, options?: { /** * Time to retry the assertion for in milliseconds. Defaults to `timeout` in `TestConfig.expect`. + * @since v1.23 */ timeout?: number; }): Promise; @@ -9597,12 +10050,14 @@ interface LocatorAssertions { * `); * ``` * + * @since v1.49 * @param expected * @param options */ toMatchAriaSnapshot(expected: string, options?: { /** * Time to retry the assertion for in milliseconds. Defaults to `timeout` in `TestConfig.expect`. + * @since v1.49 */ timeout?: number; }): Promise; @@ -9620,17 +10075,20 @@ interface LocatorAssertions { * await expect(page.locator('body')).toMatchAriaSnapshot({ name: 'body.aria.yml' }); * ``` * + * @since v1.50 * @param options */ toMatchAriaSnapshot(options?: { /** * Name of the snapshot to store in the snapshot folder corresponding to this test. Generates sequential names if not * specified. + * @since v1.50 */ name?: string; /** * Time to retry the assertion for in milliseconds. Defaults to `timeout` in `TestConfig.expect`. + * @since v1.50 */ timeout?: number; }): Promise; @@ -9646,6 +10104,7 @@ interface LocatorAssertions { * await expect(locator).not.toContainText('error'); * ``` * + * @since v1.20 */ not: LocatorAssertions; } @@ -9664,6 +10123,7 @@ interface LocatorAssertions { * }); * ``` * + * @since v1.17 */ interface PageAssertions { /** @@ -9677,6 +10137,7 @@ interface PageAssertions { * ``` * * Note that screenshot assertions only work with Playwright test runner. + * @since v1.23 * @param name Snapshot name. * @param options */ @@ -9693,6 +10154,7 @@ interface PageAssertions { * ``` * * Note that screenshot assertions only work with Playwright test runner. + * @since v1.23 * @param options */ toHaveScreenshot(options?: PageAssertionsToHaveScreenshotOptions): Promise; @@ -9706,12 +10168,14 @@ interface PageAssertions { * await expect(page).toHaveTitle(/.*checkout/); * ``` * + * @since v1.20 * @param titleOrRegExp Expected title or RegExp. * @param options */ toHaveTitle(titleOrRegExp: string|RegExp, options?: { /** * Time to retry the assertion for in milliseconds. Defaults to `timeout` in `TestConfig.expect`. + * @since v1.18 */ timeout?: number; }): Promise; @@ -9739,6 +10203,7 @@ interface PageAssertions { * }); * ``` * + * @since v1.20 * @param url Expected URL string, RegExp, or predicate receiving [URL] to match. When * [`baseURL`](https://playwright.dev/docs/api/class-browser#browser-new-context-option-base-url) is provided via the * context options and the `url` argument is a string, the two values are merged via the @@ -9752,11 +10217,13 @@ interface PageAssertions { * [`ignoreCase`](https://playwright.dev/docs/api/class-pageassertions#page-assertions-to-have-url-option-ignore-case) * option takes precedence over the corresponding regular expression parameter if specified. A provided predicate * ignores this flag. + * @since v1.44 */ ignoreCase?: boolean; /** * Time to retry the assertion for in milliseconds. Defaults to `timeout` in `TestConfig.expect`. + * @since v1.18 */ timeout?: number; }): Promise; @@ -9772,6 +10239,7 @@ interface PageAssertions { * await expect(page).not.toHaveURL('error'); * ``` * + * @since v1.20 */ not: PageAssertions; } @@ -9783,6 +10251,7 @@ interface PageAssertions { * expect(screenshot).toMatchSnapshot('landing-page.png'); * ``` * + * @since v1.20 */ interface SnapshotAssertions { /** @@ -9815,6 +10284,7 @@ interface SnapshotAssertions { * Learn more about [visual comparisons](https://playwright.dev/docs/test-snapshots). * * Note that matching snapshots only work with Playwright test runner. + * @since v1.22 * @param name Snapshot name. * @param options */ @@ -9822,12 +10292,14 @@ interface SnapshotAssertions { /** * An acceptable ratio of pixels that are different to the total amount of pixels, between `0` and `1`. Default is * configurable with `TestConfig.expect`. Unset by default. + * @since v1.22 */ maxDiffPixelRatio?: number; /** * An acceptable amount of pixels that could be different. Default is configurable with `TestConfig.expect`. Unset by * default. + * @since v1.22 */ maxDiffPixels?: number; @@ -9835,6 +10307,7 @@ interface SnapshotAssertions { * An acceptable perceived color difference in the [YIQ color space](https://en.wikipedia.org/wiki/YIQ) between the * same pixel in compared images, between zero (strict) and one (lax), default is configurable with * `TestConfig.expect`. Defaults to `0.2`. + * @since v1.22 */ threshold?: number; }): void; @@ -9868,23 +10341,27 @@ interface SnapshotAssertions { * Learn more about [visual comparisons](https://playwright.dev/docs/test-snapshots). * * Note that matching snapshots only work with Playwright test runner. + * @since v1.22 * @param options */ toMatchSnapshot(options?: { /** * An acceptable ratio of pixels that are different to the total amount of pixels, between `0` and `1`. Default is * configurable with `TestConfig.expect`. Unset by default. + * @since v1.22 */ maxDiffPixelRatio?: number; /** * An acceptable amount of pixels that could be different. Default is configurable with `TestConfig.expect`. Unset by * default. + * @since v1.22 */ maxDiffPixels?: number; /** * Snapshot name. If not passed, the test name and ordinals are used when called multiple times. + * @since v1.22 */ name?: string|Array; @@ -9892,6 +10369,7 @@ interface SnapshotAssertions { * An acceptable perceived color difference in the [YIQ color space](https://en.wikipedia.org/wiki/YIQ) between the * same pixel in compared images, between zero (strict) and one (lax), default is configurable with * `TestConfig.expect`. Defaults to `0.2`. + * @since v1.22 */ threshold?: number; }): void; @@ -9899,47 +10377,56 @@ interface SnapshotAssertions { /** * Represents a location in the source code where [TestCase] or [Suite] is defined. + * @since v1.10 */ export interface Location { /** * Column number in the source file. + * @since v1.10 */ column: number; /** * Path to the source file. + * @since v1.10 */ file: string; /** * Line number in the source file. + * @since v1.10 */ line: number; } /** * Information about an error thrown during test execution. + * @since v1.10 */ export interface TestInfoError { /** * Error cause. Set when there is a * [cause](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error/cause) for the * error. Will be `undefined` if there is no cause or if the cause is not an instance of [Error]. + * @since v1.49 */ cause?: TestInfoError; /** * Error message. Set when [Error] (or its subclass) has been thrown. + * @since v1.10 */ message?: string; /** * Error stack. Set when [Error] (or its subclass) has been thrown. + * @since v1.10 */ stack?: string; /** * The value that was thrown. Set when anything except the [Error] (or its subclass) has been thrown. + * @since v1.10 */ value?: string; } @@ -9959,6 +10446,7 @@ export interface TestInfoError { * }); * ``` * + * @since v1.51 */ export interface TestStepInfo { /** @@ -10002,6 +10490,7 @@ export interface TestStepInfo { * automatically takes care of copying attached files to a location that is accessible to reporters. You can safely * remove the attachment after awaiting the attach call. * + * @since v1.51 * @param name Attachment name. The name will also be sanitized and used as the prefix of file name when saving to disk. * @param options */ @@ -10009,6 +10498,7 @@ export interface TestStepInfo { /** * Attachment body. Mutually exclusive with * [`path`](https://playwright.dev/docs/api/class-teststepinfo#test-step-info-attach-option-path). + * @since v1.51 */ body?: string|Buffer; @@ -10017,12 +10507,14 @@ export interface TestStepInfo { * `'image/png'`. If omitted, content type is inferred based on the * [`path`](https://playwright.dev/docs/api/class-teststepinfo#test-step-info-attach-option-path), or defaults to * `text/plain` for [string] attachments and `application/octet-stream` for [Buffer] attachments. + * @since v1.51 */ contentType?: string; /** * Path on the filesystem to the attached file. Mutually exclusive with * [`body`](https://playwright.dev/docs/api/class-teststepinfo#test-step-info-attach-option-body). + * @since v1.51 */ path?: string; }): Promise; @@ -10045,6 +10537,7 @@ export interface TestStepInfo { * }); * ``` * + * @since v1.51 */ skip(): void; @@ -10066,6 +10559,7 @@ export interface TestStepInfo { * }); * ``` * + * @since v1.51 * @param condition A skip condition. Test step is skipped when the condition is `true`. * @param description Optional description that will be reflected in a test report. */ @@ -10074,6 +10568,7 @@ export interface TestStepInfo { /** * The full title path starting with the test file name, including the step titles. See also * [testInfo.titlePath](https://playwright.dev/docs/api/class-testinfo#test-info-title-path). + * @since v1.55 */ titlePath: Array; } @@ -10082,10 +10577,12 @@ export interface TestStepInfo { * `WorkerInfo` contains information about the worker that is running tests and is available to worker-scoped * fixtures. `WorkerInfo` is a subset of [TestInfo](https://playwright.dev/docs/api/class-testinfo) that is available * in many other places. + * @since v1.10 */ export interface WorkerInfo { /** * Processed configuration from the [configuration file](https://playwright.dev/docs/test-configuration). + * @since v1.10 */ config: FullConfig; @@ -10096,11 +10593,13 @@ export interface WorkerInfo { * * Also available as `process.env.TEST_PARALLEL_INDEX`. Learn more about * [parallelism and sharding](https://playwright.dev/docs/test-parallel) with Playwright Test. + * @since v1.10 */ parallelIndex: number; /** * Processed project configuration from the [configuration file](https://playwright.dev/docs/test-configuration). + * @since v1.10 */ project: FullProject; @@ -10110,6 +10609,7 @@ export interface WorkerInfo { * * Also available as `process.env.TEST_WORKER_INDEX`. Learn more about [parallelism and sharding](https://playwright.dev/docs/test-parallel) * with Playwright Test. + * @since v1.10 */ workerIndex: number; } @@ -10122,36 +10622,43 @@ export interface PageAssertionsToHaveScreenshotOptions { * - infinite animations are canceled to initial state, and then played over after the screenshot. * * Defaults to `"disabled"` that disables animations. + * @since v1.23 */ animations?: "disabled"|"allow"; /** * When set to `"hide"`, screenshot will hide text caret. When set to `"initial"`, text caret behavior will not be * changed. Defaults to `"hide"`. + * @since v1.23 */ caret?: "hide"|"initial"; /** * An object which specifies clipping of the resulting image. + * @since v1.23 */ clip?: { /** * x-coordinate of top-left corner of clip area + * @since v1.23 */ x: number; /** * y-coordinate of top-left corner of clip area + * @since v1.23 */ y: number; /** * width of clipping area + * @since v1.23 */ width: number; /** * height of clipping area + * @since v1.23 */ height: number; }; @@ -10159,6 +10666,7 @@ export interface PageAssertionsToHaveScreenshotOptions { /** * When true, takes a screenshot of the full scrollable page, instead of the currently visible viewport. Defaults to * `false`. + * @since v1.23 */ fullPage?: boolean; @@ -10168,30 +10676,35 @@ export interface PageAssertionsToHaveScreenshotOptions { * [`maskColor`](https://playwright.dev/docs/api/class-pageassertions#page-assertions-to-have-screenshot-1-option-mask-color)) * that completely covers its bounding box. The mask is also applied to invisible elements, see * [Matching only visible elements](https://playwright.dev/docs/locators#matching-only-visible-elements) to disable that. + * @since v1.23 */ mask?: Array; /** * Specify the color of the overlay box for masked elements, in * [CSS color format](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value). Default color is pink `#FF00FF`. + * @since v1.35 */ maskColor?: string; /** * An acceptable ratio of pixels that are different to the total amount of pixels, between `0` and `1`. Default is * configurable with `TestConfig.expect`. Unset by default. + * @since v1.23 */ maxDiffPixelRatio?: number; /** * An acceptable amount of pixels that could be different. Default is configurable with `TestConfig.expect`. Unset by * default. + * @since v1.23 */ maxDiffPixels?: number; /** * Hides default white background and allows capturing screenshots with transparency. Not applicable to `jpeg` images. * Defaults to `false`. + * @since v1.23 */ omitBackground?: boolean; @@ -10201,6 +10714,7 @@ export interface PageAssertionsToHaveScreenshotOptions { * screenshots of high-dpi devices will be twice as large or even larger. * * Defaults to `"css"`. + * @since v1.23 */ scale?: "css"|"device"; @@ -10208,6 +10722,7 @@ export interface PageAssertionsToHaveScreenshotOptions { * File name containing the stylesheet to apply while making the screenshot. This is where you can hide dynamic * elements, make elements invisible or change their properties to help you creating repeatable screenshots. This * stylesheet pierces the Shadow DOM and applies to the inner frames. + * @since v1.41 */ stylePath?: string|Array; @@ -10215,11 +10730,13 @@ export interface PageAssertionsToHaveScreenshotOptions { * An acceptable perceived color difference in the [YIQ color space](https://en.wikipedia.org/wiki/YIQ) between the * same pixel in compared images, between zero (strict) and one (lax), default is configurable with * `TestConfig.expect`. Defaults to `0.2`. + * @since v1.23 */ threshold?: number; /** * Time to retry the assertion for in milliseconds. Defaults to `timeout` in `TestConfig.expect`. + * @since v1.23 */ timeout?: number; } @@ -10227,16 +10744,19 @@ export interface PageAssertionsToHaveScreenshotOptions { interface TestConfigWebServer { /** * Shell command to start. For example `npm run start`.. + * @since v1.10 */ command: string; /** * Current working directory of the spawned process, defaults to the directory of the configuration file. + * @since v1.10 */ cwd?: string; /** * Environment variables to set for the command, `process.env` by default. + * @since v1.10 */ env?: { [key: string]: string; }; @@ -10246,26 +10766,36 @@ interface TestConfigWebServer { * within 500ms. You can also use `SIGINT` as the signal instead. A `0` timeout means no `SIGKILL` will be sent. * Windows doesn't support `SIGTERM` and `SIGINT` signals, so this option is ignored on Windows. Note that shutting * down a Docker container requires `SIGTERM`. + * @since v1.10 */ gracefulShutdown?: { + /** + * @since v1.10 + */ signal: "SIGINT"|"SIGTERM"; + /** + * @since v1.10 + */ timeout: number; }; /** * Whether to ignore HTTPS errors when fetching the `url`. Defaults to `false`. + * @since v1.10 */ ignoreHTTPSErrors?: boolean; /** * Specifies a custom name for the web server. This name will be prefixed to log messages. Defaults to `[WebServer]`. + * @since v1.10 */ name?: string; /** * The port that your http server is expected to appear on. It does wait until it accepts connections. Either `port` * or `url` should be specified. + * @since v1.10 */ port?: number; @@ -10274,28 +10804,33 @@ interface TestConfigWebServer { * `port` or `url`, it will run the command to start a new server. If `false`, it will throw if an existing process is * listening on the `port` or `url`. This should be commonly set to `!process.env.CI` to allow the local dev server * when running tests locally. + * @since v1.10 */ reuseExistingServer?: boolean; /** * Whether to pipe the stderr of the command to the process stderr or ignore it. Defaults to `"pipe"`. + * @since v1.10 */ stderr?: "pipe"|"ignore"; /** * If `"pipe"`, it will pipe the stdout of the command to the process stdout. If `"ignore"`, it will ignore the stdout * of the command. Default to `"ignore"`. + * @since v1.10 */ stdout?: "pipe"|"ignore"; /** * Consider command started only when given output has been produced. + * @since v1.10 */ wait?: { /** * Regular expression to wait for in the `stdout` of the command output. Named capture groups are stored in the * environment, for example `/Listening on port (?\d+)/` will store the port number in * `process.env['MY_SERVER_PORT']`. + * @since v1.10 */ stdout?: RegExp; @@ -10303,12 +10838,14 @@ interface TestConfigWebServer { * Regular expression to wait for in the `stderr` of the command output. Named capture groups are stored in the * environment, for example `/Listening on port (?\d+)/` will store the port number in * `process.env['MY_SERVER_PORT']`. + * @since v1.10 */ stderr?: RegExp; }; /** * How long to wait for the process to start up and be available in milliseconds. Defaults to 60000. + * @since v1.10 */ timeout?: number; @@ -10316,6 +10853,7 @@ interface TestConfigWebServer { * The url on your http server that is expected to return a 2xx, 3xx, 400, 401, 402, or 403 status code when the * server is ready to accept connections. Redirects (3xx status codes) are being followed and the new location is * checked. Either `port` or `url` should be specified. + * @since v1.10 */ url?: string; } diff --git a/packages/playwright/types/testReporter.d.ts b/packages/playwright/types/testReporter.d.ts index 14154e7769fb3..e18fdb148d1ff 100644 --- a/packages/playwright/types/testReporter.d.ts +++ b/packages/playwright/types/testReporter.d.ts @@ -143,12 +143,14 @@ export interface FullResult { * [TestProject](https://playwright.dev/docs/api/class-testproject) objects. E.g. if project 'Desktop Chrome' was * sharded across 5 machines then there will be 5 instances of projects with the same name in the config passed to * [reporter.onBegin(config, suite)](https://playwright.dev/docs/api/class-reporter#reporter-on-begin). + * @since v1.10 */ export interface Reporter { /** * Called after all tests have been run, or testing has been interrupted. Note that this method may return a [Promise] * and Playwright Test will await it. Reporter is allowed to override the status and hence affect the exit code of the * test runner. + * @since v1.10 * @param result Result of the full test run, `status` can be one of: * - `'passed'` - Everything went as expected. * - `'failed'` - Any test has failed. @@ -161,6 +163,7 @@ export interface Reporter { /** * Called once before running tests. All tests have been already discovered and put into a hierarchy of * [Suite](https://playwright.dev/docs/api/class-suite)s. + * @since v1.10 * @param config Resolved configuration. * @param suite The root suite that contains all projects, files and test cases. */ @@ -168,6 +171,7 @@ export interface Reporter { /** * Called on some global error, for example unhandled exception in the worker process. + * @since v1.10 * @param error The error. */ onError?(error: TestError): void; @@ -176,11 +180,13 @@ export interface Reporter { * Called immediately before test runner exists. At this point all the reporters have received the * [reporter.onEnd(result)](https://playwright.dev/docs/api/class-reporter#reporter-on-end) signal, so all the reports * should be build. You can run the code that uploads the reports in this hook. + * @since v1.33 */ onExit?(): Promise; /** * Called when something has been written to the standard error in the worker process. + * @since v1.10 * @param chunk Output chunk. * @param test Test that was running. Note that output may happen when no test is running, in which case this will be [void]. * @param result Result of the test run, this object gets populated while the test runs. @@ -189,6 +195,7 @@ export interface Reporter { /** * Called when something has been written to the standard output in the worker process. + * @since v1.10 * @param chunk Output chunk. * @param test Test that was running. Note that output may happen when no test is running, in which case this will be [void]. * @param result Result of the test run, this object gets populated while the test runs. @@ -197,6 +204,7 @@ export interface Reporter { /** * Called when a test step started in the worker process. + * @since v1.10 * @param test Test that the step belongs to. * @param result Result of the test run, this object gets populated while the test runs. * @param step Test step instance that has started. @@ -205,6 +213,7 @@ export interface Reporter { /** * Called when a test step finished in the worker process. + * @since v1.10 * @param test Test that the step belongs to. * @param result Result of the test run. * @param step Test step instance that has finished. @@ -213,6 +222,7 @@ export interface Reporter { /** * Called after a test has been started in the worker process. + * @since v1.10 * @param test Test that has been started. * @param result Result of the test run, this object gets populated while the test runs. */ @@ -220,6 +230,7 @@ export interface Reporter { /** * Called after a test has been finished in the worker process. + * @since v1.10 * @param test Test that has been finished. * @param result Result of the test run. */ @@ -228,6 +239,7 @@ export interface Reporter { /** * Whether this reporter uses stdio for reporting. When it does not, Playwright Test could add some output to enhance * user experience. If your reporter does not print to the terminal, it is strongly recommended to return `false`. + * @since v1.10 */ printsToStdio?(): boolean; } @@ -350,11 +362,13 @@ export {}; * * Reporter is given a root suite in the * [reporter.onBegin(config, suite)](https://playwright.dev/docs/api/class-reporter#reporter-on-begin) method. + * @since v1.10 */ export interface Suite { /** * Returns the list of all test cases in this suite and its descendants, as opposite to * [suite.tests](https://playwright.dev/docs/api/class-suite#suite-tests). + * @since v1.10 */ allTests(): Array; @@ -363,31 +377,37 @@ export interface Suite { * differentiate between various entry types by using * [testCase.type](https://playwright.dev/docs/api/class-testcase#test-case-type) and * [suite.type](https://playwright.dev/docs/api/class-suite#suite-type). + * @since v1.44 */ entries(): Array; /** * Configuration of the project this suite belongs to, or [void] for the root suite. + * @since v1.10 */ project(): FullProject|undefined; /** * Returns a list of titles from the root down to this suite. + * @since v1.10 */ titlePath(): Array; /** * Location in the source where the suite is defined. Missing for root and project suites. + * @since v1.10 */ location?: Location; /** * Parent suite, missing for the root suite. + * @since v1.10 */ parent?: Suite; /** * Child suites. See [Suite](https://playwright.dev/docs/api/class-suite) for the hierarchy of suites. + * @since v1.10 */ suites: Array; @@ -396,6 +416,7 @@ export interface Suite { * defined in nested * [test.describe([title, details, callback])](https://playwright.dev/docs/api/class-test#test-describe) groups are * listed in the child [suite.suites](https://playwright.dev/docs/api/class-suite#suite-suites). + * @since v1.10 */ tests: Array; @@ -407,12 +428,14 @@ export interface Suite { * - Title passed to * [test.describe([title, details, callback])](https://playwright.dev/docs/api/class-test#test-describe) for a * group suite. + * @since v1.10 */ title: string; /** * Returns the type of the suite. The Suites form the following hierarchy: `root` -> `project` -> `file` -> `describe` * -> ...`describe` -> `test`. + * @since v1.44 */ type: "root"|"project"|"file"|"describe"; } @@ -423,10 +446,12 @@ export interface Suite { * When a single [test.(call)(title[, details, body])](https://playwright.dev/docs/api/class-test#test-call) is * running in multiple projects or repeated multiple times, it will have multiple `TestCase` objects in corresponding * projects' suites. + * @since v1.10 */ export interface TestCase { /** * Whether the test is considered running fine. Non-ok tests fail the test run with non-zero exit code. + * @since v1.10 */ ok(): boolean; @@ -435,31 +460,37 @@ export interface TestCase { * [testResult.status](https://playwright.dev/docs/api/class-testresult#test-result-status): * - Test that is expected to fail and actually fails is `'expected'`. * - Test that passes on a second retry is `'flaky'`. + * @since v1.10 */ outcome(): "skipped"|"expected"|"unexpected"|"flaky"; /** * Returns a list of titles from the root down to this test. + * @since v1.10 */ titlePath(): Array; /** * [testResult.annotations](https://playwright.dev/docs/api/class-testresult#test-result-annotations) of the last test * run. + * @since v1.10 */ annotations: Array<{ /** * Annotation type, for example `'skip'` or `'fail'`. + * @since v1.10 */ type: string; /** * Optional description. + * @since v1.10 */ description?: string; /** * Optional location in the source where the annotation is added. + * @since v1.10 */ location?: Location; }>; @@ -478,33 +509,39 @@ export interface TestCase { * * See also [testResult.status](https://playwright.dev/docs/api/class-testresult#test-result-status) for the actual * status. + * @since v1.10 */ expectedStatus: "passed"|"failed"|"timedOut"|"skipped"|"interrupted"; /** * A test ID that is computed based on the test file name, test title and project name. The ID is unique within * Playwright session. + * @since v1.25 */ id: string; /** * Location in the source where the test is defined. + * @since v1.10 */ location: Location; /** * Suite this test case belongs to. + * @since v1.10 */ parent: Suite; /** * Contains the repeat index when running in "repeat each" mode. This mode is enabled by passing `--repeat-each` to * the [command line](https://playwright.dev/docs/test-cli). + * @since v1.10 */ repeatEachIndex: number; /** * Results for each run of this test. + * @since v1.10 */ results: Array; @@ -512,6 +549,7 @@ export interface TestCase { * The maximum number of retries given to this test in the configuration. * * Learn more about [test retries](https://playwright.dev/docs/test-retries#retries). + * @since v1.10 */ retries: number; @@ -522,6 +560,7 @@ export interface TestCase { * `@`-tokens extracted from test and suite titles. * * Learn more about [test tags](https://playwright.dev/docs/test-annotations#tag-tests). + * @since v1.42 */ tags: Array; @@ -532,61 +571,72 @@ export interface TestCase { * [test.setTimeout(timeout)](https://playwright.dev/docs/api/class-test#test-set-timeout), * [test.slow([condition, callback, description])](https://playwright.dev/docs/api/class-test#test-slow) and * [testInfo.setTimeout(timeout)](https://playwright.dev/docs/api/class-testinfo#test-info-set-timeout). + * @since v1.10 */ timeout: number; /** * Test title as passed to the * [test.(call)(title[, details, body])](https://playwright.dev/docs/api/class-test#test-call) call. + * @since v1.10 */ title: string; /** * Returns "test". Useful for detecting test cases in * [suite.entries()](https://playwright.dev/docs/api/class-suite#suite-entries). + * @since v1.44 */ type: "test"; } /** * Information about an error thrown during test execution. + * @since v1.10 */ export interface TestError { /** * Error cause. Set when there is a * [cause](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error/cause) for the * error. Will be `undefined` if there is no cause or if the cause is not an instance of [Error]. + * @since v1.49 */ cause?: TestError; /** * Error location in the source code. + * @since v1.30 */ location?: Location; /** * Error message. Set when [Error] (or its subclass) has been thrown. + * @since v1.10 */ message?: string; /** * Source code snippet with highlighted error. + * @since v1.33 */ snippet?: string; /** * Error stack. Set when [Error] (or its subclass) has been thrown. + * @since v1.10 */ stack?: string; /** * The value that was thrown. Set when anything except the [Error] (or its subclass) has been thrown. + * @since v1.10 */ value?: string; } /** * A result of a single [TestCase](https://playwright.dev/docs/api/class-testcase) run. + * @since v1.10 */ export interface TestResult { /** @@ -607,20 +657,24 @@ export interface TestResult { * [testInfo.annotations](https://playwright.dev/docs/api/class-testinfo#test-info-annotations). * * Learn more about [test annotations](https://playwright.dev/docs/test-annotations). + * @since v1.52 */ annotations: Array<{ /** * Annotation type, for example `'skip'` or `'fail'`. + * @since v1.52 */ type: string; /** * Optional description. + * @since v1.52 */ description?: string; /** * Optional location in the source where the annotation is added. + * @since v1.52 */ location?: Location; }>; @@ -628,49 +682,58 @@ export interface TestResult { /** * The list of files or buffers attached during the test execution through * [testInfo.attachments](https://playwright.dev/docs/api/class-testinfo#test-info-attachments). + * @since v1.10 */ attachments: Array<{ /** * Attachment name. + * @since v1.10 */ name: string; /** * Content type of this attachment to properly present in the report, for example `'application/json'` or * `'image/png'`. + * @since v1.10 */ contentType: string; /** * Optional path on the filesystem to the attached file. + * @since v1.10 */ path?: string; /** * Optional attachment body used instead of a file. + * @since v1.10 */ body?: Buffer; }>; /** * Running time in milliseconds. + * @since v1.10 */ duration: number; /** * First error thrown during test execution, if any. This is equal to the first element in * [testResult.errors](https://playwright.dev/docs/api/class-testresult#test-result-errors). + * @since v1.10 */ error?: TestError; /** * Errors thrown during the test execution. + * @since v1.10 */ errors: Array; /** * The index of the worker between `0` and `workers - 1`. It is guaranteed that workers running at the same time have * a different `parallelIndex`. + * @since v1.30 */ parallelIndex: number; @@ -678,32 +741,38 @@ export interface TestResult { * When test is retried multiple times, each retry attempt is given a sequential number. * * Learn more about [test retries](https://playwright.dev/docs/test-retries#retries). + * @since v1.10 */ retry: number; /** * Start time of this particular test run. + * @since v1.10 */ startTime: Date; /** * The status of this test result. See also * [testCase.expectedStatus](https://playwright.dev/docs/api/class-testcase#test-case-expected-status). + * @since v1.10 */ status: "passed"|"failed"|"timedOut"|"skipped"|"interrupted"; /** * Anything written to the standard error during the test run. + * @since v1.10 */ stderr: Array; /** * Anything written to the standard output during the test run. + * @since v1.10 */ stdout: Array; /** * List of steps inside this test run. + * @since v1.10 */ steps: Array; @@ -712,35 +781,42 @@ export interface TestResult { * interrupted testing, the only result will have a `workerIndex` equal to `-1`. * * Learn more about [parallelism and sharding](https://playwright.dev/docs/test-parallel) with Playwright Test. + * @since v1.10 */ workerIndex: number; } /** * Represents a step in the [TestRun]. + * @since v1.10 */ export interface TestStep { /** * Returns a list of step titles from the root step down to this step. + * @since v1.10 */ titlePath(): Array; /** * The list of annotations applicable to the current test step. + * @since v1.51 */ annotations: Array<{ /** * Annotation type, for example `'skip'`. + * @since v1.51 */ type: string; /** * Optional description. + * @since v1.51 */ description?: string; /** * Optional location in the source where the annotation is added. + * @since v1.51 */ location?: Location; }>; @@ -748,26 +824,31 @@ export interface TestStep { /** * The list of files or buffers attached in the step execution through * [testInfo.attach(name[, options])](https://playwright.dev/docs/api/class-testinfo#test-info-attach). + * @since v1.50 */ attachments: Array<{ /** * Attachment name. + * @since v1.50 */ name: string; /** * Content type of this attachment to properly present in the report, for example `'application/json'` or * `'image/png'`. + * @since v1.50 */ contentType: string; /** * Optional path on the filesystem to the attached file. + * @since v1.50 */ path?: string; /** * Optional attachment body used instead of a file. + * @since v1.50 */ body?: Buffer; }>; @@ -780,41 +861,49 @@ export interface TestStep { * - `pw:api` for Playwright API calls. * - `test.step` for test.step API calls. * - `test.attach` for testInfo.attach API calls. + * @since v1.10 */ category: string; /** * Running time in milliseconds. + * @since v1.10 */ duration: number; /** * Error thrown during the step execution, if any. + * @since v1.10 */ error?: TestError; /** * Optional location in the source where the step is defined. + * @since v1.10 */ location?: Location; /** * Parent step, if any. + * @since v1.10 */ parent?: TestStep; /** * Start time of this particular test step. + * @since v1.10 */ startTime: Date; /** * List of steps inside this step. + * @since v1.10 */ steps: Array; /** * User-friendly test step title. + * @since v1.10 */ title: string; } diff --git a/utils/generate_types/index.js b/utils/generate_types/index.js index ad0531180884f..8ece2ed336bff 100644 --- a/utils/generate_types/index.js +++ b/utils/generate_types/index.js @@ -91,7 +91,10 @@ class TypesGenerator { if (!docClass) return ''; handledClasses.add(className); - return this.writeComment(docClass.comment, '') + '\n'; + const comment = docClass.comment || ''; + const since = docClass.since ? `@since ${docClass.since}` : ''; + const lines = [comment, since].filter(Boolean).join('\n'); + return this.writeComment(lines, '') + '\n'; }, (className, methodName, overloadIndex, indent) => { if (methodName === '__call') methodName = '(call)'; @@ -200,8 +203,11 @@ class TypesGenerator { */ classToString(classDesc) { const parts = []; - if (classDesc.comment) { - parts.push(this.writeComment(classDesc.comment, '')) + if (classDesc.comment || classDesc.since) { + const comment = classDesc.comment || ''; + const since = classDesc.since ? `@since ${classDesc.since}` : ''; + const lines = [comment, since].filter(Boolean).join('\n'); + parts.push(this.writeComment(lines, '')) } const shouldExport = !this.doNotExportClassNames.has(classDesc.name); parts.push(`${shouldExport ? 'export ' : ''}interface ${classDesc.name} ${classDesc.extends ? `extends ${classDesc.extends} ` : ''}{`); @@ -486,6 +492,8 @@ class TypesGenerator { lines.push(...member.comment.split('\n')); if (member.deprecated) lines.push('@deprecated ' + md.wrapText(member.deprecated, { flattenText: true, maxColumns: 120 - 5 }, '')); + if (member.since) + lines.push(`@since ${member.since}`); lines.push(...member.argsArray.map(arg => { const paramPrefix = `@param ${arg.alias.replace(/\./g, '')} `; return paramPrefix + md.wrapText(arg.comment, { flattenText: true, maxColumns: 120 - 5 }, '');