From 5acc78d14228367e7869d4e9b4d51f67b238d0b3 Mon Sep 17 00:00:00 2001 From: Max Schmitt Date: Mon, 9 Sep 2024 10:34:37 +0200 Subject: [PATCH] review feedback --- packages/playwright-core/types/types.d.ts | 391 ++++++++++++++++------ packages/playwright/types/test.d.ts | 22 +- utils/doclint/documentation.js | 2 +- utils/markdown.js | 1 - 4 files changed, 313 insertions(+), 103 deletions(-) diff --git a/packages/playwright-core/types/types.d.ts b/packages/playwright-core/types/types.d.ts index 765c84c36e52b0..3daec734b394e2 100644 --- a/packages/playwright-core/types/types.d.ts +++ b/packages/playwright-core/types/types.d.ts @@ -286,8 +286,11 @@ export interface Page { * * **NOTE** The order of evaluation of multiple scripts installed via * [browserContext.addInitScript(script[, arg])](https://playwright.dev/docs/api/class-browsercontext#browser-context-add-init-script) - * and [page.addInitScript(script[, arg])](https://playwright.dev/docs/api/class-page#page-add-init-script) is not + * and + * + * [page.addInitScript(script[, arg])](https://playwright.dev/docs/api/class-page#page-add-init-script) is not * defined. + * * @param script Script to be evaluated in the page. * @param arg Optional argument to pass to `script` (only supported when passing a function). */ @@ -626,8 +629,9 @@ export interface Page { * Returns when element specified by selector satisfies `state` option. Returns `null` if waiting for `hidden` or * `detached`. * - * **NOTE** Playwright automatically waits for element to be ready before performing an action. Using {@link Locator} - * objects and web-first assertions makes the code wait-for-selector-free. + * **NOTE** Playwright automatically waits for element to be ready before performing an action. Using + * + * {@link Locator} objects and web-first assertions makes the code wait-for-selector-free. * * Wait for the `selector` to satisfy `state` option (either appear/disappear from dom, or become visible/hidden). If * at the moment of calling the method `selector` already satisfies the condition, the method will return immediately. @@ -664,8 +668,9 @@ export interface Page { * Returns when element specified by selector satisfies `state` option. Returns `null` if waiting for `hidden` or * `detached`. * - * **NOTE** Playwright automatically waits for element to be ready before performing an action. Using {@link Locator} - * objects and web-first assertions makes the code wait-for-selector-free. + * **NOTE** Playwright automatically waits for element to be ready before performing an action. Using + * + * {@link Locator} objects and web-first assertions makes the code wait-for-selector-free. * * Wait for the `selector` to satisfy `state` option (either appear/disappear from dom, or become visible/hidden). If * at the moment of calling the method `selector` already satisfies the condition, the method will return immediately. @@ -702,8 +707,9 @@ export interface Page { * Returns when element specified by selector satisfies `state` option. Returns `null` if waiting for `hidden` or * `detached`. * - * **NOTE** Playwright automatically waits for element to be ready before performing an action. Using {@link Locator} - * objects and web-first assertions makes the code wait-for-selector-free. + * **NOTE** Playwright automatically waits for element to be ready before performing an action. Using + * + * {@link Locator} objects and web-first assertions makes the code wait-for-selector-free. * * Wait for the `selector` to satisfy `state` option (either appear/disappear from dom, or become visible/hidden). If * at the moment of calling the method `selector` already satisfies the condition, the method will return immediately. @@ -740,8 +746,9 @@ export interface Page { * Returns when element specified by selector satisfies `state` option. Returns `null` if waiting for `hidden` or * `detached`. * - * **NOTE** Playwright automatically waits for element to be ready before performing an action. Using {@link Locator} - * objects and web-first assertions makes the code wait-for-selector-free. + * **NOTE** Playwright automatically waits for element to be ready before performing an action. Using + * + * {@link Locator} objects and web-first assertions makes the code wait-for-selector-free. * * Wait for the `selector` to satisfy `state` option (either appear/disappear from dom, or become visible/hidden). If * at the moment of calling the method `selector` already satisfies the condition, the method will return immediately. @@ -975,6 +982,7 @@ export interface Page { * **NOTE** When no [page.on('dialog')](https://playwright.dev/docs/api/class-page#page-event-dialog) or * [browserContext.on('dialog')](https://playwright.dev/docs/api/class-browsercontext#browser-context-event-dialog) * listeners are present, all dialogs are automatically dismissed. + * */ on(event: 'dialog', listener: (dialog: Dialog) => any): this; @@ -1065,7 +1073,10 @@ export interface Page { * * **NOTE** Use * [page.waitForLoadState([state, options])](https://playwright.dev/docs/api/class-page#page-wait-for-load-state) to - * wait until the page gets to a particular state (you should not need it in most cases). + * wait until the page gets to a particular state (you should not need it in most + * + * cases). + * */ on(event: 'popup', listener: (page: Page) => any): this; @@ -1086,11 +1097,14 @@ export interface Page { * ``` * * **NOTE** HTTP Error responses, such as 404 or 503, are still successful responses from HTTP standpoint, so request - * will complete with - * [page.on('requestfinished')](https://playwright.dev/docs/api/class-page#page-event-request-finished) event and not - * with [page.on('requestfailed')](https://playwright.dev/docs/api/class-page#page-event-request-failed). A request - * will only be considered failed when the client cannot get an HTTP response from the server, e.g. due to network - * error net::ERR_FAILED. + * will complete + * + * with [page.on('requestfinished')](https://playwright.dev/docs/api/class-page#page-event-request-finished) event and + * not with [page.on('requestfailed')](https://playwright.dev/docs/api/class-page#page-event-request-failed). A + * request will only be considered + * + * failed when the client cannot get an HTTP response from the server, e.g. due to network error net::ERR_FAILED. + * */ on(event: 'requestfailed', listener: (request: Request) => any): this; @@ -1273,6 +1287,7 @@ export interface Page { * **NOTE** When no [page.on('dialog')](https://playwright.dev/docs/api/class-page#page-event-dialog) or * [browserContext.on('dialog')](https://playwright.dev/docs/api/class-browsercontext#browser-context-event-dialog) * listeners are present, all dialogs are automatically dismissed. + * */ addListener(event: 'dialog', listener: (dialog: Dialog) => any): this; @@ -1363,7 +1378,10 @@ export interface Page { * * **NOTE** Use * [page.waitForLoadState([state, options])](https://playwright.dev/docs/api/class-page#page-wait-for-load-state) to - * wait until the page gets to a particular state (you should not need it in most cases). + * wait until the page gets to a particular state (you should not need it in most + * + * cases). + * */ addListener(event: 'popup', listener: (page: Page) => any): this; @@ -1384,11 +1402,14 @@ export interface Page { * ``` * * **NOTE** HTTP Error responses, such as 404 or 503, are still successful responses from HTTP standpoint, so request - * will complete with - * [page.on('requestfinished')](https://playwright.dev/docs/api/class-page#page-event-request-finished) event and not - * with [page.on('requestfailed')](https://playwright.dev/docs/api/class-page#page-event-request-failed). A request - * will only be considered failed when the client cannot get an HTTP response from the server, e.g. due to network - * error net::ERR_FAILED. + * will complete + * + * with [page.on('requestfinished')](https://playwright.dev/docs/api/class-page#page-event-request-finished) event and + * not with [page.on('requestfailed')](https://playwright.dev/docs/api/class-page#page-event-request-failed). A + * request will only be considered + * + * failed when the client cannot get an HTTP response from the server, e.g. due to network error net::ERR_FAILED. + * */ addListener(event: 'requestfailed', listener: (request: Request) => any): this; @@ -1666,6 +1687,7 @@ export interface Page { * **NOTE** When no [page.on('dialog')](https://playwright.dev/docs/api/class-page#page-event-dialog) or * [browserContext.on('dialog')](https://playwright.dev/docs/api/class-browsercontext#browser-context-event-dialog) * listeners are present, all dialogs are automatically dismissed. + * */ prependListener(event: 'dialog', listener: (dialog: Dialog) => any): this; @@ -1756,7 +1778,10 @@ export interface Page { * * **NOTE** Use * [page.waitForLoadState([state, options])](https://playwright.dev/docs/api/class-page#page-wait-for-load-state) to - * wait until the page gets to a particular state (you should not need it in most cases). + * wait until the page gets to a particular state (you should not need it in most + * + * cases). + * */ prependListener(event: 'popup', listener: (page: Page) => any): this; @@ -1777,11 +1802,14 @@ export interface Page { * ``` * * **NOTE** HTTP Error responses, such as 404 or 503, are still successful responses from HTTP standpoint, so request - * will complete with - * [page.on('requestfinished')](https://playwright.dev/docs/api/class-page#page-event-request-finished) event and not - * with [page.on('requestfailed')](https://playwright.dev/docs/api/class-page#page-event-request-failed). A request - * will only be considered failed when the client cannot get an HTTP response from the server, e.g. due to network - * error net::ERR_FAILED. + * will complete + * + * with [page.on('requestfinished')](https://playwright.dev/docs/api/class-page#page-event-request-finished) event and + * not with [page.on('requestfailed')](https://playwright.dev/docs/api/class-page#page-event-request-failed). A + * request will only be considered + * + * failed when the client cannot get an HTTP response from the server, e.g. due to network error net::ERR_FAILED. + * */ prependListener(event: 'requestfailed', listener: (request: Request) => any): this; @@ -1834,13 +1862,25 @@ export interface Page { * * **NOTE** Running the handler will alter your page state mid-test. For example it will change the currently focused * element and move the mouse. Make sure that actions that run after the handler are self-contained and do not rely on - * the focus and mouse state being unchanged.

For example, consider a test that calls + * the focus and mouse state being unchanged. + * + *
+ * + *
+ * + * For example, consider a test that calls * [locator.focus([options])](https://playwright.dev/docs/api/class-locator#locator-focus) followed by * [keyboard.press(key[, options])](https://playwright.dev/docs/api/class-keyboard#keyboard-press). If your handler * clicks a button between these two actions, the focused element most likely will be wrong, and key press will happen * on the unexpected element. Use * [locator.press(key[, options])](https://playwright.dev/docs/api/class-locator#locator-press) instead to avoid this - * problem.

Another example is a series of mouse actions, where + * problem. + * + *
+ * + *
+ * + * Another example is a series of mouse actions, where * [mouse.move(x, y[, options])](https://playwright.dev/docs/api/class-mouse#mouse-move) is followed by * [mouse.down([options])](https://playwright.dev/docs/api/class-mouse#mouse-down). Again, when the handler runs * between these two actions, the mouse position will be wrong during the mouse down. Prefer self-contained actions @@ -2132,7 +2172,9 @@ export interface Page { * By default, `page.close()` **does not** run `beforeunload` handlers. * * **NOTE** if `runBeforeUnload` is passed as true, a `beforeunload` dialog might be summoned and should be handled + * * manually via [page.on('dialog')](https://playwright.dev/docs/api/class-page#page-event-dialog) event. + * * @param options */ close(options?: { @@ -2174,6 +2216,7 @@ export interface Page { * TimeoutError}. Passing zero timeout disables this. * * **NOTE** `page.dblclick()` dispatches two `click` events and a single `dblclick` event. + * * @param selector A selector to search for an element. If there are multiple elements satisfying the selector, the first will be * used. * @param options @@ -2768,8 +2811,10 @@ export interface Page { /** * An attribute that is usually set by `aria-disabled` or `disabled`. * - * **NOTE** Unlike most other attributes, `disabled` is inherited through the DOM hierarchy. Learn more about - * [`aria-disabled`](https://www.w3.org/TR/wai-aria-1.2/#aria-disabled). + * **NOTE** Unlike most other attributes, `disabled` is inherited through the DOM hierarchy. + * + * Learn more about [`aria-disabled`](https://www.w3.org/TR/wai-aria-1.2/#aria-disabled). + * */ disabled?: boolean; @@ -3019,10 +3064,14 @@ export interface Page { * [response.status()](https://playwright.dev/docs/api/class-response#response-status). * * **NOTE** The method either throws an error or returns a main resource response. The only exceptions are navigation - * to `about:blank` or navigation to the same URL with a different hash, which would succeed and return `null`. + * to + * + * `about:blank` or navigation to the same URL with a different hash, which would succeed and return `null`. * * **NOTE** Headless mode doesn't support navigation to a PDF document. See the + * * [upstream issue](https://bugs.chromium.org/p/chromium/issues/detail?id=761295). + * * @param url URL to navigate page to. The url should include scheme, e.g. `https://`. When a `baseURL` 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. @@ -3426,8 +3475,10 @@ export interface Page { * User can inspect selectors or perform manual steps while paused. Resume will continue running the original script * from the place it was paused. * - * **NOTE** This method requires Playwright to be started in a headed mode, with a falsy `headless` value in the - * [browserType.launch([options])](https://playwright.dev/docs/api/class-browsertype#browser-type-launch). + * **NOTE** This method requires Playwright to be started in a headed mode, with a falsy `headless` value in + * + * the [browserType.launch([options])](https://playwright.dev/docs/api/class-browsertype#browser-type-launch). + * */ pause(): Promise; @@ -3441,8 +3492,11 @@ export interface Page { * `page.pdf()`: * * **NOTE** By default, `page.pdf()` generates a pdf with modified colors for printing. Use the + * * [`-webkit-print-color-adjust`](https://developer.mozilla.org/en-US/docs/Web/CSS/-webkit-print-color-adjust) - * property to force rendering of exact colors. + * property to + * + * force rendering of exact colors. * * **Usage** * @@ -3480,7 +3534,9 @@ export interface Page { * - `A6`: 4.13in x 5.83in * * **NOTE** `headerTemplate` and `footerTemplate` markup have the following limitations: > 1. Script tags inside + * * templates are not evaluated. > 2. Page styles are not visible inside templates. + * * @param options */ pdf(options?: { @@ -3760,6 +3816,7 @@ export interface Page { * [page.unroute(url[, handler])](https://playwright.dev/docs/api/class-page#page-unroute). * * **NOTE** Enabling routing disables http cache. + * * @param url A glob pattern, regex pattern or predicate receiving [URL] to match while routing. When a `baseURL` 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. @@ -4031,9 +4088,11 @@ export interface Page { * [page.setDefaultNavigationTimeout(timeout)](https://playwright.dev/docs/api/class-page#page-set-default-navigation-timeout) * takes priority over * [page.setDefaultTimeout(timeout)](https://playwright.dev/docs/api/class-page#page-set-default-timeout), + * * [browserContext.setDefaultTimeout(timeout)](https://playwright.dev/docs/api/class-browsercontext#browser-context-set-default-timeout) * and * [browserContext.setDefaultNavigationTimeout(timeout)](https://playwright.dev/docs/api/class-browsercontext#browser-context-set-default-navigation-timeout). + * * @param timeout Maximum navigation time in milliseconds */ setDefaultNavigationTimeout(timeout: number): void; @@ -4045,6 +4104,7 @@ export interface Page { * [page.setDefaultNavigationTimeout(timeout)](https://playwright.dev/docs/api/class-page#page-set-default-navigation-timeout) * takes priority over * [page.setDefaultTimeout(timeout)](https://playwright.dev/docs/api/class-page#page-set-default-timeout). + * * @param timeout Maximum time in milliseconds */ setDefaultTimeout(timeout: number): void; @@ -4055,6 +4115,7 @@ export interface Page { * **NOTE** * [page.setExtraHTTPHeaders(headers)](https://playwright.dev/docs/api/class-page#page-set-extra-http-headers) does * not guarantee the order of headers in the outgoing requests. + * * @param headers An object containing additional HTTP headers to be sent with every request. All header values must be strings. */ setExtraHTTPHeaders(headers: { [key: string]: string; }): Promise; @@ -4184,6 +4245,7 @@ export interface Page { * * **NOTE** [page.tap(selector[, options])](https://playwright.dev/docs/api/class-page#page-tap) the method will throw * if `hasTouch` option of the browser context is false. + * * @param selector A selector to search for an element. If there are multiple elements satisfying the selector, the first will be * used. * @param options @@ -4485,6 +4547,7 @@ export interface Page { * **NOTE** When no [page.on('dialog')](https://playwright.dev/docs/api/class-page#page-event-dialog) or * [browserContext.on('dialog')](https://playwright.dev/docs/api/class-browsercontext#browser-context-event-dialog) * listeners are present, all dialogs are automatically dismissed. + * */ waitForEvent(event: 'dialog', optionsOrPredicate?: { predicate?: (dialog: Dialog) => boolean | Promise, timeout?: number } | ((dialog: Dialog) => boolean | Promise)): Promise; @@ -4575,7 +4638,10 @@ export interface Page { * * **NOTE** Use * [page.waitForLoadState([state, options])](https://playwright.dev/docs/api/class-page#page-wait-for-load-state) to - * wait until the page gets to a particular state (you should not need it in most cases). + * wait until the page gets to a particular state (you should not need it in most + * + * cases). + * */ waitForEvent(event: 'popup', optionsOrPredicate?: { predicate?: (page: Page) => boolean | Promise, timeout?: number } | ((page: Page) => boolean | Promise)): Promise; @@ -4596,11 +4662,14 @@ export interface Page { * ``` * * **NOTE** HTTP Error responses, such as 404 or 503, are still successful responses from HTTP standpoint, so request - * will complete with - * [page.on('requestfinished')](https://playwright.dev/docs/api/class-page#page-event-request-finished) event and not - * with [page.on('requestfailed')](https://playwright.dev/docs/api/class-page#page-event-request-failed). A request - * will only be considered failed when the client cannot get an HTTP response from the server, e.g. due to network - * error net::ERR_FAILED. + * will complete + * + * with [page.on('requestfinished')](https://playwright.dev/docs/api/class-page#page-event-request-finished) event and + * not with [page.on('requestfailed')](https://playwright.dev/docs/api/class-page#page-event-request-failed). A + * request will only be considered + * + * failed when the client cannot get an HTTP response from the server, e.g. due to network error net::ERR_FAILED. + * */ waitForEvent(event: 'requestfailed', optionsOrPredicate?: { predicate?: (request: Request) => boolean | Promise, timeout?: number } | ((request: Request) => boolean | Promise)): Promise; @@ -4692,7 +4761,10 @@ export interface Page { * ``` * * **NOTE** Usage of the [History API](https://developer.mozilla.org/en-US/docs/Web/API/History_API) to change the URL - * is considered a navigation. + * is considered + * + * a navigation. + * * @deprecated This method is inherently racy, please use * [page.waitForURL(url[, options])](https://playwright.dev/docs/api/class-page#page-wait-for-url) instead. * @param options @@ -4858,6 +4930,7 @@ export interface Page { * [WebWorkers](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API) associated with the page. * * **NOTE** This does not contain ServiceWorkers + * */ workers(): Array; @@ -5466,8 +5539,9 @@ export interface Frame { * Returns when element specified by selector satisfies `state` option. Returns `null` if waiting for `hidden` or * `detached`. * - * **NOTE** Playwright automatically waits for element to be ready before performing an action. Using {@link Locator} - * objects and web-first assertions make the code wait-for-selector-free. + * **NOTE** Playwright automatically waits for element to be ready before performing an action. Using + * + * {@link Locator} objects and web-first assertions make the code wait-for-selector-free. * * Wait for the `selector` to satisfy `state` option (either appear/disappear from dom, or become visible/hidden). If * at the moment of calling the method `selector` already satisfies the condition, the method will return immediately. @@ -5504,8 +5578,9 @@ export interface Frame { * Returns when element specified by selector satisfies `state` option. Returns `null` if waiting for `hidden` or * `detached`. * - * **NOTE** Playwright automatically waits for element to be ready before performing an action. Using {@link Locator} - * objects and web-first assertions make the code wait-for-selector-free. + * **NOTE** Playwright automatically waits for element to be ready before performing an action. Using + * + * {@link Locator} objects and web-first assertions make the code wait-for-selector-free. * * Wait for the `selector` to satisfy `state` option (either appear/disappear from dom, or become visible/hidden). If * at the moment of calling the method `selector` already satisfies the condition, the method will return immediately. @@ -5542,8 +5617,9 @@ export interface Frame { * Returns when element specified by selector satisfies `state` option. Returns `null` if waiting for `hidden` or * `detached`. * - * **NOTE** Playwright automatically waits for element to be ready before performing an action. Using {@link Locator} - * objects and web-first assertions make the code wait-for-selector-free. + * **NOTE** Playwright automatically waits for element to be ready before performing an action. Using + * + * {@link Locator} objects and web-first assertions make the code wait-for-selector-free. * * Wait for the `selector` to satisfy `state` option (either appear/disappear from dom, or become visible/hidden). If * at the moment of calling the method `selector` already satisfies the condition, the method will return immediately. @@ -5580,8 +5656,9 @@ export interface Frame { * Returns when element specified by selector satisfies `state` option. Returns `null` if waiting for `hidden` or * `detached`. * - * **NOTE** Playwright automatically waits for element to be ready before performing an action. Using {@link Locator} - * objects and web-first assertions make the code wait-for-selector-free. + * **NOTE** Playwright automatically waits for element to be ready before performing an action. Using + * + * {@link Locator} objects and web-first assertions make the code wait-for-selector-free. * * Wait for the `selector` to satisfy `state` option (either appear/disappear from dom, or become visible/hidden). If * at the moment of calling the method `selector` already satisfies the condition, the method will return immediately. @@ -5839,6 +5916,7 @@ export interface Frame { * TimeoutError}. Passing zero timeout disables this. * * **NOTE** `frame.dblclick()` dispatches two `click` events and a single `dblclick` event. + * * @param selector A selector to search for an element. If there are multiple elements satisfying the selector, the first will be * used. * @param options @@ -6298,8 +6376,10 @@ export interface Frame { /** * An attribute that is usually set by `aria-disabled` or `disabled`. * - * **NOTE** Unlike most other attributes, `disabled` is inherited through the DOM hierarchy. Learn more about - * [`aria-disabled`](https://www.w3.org/TR/wai-aria-1.2/#aria-disabled). + * **NOTE** Unlike most other attributes, `disabled` is inherited through the DOM hierarchy. + * + * Learn more about [`aria-disabled`](https://www.w3.org/TR/wai-aria-1.2/#aria-disabled). + * */ disabled?: boolean; @@ -6489,10 +6569,14 @@ export interface Frame { * [response.status()](https://playwright.dev/docs/api/class-response#response-status). * * **NOTE** The method either throws an error or returns a main resource response. The only exceptions are navigation - * to `about:blank` or navigation to the same URL with a different hash, which would succeed and return `null`. + * to + * + * `about:blank` or navigation to the same URL with a different hash, which would succeed and return `null`. * * **NOTE** Headless mode doesn't support navigation to a PDF document. See the + * * [upstream issue](https://bugs.chromium.org/p/chromium/issues/detail?id=761295). + * * @param url URL to navigate frame to. The url should include scheme, e.g. `https://`. * @param options */ @@ -6883,6 +6967,7 @@ export interface Frame { * * **NOTE** This value is calculated once when the frame is created, and will not update if the attribute is changed * later. + * */ name(): string; @@ -7226,6 +7311,7 @@ export interface Frame { * TimeoutError}. Passing zero timeout disables this. * * **NOTE** `frame.tap()` requires that the `hasTouch` option of the browser context be set to true. + * * @param selector A selector to search for an element. If there are multiple elements satisfying the selector, the first will be * used. * @param options @@ -7480,7 +7566,10 @@ export interface Frame { * ``` * * **NOTE** Usage of the [History API](https://developer.mozilla.org/en-US/docs/Web/API/History_API) to change the URL - * is considered a navigation. + * is considered + * + * a navigation. + * * @deprecated This method is inherently racy, please use * [frame.waitForURL(url[, options])](https://playwright.dev/docs/api/class-frame#frame-wait-for-url) instead. * @param options @@ -7698,8 +7787,11 @@ export interface BrowserContext { * * **NOTE** The order of evaluation of multiple scripts installed via * [browserContext.addInitScript(script[, arg])](https://playwright.dev/docs/api/class-browsercontext#browser-context-add-init-script) - * and [page.addInitScript(script[, arg])](https://playwright.dev/docs/api/class-page#page-add-init-script) is not + * and + * + * [page.addInitScript(script[, arg])](https://playwright.dev/docs/api/class-page#page-add-init-script) is not * defined. + * * @param script Script to be evaluated in all pages in the browser context. * @param arg Optional argument to pass to `script` (only supported when passing a function). */ @@ -7786,6 +7878,7 @@ export interface BrowserContext { * **NOTE** When no [page.on('dialog')](https://playwright.dev/docs/api/class-page#page-event-dialog) or * [browserContext.on('dialog')](https://playwright.dev/docs/api/class-browsercontext#browser-context-event-dialog) * listeners are present, all dialogs are automatically dismissed. + * */ on(event: 'dialog', listener: (dialog: Dialog) => any): this; @@ -7813,7 +7906,10 @@ export interface BrowserContext { * * **NOTE** Use * [page.waitForLoadState([state, options])](https://playwright.dev/docs/api/class-page#page-wait-for-load-state) to - * wait until the page gets to a particular state (you should not need it in most cases). + * wait until the page gets to a particular state (you should not need it in most + * + * cases). + * */ on(event: 'page', listener: (page: Page) => any): this; @@ -7833,10 +7929,13 @@ export interface BrowserContext { * use [page.on('requestfailed')](https://playwright.dev/docs/api/class-page#page-event-request-failed). * * **NOTE** HTTP Error responses, such as 404 or 503, are still successful responses from HTTP standpoint, so request - * will complete with + * will complete + * + * with * [browserContext.on('requestfinished')](https://playwright.dev/docs/api/class-browsercontext#browser-context-event-request-finished) * event and not with * [browserContext.on('requestfailed')](https://playwright.dev/docs/api/class-browsercontext#browser-context-event-request-failed). + * */ on(event: 'requestfailed', listener: (request: Request) => any): this; @@ -7982,6 +8081,7 @@ export interface BrowserContext { * **NOTE** When no [page.on('dialog')](https://playwright.dev/docs/api/class-page#page-event-dialog) or * [browserContext.on('dialog')](https://playwright.dev/docs/api/class-browsercontext#browser-context-event-dialog) * listeners are present, all dialogs are automatically dismissed. + * */ addListener(event: 'dialog', listener: (dialog: Dialog) => any): this; @@ -8009,7 +8109,10 @@ export interface BrowserContext { * * **NOTE** Use * [page.waitForLoadState([state, options])](https://playwright.dev/docs/api/class-page#page-wait-for-load-state) to - * wait until the page gets to a particular state (you should not need it in most cases). + * wait until the page gets to a particular state (you should not need it in most + * + * cases). + * */ addListener(event: 'page', listener: (page: Page) => any): this; @@ -8029,10 +8132,13 @@ export interface BrowserContext { * use [page.on('requestfailed')](https://playwright.dev/docs/api/class-page#page-event-request-failed). * * **NOTE** HTTP Error responses, such as 404 or 503, are still successful responses from HTTP standpoint, so request - * will complete with + * will complete + * + * with * [browserContext.on('requestfinished')](https://playwright.dev/docs/api/class-browsercontext#browser-context-event-request-finished) * event and not with * [browserContext.on('requestfailed')](https://playwright.dev/docs/api/class-browsercontext#browser-context-event-request-failed). + * */ addListener(event: 'requestfailed', listener: (request: Request) => any): this; @@ -8233,6 +8339,7 @@ export interface BrowserContext { * **NOTE** When no [page.on('dialog')](https://playwright.dev/docs/api/class-page#page-event-dialog) or * [browserContext.on('dialog')](https://playwright.dev/docs/api/class-browsercontext#browser-context-event-dialog) * listeners are present, all dialogs are automatically dismissed. + * */ prependListener(event: 'dialog', listener: (dialog: Dialog) => any): this; @@ -8260,7 +8367,10 @@ export interface BrowserContext { * * **NOTE** Use * [page.waitForLoadState([state, options])](https://playwright.dev/docs/api/class-page#page-wait-for-load-state) to - * wait until the page gets to a particular state (you should not need it in most cases). + * wait until the page gets to a particular state (you should not need it in most + * + * cases). + * */ prependListener(event: 'page', listener: (page: Page) => any): this; @@ -8280,10 +8390,13 @@ export interface BrowserContext { * use [page.on('requestfailed')](https://playwright.dev/docs/api/class-page#page-event-request-failed). * * **NOTE** HTTP Error responses, such as 404 or 503, are still successful responses from HTTP standpoint, so request - * will complete with + * will complete + * + * with * [browserContext.on('requestfinished')](https://playwright.dev/docs/api/class-browsercontext#browser-context-event-request-finished) * event and not with * [browserContext.on('requestfailed')](https://playwright.dev/docs/api/class-browsercontext#browser-context-event-request-failed). + * */ prependListener(event: 'requestfailed', listener: (request: Request) => any): this; @@ -8434,6 +8547,7 @@ export interface BrowserContext { * Closes the browser context. All the pages that belong to the browser context will be closed. * * **NOTE** The default browser context cannot be closed. + * * @param options */ close(options?: { @@ -8592,6 +8706,7 @@ export interface BrowserContext { * [browserContext.unroute(url[, handler])](https://playwright.dev/docs/api/class-browsercontext#browser-context-unroute). * * **NOTE** Enabling routing disables http cache. + * * @param url A glob pattern, regex pattern or predicate receiving [URL] to match while routing. When a `baseURL` 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. @@ -8673,7 +8788,9 @@ export interface BrowserContext { * [page.setDefaultNavigationTimeout(timeout)](https://playwright.dev/docs/api/class-page#page-set-default-navigation-timeout) * and [page.setDefaultTimeout(timeout)](https://playwright.dev/docs/api/class-page#page-set-default-timeout) take * priority over + * * [browserContext.setDefaultNavigationTimeout(timeout)](https://playwright.dev/docs/api/class-browsercontext#browser-context-set-default-navigation-timeout). + * * @param timeout Maximum navigation time in milliseconds */ setDefaultNavigationTimeout(timeout: number): void; @@ -8684,9 +8801,11 @@ export interface BrowserContext { * **NOTE** * [page.setDefaultNavigationTimeout(timeout)](https://playwright.dev/docs/api/class-page#page-set-default-navigation-timeout), * [page.setDefaultTimeout(timeout)](https://playwright.dev/docs/api/class-page#page-set-default-timeout) and + * * [browserContext.setDefaultNavigationTimeout(timeout)](https://playwright.dev/docs/api/class-browsercontext#browser-context-set-default-navigation-timeout) * take priority over * [browserContext.setDefaultTimeout(timeout)](https://playwright.dev/docs/api/class-browsercontext#browser-context-set-default-timeout). + * * @param timeout Maximum time in milliseconds */ setDefaultTimeout(timeout: number): void; @@ -8701,6 +8820,7 @@ export interface BrowserContext { * **NOTE** * [browserContext.setExtraHTTPHeaders(headers)](https://playwright.dev/docs/api/class-browsercontext#browser-context-set-extra-http-headers) * does not guarantee the order of headers in the outgoing requests. + * * @param headers An object containing additional HTTP headers to be sent with every request. All header values must be strings. */ setExtraHTTPHeaders(headers: { [key: string]: string; }): Promise; @@ -8716,7 +8836,10 @@ export interface BrowserContext { * * **NOTE** Consider using * [browserContext.grantPermissions(permissions[, options])](https://playwright.dev/docs/api/class-browsercontext#browser-context-grant-permissions) - * to grant permissions for the browser context pages to read its geolocation. + * to grant permissions for the browser context pages to read + * + * its geolocation. + * * @param geolocation */ setGeolocation(geolocation: null|{ @@ -8883,6 +9006,7 @@ export interface BrowserContext { * **NOTE** When no [page.on('dialog')](https://playwright.dev/docs/api/class-page#page-event-dialog) or * [browserContext.on('dialog')](https://playwright.dev/docs/api/class-browsercontext#browser-context-event-dialog) * listeners are present, all dialogs are automatically dismissed. + * */ waitForEvent(event: 'dialog', optionsOrPredicate?: { predicate?: (dialog: Dialog) => boolean | Promise, timeout?: number } | ((dialog: Dialog) => boolean | Promise)): Promise; @@ -8910,7 +9034,10 @@ export interface BrowserContext { * * **NOTE** Use * [page.waitForLoadState([state, options])](https://playwright.dev/docs/api/class-page#page-wait-for-load-state) to - * wait until the page gets to a particular state (you should not need it in most cases). + * wait until the page gets to a particular state (you should not need it in most + * + * cases). + * */ waitForEvent(event: 'page', optionsOrPredicate?: { predicate?: (page: Page) => boolean | Promise, timeout?: number } | ((page: Page) => boolean | Promise)): Promise; @@ -8930,10 +9057,13 @@ export interface BrowserContext { * use [page.on('requestfailed')](https://playwright.dev/docs/api/class-page#page-event-request-failed). * * **NOTE** HTTP Error responses, such as 404 or 503, are still successful responses from HTTP standpoint, so request - * will complete with + * will complete + * + * with * [browserContext.on('requestfinished')](https://playwright.dev/docs/api/class-browsercontext#browser-context-event-request-finished) * event and not with * [browserContext.on('requestfailed')](https://playwright.dev/docs/api/class-browsercontext#browser-context-event-request-failed). + * */ waitForEvent(event: 'requestfailed', optionsOrPredicate?: { predicate?: (request: Request) => boolean | Promise, timeout?: number } | ((request: Request) => boolean | Promise)): Promise; @@ -9123,9 +9253,10 @@ export interface Browser { * **NOTE** If directly using this method to create {@link BrowserContext}s, it is best practice to explicitly close * the returned context via * [browserContext.close([options])](https://playwright.dev/docs/api/class-browsercontext#browser-context-close) when - * your code is done with the {@link BrowserContext}, and before calling - * [browser.close([options])](https://playwright.dev/docs/api/class-browser#browser-close). This will ensure the - * `context` is closed gracefully and any artifacts—like HARs and videos—are fully flushed and saved. + * your code is done with the {@link BrowserContext}, + * + * and before calling [browser.close([options])](https://playwright.dev/docs/api/class-browser#browser-close). This + * will ensure the `context` is closed gracefully and any artifacts—like HARs and videos—are fully flushed and saved. * * **Usage** * @@ -9201,6 +9332,7 @@ export interface Browser { * * **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`. + * */ clientCertificates?: Array<{ /** @@ -9586,8 +9718,12 @@ export interface Browser { * Emulates consistent viewport for each page. Defaults to an 1280x720 viewport. Use `null` to disable the consistent * viewport emulation. Learn more about [viewport emulation](https://playwright.dev/docs/emulation#viewport). * - * **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. + * **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. + * */ viewport?: null|{ /** @@ -9888,7 +10024,10 @@ export interface JSHandle { * Returns a JSON representation of the object. If the object has a `toJSON` function, it **will not be called**. * * **NOTE** The method will return an empty JSON object if the referenced object is not stringifiable. It will throw - * an error if the object has circular references. + * an error if the + * + * object has circular references. + * */ jsonValue(): Promise; /** @@ -10288,6 +10427,7 @@ export interface ElementHandle extends JSHandle { * **NOTE** This method does not work across navigations, use * [page.waitForSelector(selector[, options])](https://playwright.dev/docs/api/class-page#page-wait-for-selector) * instead. + * * @param selector A selector to query for. * @param options */ @@ -10316,6 +10456,7 @@ export interface ElementHandle extends JSHandle { * **NOTE** This method does not work across navigations, use * [page.waitForSelector(selector[, options])](https://playwright.dev/docs/api/class-page#page-wait-for-selector) * instead. + * * @param selector A selector to query for. * @param options */ @@ -10344,6 +10485,7 @@ export interface ElementHandle extends JSHandle { * **NOTE** This method does not work across navigations, use * [page.waitForSelector(selector[, options])](https://playwright.dev/docs/api/class-page#page-wait-for-selector) * instead. + * * @param selector A selector to query for. * @param options */ @@ -10372,6 +10514,7 @@ export interface ElementHandle extends JSHandle { * **NOTE** This method does not work across navigations, use * [page.waitForSelector(selector[, options])](https://playwright.dev/docs/api/class-page#page-wait-for-selector) * instead. + * * @param selector A selector to query for. * @param options */ @@ -10575,6 +10718,7 @@ export interface ElementHandle extends JSHandle { * TimeoutError}. Passing zero timeout disables this. * * **NOTE** `elementHandle.dblclick()` dispatches two `click` events and a single `dblclick` event. + * * @param options */ dblclick(options?: { @@ -11301,6 +11445,7 @@ export interface ElementHandle extends JSHandle { * TimeoutError}. Passing zero timeout disables this. * * **NOTE** `elementHandle.tap()` requires that the `hasTouch` option of the browser context be set to true. + * * @param options */ tap(options?: { @@ -11655,10 +11800,14 @@ export interface Locator { * elements. * * **NOTE** [locator.all()](https://playwright.dev/docs/api/class-locator#locator-all) does not wait for elements to - * match the locator, and instead immediately returns whatever is present in the page. When the list of elements - * changes dynamically, [locator.all()](https://playwright.dev/docs/api/class-locator#locator-all) will produce - * unpredictable and flaky results. When the list of elements is stable, but loaded dynamically, wait for the full - * list to finish loading before calling [locator.all()](https://playwright.dev/docs/api/class-locator#locator-all). + * match the locator, and instead immediately returns whatever is present in the page. + * + * When the list of elements changes dynamically, + * [locator.all()](https://playwright.dev/docs/api/class-locator#locator-all) will produce unpredictable and flaky + * results. + * + * When the list of elements is stable, but loaded dynamically, wait for the full list to finish loading before + * calling [locator.all()](https://playwright.dev/docs/api/class-locator#locator-all). * * **Usage** * @@ -12045,6 +12194,7 @@ export interface Locator { * TimeoutError}. Passing zero timeout disables this. * * **NOTE** `element.dblclick()` dispatches two `click` events and a single `dblclick` event. + * * @param options */ dblclick(options?: { @@ -12373,6 +12523,7 @@ export interface Locator { * **NOTE** If you need to assert an element's attribute, prefer * [expect(locator).toHaveAttribute(name, value[, options])](https://playwright.dev/docs/api/class-locatorassertions#locator-assertions-to-have-attribute) * to avoid flakiness. See [assertions guide](https://playwright.dev/docs/test-assertions) for more details. + * * @param name Attribute name to get the value for. * @param options */ @@ -12523,8 +12674,10 @@ export interface Locator { /** * An attribute that is usually set by `aria-disabled` or `disabled`. * - * **NOTE** Unlike most other attributes, `disabled` is inherited through the DOM hierarchy. Learn more about - * [`aria-disabled`](https://www.w3.org/TR/wai-aria-1.2/#aria-disabled). + * **NOTE** Unlike most other attributes, `disabled` is inherited through the DOM hierarchy. + * + * Learn more about [`aria-disabled`](https://www.w3.org/TR/wai-aria-1.2/#aria-disabled). + * */ disabled?: boolean; @@ -12791,6 +12944,7 @@ export interface Locator { * **NOTE** If you need to assert text on the page, prefer * [expect(locator).toHaveText(expected[, options])](https://playwright.dev/docs/api/class-locatorassertions#locator-assertions-to-have-text) * with `useInnerText` option to avoid flakiness. See [assertions guide](https://playwright.dev/docs/test-assertions) for more details. + * * @param options */ innerText(options?: { @@ -13523,6 +13677,7 @@ export interface Locator { * TimeoutError}. Passing zero timeout disables this. * * **NOTE** `element.tap()` requires that the `hasTouch` option of the browser context be set to true. + * * @param options */ tap(options?: { @@ -13575,6 +13730,7 @@ export interface Locator { * **NOTE** If you need to assert text on the page, prefer * [expect(locator).toHaveText(expected[, options])](https://playwright.dev/docs/api/class-locatorassertions#locator-assertions-to-have-text) * to avoid flakiness. See [assertions guide](https://playwright.dev/docs/test-assertions) for more details. + * * @param options */ textContent(options?: { @@ -13920,6 +14076,7 @@ export interface BrowserType { * * **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`. + * */ clientCertificates?: Array<{ /** @@ -14327,8 +14484,12 @@ export interface BrowserType { * Emulates consistent viewport for each page. Defaults to an 1280x720 viewport. Use `null` to disable the consistent * viewport emulation. Learn more about [viewport emulation](https://playwright.dev/docs/emulation#viewport). * - * **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. + * **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. + * */ viewport?: null|{ /** @@ -14507,8 +14668,12 @@ export interface BrowserType { /** * Path at which to serve the Browser Server. For security, this defaults to an unguessable string. * - * **NOTE** Any process or web page (including those running in Playwright) with knowledge of the `wsPath` can take - * control of the OS user. For this reason, you should use an unguessable token when using this option. + * **NOTE** Any process or web page (including those running in Playwright) with knowledge + * + * of the `wsPath` can take control of the OS user. For this reason, you should + * + * use an unguessable token when using this option. + * */ wsPath?: string; }): Promise; @@ -14627,8 +14792,9 @@ export interface Accessibility { * the page. * * **NOTE** The Chromium accessibility tree contains nodes that go unused on most platforms and by most screen - * readers. Playwright will discard them as well for an easier to process tree, unless `interestingOnly` is set to - * `false`. + * readers. Playwright + * + * will discard them as well for an easier to process tree, unless `interestingOnly` is set to `false`. * * **Usage** * @@ -15348,8 +15514,12 @@ export interface Android { /** * Path at which to serve the Android Server. For security, this defaults to an unguessable string. * - * **NOTE** Any process or web page (including those running in Playwright) with knowledge of the `wsPath` can take - * control of the OS user. For this reason, you should use an unguessable token when using this option. + * **NOTE** Any process or web page (including those running in Playwright) with knowledge + * + * of the `wsPath` can take control of the OS user. For this reason, you should + * + * use an unguessable token when using this option. + * */ wsPath?: string; }): Promise; @@ -15843,8 +16013,12 @@ export interface AndroidDevice { * Emulates consistent viewport for each page. Defaults to an 1280x720 viewport. Use `null` to disable the consistent * viewport emulation. Learn more about [viewport emulation](https://playwright.dev/docs/emulation#viewport). * - * **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. + * **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. + * */ viewport?: null|{ /** @@ -16346,6 +16520,7 @@ export interface APIRequest { * * **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`. + * */ clientCertificates?: Array<{ /** @@ -17669,8 +17844,12 @@ export interface Coverage { * Returns coverage is started * * **NOTE** Anonymous scripts are ones that don't have an associated url. These are scripts that are dynamically - * created on the page using `eval` or `new Function`. If `reportAnonymousScripts` is set to `true`, anonymous scripts + * created + * + * on the page using `eval` or `new Function`. If `reportAnonymousScripts` is set to `true`, anonymous scripts + * * will have `__playwright_evaluation_script__` as their URL. + * * @param options */ startJSCoverage(options?: { @@ -17689,6 +17868,7 @@ export interface Coverage { * Returns the array of coverage reports for all stylesheets * * **NOTE** CSS Coverage doesn't include dynamically injected style tags without sourceURLs. + * */ stopCSSCoverage(): Promise; @@ -18763,6 +18950,7 @@ export interface Keyboard { * * **NOTE** Modifier keys DO NOT effect `keyboard.insertText`. Holding down `Shift` will not type the text in upper * case. + * * @param text Sets input to the specified text value. */ insertText(text: string): Promise; @@ -18838,6 +19026,7 @@ export interface Keyboard { * **NOTE** Modifier keys DO NOT effect `keyboard.type`. Holding down `Shift` will not type the text in upper case. * * **NOTE** For characters that are not on a US keyboard, only an `input` event will be sent. + * * @param text A text to type into a focused element. * @param options */ @@ -19011,8 +19200,10 @@ export interface Mouse { * Dispatches a `wheel` event. This method is usually used to manually scroll the page. See * [scrolling](https://playwright.dev/docs/input#scrolling) for alternative ways to scroll. * - * **NOTE** Wheel events may cause scrolling if they are not handled, and this method does not wait for the scrolling - * to finish before returning. + * **NOTE** Wheel events may cause scrolling if they are not handled, and this method does not + * + * wait for the scrolling to finish before returning. + * * @param deltaX Pixels to scroll horizontally. * @param deltaY Pixels to scroll vertically. */ @@ -19060,7 +19251,9 @@ export const webkit: BrowserType; * is emitted. * * **NOTE** HTTP Error responses, such as 404 or 503, are still successful responses from HTTP standpoint, so request - * will complete with `'requestfinished'` event. + * will complete + * + * with `'requestfinished'` event. * * If request gets a 'redirect' response, the request is successfully finished with the `requestfinished` event, and a * new request is issued to a redirected url. @@ -19907,6 +20100,7 @@ export interface Touchscreen { * * **NOTE** [page.tap(selector[, options])](https://playwright.dev/docs/api/class-page#page-tap) the method will throw * if `hasTouch` option of the browser context is false. + * * @param x X coordinate relative to the main frame's viewport in CSS pixels. * @param y Y coordinate relative to the main frame's viewport in CSS pixels. */ @@ -20708,6 +20902,7 @@ 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`. + * */ clientCertificates?: Array<{ /** @@ -21061,8 +21256,12 @@ export interface BrowserContextOptions { * Emulates consistent viewport for each page. Defaults to an 1280x720 viewport. Use `null` to disable the consistent * viewport emulation. Learn more about [viewport emulation](https://playwright.dev/docs/emulation#viewport). * - * **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. + * **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. + * */ viewport?: null|ViewportSize; } diff --git a/packages/playwright/types/test.d.ts b/packages/playwright/types/test.d.ts index 09b5c7efdb82c4..d8664e22792584 100644 --- a/packages/playwright/types/test.d.ts +++ b/packages/playwright/types/test.d.ts @@ -2515,6 +2515,7 @@ export interface TestType