@molecule/app-e2e-fixtures-default
Feature · e2e-fixtures-default · App (browser) · v1.2.2 · Apache-2.0
The @playwright/test drop-in for molecule apps: Playwright's test, expect and page with the browser supplied by the bonded e2e provider (live preview or real browsers), a console-error guard on every test, and the Playwright-shaped page adapter for evaluate-only bonds.
npm install @molecule/app-e2e-fixtures-defaultHow it works
@molecule/app-e2e-fixtures-default is a ready-made e2e-fixtures-default feature for the app (browser) side. It composes the core interfaces it needs, so it works with whichever providers your app has bonded.
// e2e/bonds.ts — scaffolded; wires the provider for THIS environment
import { resolveE2EProviderName, setProvider } from '@molecule/app-e2e'
import { provider as playwright } from '@molecule/app-e2e-playwright'
import { provider as preview } from '@molecule/app-e2e-preview'
setProvider(resolveE2EProviderName() === 'preview' ? preview : playwright)
// e2e/post.spec.ts — an ordinary Playwright spec
import { expect, test } from '@molecule/app-e2e-fixtures-default'
import './bonds.js'
test('the phone layout keeps the prose large', async ({ page }) => {
await page.setViewportSize({ width: 390, height: 844 })
await page.goto('/blog/hello/')
const prose = page.locator('article p').first()
const size = await prose.evaluate((el) => parseFloat(getComputedStyle(el).fontSize))
expect(size).toBeGreaterThanOrEqual(18)
await expect(page.getByRole('switch', { name: /summar/i })).toBeVisible()
})Works with: @molecule/app-bond, @molecule/app-e2e
Reference
The @playwright/test drop-in for molecule apps: Playwright's test,
expect and page, with the browser supplied by the bonded e2e provider
and a console-error guard on every test.
Import test and expect from here instead of @playwright/test and
write ordinary Playwright specs. Which browser runs them is the e2e bond
(@molecule/app-e2e):
@molecule/app-e2e-playwrightlaunches a real Playwright browser. Every molecule sandbox image bakes Chromium, so this is what a sandbox uses as well as your own machine and CI — the specs run against the app's dev server onlocalhost, no IDE tab involved.@molecule/app-e2e-previewdrives the LIVE PREVIEW the molecule.dev IDE is showing — the page the person is looking at, in their own browser — over a WebSocket through the dev server. Pick it withMOL_E2E_PROVIDER=previewwhen the point is that tab.
The same spec file runs unchanged in both. The provider is picked by
resolveE2EProviderName(): MOL_E2E_PROVIDER when set; otherwise, inside
a molecule sandbox (the /etc/mol/app-root marker exists), playwright
when a Playwright browser is installed and preview when none is; and
playwright everywhere else. The scaffolded e2e/bonds.ts bonds the
matching provider (and test bonds it by name as a fallback); test reads
the same answer to decide whether to launch a browser.
Every test also carries the console-error guard: the page's pageerror
and console.error events fail the test at teardown, so a spec that only
asserts on page.request cannot stay green while the rendered page is
blank. Allow a known error with
test.info().annotations.push({ type: 'allow-console-error', description: '<regex>' }).
Quick Start
// e2e/bonds.ts — scaffolded; wires the provider for THIS environment
import { resolveE2EProviderName, setProvider } from '@molecule/app-e2e'
import { provider as playwright } from '@molecule/app-e2e-playwright'
import { provider as preview } from '@molecule/app-e2e-preview'
setProvider(resolveE2EProviderName() === 'preview' ? preview : playwright)
// e2e/post.spec.ts — an ordinary Playwright spec
import { expect, test } from '@molecule/app-e2e-fixtures-default'
import './bonds.js'
test('the phone layout keeps the prose large', async ({ page }) => {
await page.setViewportSize({ width: 390, height: 844 })
await page.goto('/blog/hello/')
const prose = page.locator('article p').first()
const size = await prose.evaluate((el) => parseFloat(getComputedStyle(el).fontSize))
expect(size).toBeGreaterThanOrEqual(18)
await expect(page.getByRole('switch', { name: /summar/i })).toBeVisible()
})
Type
feature
Installation
npm install @molecule/app-e2e-fixtures-default @molecule/app-bond @molecule/app-e2e @playwright/test
API
Interfaces
APIRequestContext
This API is used for the Web API testing. You can use it to trigger API endpoints, configure micro-services, prepare environment or the service to your e2e test.
Each Playwright browser context has an associated APIRequestContext, accessible via browserContext.request or page.request (these return the
same instance — page.request is a shortcut for page.context().request). You can also create a standalone,
isolated instance with
apiRequest.newContext([options]).
Cookie management
The APIRequestContext returned by browserContext.request and
page.request uses the same cookie jar as its BrowserContext:
If you want API requests that do not share cookies with the browser, create an isolated context via
apiRequest.newContext([options]). Such
APIRequestContext object will have its own isolated cookie storage.
interface APIRequestContext {
/**
* Sends HTTP(S) [DELETE](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/DELETE) request and returns its
* response. The method will populate request cookies from the context and update context cookies from the response.
* The method will automatically follow redirects.
* @param url Target URL.
* @param options
*/
delete<T = any>(
url: string,
options?: {
/**
* Allows to set post data of the request. If the data parameter is an object, it will be serialized to json string
* and `content-type` header will be set to `application/json` if not explicitly set. Otherwise the `content-type`
* header will be set to `application/octet-stream` if not explicitly set.
*/
data?: string | Buffer | Serializable
/**
* Whether to throw on response codes other than 2xx and 3xx. By default response object is returned for all status
* codes.
*/
failOnStatusCode?: boolean
/**
* Provides an object that will be serialized as html form using `application/x-www-form-urlencoded` encoding and sent
* as this request body. If this parameter is specified `content-type` header will be set to
* `application/x-www-form-urlencoded` unless explicitly provided.
*/
form?: { [key: string]: string | number | boolean } | FormData
/**
* Allows to set HTTP headers. These headers will apply to the fetched request as well as any redirects initiated by
* it.
*/
headers?: { [key: string]: string }
/**
* Whether to ignore HTTPS errors when sending network requests. Defaults to `false`.
*/
ignoreHTTPSErrors?: boolean
/**
* Maximum number of request redirects that will be followed automatically. An error will be thrown if the number is
* exceeded. Defaults to `20`. Pass `0` to not follow redirects.
*/
maxRedirects?: number
/**
* Maximum number of times network errors should be retried. Currently only `ECONNRESET` error is retried. Does not
* retry based on HTTP response codes. An error will be thrown if the limit is exceeded. Defaults to `0` - no retries.
*/
maxRetries?: number
/**
* Provides an object that will be serialized as html form using `multipart/form-data` encoding and sent as this
* request body. If this parameter is specified `content-type` header will be set to `multipart/form-data` unless
* explicitly provided. File values can be passed either as
* [`fs.ReadStream`](https://nodejs.org/api/fs.html#fs_class_fs_readstream) or as file-like object containing file
* name, mime-type and its content.
*/
multipart?:
| FormData
| {
[key: string]:
| string
| number
| boolean
| ReadStream
| {
/**
* File name
*/
name: string
/**
* File type
*/
mimeType: string
/**
* File content
*/
buffer: Buffer
}
}
/**
* Query parameters to be sent with the URL.
*/
params?: { [key: string]: string | number | boolean } | URLSearchParams | string
/**
* Allows to cancel the operation using an
* [`AbortSignal`](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal). If the signal is aborted, the
* operation will be aborted and throw an error. Note that providing a signal does not disable the default timeout,
* which can be changed using
* [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); pass
* `timeout: 0` to disable the timeout entirely.
*/
signal?: AbortSignal
/**
* Request timeout in milliseconds. Defaults to `30000` (30 seconds). Pass `0` to disable timeout.
*/
timeout?: number
},
): Promise<APIResponse<T>>
/**
* All responses returned by
* [apiRequestContext.get(url[, options])](https://playwright.dev/docs/api/class-apirequestcontext#api-request-context-get)
* and similar methods are stored in the memory, so that you can later call
* [apiResponse.body()](https://playwright.dev/docs/api/class-apiresponse#api-response-body).This method discards all
* its resources, calling any method on disposed
* [APIRequestContext](https://playwright.dev/docs/api/class-apirequestcontext) will throw an exception.
* @param options
*/
dispose(options?: {
/**
* The reason to be reported to the operations interrupted by the context disposal.
*/
reason?: string
}): Promise<void>
/**
* Sends HTTP(S) request and returns its response. The method will populate request cookies from the context and
* update context cookies from the response. The method will automatically follow redirects.
*
* **Usage**
*
* JSON objects can be passed directly to the request:
*
* ```js
* await request.fetch('https://example.com/api/createBook', {
* method: 'post',
* data: {
* title: 'Book Title',
* author: 'John Doe',
* }
* });
* ```
*
* The common way to send file(s) in the body of a request is to upload them as form fields with `multipart/form-data`
* encoding, by specifiying the `multipart` parameter:
*
* ```js
* const form = new FormData();
* form.set('name', 'John');
* form.append('name', 'Doe');
* // Send two file fields with the same name.
* form.append('file', new File(['console.log(2024);'], 'f1.js', { type: 'text/javascript' }));
* form.append('file', new File(['hello'], 'f2.txt', { type: 'text/plain' }));
* await request.fetch('https://example.com/api/uploadForm', {
* multipart: form
* });
* ```
*
* @param urlOrRequest Target URL or Request to get all parameters from.
* @param options
*/
fetch<T = any>(
urlOrRequest: string | Request,
options?: {
/**
* Allows to set post data of the request. If the data parameter is an object, it will be serialized to json string
* and `content-type` header will be set to `application/json` if not explicitly set. Otherwise the `content-type`
* header will be set to `application/octet-stream` if not explicitly set.
*/
data?: string | Buffer | Serializable
/**
* Whether to throw on response codes other than 2xx and 3xx. By default response object is returned for all status
* codes.
*/
failOnStatusCode?: boolean
/**
* Provides an object that will be serialized as html form using `application/x-www-form-urlencoded` encoding and sent
* as this request body. If this parameter is specified `content-type` header will be set to
* `application/x-www-form-urlencoded` unless explicitly provided.
*/
form?: { [key: string]: string | number | boolean } | FormData
/**
* Allows to set HTTP headers. These headers will apply to the fetched request as well as any redirects initiated by
* it.
*/
headers?: { [key: string]: string }
/**
* Whether to ignore HTTPS errors when sending network requests. Defaults to `false`.
*/
ignoreHTTPSErrors?: boolean
/**
* Maximum number of request redirects that will be followed automatically. An error will be thrown if the number is
* exceeded. Defaults to `20`. Pass `0` to not follow redirects.
*/
maxRedirects?: number
/**
* Maximum number of times network errors should be retried. Currently only `ECONNRESET` error is retried. Does not
* retry based on HTTP response codes. An error will be thrown if the limit is exceeded. Defaults to `0` - no retries.
*/
maxRetries?: number
/**
* If set changes the fetch method (e.g. [PUT](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/PUT) or
* [POST](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/POST)). If not specified, GET method is used.
*/
method?: string
/**
* Provides an object that will be serialized as html form using `multipart/form-data` encoding and sent as this
* request body. If this parameter is specified `content-type` header will be set to `multipart/form-data` unless
* explicitly provided. File values can be passed either as
* [`fs.ReadStream`](https://nodejs.org/api/fs.html#fs_class_fs_readstream) or as file-like object containing file
* name, mime-type and its content.
*/
multipart?:
| FormData
| {
[key: string]:
| string
| number
| boolean
| ReadStream
| {
/**
* File name
*/
name: string
/**
* File type
*/
mimeType: string
/**
* File content
*/
buffer: Buffer
}
}
/**
* Query parameters to be sent with the URL.
*/
params?: { [key: string]: string | number | boolean } | URLSearchParams | string
/**
* Allows to cancel the operation using an
* [`AbortSignal`](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal). If the signal is aborted, the
* operation will be aborted and throw an error. Note that providing a signal does not disable the default timeout,
* which can be changed using
* [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); pass
* `timeout: 0` to disable the timeout entirely.
*/
signal?: AbortSignal
/**
* Request timeout in milliseconds. Defaults to `30000` (30 seconds). Pass `0` to disable timeout.
*/
timeout?: number
},
): Promise<APIResponse<T>>
/**
* Sends HTTP(S) [GET](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/GET) request and returns its
* response. The method will populate request cookies from the context and update context cookies from the response.
* The method will automatically follow redirects.
*
* **Usage**
*
* Request parameters can be configured with `params` option, they will be serialized into the URL search parameters:
*
* ```js
* // Passing params as object
* await request.get('https://example.com/api/getText', {
* params: {
* 'isbn': '1234',
* 'page': 23,
* }
* });
*
* // Passing params as URLSearchParams
* const searchParams = new URLSearchParams();
* searchParams.set('isbn', '1234');
* searchParams.append('page', 23);
* searchParams.append('page', 24);
* await request.get('https://example.com/api/getText', { params: searchParams });
*
* // Passing params as string
* const queryString = 'isbn=1234&page=23&page=24';
* await request.get('https://example.com/api/getText', { params: queryString });
* ```
*
* @param url Target URL.
* @param options
*/
get<T = any>(
url: string,
options?: {
/**
* Allows to set post data of the request. If the data parameter is an object, it will be serialized to json string
* and `content-type` header will be set to `application/json` if not explicitly set. Otherwise the `content-type`
* header will be set to `application/octet-stream` if not explicitly set.
*/
data?: string | Buffer | Serializable
/**
* Whether to throw on response codes other than 2xx and 3xx. By default response object is returned for all status
* codes.
*/
failOnStatusCode?: boolean
/**
* Provides an object that will be serialized as html form using `application/x-www-form-urlencoded` encoding and sent
* as this request body. If this parameter is specified `content-type` header will be set to
* `application/x-www-form-urlencoded` unless explicitly provided.
*/
form?: { [key: string]: string | number | boolean } | FormData
/**
* Allows to set HTTP headers. These headers will apply to the fetched request as well as any redirects initiated by
* it.
*/
headers?: { [key: string]: string }
/**
* Whether to ignore HTTPS errors when sending network requests. Defaults to `false`.
*/
ignoreHTTPSErrors?: boolean
/**
* Maximum number of request redirects that will be followed automatically. An error will be thrown if the number is
* exceeded. Defaults to `20`. Pass `0` to not follow redirects.
*/
maxRedirects?: number
/**
* Maximum number of times network errors should be retried. Currently only `ECONNRESET` error is retried. Does not
* retry based on HTTP response codes. An error will be thrown if the limit is exceeded. Defaults to `0` - no retries.
*/
maxRetries?: number
/**
* Provides an object that will be serialized as html form using `multipart/form-data` encoding and sent as this
* request body. If this parameter is specified `content-type` header will be set to `multipart/form-data` unless
* explicitly provided. File values can be passed either as
* [`fs.ReadStream`](https://nodejs.org/api/fs.html#fs_class_fs_readstream) or as file-like object containing file
* name, mime-type and its content.
*/
multipart?:
| FormData
| {
[key: string]:
| string
| number
| boolean
| ReadStream
| {
/**
* File name
*/
name: string
/**
* File type
*/
mimeType: string
/**
* File content
*/
buffer: Buffer
}
}
/**
* Query parameters to be sent with the URL.
*/
params?: { [key: string]: string | number | boolean } | URLSearchParams | string
/**
* Allows to cancel the operation using an
* [`AbortSignal`](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal). If the signal is aborted, the
* operation will be aborted and throw an error. Note that providing a signal does not disable the default timeout,
* which can be changed using
* [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); pass
* `timeout: 0` to disable the timeout entirely.
*/
signal?: AbortSignal
/**
* Request timeout in milliseconds. Defaults to `30000` (30 seconds). Pass `0` to disable timeout.
*/
timeout?: number
},
): Promise<APIResponse<T>>
/**
* Sends HTTP(S) [HEAD](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/HEAD) request and returns its
* response. The method will populate request cookies from the context and update context cookies from the response.
* The method will automatically follow redirects.
* @param url Target URL.
* @param options
*/
head<T = any>(
url: string,
options?: {
/**
* Allows to set post data of the request. If the data parameter is an object, it will be serialized to json string
* and `content-type` header will be set to `application/json` if not explicitly set. Otherwise the `content-type`
* header will be set to `application/octet-stream` if not explicitly set.
*/
data?: string | Buffer | Serializable
/**
* Whether to throw on response codes other than 2xx and 3xx. By default response object is returned for all status
* codes.
*/
failOnStatusCode?: boolean
/**
* Provides an object that will be serialized as html form using `application/x-www-form-urlencoded` encoding and sent
* as this request body. If this parameter is specified `content-type` header will be set to
* `application/x-www-form-urlencoded` unless explicitly provided.
*/
form?: { [key: string]: string | number | boolean } | FormData
/**
* Allows to set HTTP headers. These headers will apply to the fetched request as well as any redirects initiated by
* it.
*/
headers?: { [key: string]: string }
/**
* Whether to ignore HTTPS errors when sending network requests. Defaults to `false`.
*/
ignoreHTTPSErrors?: boolean
/**
* Maximum number of request redirects that will be followed automatically. An error will be thrown if the number is
* exceeded. Defaults to `20`. Pass `0` to not follow redirects.
*/
maxRedirects?: number
/**
* Maximum number of times network errors should be retried. Currently only `ECONNRESET` error is retried. Does not
* retry based on HTTP response codes. An error will be thrown if the limit is exceeded. Defaults to `0` - no retries.
*/
maxRetries?: number
/**
* Provides an object that will be serialized as html form using `multipart/form-data` encoding and sent as this
* request body. If this parameter is specified `content-type` header will be set to `multipart/form-data` unless
* explicitly provided. File values can be passed either as
* [`fs.ReadStream`](https://nodejs.org/api/fs.html#fs_class_fs_readstream) or as file-like object containing file
* name, mime-type and its content.
*/
multipart?:
| FormData
| {
[key: string]:
| string
| number
| boolean
| ReadStream
| {
/**
* File name
*/
name: string
/**
* File type
*/
mimeType: string
/**
* File content
*/
buffer: Buffer
}
}
/**
* Query parameters to be sent with the URL.
*/
params?: { [key: string]: string | number | boolean } | URLSearchParams | string
/**
* Allows to cancel the operation using an
* [`AbortSignal`](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal). If the signal is aborted, the
* operation will be aborted and throw an error. Note that providing a signal does not disable the default timeout,
* which can be changed using
* [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); pass
* `timeout: 0` to disable the timeout entirely.
*/
signal?: AbortSignal
/**
* Request timeout in milliseconds. Defaults to `30000` (30 seconds). Pass `0` to disable timeout.
*/
timeout?: number
},
): Promise<APIResponse<T>>
/**
* Sends HTTP(S) [PATCH](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/PATCH) request and returns its
* response. The method will populate request cookies from the context and update context cookies from the response.
* The method will automatically follow redirects.
* @param url Target URL.
* @param options
*/
patch<T = any>(
url: string,
options?: {
/**
* Allows to set post data of the request. If the data parameter is an object, it will be serialized to json string
* and `content-type` header will be set to `application/json` if not explicitly set. Otherwise the `content-type`
* header will be set to `application/octet-stream` if not explicitly set.
*/
data?: string | Buffer | Serializable
/**
* Whether to throw on response codes other than 2xx and 3xx. By default response object is returned for all status
* codes.
*/
failOnStatusCode?: boolean
/**
* Provides an object that will be serialized as html form using `application/x-www-form-urlencoded` encoding and sent
* as this request body. If this parameter is specified `content-type` header will be set to
* `application/x-www-form-urlencoded` unless explicitly provided.
*/
form?: { [key: string]: string | number | boolean } | FormData
/**
* Allows to set HTTP headers. These headers will apply to the fetched request as well as any redirects initiated by
* it.
*/
headers?: { [key: string]: string }
/**
* Whether to ignore HTTPS errors when sending network requests. Defaults to `false`.
*/
ignoreHTTPSErrors?: boolean
/**
* Maximum number of request redirects that will be followed automatically. An error will be thrown if the number is
* exceeded. Defaults to `20`. Pass `0` to not follow redirects.
*/
maxRedirects?: number
/**
* Maximum number of times network errors should be retried. Currently only `ECONNRESET` error is retried. Does not
* retry based on HTTP response codes. An error will be thrown if the limit is exceeded. Defaults to `0` - no retries.
*/
maxRetries?: number
/**
* Provides an object that will be serialized as html form using `multipart/form-data` encoding and sent as this
* request body. If this parameter is specified `content-type` header will be set to `multipart/form-data` unless
* explicitly provided. File values can be passed either as
* [`fs.ReadStream`](https://nodejs.org/api/fs.html#fs_class_fs_readstream) or as file-like object containing file
* name, mime-type and its content.
*/
multipart?:
| FormData
| {
[key: string]:
| string
| number
| boolean
| ReadStream
| {
/**
* File name
*/
name: string
/**
* File type
*/
mimeType: string
/**
* File content
*/
buffer: Buffer
}
}
/**
* Query parameters to be sent with the URL.
*/
params?: { [key: string]: string | number | boolean } | URLSearchParams | string
/**
* Allows to cancel the operation using an
* [`AbortSignal`](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal). If the signal is aborted, the
* operation will be aborted and throw an error. Note that providing a signal does not disable the default timeout,
* which can be changed using
* [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); pass
* `timeout: 0` to disable the timeout entirely.
*/
signal?: AbortSignal
/**
* Request timeout in milliseconds. Defaults to `30000` (30 seconds). Pass `0` to disable timeout.
*/
timeout?: number
},
): Promise<APIResponse<T>>
/**
* Sends HTTP(S) [POST](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/POST) request and returns its
* response. The method will populate request cookies from the context and update context cookies from the response.
* The method will automatically follow redirects.
*
* **Usage**
*
* JSON objects can be passed directly to the request:
*
* ```js
* await request.post('https://example.com/api/createBook', {
* data: {
* title: 'Book Title',
* author: 'John Doe',
* }
* });
* ```
*
* To send form data to the server use `form` option. Its value will be encoded into the request body with
* `application/x-www-form-urlencoded` encoding (see below how to use `multipart/form-data` form encoding to send
* files):
*
* ```js
* await request.post('https://example.com/api/findBook', {
* form: {
* title: 'Book Title',
* author: 'John Doe',
* }
* });
* ```
*
* The common way to send file(s) in the body of a request is to upload them as form fields with `multipart/form-data`
* encoding. Use [FormData] to construct request body and pass it to the request as `multipart` parameter:
*
* ```js
* const form = new FormData();
* form.set('name', 'John');
* form.append('name', 'Doe');
* // Send two file fields with the same name.
* form.append('file', new File(['console.log(2024);'], 'f1.js', { type: 'text/javascript' }));
* form.append('file', new File(['hello'], 'f2.txt', { type: 'text/plain' }));
* await request.post('https://example.com/api/uploadForm', {
* multipart: form
* });
* ```
*
* @param url Target URL.
* @param options
*/
post<T = any>(
url: string,
options?: {
/**
* Allows to set post data of the request. If the data parameter is an object, it will be serialized to json string
* and `content-type` header will be set to `application/json` if not explicitly set. Otherwise the `content-type`
* header will be set to `application/octet-stream` if not explicitly set.
*/
data?: string | Buffer | Serializable
/**
* Whether to throw on response codes other than 2xx and 3xx. By default response object is returned for all status
* codes.
*/
failOnStatusCode?: boolean
/**
* Provides an object that will be serialized as html form using `application/x-www-form-urlencoded` encoding and sent
* as this request body. If this parameter is specified `content-type` header will be set to
* `application/x-www-form-urlencoded` unless explicitly provided.
*/
form?: { [key: string]: string | number | boolean } | FormData
/**
* Allows to set HTTP headers. These headers will apply to the fetched request as well as any redirects initiated by
* it.
*/
headers?: { [key: string]: string }
/**
* Whether to ignore HTTPS errors when sending network requests. Defaults to `false`.
*/
ignoreHTTPSErrors?: boolean
/**
* Maximum number of request redirects that will be followed automatically. An error will be thrown if the number is
* exceeded. Defaults to `20`. Pass `0` to not follow redirects.
*/
maxRedirects?: number
/**
* Maximum number of times network errors should be retried. Currently only `ECONNRESET` error is retried. Does not
* retry based on HTTP response codes. An error will be thrown if the limit is exceeded. Defaults to `0` - no retries.
*/
maxRetries?: number
/**
* Provides an object that will be serialized as html form using `multipart/form-data` encoding and sent as this
* request body. If this parameter is specified `content-type` header will be set to `multipart/form-data` unless
* explicitly provided. File values can be passed either as
* [`fs.ReadStream`](https://nodejs.org/api/fs.html#fs_class_fs_readstream) or as file-like object containing file
* name, mime-type and its content.
*/
multipart?:
| FormData
| {
[key: string]:
| string
| number
| boolean
| ReadStream
| {
/**
* File name
*/
name: string
/**
* File type
*/
mimeType: string
/**
* File content
*/
buffer: Buffer
}
}
/**
* Query parameters to be sent with the URL.
*/
params?: { [key: string]: string | number | boolean } | URLSearchParams | string
/**
* Allows to cancel the operation using an
* [`AbortSignal`](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal). If the signal is aborted, the
* operation will be aborted and throw an error. Note that providing a signal does not disable the default timeout,
* which can be changed using
* [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); pass
* `timeout: 0` to disable the timeout entirely.
*/
signal?: AbortSignal
/**
* Request timeout in milliseconds. Defaults to `30000` (30 seconds). Pass `0` to disable timeout.
*/
timeout?: number
},
): Promise<APIResponse<T>>
/**
* Sends HTTP(S) [PUT](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/PUT) request and returns its
* response. The method will populate request cookies from the context and update context cookies from the response.
* The method will automatically follow redirects.
* @param url Target URL.
* @param options
*/
put<T = any>(
url: string,
options?: {
/**
* Allows to set post data of the request. If the data parameter is an object, it will be serialized to json string
* and `content-type` header will be set to `application/json` if not explicitly set. Otherwise the `content-type`
* header will be set to `application/octet-stream` if not explicitly set.
*/
data?: string | Buffer | Serializable
/**
* Whether to throw on response codes other than 2xx and 3xx. By default response object is returned for all status
* codes.
*/
failOnStatusCode?: boolean
/**
* Provides an object that will be serialized as html form using `application/x-www-form-urlencoded` encoding and sent
* as this request body. If this parameter is specified `content-type` header will be set to
* `application/x-www-form-urlencoded` unless explicitly provided.
*/
form?: { [key: string]: string | number | boolean } | FormData
/**
* Allows to set HTTP headers. These headers will apply to the fetched request as well as any redirects initiated by
* it.
*/
headers?: { [key: string]: string }
/**
* Whether to ignore HTTPS errors when sending network requests. Defaults to `false`.
*/
ignoreHTTPSErrors?: boolean
/**
* Maximum number of request redirects that will be followed automatically. An error will be thrown if the number is
* exceeded. Defaults to `20`. Pass `0` to not follow redirects.
*/
maxRedirects?: number
/**
* Maximum number of times network errors should be retried. Currently only `ECONNRESET` error is retried. Does not
* retry based on HTTP response codes. An error will be thrown if the limit is exceeded. Defaults to `0` - no retries.
*/
maxRetries?: number
/**
* Provides an object that will be serialized as html form using `multipart/form-data` encoding and sent as this
* request body. If this parameter is specified `content-type` header will be set to `multipart/form-data` unless
* explicitly provided. File values can be passed either as
* [`fs.ReadStream`](https://nodejs.org/api/fs.html#fs_class_fs_readstream) or as file-like object containing file
* name, mime-type and its content.
*/
multipart?:
| FormData
| {
[key: string]:
| string
| number
| boolean
| ReadStream
| {
/**
* File name
*/
name: string
/**
* File type
*/
mimeType: string
/**
* File content
*/
buffer: Buffer
}
}
/**
* Query parameters to be sent with the URL.
*/
params?: { [key: string]: string | number | boolean } | URLSearchParams | string
/**
* Allows to cancel the operation using an
* [`AbortSignal`](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal). If the signal is aborted, the
* operation will be aborted and throw an error. Note that providing a signal does not disable the default timeout,
* which can be changed using
* [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); pass
* `timeout: 0` to disable the timeout entirely.
*/
signal?: AbortSignal
/**
* Request timeout in milliseconds. Defaults to `30000` (30 seconds). Pass `0` to disable timeout.
*/
timeout?: number
},
): Promise<APIResponse<T>>
/**
* Returns storage state for this request context, contains current cookies and local storage snapshot if it was
* passed to the constructor.
* @param options
*/
storageState(options?: {
/**
* Set to `true` to include IndexedDB in the storage state snapshot.
*/
indexedDB?: boolean
/**
* Set to `true` to include the origin private file system in the storage state snapshot.
*/
opfs?: boolean
/**
* The file path to save the storage state to. If
* [`path`](https://playwright.dev/docs/api/class-apirequestcontext#api-request-context-storage-state-option-path) is
* a relative path, then it is resolved relative to current working directory. If no path is provided, storage state
* is still returned, but won't be saved to the disk.
*/
path?: string
}): Promise<{
cookies: Array<{
name: string
value: string
domain: string
path: string
/**
* Unix time in seconds.
*/
expires: number
httpOnly: boolean
secure: boolean
sameSite: 'Strict' | 'Lax' | 'None'
}>
origins: Array<{
origin: string
localStorage: Array<{
name: string
value: string
}>
}>
}>
/**
* Tracing recorder for requests made through this API request context.
*/
tracing: Tracing
[Symbol.asyncDispose](): Promise<void>
}
APIResponse
APIResponse class represents responses returned by apiRequestContext.get(url[, options]) and similar methods.
interface APIResponse<T = any> {
/**
* Returns the JSON representation of response body.
*
* This method will throw if the response body is not parsable via `JSON.parse`.
*/
json(): Promise<T>
/**
* Returns the buffer with response body.
*/
body(): Promise<Buffer>
/**
* Disposes the body of this response. If not called then the body will stay in memory until the context closes.
*/
dispose(): Promise<void>
/**
* An object with all the response HTTP headers associated with this response.
*/
headers(): { [key: string]: string }
/**
* An array with all the response HTTP headers associated with this response. Header names are not lower-cased.
* Headers with multiple entries, such as `Set-Cookie`, appear in the array multiple times.
*/
headersArray(): Array<{
/**
* Name of the header.
*/
name: string
/**
* Value of the header.
*/
value: string
}>
/**
* Contains a boolean stating whether the response was successful (status in the range 200-299) or not.
*/
ok(): boolean
/**
* Returns SSL and other security information. Resolves to `null` for non-HTTPS responses. For redirected requests,
* returns the information for the last request in the redirect chain.
*/
securityDetails(): Promise<null | {
/**
* Common Name component of the Issuer field. from the certificate. This should only be used for informational
* purposes. Optional.
*/
issuer?: string
/**
* The specific TLS protocol used. (e.g. `TLS 1.3`). Optional.
*/
protocol?: string
/**
* Common Name component of the Subject field from the certificate. This should only be used for informational
* purposes. Optional.
*/
subjectName?: string
/**
* Unix timestamp (in seconds) specifying when this cert becomes valid. Optional.
*/
validFrom?: number
/**
* Unix timestamp (in seconds) specifying when this cert becomes invalid. Optional.
*/
validTo?: number
}>
/**
* Returns the IP address and port of the server. Resolves to `null` if the server address is not available. For
* redirected requests, returns the information for the last request in the redirect chain.
*/
serverAddr(): Promise<null | {
/**
* IPv4 or IPV6 address of the server.
*/
ipAddress: string
port: number
}>
/**
* Contains the status code of the response (e.g., 200 for a success).
*/
status(): number
/**
* Contains the status text of the response (e.g. usually an "OK" for a success).
*/
statusText(): string
/**
* Returns the text representation of response body.
*/
text(): Promise<string>
/**
* Returns resource timing information for given response. For redirected requests, returns the information for the
* last request in the redirect chain. When the response is served [from the HAR file](https://playwright.dev/docs/mock#replaying-from-har),
* timing information is not available and all the values are -1. Find more information at
* [Resource Timing API](https://developer.mozilla.org/en-US/docs/Web/API/PerformanceResourceTiming).
*/
timing(): {
/**
* Request start time in milliseconds elapsed since January 1, 1970 00:00:00 UTC
*/
startTime: number
/**
* Time immediately before the client starts the domain name lookup for the resource. The value is given in
* milliseconds relative to `startTime`, -1 if not available.
*/
domainLookupStart: number
/**
* Time immediately after the client ends the domain name lookup for the resource. The value is given in milliseconds
* relative to `startTime`, -1 if not available.
*/
domainLookupEnd: number
/**
* Time immediately before the client starts establishing the connection to the server to retrieve the resource. The
* value is given in milliseconds relative to `startTime`, -1 if not available.
*/
connectStart: number
/**
* Time immediately before the client starts the handshake process to secure the current connection. The value is
* given in milliseconds relative to `startTime`, -1 if not available.
*/
secureConnectionStart: number
/**
* Time immediately after the client establishes the connection to the server to retrieve the resource. The value is
* given in milliseconds relative to `startTime`, -1 if not available.
*/
connectEnd: number
/**
* Time immediately before the client starts requesting the resource from the server, cache, or local resource. The
* value is given in milliseconds relative to `startTime`, -1 if not available.
*/
requestStart: number
/**
* Time immediately after the client receives the first byte of the response from the server, cache, or local
* resource. The value is given in milliseconds relative to `startTime`, -1 if not available.
*/
responseStart: number
/**
* Time immediately after the client receives the last byte of the resource or immediately before the transport
* connection is closed, whichever comes first. The value is given in milliseconds relative to `startTime`, -1 if not
* available.
*/
responseEnd: number
}
/**
* Contains the URL of the response.
*/
url(): string
[Symbol.asyncDispose](): Promise<void>
}
Browser
A Browser is created via browserType.launch([options]). An example of using a Browser to create a Page:
const { firefox } = require('playwright') // Or 'chromium' or 'webkit'.
;(async () => {
const browser = await firefox.launch()
const page = await browser.newPage()
await page.goto('https://example.com')
await browser.close()
})()
interface Browser {
/**
* Removes all the listeners of the given type (or all registered listeners if no type given). Allows to wait for
* async listeners to complete or to ignore subsequent errors from these listeners.
* @param type
* @param options
*/
removeAllListeners(type?: string): this
/**
* Removes all the listeners of the given type (or all registered listeners if no type given). Allows to wait for
* async listeners to complete or to ignore subsequent errors from these listeners.
* @param type
* @param options
*/
removeAllListeners(
type: string | undefined,
options: {
/**
* Specifies whether to wait for already running listeners and what to do if they throw errors:
* - `'default'` - do not wait for current listener calls (if any) to finish, if the listener throws, it may result in unhandled error
* - `'wait'` - wait for current listener calls (if any) to finish
* - `'ignoreErrors'` - do not wait for current listener calls (if any) to finish, all errors thrown by the listeners after removal are silently caught
*/
behavior?: 'wait' | 'ignoreErrors' | 'default'
},
): Promise<void>
/**
* Emitted when a new browser context is created.
*/
on(event: 'context', listener: (browserContext: BrowserContext) => any): this
/**
* Emitted when Browser gets disconnected from the browser application. This might happen because of one of the
* following:
* - Browser application is closed or crashed.
* - The [browser.close([options])](https://playwright.dev/docs/api/class-browser#browser-close) method was called.
*/
on(event: 'disconnected', listener: (browser: Browser) => any): this
/**
* Adds an event listener that will be automatically removed after it is triggered once. See `addListener` for more information about this event.
*/
once(event: 'context', listener: (browserContext: BrowserContext) => any): this
/**
* Adds an event listener that will be automatically removed after it is triggered once. See `addListener` for more information about this event.
*/
once(event: 'disconnected', listener: (browser: Browser) => any): this
/**
* Emitted when a new browser context is created.
*/
addListener(event: 'context', listener: (browserContext: BrowserContext) => any): this
/**
* Emitted when Browser gets disconnected from the browser application. This might happen because of one of the
* following:
* - Browser application is closed or crashed.
* - The [browser.close([options])](https://playwright.dev/docs/api/class-browser#browser-close) method was called.
*/
addListener(event: 'disconnected', listener: (browser: Browser) => any): this
/**
* Removes an event listener added by `on` or `addListener`.
*/
removeListener(event: 'context', listener: (browserContext: BrowserContext) => any): this
/**
* Removes an event listener added by `on` or `addListener`.
*/
removeListener(event: 'disconnected', listener: (browser: Browser) => any): this
/**
* Removes an event listener added by `on` or `addListener`.
*/
off(event: 'context', listener: (browserContext: BrowserContext) => any): this
/**
* Removes an event listener added by `on` or `addListener`.
*/
off(event: 'disconnected', listener: (browser: Browser) => any): this
/**
* Emitted when a new browser context is created.
*/
prependListener(event: 'context', listener: (browserContext: BrowserContext) => any): this
/**
* Emitted when Browser gets disconnected from the browser application. This might happen because of one of the
* following:
* - Browser application is closed or crashed.
* - The [browser.close([options])](https://playwright.dev/docs/api/class-browser#browser-close) method was called.
*/
prependListener(event: 'disconnected', listener: (browser: Browser) => any): this
/**
* Binds the browser to a named pipe or web socket, making it available for other clients to connect to.
* @param title Title of the browser server, used for identification.
* @param options
*/
bind(
title: string,
options?: {
/**
* Host to bind the web socket server to. When specified, a web socket server is created instead of a named pipe.
*/
host?: string
/**
* Additional metadata to associate with the browser server.
*/
metadata?: { [key: string]: any }
/**
* Port to bind the web socket server to. When specified, a web socket server is created instead of a named pipe. Use
* `0` to let the OS pick an available port.
*/
port?: number
/**
* Working directory associated with this browser server.
*/
workspaceDir?: string
},
): Promise<{
endpoint: string
}>
/**
* Get the browser type (chromium, firefox or webkit) that the browser belongs to.
*/
browserType(): BrowserType
/**
* In case this browser is obtained using
* [browserType.launch([options])](https://playwright.dev/docs/api/class-browsertype#browser-type-launch), closes the
* browser and all of its pages (if any were opened).
*
* In case this browser is connected to, clears all created contexts belonging to this browser and disconnects from
* the browser server.
*
* **NOTE** This is similar to force-quitting the browser. To close pages gracefully and ensure you receive page close
* events, call
* [browserContext.close([options])](https://playwright.dev/docs/api/class-browsercontext#browser-context-close) on
* any [BrowserContext](https://playwright.dev/docs/api/class-browsercontext) instances you explicitly created earlier
* using [browser.newContext([options])](https://playwright.dev/docs/api/class-browser#browser-new-context) **before**
* calling [browser.close([options])](https://playwright.dev/docs/api/class-browser#browser-close).
*
* The [Browser](https://playwright.dev/docs/api/class-browser) object itself is considered to be disposed and cannot
* be used anymore.
* @param options
*/
close(options?: {
/**
* The reason to be reported to the operations interrupted by the browser closure.
*/
reason?: string
}): Promise<void>
/**
* Returns an array of all open browser contexts. In a newly created browser, this will return zero browser contexts.
*
* **Usage**
*
* ```js
* const browser = await pw.webkit.launch();
* console.log(browser.contexts().length); // prints `0`
*
* const context = await browser.newContext();
* console.log(browser.contexts().length); // prints `1`
* ```
*
*/
contexts(): Array<BrowserContext>
/**
* Indicates that the browser is connected.
*/
isConnected(): boolean
/**
* **NOTE** CDP Sessions are only supported on Chromium-based browsers.
*
* Returns the newly created browser session.
*/
newBrowserCDPSession(): Promise<CDPSession>
/**
* Creates a new browser context. It won't share cookies/cache with other browser contexts.
*
* **NOTE** If directly using this method to create
* [BrowserContext](https://playwright.dev/docs/api/class-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 [BrowserContext](https://playwright.dev/docs/api/class-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**
*
* ```js
* (async () => {
* const browser = await playwright.firefox.launch(); // Or 'chromium' or 'webkit'.
* // Create a new incognito browser context.
* const context = await browser.newContext();
* // Create a new page in a pristine context.
* const page = await context.newPage();
* await page.goto('https://example.com');
*
* // Gracefully close up everything
* await context.close();
* await browser.close();
* })();
* ```
*
* @param options
*/
newContext(options?: BrowserContextOptions): Promise<BrowserContext>
/**
* Creates a new page in a new browser context. Closing this page will close the context as well.
*
* This is a convenience API that should only be used for the single-page scenarios and short snippets. Production
* code and testing frameworks should explicitly create
* [browser.newContext([options])](https://playwright.dev/docs/api/class-browser#browser-new-context) followed by the
* [browserContext.newPage()](https://playwright.dev/docs/api/class-browsercontext#browser-context-new-page) to
* control their exact life times.
* @param options
*/
newPage(options?: {
/**
* Whether to automatically download all the attachments. Defaults to `true` where all the downloads are accepted.
*/
acceptDownloads?: boolean
/**
* When using [page.goto(url[, options])](https://playwright.dev/docs/api/class-page#page-goto),
* [page.route(url, handler[, options])](https://playwright.dev/docs/api/class-page#page-route),
* [page.waitForURL(url[, options])](https://playwright.dev/docs/api/class-page#page-wait-for-url),
* [page.waitForRequest(urlOrPredicate[, options])](https://playwright.dev/docs/api/class-page#page-wait-for-request),
* or
* [page.waitForResponse(urlOrPredicate[, options])](https://playwright.dev/docs/api/class-page#page-wait-for-response)
* it takes the base URL in consideration by using the
* [`URL()`](https://developer.mozilla.org/en-US/docs/Web/API/URL/URL) constructor for building the corresponding URL.
* Unset by default. Examples:
* - baseURL: `http://localhost:3000` and navigating to `/bar.html` results in `http://localhost:3000/bar.html`
* - baseURL: `http://localhost:3000/foo/` and navigating to `./bar.html` results in
* `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`
*/
baseURL?: string
/**
* Toggles bypassing page's Content-Security-Policy. Defaults to `false`.
*/
bypassCSP?: boolean
/**
* TLS Client Authentication allows the server to request a client certificate and verify it.
*
* **Details**
*
* An array of client certificates to be used. Each certificate object must have either both `certPath` and `keyPath`,
* a single `pfxPath`, or their corresponding direct value equivalents (`cert` and `key`, or `pfx`). Optionally,
* `passphrase` property should be provided if the certificate is encrypted. The `origin` property should be provided
* with an exact match to the request origin that the certificate is valid for.
*
* Client certificate authentication is only active when at least one client certificate is provided. If you want to
* reject all client certificates sent by the server, you need to provide a client certificate with an `origin` that
* does not match any of the domains you plan to visit.
*
* **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<{
/**
* Exact origin that the certificate is valid for. Origin includes `https` protocol, a hostname and optionally a port.
*/
origin: string
/**
* Path to the file with the certificate in PEM format.
*/
certPath?: string
/**
* Direct value of the certificate in PEM format.
*/
cert?: Buffer
/**
* Path to the file with the private key in PEM format.
*/
keyPath?: string
/**
* Direct value of the private key in PEM format.
*/
key?: Buffer
/**
* Path to the PFX or PKCS12 encoded private key and certificate chain.
*/
pfxPath?: string
/**
* Direct value of the PFX or PKCS12 encoded private key and certificate chain.
*/
pfx?: Buffer
/**
* Passphrase for the private key (PEM or PFX).
*/
passphrase?: string
}>
/**
* Emulates [prefers-colors-scheme](https://developer.mozilla.org/en-US/docs/Web/CSS/@media/prefers-color-scheme)
* 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'`.
*/
colorScheme?: null | 'light' | 'dark' | 'no-preference'
/**
* 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'`.
*/
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).
*/
deviceScaleFactor?: number
/**
* An object containing additional HTTP headers to be sent with every request. Defaults to none.
*/
extraHTTPHeaders?: { [key: string]: string }
/**
* 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'`.
*/
forcedColors?: null | 'active' | 'none'
geolocation?: {
/**
* Latitude between -90 and 90.
*/
latitude: number
/**
* Longitude between -180 and 180.
*/
longitude: number
/**
* Non-negative accuracy value. Defaults to `0`.
*/
accuracy?: number
}
/**
* Specifies if viewport supports touch events. Defaults to false. Learn more about
* [mobile emulation](https://playwright.dev/docs/emulation#devices).
*/
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.
*
* Pass an array to use different credentials for different origins. The first entry that matches the request origin
* is used, and entries with no origin match any request.
*/
httpCredentials?:
| {
username: string
password: string
/**
* Restrain sending http credentials on specific origin (scheme://host:port).
*/
origin?: string
/**
* This option only applies to the requests sent from corresponding
* [APIRequestContext](https://playwright.dev/docs/api/class-apirequestcontext) and does not affect requests sent from
* 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'`.
*/
send?: 'unauthorized' | 'always'
}
| Array<{
username: string
password: string
/**
* Restrain sending http credentials on specific origin (scheme://host:port).
*/
origin?: string
/**
* This option only applies to the requests sent from corresponding
* [APIRequestContext](https://playwright.dev/docs/api/class-apirequestcontext) and does not affect requests sent from
* 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'`.
*/
send?: 'unauthorized' | 'always'
}>
/**
* Whether to ignore HTTPS errors when sending network requests. Defaults to `false`.
*/
ignoreHTTPSErrors?: boolean
/**
* 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).
*/
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).
*/
javaScriptEnabled?: boolean
/**
* 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).
*/
locale?: string
/**
* Logger sink for Playwright logging.
* @deprecated The logs received by the logger are incomplete. Please use tracing instead.
*/
logger?: Logger
/**
* Whether to emulate network being offline. Defaults to `false`. Learn more about
* [network emulation](https://playwright.dev/docs/emulation#offline).
*/
offline?: boolean
/**
* 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.
*/
permissions?: Array<string>
/**
* Network proxy settings to use with this context. Defaults to none.
*/
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.
*/
server: string
/**
* Optional comma-separated domains to bypass proxy, for example `".com, chromium.org, .domain.com"`.
*/
bypass?: string
/**
* Optional username to use if HTTP proxy requires authentication.
*/
username?: string
/**
* Optional password to use if HTTP proxy requires authentication.
*/
password?: string
}
/**
* Enables [HAR](http://www.softwareishard.com/blog/har-12-spec) recording for all pages into `recordHar.path` file.
* 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.
*/
recordHar?: {
/**
* Optional setting to control whether to omit request content from the HAR. Defaults to `false`. Deprecated, use
* `content` policy instead.
*/
omitContent?: boolean
/**
* Optional setting to control resource content management. If `omit` is specified, content is not persisted. If
* `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.
*/
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.
*/
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`.
*/
mode?: 'full' | 'minimal'
/**
* A glob or regex pattern to filter requests that are stored in the HAR. When a
* [`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.
*/
urlFilter?: string | RegExp
}
/**
* Enables video recording for all pages into `recordVideo.dir` directory. If not specified videos are not recorded.
* Make sure to await
* [browserContext.close([options])](https://playwright.dev/docs/api/class-browsercontext#browser-context-close) for
* videos to be saved.
*/
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).
*/
dir?: string
/**
* 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.
*/
size?: {
/**
* Video frame width.
*/
width: number
/**
* Video frame height.
*/
height: number
}
/**
* If specified, enables visual annotations on interacted elements during video recording.
*/
showActions?: {
/**
* How long each annotation is displayed in milliseconds. Defaults to `500`.
*/
duration?: number
/**
* Position of the action title overlay. Defaults to `"top-right"`.
*/
position?: 'top-left' | 'top' | 'top-right' | 'bottom-left' | 'bottom' | 'bottom-right'
/**
* Font size of the action title in pixels. Defaults to `24`.
*/
fontSize?: number
/**
* Cursor decoration shown for pointer actions. `"pointer"` (the default) renders a mouse pointer that animates from
* the previous action point to the next one. `"none"` disables the cursor decoration.
*/
cursor?: 'none' | 'pointer'
}
}
/**
* 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'`.
*/
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-page-option-viewport) is set.
*/
screen?: {
/**
* page width in pixels.
*/
width: number
/**
* page height in pixels.
*/
height: number
}
/**
* Whether to allow sites to register Service workers. Defaults to `'allow'`.
* - `'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.
*/
serviceWorkers?: 'allow' | 'block'
/**
* Learn more about [storage state and auth](https://playwright.dev/docs/auth).
*
* 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).
*/
storageState?:
| string
| {
/**
* Cookies to set for context
*/
cookies: Array<{
name: string
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"
*/
domain: string
/**
* Domain and path are required
*/
path: string
/**
* Unix time in seconds.
*/
expires: number
httpOnly: boolean
secure: boolean
/**
* sameSite flag
*/
sameSite: 'Strict' | 'Lax' | 'None'
}>
origins: Array<{
origin: string
/**
* localStorage to set for context
*/
localStorage: Array<{
name: string
value: string
}>
}>
}
/**
* If set to true, enables strict selectors mode for this context. In the strict selectors mode all operations on
* 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.
*/
strictSelectors?: boolean
/**
* 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.
*/
timezoneId?: string
/**
* Specific user agent to use in this context.
*/
userAgent?: string
/**
* 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.
*
*/
viewport?: null | {
/**
* page width in pixels.
*/
width: number
/**
* page height in pixels.
*/
height: number
}
}): Promise<Page>
/**
* **NOTE** This API controls
* [Chromium Tracing](https://www.chromium.org/developers/how-tos/trace-event-profiling-tool) which is a low-level
* chromium-specific debugging tool. API to control [Playwright Tracing](https://playwright.dev/docs/trace-viewer) could be found
* [here](https://playwright.dev/docs/api/class-tracing).
*
* You can use
* [browser.startTracing([page, options])](https://playwright.dev/docs/api/class-browser#browser-start-tracing) and
* [browser.stopTracing()](https://playwright.dev/docs/api/class-browser#browser-stop-tracing) to create a trace file
* that can be opened in Chrome DevTools performance panel.
*
* **Usage**
*
* ```js
* await browser.startTracing(page, { path: 'trace.json' });
* await page.goto('https://www.google.com');
* await browser.stopTracing();
* ```
*
* @param page Optional, if specified, tracing includes screenshots of the given page.
* @param options
*/
startTracing(
page?: Page,
options?: {
/**
* specify custom categories to use instead of default.
*/
categories?: Array<string>
/**
* A path to write the trace file to.
*/
path?: string
/**
* captures screenshots in the trace.
*/
screenshots?: boolean
},
): Promise<void>
/**
* **NOTE** This API controls
* [Chromium Tracing](https://www.chromium.org/developers/how-tos/trace-event-profiling-tool) which is a low-level
* chromium-specific debugging tool. API to control [Playwright Tracing](https://playwright.dev/docs/trace-viewer) could be found
* [here](https://playwright.dev/docs/api/class-tracing).
*
* Returns the buffer with trace data.
*/
stopTracing(): Promise<Buffer>
/**
* Unbinds the browser server previously bound with
* [browser.bind(title[, options])](https://playwright.dev/docs/api/class-browser#browser-bind).
*/
unbind(): Promise<void>
/**
* Returns the browser version.
*/
version(): string
[Symbol.asyncDispose](): Promise<void>
}
BrowserContext
BrowserContexts provide a way to operate multiple independent browser sessions.
If a page opens another page, e.g. with a window.open call, the popup will belong to the parent page's browser
context.
Playwright allows creating isolated non-persistent browser contexts with browser.newContext([options]) method. Non-persistent browser contexts don't write any browsing data to disk.
// Create a new incognito browser context
const context = await browser.newContext()
// Create a new page inside context.
const page = await context.newPage()
await page.goto('https://example.com')
// Dispose context once it's no longer needed.
await context.close()
interface BrowserContext {
/**
* The method adds a function called
* [`name`](https://playwright.dev/docs/api/class-browsercontext#browser-context-expose-binding-option-name) on the
* `window` object of every frame in every page in the context. When called, the function executes
* [`callback`](https://playwright.dev/docs/api/class-browsercontext#browser-context-expose-binding-option-callback)
* and returns a [Promise] which resolves to the return value of
* [`callback`](https://playwright.dev/docs/api/class-browsercontext#browser-context-expose-binding-option-callback).
* If the
* [`callback`](https://playwright.dev/docs/api/class-browsercontext#browser-context-expose-binding-option-callback)
* returns a [Promise], it will be awaited.
*
* The first argument of the
* [`callback`](https://playwright.dev/docs/api/class-browsercontext#browser-context-expose-binding-option-callback)
* function contains information about the caller: `{ browserContext: BrowserContext, page: Page, frame: Frame }`.
*
* See [page.exposeBinding(name, callback)](https://playwright.dev/docs/api/class-page#page-expose-binding) for
* page-only version.
*
* **Usage**
*
* An example of exposing page URL to all frames in all pages in the context:
*
* ```js
* const { webkit } = require('playwright'); // Or 'chromium' or 'firefox'.
*
* (async () => {
* const browser = await webkit.launch({ headless: false });
* const context = await browser.newContext();
* await context.exposeBinding('pageURL', ({ page }) => page.url());
* const page = await context.newPage();
* await page.setContent(`
* <script>
* async function onClick() {
* document.querySelector('div').textContent = await window.pageURL();
* }
* </script>
* <button onclick="onClick()">Click me</button>
* <div></div>
* `);
* await page.getByRole('button').click();
* })();
* ```
*
* @param name Name of the function on the window object.
* @param callback Callback function that will be called in the Playwright's context.
*/
exposeBinding(
name: string,
playwrightBinding: (source: BindingSource, ...args: any[]) => any,
): Promise<Disposable>
/**
* Adds a script which would be evaluated in one of the following scenarios:
* - Whenever a page is created in the browser context or is navigated.
* - Whenever a child frame is attached or navigated in any page in the browser context. In this case, the script is
* evaluated in the context of the newly attached frame.
*
* The script is evaluated after the document was created but before any of its scripts were run. This is useful to
* amend the JavaScript environment, e.g. to seed `Math.random`.
*
* **Usage**
*
* An example of overriding `Math.random` before the page loads:
*
* ```js
* // preload.js
* Math.random = () => 42;
* ```
*
* ```js
* // In your playwright script, assuming the preload.js file is in same directory.
* await browserContext.addInitScript({
* path: 'preload.js'
* });
* ```
*
* **NOTE** The order of evaluation of multiple scripts installed via
* [browserContext.addInitScript(script[, arg, options])](https://playwright.dev/docs/api/class-browsercontext#browser-context-add-init-script)
* and [page.addInitScript(script[, arg, options])](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`](https://playwright.dev/docs/api/class-browsercontext#browser-context-add-init-script-option-script)
* (only supported when passing a function).
* @param options
*/
addInitScript<Arg>(
script: PageFunction<Arg, any> | { path?: string; content?: string },
arg?: Arg,
options?: { exposeFunctions?: boolean },
): Promise<Disposable>
/**
* Removes all the listeners of the given type (or all registered listeners if no type given). Allows to wait for
* async listeners to complete or to ignore subsequent errors from these listeners.
* @param type
* @param options
*/
removeAllListeners(type?: string): this
/**
* Removes all the listeners of the given type (or all registered listeners if no type given). Allows to wait for
* async listeners to complete or to ignore subsequent errors from these listeners.
* @param type
* @param options
*/
removeAllListeners(
type: string | undefined,
options: {
/**
* Specifies whether to wait for already running listeners and what to do if they throw errors:
* - `'default'` - do not wait for current listener calls (if any) to finish, if the listener throws, it may result in unhandled error
* - `'wait'` - wait for current listener calls (if any) to finish
* - `'ignoreErrors'` - do not wait for current listener calls (if any) to finish, all errors thrown by the listeners after removal are silently caught
*/
behavior?: 'wait' | 'ignoreErrors' | 'default'
},
): Promise<void>
/**
* This event is not emitted.
*/
on(event: 'backgroundpage', listener: (page: Page) => any): this
/**
* Emitted when Browser context gets closed. This might happen because of one of the following:
* - Browser context is closed.
* - Browser application is closed or crashed.
* - The [browser.close([options])](https://playwright.dev/docs/api/class-browser#browser-close) method was called.
*/
on(event: 'close', listener: (browserContext: BrowserContext) => any): this
/**
* Emitted when JavaScript within the page calls one of console API methods, e.g. `console.log` or `console.dir`.
*
* The arguments passed into `console.log` and the page are available on the
* [ConsoleMessage](https://playwright.dev/docs/api/class-consolemessage) event handler argument.
*
* **Usage**
*
* ```js
* context.on('console', async msg => {
* const values = [];
* for (const arg of msg.args())
* values.push(await arg.jsonValue());
* console.log(...values);
* });
* await page.evaluate(() => console.log('hello', 5, { foo: 'bar' }));
* ```
*
*/
on(event: 'console', listener: (consoleMessage: ConsoleMessage) => any): this
/**
* Emitted when a JavaScript dialog appears, such as `alert`, `prompt`, `confirm` or `beforeunload`. Listener **must**
* either [dialog.accept([promptText])](https://playwright.dev/docs/api/class-dialog#dialog-accept) or
* [dialog.dismiss()](https://playwright.dev/docs/api/class-dialog#dialog-dismiss) the dialog - otherwise the page
* will [freeze](https://developer.mozilla.org/en-US/docs/Web/JavaScript/EventLoop#never_blocking) waiting for the
* dialog, and actions like click will never finish.
*
* **Usage**
*
* ```js
* context.on('dialog', dialog => {
* dialog.accept();
* });
* ```
*
* **NOTE** When no [page.on('dialog')](https://playwright.dev/docs/api/class-page#page-event-dialog) or
* [browserContext.on('dialog')](https://playwright.dev/docs/api/class-browsercontext#browser-context-event-dialog)
* listeners are present, all dialogs are automatically dismissed.
*
*/
on(event: 'dialog', listener: (dialog: Dialog) => any): this
/**
* Emitted when a JavaScript dialog in any page belonging to this context has been closed, either by
* [dialog.accept([promptText])](https://playwright.dev/docs/api/class-dialog#dialog-accept), by
* [dialog.dismiss()](https://playwright.dev/docs/api/class-dialog#dialog-dismiss), or manually by the user in the
* headed browser.
*/
on(event: 'dialogclosed', listener: (dialog: Dialog) => any): this
/**
* Emitted when attachment download started in any page belonging to this context. User can access basic file
* operations on downloaded content via the passed [Download](https://playwright.dev/docs/api/class-download)
* instance. See also [page.on('download')](https://playwright.dev/docs/api/class-page#page-event-download) to receive
* events about a specific page.
*/
on(event: 'download', listener: (download: Download) => any): this
/**
* Emitted when a frame is attached in any page belonging to this context. See also
* [page.on('frameattached')](https://playwright.dev/docs/api/class-page#page-event-frame-attached) to receive events
* about a specific page.
*/
on(event: 'frameattached', listener: (frame: Frame) => any): this
/**
* Emitted when a frame is detached in any page belonging to this context. See also
* [page.on('framedetached')](https://playwright.dev/docs/api/class-page#page-event-frame-detached) to receive events
* about a specific page.
*/
on(event: 'framedetached', listener: (frame: Frame) => any): this
/**
* Emitted when a frame is navigated to a new url in any page belonging to this context. See also
* [page.on('framenavigated')](https://playwright.dev/docs/api/class-page#page-event-frame-navigated) to receive
* events about navigations in a specific page.
*/
on(event: 'framenavigated', listener: (frame: Frame) => any): this
/**
* The event is emitted when a new Page is created in the BrowserContext. The page may still be loading. The event
* will also fire for popup pages. See also
* [page.on('popup')](https://playwright.dev/docs/api/class-page#page-event-popup) to receive events about popups
* relevant to a specific page.
*
* The earliest moment that page is available is when it has navigated to the initial url. For example, when opening a
* popup with `window.open('http://example.com')`, this event will fire when the network request to
* "http://example.com" is done and its response has started loading in the popup. If you would like to route/listen
* to this network request, use
* [browserContext.route(url, handler[, options])](https://playwright.dev/docs/api/class-browsercontext#browser-context-route)
* and
* [browserContext.on('request')](https://playwright.dev/docs/api/class-browsercontext#browser-context-event-request)
* respectively instead of similar methods on the [Page](https://playwright.dev/docs/api/class-page).
*
* ```js
* const newPagePromise = context.waitForEvent('page');
* await page.getByText('open new page').click();
* const newPage = await newPagePromise;
* console.log(await newPage.evaluate('location.href'));
* ```
*
* **NOTE** Use
* [page.waitForLoadState([state, options])](https://playwright.dev/docs/api/class-page#page-wait-for-load-state) to
* wait until the page gets to a particular state (you should not need it in most cases).
*
*/
on(event: 'page', listener: (page: Page) => any): this
/**
* Emitted when a page in this context is closed. See also
* [page.on('close')](https://playwright.dev/docs/api/class-page#page-event-close) to receive events about a specific
* page.
*/
on(event: 'pageclose', listener: (page: Page) => any): this
/**
* Emitted when the JavaScript [`load`](https://developer.mozilla.org/en-US/docs/Web/Events/load) event is dispatched
* in any page belonging to this context. See also
* [page.on('load')](https://playwright.dev/docs/api/class-page#page-event-load) to receive events about a specific
* page.
*/
on(event: 'pageload', listener: (page: Page) => any): this
/**
* Emitted when a request is issued from any pages created through this context. The [request] object is read-only. To
* only listen for requests from a particular page, use
* [page.on('request')](https://playwright.dev/docs/api/class-page#page-event-request).
*
* In order to intercept and mutate requests, see
* [browserContext.route(url, handler[, options])](https://playwright.dev/docs/api/class-browsercontext#browser-context-route)
* or [page.route(url, handler[, options])](https://playwright.dev/docs/api/class-page#page-route).
*/
on(event: 'request', listener: (request: Request) => any): this
/**
* Emitted when a request fails, for example by timing out. To only listen for failed requests from a particular page,
* 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
* [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
/**
* Emitted when a request finishes successfully after downloading the response body. For a successful response, the
* sequence of events is `request`, `response` and `requestfinished`. To listen for successful requests from a
* particular page, use
* [page.on('requestfinished')](https://playwright.dev/docs/api/class-page#page-event-request-finished).
*/
on(event: 'requestfinished', listener: (request: Request) => any): this
/**
* Emitted when [response] status and headers are received for a request. For a successful response, the sequence of
* events is `request`, `response` and `requestfinished`. To listen for response events from a particular page, use
* [page.on('response')](https://playwright.dev/docs/api/class-page#page-event-response).
*/
on(event: 'response', listener: (response: Response) => any): this
/**
* **NOTE** Service workers are only supported on Chromium-based browsers.
*
* Emitted when new service worker is created in the context.
*/
on(event: 'serviceworker', listener: (worker: Worker) => any): this
/**
* Emitted when exception is unhandled in any of the pages in this context. To listen for errors from a particular
* page, use [page.on('pageerror')](https://playwright.dev/docs/api/class-page#page-event-page-error) instead.
*/
on(event: 'weberror', listener: (webError: WebError) => any): this
/**
* Adds an event listener that will be automatically removed after it is triggered once. See `addListener` for more information about this event.
*/
once(event: 'backgroundpage', listener: (page: Page) => any): this
/**
* Adds an event listener that will be automatically removed after it is triggered once. See `addListener` for more information about this event.
*/
once(event: 'close', listener: (browserContext: BrowserContext) => any): this
/**
* Adds an event listener that will be automatically removed after it is triggered once. See `addListener` for more information about this event.
*/
once(event: 'console', listener: (consoleMessage: ConsoleMessage) => any): this
/**
* Adds an event listener that will be automatically removed after it is triggered once. See `addListener` for more information about this event.
*/
once(event: 'dialog', listener: (dialog: Dialog) => any): this
/**
* Adds an event listener that will be automatically removed after it is triggered once. See `addListener` for more information about this event.
*/
once(event: 'dialogclosed', listener: (dialog: Dialog) => any): this
/**
* Adds an event listener that will be automatically removed after it is triggered once. See `addListener` for more information about this event.
*/
once(event: 'download', listener: (download: Download) => any): this
/**
* Adds an event listener that will be automatically removed after it is triggered once. See `addListener` for more information about this event.
*/
once(event: 'frameattached', listener: (frame: Frame) => any): this
/**
* Adds an event listener that will be automatically removed after it is triggered once. See `addListener` for more information about this event.
*/
once(event: 'framedetached', listener: (frame: Frame) => any): this
/**
* Adds an event listener that will be automatically removed after it is triggered once. See `addListener` for more information about this event.
*/
once(event: 'framenavigated', listener: (frame: Frame) => any): this
/**
* Adds an event listener that will be automatically removed after it is triggered once. See `addListener` for more information about this event.
*/
once(event: 'page', listener: (page: Page) => any): this
/**
* Adds an event listener that will be automatically removed after it is triggered once. See `addListener` for more information about this event.
*/
once(event: 'pageclose', listener: (page: Page) => any): this
/**
* Adds an event listener that will be automatically removed after it is triggered once. See `addListener` for more information about this event.
*/
once(event: 'pageload', listener: (page: Page) => any): this
/**
* Adds an event listener that will be automatically removed after it is triggered once. See `addListener` for more information about this event.
*/
once(event: 'request', listener: (request: Request) => any): this
/**
* Adds an event listener that will be automatically removed after it is triggered once. See `addListener` for more information about this event.
*/
once(event: 'requestfailed', listener: (request: Request) => any): this
/**
* Adds an event listener that will be automatically removed after it is triggered once. See `addListener` for more information about this event.
*/
once(event: 'requestfinished', listener: (request: Request) => any): this
/**
* Adds an event listener that will be automatically removed after it is triggered once. See `addListener` for more information about this event.
*/
once(event: 'response', listener: (response: Response) => any): this
/**
* Adds an event listener that will be automatically removed after it is triggered once. See `addListener` for more information about this event.
*/
once(event: 'serviceworker', listener: (worker: Worker) => any): this
/**
* Adds an event listener that will be automatically removed after it is triggered once. See `addListener` for more information about this event.
*/
once(event: 'weberror', listener: (webError: WebError) => any): this
/**
* This event is not emitted.
*/
addListener(event: 'backgroundpage', listener: (page: Page) => any): this
/**
* Emitted when Browser context gets closed. This might happen because of one of the following:
* - Browser context is closed.
* - Browser application is closed or crashed.
* - The [browser.close([options])](https://playwright.dev/docs/api/class-browser#browser-close) method was called.
*/
addListener(event: 'close', listener: (browserContext: BrowserContext) => any): this
/**
* Emitted when JavaScript within the page calls one of console API methods, e.g. `console.log` or `console.dir`.
*
* The arguments passed into `console.log` and the page are available on the
* [ConsoleMessage](https://playwright.dev/docs/api/class-consolemessage) event handler argument.
*
* **Usage**
*
* ```js
* context.on('console', async msg => {
* const values = [];
* for (const arg of msg.args())
* values.push(await arg.jsonValue());
* console.log(...values);
* });
* await page.evaluate(() => console.log('hello', 5, { foo: 'bar' }));
* ```
*
*/
addListener(event: 'console', listener: (consoleMessage: ConsoleMessage) => any): this
/**
* Emitted when a JavaScript dialog appears, such as `alert`, `prompt`, `confirm` or `beforeunload`. Listener **must**
* either [dialog.accept([promptText])](https://playwright.dev/docs/api/class-dialog#dialog-accept) or
* [dialog.dismiss()](https://playwright.dev/docs/api/class-dialog#dialog-dismiss) the dialog - otherwise the page
* will [freeze](https://developer.mozilla.org/en-US/docs/Web/JavaScript/EventLoop#never_blocking) waiting for the
* dialog, and actions like click will never finish.
*
* **Usage**
*
* ```js
* context.on('dialog', dialog => {
* dialog.accept();
* });
* ```
*
* **NOTE** When no [page.on('dialog')](https://playwright.dev/docs/api/class-page#page-event-dialog) or
* [browserContext.on('dialog')](https://playwright.dev/docs/api/class-browsercontext#browser-context-event-dialog)
* listeners are present, all dialogs are automatically dismissed.
*
*/
addListener(event: 'dialog', listener: (dialog: Dialog) => any): this
/**
* Emitted when a JavaScript dialog in any page belonging to this context has been closed, either by
* [dialog.accept([promptText])](https://playwright.dev/docs/api/class-dialog#dialog-accept), by
* [dialog.dismiss()](https://playwright.dev/docs/api/class-dialog#dialog-dismiss), or manually by the user in the
* headed browser.
*/
addListener(event: 'dialogclosed', listener: (dialog: Dialog) => any): this
/**
* Emitted when attachment download started in any page belonging to this context. User can access basic file
* operations on downloaded content via the passed [Download](https://playwright.dev/docs/api/class-download)
* instance. See also [page.on('download')](https://playwright.dev/docs/api/class-page#page-event-download) to receive
* events about a specific page.
*/
addListener(event: 'download', listener: (download: Download) => any): this
/**
* Emitted when a frame is attached in any page belonging to this context. See also
* [page.on('frameattached')](https://playwright.dev/docs/api/class-page#page-event-frame-attached) to receive events
* about a specific page.
*/
addListener(event: 'frameattached', listener: (frame: Frame) => any): this
/**
* Emitted when a frame is detached in any page belonging to this context. See also
* [page.on('framedetached')](https://playwright.dev/docs/api/class-page#page-event-frame-detached) to receive events
* about a specific page.
*/
addListener(event: 'framedetached', listener: (frame: Frame) => any): this
/**
* Emitted when a frame is navigated to a new url in any page belonging to this context. See also
* [page.on('framenavigated')](https://playwright.dev/docs/api/class-page#page-event-frame-navigated) to receive
* events about navigations in a specific page.
*/
addListener(event: 'framenavigated', listener: (frame: Frame) => any): this
/**
* The event is emitted when a new Page is created in the BrowserContext. The page may still be loading. The event
* will also fire for popup pages. See also
* [page.on('popup')](https://playwright.dev/docs/api/class-page#page-event-popup) to receive events about popups
* relevant to a specific page.
*
* The earliest moment that page is available is when it has navigated to the initial url. For example, when opening a
* popup with `window.open('http://example.com')`, this event will fire when the network request to
* "http://example.com" is done and its response has started loading in the popup. If you would like to route/listen
* to this network request, use
* [browserContext.route(url, handler[, options])](https://playwright.dev/docs/api/class-browsercontext#browser-context-route)
* and
* [browserContext.on('request')](https://playwright.dev/docs/api/class-browsercontext#browser-context-event-request)
* respectively instead of similar methods on the [Page](https://playwright.dev/docs/api/class-page).
*
* ```js
* const newPagePromise = context.waitForEvent('page');
* await page.getByText('open new page').click();
* const newPage = await newPagePromise;
* console.log(await newPage.evaluate('location.href'));
* ```
*
* **NOTE** Use
* [page.waitForLoadState([state, options])](https://playwright.dev/docs/api/class-page#page-wait-for-load-state) to
* wait until the page gets to a particular state (you should not need it in most cases).
*
*/
addListener(event: 'page', listener: (page: Page) => any): this
/**
* Emitted when a page in this context is closed. See also
* [page.on('close')](https://playwright.dev/docs/api/class-page#page-event-close) to receive events about a specific
* page.
*/
addListener(event: 'pageclose', listener: (page: Page) => any): this
/**
* Emitted when the JavaScript [`load`](https://developer.mozilla.org/en-US/docs/Web/Events/load) event is dispatched
* in any page belonging to this context. See also
* [page.on('load')](https://playwright.dev/docs/api/class-page#page-event-load) to receive events about a specific
* page.
*/
addListener(event: 'pageload', listener: (page: Page) => any): this
/**
* Emitted when a request is issued from any pages created through this context. The [request] object is read-only. To
* only listen for requests from a particular page, use
* [page.on('request')](https://playwright.dev/docs/api/class-page#page-event-request).
*
* In order to intercept and mutate requests, see
* [browserContext.route(url, handler[, options])](https://playwright.dev/docs/api/class-browsercontext#browser-context-route)
* or [page.route(url, handler[, options])](https://playwright.dev/docs/api/class-page#page-route).
*/
addListener(event: 'request', listener: (request: Request) => any): this
/**
* Emitted when a request fails, for example by timing out. To only listen for failed requests from a particular page,
* 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
* [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
/**
* Emitted when a request finishes successfully after downloading the response body. For a successful response, the
* sequence of events is `request`, `response` and `requestfinished`. To listen for successful requests from a
* particular page, use
* [page.on('requestfinished')](https://playwright.dev/docs/api/class-page#page-event-request-finished).
*/
addListener(event: 'requestfinished', listener: (request: Request) => any): this
/**
* Emitted when [response] status and headers are received for a request. For a successful response, the sequence of
* events is `request`, `response` and `requestfinished`. To listen for response events from a particular page, use
* [page.on('response')](https://playwright.dev/docs/api/class-page#page-event-response).
*/
addListener(event: 'response', listener: (response: Response) => any): this
/**
* **NOTE** Service workers are only supported on Chromium-based browsers.
*
* Emitted when new service worker is created in the context.
*/
addListener(event: 'serviceworker', listener: (worker: Worker) => any): this
/**
* Emitted when exception is unhandled in any of the pages in this context. To listen for errors from a particular
* page, use [page.on('pageerror')](https://playwright.dev/docs/api/class-page#page-event-page-error) instead.
*/
addListener(event: 'weberror', listener: (webError: WebError) => any): this
/**
* Removes an event listener added by `on` or `addListener`.
*/
removeListener(event: 'backgroundpage', listener: (page: Page) => any): this
/**
* Removes an event listener added by `on` or `addListener`.
*/
removeListener(event: 'close', listener: (browserContext: BrowserContext) => any): this
/**
* Removes an event listener added by `on` or `addListener`.
*/
removeListener(event: 'console', listener: (consoleMessage: ConsoleMessage) => any): this
/**
* Removes an event listener added by `on` or `addListener`.
*/
removeListener(event: 'dialog', listener: (dialog: Dialog) => any): this
/**
* Removes an event listener added by `on` or `addListener`.
*/
removeListener(event: 'dialogclosed', listener: (dialog: Dialog) => any): this
/**
* Removes an event listener added by `on` or `addListener`.
*/
removeListener(event: 'download', listener: (download: Download) => any): this
/**
* Removes an event listener added by `on` or `addListener`.
*/
removeListener(event: 'frameattached', listener: (frame: Frame) => any): this
/**
* Removes an event listener added by `on` or `addListener`.
*/
removeListener(event: 'framedetached', listener: (frame: Frame) => any): this
/**
* Removes an event listener added by `on` or `addListener`.
*/
removeListener(event: 'framenavigated', listener: (frame: Frame) => any): this
/**
* Removes an event listener added by `on` or `addListener`.
*/
removeListener(event: 'page', listener: (page: Page) => any): this
/**
* Removes an event listener added by `on` or `addListener`.
*/
removeListener(event: 'pageclose', listener: (page: Page) => any): this
/**
* Removes an event listener added by `on` or `addListener`.
*/
removeListener(event: 'pageload', listener: (page: Page) => any): this
/**
* Removes an event listener added by `on` or `addListener`.
*/
removeListener(event: 'request', listener: (request: Request) => any): this
/**
* Removes an event listener added by `on` or `addListener`.
*/
removeListener(event: 'requestfailed', listener: (request: Request) => any): this
/**
* Removes an event listener added by `on` or `addListener`.
*/
removeListener(event: 'requestfinished', listener: (request: Request) => any): this
/**
* Removes an event listener added by `on` or `addListener`.
*/
removeListener(event: 'response', listener: (response: Response) => any): this
/**
* Removes an event listener added by `on` or `addListener`.
*/
removeListener(event: 'serviceworker', listener: (worker: Worker) => any): this
/**
* Removes an event listener added by `on` or `addListener`.
*/
removeListener(event: 'weberror', listener: (webError: WebError) => any): this
/**
* Removes an event listener added by `on` or `addListener`.
*/
off(event: 'backgroundpage', listener: (page: Page) => any): this
/**
* Removes an event listener added by `on` or `addListener`.
*/
off(event: 'close', listener: (browserContext: BrowserContext) => any): this
/**
* Removes an event listener added by `on` or `addListener`.
*/
off(event: 'console', listener: (consoleMessage: ConsoleMessage) => any): this
/**
* Removes an event listener added by `on` or `addListener`.
*/
off(event: 'dialog', listener: (dialog: Dialog) => any): this
/**
* Removes an event listener added by `on` or `addListener`.
*/
off(event: 'dialogclosed', listener: (dialog: Dialog) => any): this
/**
* Removes an event listener added by `on` or `addListener`.
*/
off(event: 'download', listener: (download: Download) => any): this
/**
* Removes an event listener added by `on` or `addListener`.
*/
off(event: 'frameattached', listener: (frame: Frame) => any): this
/**
* Removes an event listener added by `on` or `addListener`.
*/
off(event: 'framedetached', listener: (frame: Frame) => any): this
/**
* Removes an event listener added by `on` or `addListener`.
*/
off(event: 'framenavigated', listener: (frame: Frame) => any): this
/**
* Removes an event listener added by `on` or `addListener`.
*/
off(event: 'page', listener: (page: Page) => any): this
/**
* Removes an event listener added by `on` or `addListener`.
*/
off(event: 'pageclose', listener: (page: Page) => any): this
/**
* Removes an event listener added by `on` or `addListener`.
*/
off(event: 'pageload', listener: (page: Page) => any): this
/**
* Removes an event listener added by `on` or `addListener`.
*/
off(event: 'request', listener: (request: Request) => any): this
/**
* Removes an event listener added by `on` or `addListener`.
*/
off(event: 'requestfailed', listener: (request: Request) => any): this
/**
* Removes an event listener added by `on` or `addListener`.
*/
off(event: 'requestfinished', listener: (request: Request) => any): this
/**
* Removes an event listener added by `on` or `addListener`.
*/
off(event: 'response', listener: (response: Response) => any): this
/**
* Removes an event listener added by `on` or `addListener`.
*/
off(event: 'serviceworker', listener: (worker: Worker) => any): this
/**
* Removes an event listener added by `on` or `addListener`.
*/
off(event: 'weberror', listener: (webError: WebError) => any): this
/**
* This event is not emitted.
*/
prependListener(event: 'backgroundpage', listener: (page: Page) => any): this
/**
* Emitted when Browser context gets closed. This might happen because of one of the following:
* - Browser context is closed.
* - Browser application is closed or crashed.
* - The [browser.close([options])](https://playwright.dev/docs/api/class-browser#browser-close) method was called.
*/
prependListener(event: 'close', listener: (browserContext: BrowserContext) => any): this
/**
* Emitted when JavaScript within the page calls one of console API methods, e.g. `console.log` or `console.dir`.
*
* The arguments passed into `console.log` and the page are available on the
* [ConsoleMessage](https://playwright.dev/docs/api/class-consolemessage) event handler argument.
*
* **Usage**
*
* ```js
* context.on('console', async msg => {
* const values = [];
* for (const arg of msg.args())
* values.push(await arg.jsonValue());
* console.log(...values);
* });
* await page.evaluate(() => console.log('hello', 5, { foo: 'bar' }));
* ```
*
*/
prependListener(event: 'console', listener: (consoleMessage: ConsoleMessage) => any): this
/**
* Emitted when a JavaScript dialog appears, such as `alert`, `prompt`, `confirm` or `beforeunload`. Listener **must**
* either [dialog.accept([promptText])](https://playwright.dev/docs/api/class-dialog#dialog-accept) or
* [dialog.dismiss()](https://playwright.dev/docs/api/class-dialog#dialog-dismiss) the dialog - otherwise the page
* will [freeze](https://developer.mozilla.org/en-US/docs/Web/JavaScript/EventLoop#never_blocking) waiting for the
* dialog, and actions like click will never finish.
*
* **Usage**
*
* ```js
* context.on('dialog', dialog => {
* dialog.accept();
* });
* ```
*
* **NOTE** When no [page.on('dialog')](https://playwright.dev/docs/api/class-page#page-event-dialog) or
* [browserContext.on('dialog')](https://playwright.dev/docs/api/class-browsercontext#browser-context-event-dialog)
* listeners are present, all dialogs are automatically dismissed.
*
*/
prependListener(event: 'dialog', listener: (dialog: Dialog) => any): this
/**
* Emitted when a JavaScript dialog in any page belonging to this context has been closed, either by
* [dialog.accept([promptText])](https://playwright.dev/docs/api/class-dialog#dialog-accept), by
* [dialog.dismiss()](https://playwright.dev/docs/api/class-dialog#dialog-dismiss), or manually by the user in the
* headed browser.
*/
prependListener(event: 'dialogclosed', listener: (dialog: Dialog) => any): this
/**
* Emitted when attachment download started in any page belonging to this context. User can access basic file
* operations on downloaded content via the passed [Download](https://playwright.dev/docs/api/class-download)
* instance. See also [page.on('download')](https://playwright.dev/docs/api/class-page#page-event-download) to receive
* events about a specific page.
*/
prependListener(event: 'download', listener: (download: Download) => any): this
/**
* Emitted when a frame is attached in any page belonging to this context. See also
* [page.on('frameattached')](https://playwright.dev/docs/api/class-page#page-event-frame-attached) to receive events
* about a specific page.
*/
prependListener(event: 'frameattached', listener: (frame: Frame) => any): this
/**
* Emitted when a frame is detached in any page belonging to this context. See also
* [page.on('framedetached')](https://playwright.dev/docs/api/class-page#page-event-frame-detached) to receive events
* about a specific page.
*/
prependListener(event: 'framedetached', listener: (frame: Frame) => any): this
/**
* Emitted when a frame is navigated to a new url in any page belonging to this context. See also
* [page.on('framenavigated')](https://playwright.dev/docs/api/class-page#page-event-frame-navigated) to receive
* events about navigations in a specific page.
*/
prependListener(event: 'framenavigated', listener: (frame: Frame) => any): this
/**
* The event is emitted when a new Page is created in the BrowserContext. The page may still be loading. The event
* will also fire for popup pages. See also
* [page.on('popup')](https://playwright.dev/docs/api/class-page#page-event-popup) to receive events about popups
* relevant to a specific page.
*
* The earliest moment that page is available is when it has navigated to the initial url. For example, when opening a
* popup with `window.open('http://example.com')`, this event will fire when the network request to
* "http://example.com" is done and its response has started loading in the popup. If you would like to route/listen
* to this network request, use
* [browserContext.route(url, handler[, options])](https://playwright.dev/docs/api/class-browsercontext#browser-context-route)
* and
* [browserContext.on('request')](https://playwright.dev/docs/api/class-browsercontext#browser-context-event-request)
* respectively instead of similar methods on the [Page](https://playwright.dev/docs/api/class-page).
*
* ```js
* const newPagePromise = context.waitForEvent('page');
* await page.getByText('open new page').click();
* const newPage = await newPagePromise;
* console.log(await newPage.evaluate('location.href'));
* ```
*
* **NOTE** Use
* [page.waitForLoadState([state, options])](https://playwright.dev/docs/api/class-page#page-wait-for-load-state) to
* wait until the page gets to a particular state (you should not need it in most cases).
*
*/
prependListener(event: 'page', listener: (page: Page) => any): this
/**
* Emitted when a page in this context is closed. See also
* [page.on('close')](https://playwright.dev/docs/api/class-page#page-event-close) to receive events about a specific
* page.
*/
prependListener(event: 'pageclose', listener: (page: Page) => any): this
/**
* Emitted when the JavaScript [`load`](https://developer.mozilla.org/en-US/docs/Web/Events/load) event is dispatched
* in any page belonging to this context. See also
* [page.on('load')](https://playwright.dev/docs/api/class-page#page-event-load) to receive events about a specific
* page.
*/
prependListener(event: 'pageload', listener: (page: Page) => any): this
/**
* Emitted when a request is issued from any pages created through this context. The [request] object is read-only. To
* only listen for requests from a particular page, use
* [page.on('request')](https://playwright.dev/docs/api/class-page#page-event-request).
*
* In order to intercept and mutate requests, see
* [browserContext.route(url, handler[, options])](https://playwright.dev/docs/api/class-browsercontext#browser-context-route)
* or [page.route(url, handler[, options])](https://playwright.dev/docs/api/class-page#page-route).
*/
prependListener(event: 'request', listener: (request: Request) => any): this
/**
* Emitted when a request fails, for example by timing out. To only listen for failed requests from a particular page,
* 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
* [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
/**
* Emitted when a request finishes successfully after downloading the response body. For a successful response, the
* sequence of events is `request`, `response` and `requestfinished`. To listen for successful requests from a
* particular page, use
* [page.on('requestfinished')](https://playwright.dev/docs/api/class-page#page-event-request-finished).
*/
prependListener(event: 'requestfinished', listener: (request: Request) => any): this
/**
* Emitted when [response] status and headers are received for a request. For a successful response, the sequence of
* events is `request`, `response` and `requestfinished`. To listen for response events from a particular page, use
* [page.on('response')](https://playwright.dev/docs/api/class-page#page-event-response).
*/
prependListener(event: 'response', listener: (response: Response) => any): this
/**
* **NOTE** Service workers are only supported on Chromium-based browsers.
*
* Emitted when new service worker is created in the context.
*/
prependListener(event: 'serviceworker', listener: (worker: Worker) => any): this
/**
* Emitted when exception is unhandled in any of the pages in this context. To listen for errors from a particular
* page, use [page.on('pageerror')](https://playwright.dev/docs/api/class-page#page-event-page-error) instead.
*/
prependListener(event: 'weberror', listener: (webError: WebError) => any): this
/**
* Adds cookies into this browser context. All pages within this context will have these cookies installed. Cookies
* can be obtained via
* [browserContext.cookies([urls])](https://playwright.dev/docs/api/class-browsercontext#browser-context-cookies).
*
* **Usage**
*
* ```js
* await browserContext.addCookies([cookieObject1, cookieObject2]);
* ```
*
* @param cookies
*/
addCookies(
cookies: ReadonlyArray<{
name: string
value: string
/**
* Either `url` or both `domain` and `path` are required. Optional.
*/
url?: string
/**
* For the cookie to apply to all subdomains as well, prefix domain with a dot, like this: ".example.com". Either
* `url` or both `domain` and `path` are required. Optional.
*/
domain?: string
/**
* Either `url` or both `domain` and `path` are required. Optional.
*/
path?: string
/**
* Unix time in seconds. Optional.
*/
expires?: number
/**
* Optional.
*/
httpOnly?: boolean
/**
* Optional.
*/
secure?: boolean
/**
* Optional.
*/
sameSite?: 'Strict' | 'Lax' | 'None'
/**
* For partitioned third-party cookies (aka
* [CHIPS](https://developer.mozilla.org/en-US/docs/Web/Privacy/Guides/Privacy_sandbox/Partitioned_cookies)), the
* partition key. Optional.
*/
partitionKey?: string
}>,
): Promise<void>
/**
* Returns an empty list.
* @deprecated Background pages have been removed from Chromium together with Manifest V2 extensions.
*/
backgroundPages(): Array<Page>
/**
* Gets the browser instance that owns the context. Returns `null` if the context is created outside of normal
* browser, e.g. Android or Electron.
*/
browser(): null | Browser
/**
* Removes cookies from context. Accepts optional filter.
*
* **Usage**
*
* ```js
* await context.clearCookies();
* await context.clearCookies({ name: 'session-id' });
* await context.clearCookies({ domain: 'my-origin.com' });
* await context.clearCookies({ domain: /.*my-origin\.com/ });
* await context.clearCookies({ path: '/api/v1' });
* await context.clearCookies({ name: 'session-id', domain: 'my-origin.com' });
* ```
*
* @param options
*/
clearCookies(options?: {
/**
* Only removes cookies with the given domain.
*/
domain?: string | RegExp
/**
* Only removes cookies with the given name.
*/
name?: string | RegExp
/**
* Only removes cookies with the given path.
*/
path?: string | RegExp
}): Promise<void>
/**
* Clears all permission overrides for the browser context.
*
* **Usage**
*
* ```js
* const context = await browser.newContext();
* await context.grantPermissions(['clipboard-read']);
* // do stuff ..
* context.clearPermissions();
* ```
*
*/
clearPermissions(): Promise<void>
/**
* 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?: {
/**
* The reason to be reported to the operations interrupted by the context closure.
*/
reason?: string
}): Promise<void>
/**
* If no URLs are specified, this method returns all cookies. If URLs are specified, only cookies that affect those
* URLs are returned.
* @param urls Optional list of URLs.
*/
cookies(urls?: string | ReadonlyArray<string>): Promise<Array<Cookie>>
/**
* The method adds a function called
* [`name`](https://playwright.dev/docs/api/class-browsercontext#browser-context-expose-function-option-name) on the
* `window` object of every frame in every page in the context. When called, the function executes
* [`callback`](https://playwright.dev/docs/api/class-browsercontext#browser-context-expose-function-option-callback)
* and returns a [Promise] which resolves to the return value of
* [`callback`](https://playwright.dev/docs/api/class-browsercontext#browser-context-expose-function-option-callback).
*
* If the
* [`callback`](https://playwright.dev/docs/api/class-browsercontext#browser-context-expose-function-option-callback)
* returns a [Promise], it will be awaited.
*
* See [page.exposeFunction(name, callback)](https://playwright.dev/docs/api/class-page#page-expose-function) for
* page-only version.
*
* **Usage**
*
* An example of adding a `sha256` function to all pages in the context:
*
* ```js
* const { webkit } = require('playwright'); // Or 'chromium' or 'firefox'.
* const crypto = require('crypto');
*
* (async () => {
* const browser = await webkit.launch({ headless: false });
* const context = await browser.newContext();
* await context.exposeFunction('sha256', text =>
* crypto.createHash('sha256').update(text).digest('hex'),
* );
* const page = await context.newPage();
* await page.setContent(`
* <script>
* async function onClick() {
* document.querySelector('div').textContent = await window.sha256('PLAYWRIGHT');
* }
* </script>
* <button onclick="onClick()">Click me</button>
* <div></div>
* `);
* await page.getByRole('button').click();
* })();
* ```
*
* @param name Name of the function on the window object.
* @param callback Callback function that will be called in the Playwright's context.
*/
exposeFunction(name: string, callback: Function): Promise<Disposable>
/**
* Grants specified permissions to the browser context. Only grants corresponding permissions to the given origin if
* specified.
* @param permissions A list of permissions to grant.
*
* **NOTE** Supported permissions differ between browsers, and even between different versions of the same browser.
* Any permission may stop working after an update.
*
* Here are some permissions that may be supported by some browsers:
* - `'accelerometer'`
* - `'ambient-light-sensor'`
* - `'background-sync'`
* - `'camera'`
* - `'clipboard-read'`
* - `'clipboard-write'`
* - `'geolocation'`
* - `'gyroscope'`
* - `'local-fonts'`
* - `'local-network-access'`
* - `'magnetometer'`
* - `'microphone'`
* - `'midi-sysex'` (system-exclusive midi)
* - `'midi'`
* - `'notifications'`
* - `'payment-handler'`
* - `'storage-access'`
* - `'screen-wake-lock'`
* @param options
*/
grantPermissions(
permissions: ReadonlyArray<string>,
options?: {
/**
* The [origin] to grant permissions to, e.g. "https://example.com".
*/
origin?: string
},
): Promise<void>
/**
* Indicates that the browser context is in the process of closing or has already been closed.
*/
isClosed(): boolean
/**
* **NOTE** CDP sessions are only supported on Chromium-based browsers.
*
* Returns the newly created session.
* @param page Target to create new session for. For backwards-compatibility, this parameter is named `page`, but it can be a
* `Page` or `Frame` type.
*/
newCDPSession(page: Page | Frame): Promise<CDPSession>
/**
* Creates a new page in the browser context.
*/
newPage(): Promise<Page>
/**
* Returns all open pages in the context.
*/
pages(): Array<Page>
/**
* Routing provides the capability to modify network requests that are made by any page in the browser context. Once
* route is enabled, every request matching the url pattern will stall unless it's continued, fulfilled or aborted.
*
* **NOTE**
* [browserContext.route(url, handler[, options])](https://playwright.dev/docs/api/class-browsercontext#browser-context-route)
* will not intercept requests intercepted by Service Worker. See
* [this](https://github.com/microsoft/playwright/issues/1090) issue. We recommend disabling Service Workers when
* using request interception by setting
* [`serviceWorkers`](https://playwright.dev/docs/api/class-browser#browser-new-context-option-service-workers) to
* `'block'`.
*
* **Usage**
*
* An example of a naive handler that aborts all image requests:
*
* ```js
* const context = await browser.newContext();
* await context.route('**\/*.{png,jpg,jpeg}', route => route.abort());
* const page = await context.newPage();
* await page.goto('https://example.com');
* await browser.close();
* ```
*
* or the same snippet using a regex pattern instead:
*
* ```js
* const context = await browser.newContext();
* await context.route(/(\.png$)|(\.jpg$)/, route => route.abort());
* const page = await context.newPage();
* await page.goto('https://example.com');
* await browser.close();
* ```
*
* It is possible to examine the request to decide the route action. For example, mocking all requests that contain
* some post data, and leaving all other requests as is:
*
* ```js
* await context.route('/api/**', async route => {
* if (route.request().postData().includes('my-string'))
* await route.fulfill({ body: 'mocked-data' });
* else
* await route.continue();
* });
* ```
*
* Page routes (set up with
* [page.route(url, handler[, options])](https://playwright.dev/docs/api/class-page#page-route)) take precedence over
* browser context routes when request matches both handlers.
*
* To remove a route with its handler you can use
* [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, URL pattern, or predicate that receives a [URL] to match during routing. If
* [`baseURL`](https://playwright.dev/docs/api/class-browser#browser-new-context-option-base-url) is set in the
* context options and the provided URL is a string that does not start with `*`, it is resolved using the
* [`new URL()`](https://developer.mozilla.org/en-US/docs/Web/API/URL/URL) constructor.
* @param handler handler function to route the request.
* @param options
*/
route(
url: string | RegExp | URLPattern | ((url: URL) => boolean),
handler: (route: Route, request: Request) => Promise<any> | any,
options?: {
/**
* How often a route should be used. By default it will be used every time.
*/
times?: number
},
): Promise<Disposable>
/**
* If specified the network requests that are made in the context will be served from the HAR file. Read more about
* [Replaying from HAR](https://playwright.dev/docs/mock#replaying-from-har).
*
* Playwright will not serve requests intercepted by Service Worker from the HAR file. See
* [this](https://github.com/microsoft/playwright/issues/1090) issue. We recommend disabling Service Workers when
* using request interception by setting
* [`serviceWorkers`](https://playwright.dev/docs/api/class-browser#browser-new-context-option-service-workers) to
* `'block'`.
* @param har Path to a [HAR](http://www.softwareishard.com/blog/har-12-spec) file with prerecorded network data. If `path` is a
* relative path, then it is resolved relative to the current working directory.
* @param options
*/
routeFromHAR(
har: string,
options?: {
/**
* - If set to 'abort' any request not found in the HAR file will be aborted.
* - If set to 'fallback' falls through to the next route handler in the handler chain.
*
* Defaults to abort.
*/
notFound?: 'abort' | 'fallback'
/**
* If specified, updates the given HAR with the actual network information instead of serving from file. The file is
* written to disk when
* [browserContext.close([options])](https://playwright.dev/docs/api/class-browsercontext#browser-context-close) is
* called.
*/
update?: boolean
/**
* Optional setting to control resource content management. If `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.
*/
updateContent?: 'embed' | 'attach'
/**
* 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
* `minimal`.
*/
updateMode?: 'full' | 'minimal'
/**
* A glob pattern, regular expression or predicate to match the request URL. Only requests with URL matching the
* pattern will be served from the HAR file. If not specified, all requests are served from the HAR file.
*/
url?: string | RegExp
},
): Promise<void>
/**
* This method allows to modify websocket connections that are made by any page in the browser context.
*
* Note that only `WebSocket`s created after this method was called will be routed. It is recommended to call this
* method before creating any pages.
*
* **Usage**
*
* Below is an example of a simple handler that blocks some websocket messages. See
* [WebSocketRoute](https://playwright.dev/docs/api/class-websocketroute) for more details and examples.
*
* ```js
* await context.routeWebSocket('/ws', async ws => {
* ws.routeSend(message => {
* if (message === 'to-be-blocked')
* return;
* ws.send(message);
* });
* await ws.connect();
* });
* ```
*
* @param url Only WebSockets with the url matching this pattern will be routed. A string pattern can be relative to the
* [`baseURL`](https://playwright.dev/docs/api/class-browser#browser-new-context-option-base-url) context option.
* @param handler Handler function to route the WebSocket.
*/
routeWebSocket(
url: string | RegExp | ((url: URL) => boolean),
handler: (websocketroute: WebSocketRoute) => Promise<any> | any,
): Promise<void>
/**
* **NOTE** Service workers are only supported on Chromium-based browsers.
*
* All existing service workers in the context.
*/
serviceWorkers(): Array<Worker>
/**
* This setting will change the default maximum navigation time for the following methods and related shortcuts:
* - [page.goBack([options])](https://playwright.dev/docs/api/class-page#page-go-back)
* - [page.goForward([options])](https://playwright.dev/docs/api/class-page#page-go-forward)
* - [page.goto(url[, options])](https://playwright.dev/docs/api/class-page#page-goto)
* - [page.reload([options])](https://playwright.dev/docs/api/class-page#page-reload)
* - [page.setContent(html[, options])](https://playwright.dev/docs/api/class-page#page-set-content)
* - [page.waitForNavigation([options])](https://playwright.dev/docs/api/class-page#page-wait-for-navigation)
*
* **NOTE**
* [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
/**
* This setting will change the default maximum time for all the methods accepting
* [`timeout`](https://playwright.dev/docs/api/class-browsercontext#browser-context-set-default-timeout-option-timeout)
* option.
*
* **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. Pass `0` to disable timeout.
*/
setDefaultTimeout(timeout: number): void
/**
* The extra HTTP headers will be sent with every request initiated by any page in the context. These headers are
* merged with page-specific extra HTTP headers set with
* [page.setExtraHTTPHeaders(headers)](https://playwright.dev/docs/api/class-page#page-set-extra-http-headers). If
* page overrides a particular header, page-specific header value will be used instead of the browser context header
* value.
*
* **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<void>
/**
* Sets the context's geolocation. Passing `null` or `undefined` emulates position unavailable.
*
* **Usage**
*
* ```js
* await browserContext.setGeolocation({ latitude: 59.95, longitude: 30.31667 });
* ```
*
* **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.
*
* @param geolocation
*/
setGeolocation(
geolocation: null | {
/**
* Latitude between -90 and 90.
*/
latitude: number
/**
* Longitude between -180 and 180.
*/
longitude: number
/**
* Non-negative accuracy value. Defaults to `0`.
*/
accuracy?: number
},
): Promise<void>
/**
* Sets the credentials for HTTP authentication for this browser context.
*
* **NOTE** Browsers may cache credentials per origin after a successful authentication, so changing credentials for
* an origin that has already been authenticated may have no effect.
*
* @param httpCredentials Pass an array to use different credentials for different origins. The first entry that matches the request origin
* is used, and entries with no origin match any request.
*/
setHTTPCredentials(
httpCredentials:
| null
| {
username: string
password: string
/**
* Restrain sending http credentials on specific origin (scheme://host:port).
*/
origin?: string
}
| ReadonlyArray<{
username: string
password: string
/**
* Restrain sending http credentials on specific origin (scheme://host:port).
*/
origin?: string
}>,
): Promise<void>
/**
* @param offline Whether to emulate network being offline for the browser context.
*/
setOffline(offline: boolean): Promise<void>
/**
* Clears the existing cookies, local storage, IndexedDB entries, origin private file system entries and virtual
* WebAuthn credentials, and sets the new storage state. When the storage state contains credentials, the virtual
* WebAuthn authenticator is installed (equivalent to
* [credentials.install()](https://playwright.dev/docs/api/class-credentials#credentials-install)), preventing all
* real authenticators from working in this context.
*
* **Usage**
*
* ```js
* // Load storage state from a file and apply it to the context.
* await context.setStorageState('state.json');
* ```
*
* @param storageState Learn more about [storage state and auth](https://playwright.dev/docs/auth).
*
* 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).
*/
setStorageState(
storageState:
| string
| {
/**
* Cookies to set for context
*/
cookies: Array<{
name: string
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"
*/
domain: string
/**
* Domain and path are required
*/
path: string
/**
* Unix time in seconds.
*/
expires: number
httpOnly: boolean
secure: boolean
/**
* sameSite flag
*/
sameSite: 'Strict' | 'Lax' | 'None'
}>
origins: Array<{
origin: string
/**
* localStorage to set for context
*/
localStorage: Array<{
name: string
value: string
}>
}>
},
): Promise<void>
/**
* Returns storage state for this browser context, contains current cookies, local storage snapshot, IndexedDB
* snapshot, origin private file system snapshot and virtual WebAuthn credentials.
* @param options
*/
storageState(options?: {
/**
* Set to `true` to include the context's virtual WebAuthn
* [browserContext.credentials](https://playwright.dev/docs/api/class-browsercontext#browser-context-credentials)
* (passkeys) in the storage state snapshot. The captured credentials carry their private keys, so they can be
* re-seeded into a later context via the
* [`storageState`](https://playwright.dev/docs/api/class-browser#browser-new-context-option-storage-state) option or
* [browserContext.setStorageState(storageState)](https://playwright.dev/docs/api/class-browsercontext#browser-context-set-storage-state).
* Note that restoring the storage state that contains credentials will automatically install the virtual WebAuthn
* authenticator (see [credentials.install()](https://playwright.dev/docs/api/class-credentials#credentials-install)),
* and prevent all real authenticators from working in this context.
*/
credentials?: boolean
/**
* Set to `true` to include [IndexedDB](https://developer.mozilla.org/en-US/docs/Web/API/IndexedDB_API) in the storage
* state snapshot. If your application uses IndexedDB to store authentication tokens, like Firebase Authentication,
* enable this.
*/
indexedDB?: boolean
/**
* Set to `true` to include the
* [origin private file system](https://developer.mozilla.org/en-US/docs/Web/API/File_System_API/Origin_private_file_system)
* in the storage state snapshot.
*
* **NOTE** OPFS is currently not supported in ephemeral WebKit contexts.
*
*/
opfs?: boolean
/**
* The file path to save the storage state to. If
* [`path`](https://playwright.dev/docs/api/class-browsercontext#browser-context-storage-state-option-path) is a
* relative path, then it is resolved relative to current working directory. If no path is provided, storage state is
* still returned, but won't be saved to the disk.
*/
path?: string
}): Promise<{
cookies: Array<{
name: string
value: string
domain: string
path: string
/**
* Unix time in seconds.
*/
expires: number
httpOnly: boolean
secure: boolean
sameSite: 'Strict' | 'Lax' | 'None'
}>
origins: Array<{
origin: string
localStorage: Array<{
name: string
value: string
}>
}>
}>
/**
* Removes a route created with
* [browserContext.route(url, handler[, options])](https://playwright.dev/docs/api/class-browsercontext#browser-context-route).
* When [`handler`](https://playwright.dev/docs/api/class-browsercontext#browser-context-unroute-option-handler) is
* not specified, removes all routes for the
* [`url`](https://playwright.dev/docs/api/class-browsercontext#browser-context-unroute-option-url).
* @param url A glob pattern, regex pattern, URL pattern, or predicate receiving [URL] used to register a routing with
* [browserContext.route(url, handler[, options])](https://playwright.dev/docs/api/class-browsercontext#browser-context-route).
* @param handler Optional handler function used to register a routing with
* [browserContext.route(url, handler[, options])](https://playwright.dev/docs/api/class-browsercontext#browser-context-route).
*/
unroute(
url: string | RegExp | URLPattern | ((url: URL) => boolean),
handler?: (route: Route, request: Request) => Promise<any> | any,
): Promise<void>
/**
* Removes all routes created with
* [browserContext.route(url, handler[, options])](https://playwright.dev/docs/api/class-browsercontext#browser-context-route)
* and
* [browserContext.routeFromHAR(har[, options])](https://playwright.dev/docs/api/class-browsercontext#browser-context-route-from-har).
* @param options
*/
unrouteAll(options?: {
/**
* Specifies whether to wait for already running handlers and what to do if they throw errors:
* - `'default'` - do not wait for current handler calls (if any) to finish, if unrouted handler throws, it may
* result in unhandled error
* - `'wait'` - wait for current handler calls (if any) to finish
* - `'ignoreErrors'` - do not wait for current handler calls (if any) to finish, all errors thrown by the handlers
* after unrouting are silently caught
*/
behavior?: 'wait' | 'ignoreErrors' | 'default'
}): Promise<void>
/**
* This event is not emitted.
*/
waitForEvent(
event: 'backgroundpage',
optionsOrPredicate?:
| {
predicate?: (page: Page) => boolean | Promise<boolean>
timeout?: number
signal?: AbortSignal
}
| ((page: Page) => boolean | Promise<boolean>),
): Promise<Page>
/**
* Emitted when Browser context gets closed. This might happen because of one of the following:
* - Browser context is closed.
* - Browser application is closed or crashed.
* - The [browser.close([options])](https://playwright.dev/docs/api/class-browser#browser-close) method was called.
*/
waitForEvent(
event: 'close',
optionsOrPredicate?:
| {
predicate?: (browserContext: BrowserContext) => boolean | Promise<boolean>
timeout?: number
signal?: AbortSignal
}
| ((browserContext: BrowserContext) => boolean | Promise<boolean>),
): Promise<BrowserContext>
/**
* Emitted when JavaScript within the page calls one of console API methods, e.g. `console.log` or `console.dir`.
*
* The arguments passed into `console.log` and the page are available on the
* [ConsoleMessage](https://playwright.dev/docs/api/class-consolemessage) event handler argument.
*
* **Usage**
*
* ```js
* context.on('console', async msg => {
* const values = [];
* for (const arg of msg.args())
* values.push(await arg.jsonValue());
* console.log(...values);
* });
* await page.evaluate(() => console.log('hello', 5, { foo: 'bar' }));
* ```
*
*/
waitForEvent(
event: 'console',
optionsOrPredicate?:
| {
predicate?: (consoleMessage: ConsoleMessage) => boolean | Promise<boolean>
timeout?: number
signal?: AbortSignal
}
| ((consoleMessage: ConsoleMessage) => boolean | Promise<boolean>),
): Promise<ConsoleMessage>
/**
* Emitted when a JavaScript dialog appears, such as `alert`, `prompt`, `confirm` or `beforeunload`. Listener **must**
* either [dialog.accept([promptText])](https://playwright.dev/docs/api/class-dialog#dialog-accept) or
* [dialog.dismiss()](https://playwright.dev/docs/api/class-dialog#dialog-dismiss) the dialog - otherwise the page
* will [freeze](https://developer.mozilla.org/en-US/docs/Web/JavaScript/EventLoop#never_blocking) waiting for the
* dialog, and actions like click will never finish.
*
* **Usage**
*
* ```js
* context.on('dialog', dialog => {
* dialog.accept();
* });
* ```
*
* **NOTE** When no [page.on('dialog')](https://playwright.dev/docs/api/class-page#page-event-dialog) or
* [browserContext.on('dialog')](https://playwright.dev/docs/api/class-browsercontext#browser-context-event-dialog)
* listeners are present, all dialogs are automatically dismissed.
*
*/
waitForEvent(
event: 'dialog',
optionsOrPredicate?:
| {
predicate?: (dialog: Dialog) => boolean | Promise<boolean>
timeout?: number
signal?: AbortSignal
}
| ((dialog: Dialog) => boolean | Promise<boolean>),
): Promise<Dialog>
/**
* Emitted when a JavaScript dialog in any page belonging to this context has been closed, either by
* [dialog.accept([promptText])](https://playwright.dev/docs/api/class-dialog#dialog-accept), by
* [dialog.dismiss()](https://playwright.dev/docs/api/class-dialog#dialog-dismiss), or manually by the user in the
* headed browser.
*/
waitForEvent(
event: 'dialogclosed',
optionsOrPredicate?:
| {
predicate?: (dialog: Dialog) => boolean | Promise<boolean>
timeout?: number
signal?: AbortSignal
}
| ((dialog: Dialog) => boolean | Promise<boolean>),
): Promise<Dialog>
/**
* Emitted when attachment download started in any page belonging to this context. User can access basic file
* operations on downloaded content via the passed [Download](https://playwright.dev/docs/api/class-download)
* instance. See also [page.on('download')](https://playwright.dev/docs/api/class-page#page-event-download) to receive
* events about a specific page.
*/
waitForEvent(
event: 'download',
optionsOrPredicate?:
| {
predicate?: (download: Download) => boolean | Promise<boolean>
timeout?: number
signal?: AbortSignal
}
| ((download: Download) => boolean | Promise<boolean>),
): Promise<Download>
/**
* Emitted when a frame is attached in any page belonging to this context. See also
* [page.on('frameattached')](https://playwright.dev/docs/api/class-page#page-event-frame-attached) to receive events
* about a specific page.
*/
waitForEvent(
event: 'frameattached',
optionsOrPredicate?:
| {
predicate?: (frame: Frame) => boolean | Promise<boolean>
timeout?: number
signal?: AbortSignal
}
| ((frame: Frame) => boolean | Promise<boolean>),
): Promise<Frame>
/**
* Emitted when a frame is detached in any page belonging to this context. See also
* [page.on('framedetached')](https://playwright.dev/docs/api/class-page#page-event-frame-detached) to receive events
* about a specific page.
*/
waitForEvent(
event: 'framedetached',
optionsOrPredicate?:
| {
predicate?: (frame: Frame) => boolean | Promise<boolean>
timeout?: number
signal?: AbortSignal
}
| ((frame: Frame) => boolean | Promise<boolean>),
): Promise<Frame>
/**
* Emitted when a frame is navigated to a new url in any page belonging to this context. See also
* [page.on('framenavigated')](https://playwright.dev/docs/api/class-page#page-event-frame-navigated) to receive
* events about navigations in a specific page.
*/
waitForEvent(
event: 'framenavigated',
optionsOrPredicate?:
| {
predicate?: (frame: Frame) => boolean | Promise<boolean>
timeout?: number
signal?: AbortSignal
}
| ((frame: Frame) => boolean | Promise<boolean>),
): Promise<Frame>
/**
* The event is emitted when a new Page is created in the BrowserContext. The page may still be loading. The event
* will also fire for popup pages. See also
* [page.on('popup')](https://playwright.dev/docs/api/class-page#page-event-popup) to receive events about popups
* relevant to a specific page.
*
* The earliest moment that page is available is when it has navigated to the initial url. For example, when opening a
* popup with `window.open('http://example.com')`, this event will fire when the network request to
* "http://example.com" is done and its response has started loading in the popup. If you would like to route/listen
* to this network request, use
* [browserContext.route(url, handler[, options])](https://playwright.dev/docs/api/class-browsercontext#browser-context-route)
* and
* [browserContext.on('request')](https://playwright.dev/docs/api/class-browsercontext#browser-context-event-request)
* respectively instead of similar methods on the [Page](https://playwright.dev/docs/api/class-page).
*
* ```js
* const newPagePromise = context.waitForEvent('page');
* await page.getByText('open new page').click();
* const newPage = await newPagePromise;
* console.log(await newPage.evaluate('location.href'));
* ```
*
* **NOTE** Use
* [page.waitForLoadState([state, options])](https://playwright.dev/docs/api/class-page#page-wait-for-load-state) to
* wait until the page gets to a particular state (you should not need it in most cases).
*
*/
waitForEvent(
event: 'page',
optionsOrPredicate?:
| {
predicate?: (page: Page) => boolean | Promise<boolean>
timeout?: number
signal?: AbortSignal
}
| ((page: Page) => boolean | Promise<boolean>),
): Promise<Page>
/**
* Emitted when a page in this context is closed. See also
* [page.on('close')](https://playwright.dev/docs/api/class-page#page-event-close) to receive events about a specific
* page.
*/
waitForEvent(
event: 'pageclose',
optionsOrPredicate?:
| {
predicate?: (page: Page) => boolean | Promise<boolean>
timeout?: number
signal?: AbortSignal
}
| ((page: Page) => boolean | Promise<boolean>),
): Promise<Page>
/**
* Emitted when the JavaScript [`load`](https://developer.mozilla.org/en-US/docs/Web/Events/load) event is dispatched
* in any page belonging to this context. See also
* [page.on('load')](https://playwright.dev/docs/api/class-page#page-event-load) to receive events about a specific
* page.
*/
waitForEvent(
event: 'pageload',
optionsOrPredicate?:
| {
predicate?: (page: Page) => boolean | Promise<boolean>
timeout?: number
signal?: AbortSignal
}
| ((page: Page) => boolean | Promise<boolean>),
): Promise<Page>
/**
* Emitted when a request is issued from any pages created through this context. The [request] object is read-only. To
* only listen for requests from a particular page, use
* [page.on('request')](https://playwright.dev/docs/api/class-page#page-event-request).
*
* In order to intercept and mutate requests, see
* [browserContext.route(url, handler[, options])](https://playwright.dev/docs/api/class-browsercontext#browser-context-route)
* or [page.route(url, handler[, options])](https://playwright.dev/docs/api/class-page#page-route).
*/
waitForEvent(
event: 'request',
optionsOrPredicate?:
| {
predicate?: (request: Request) => boolean | Promise<boolean>
timeout?: number
signal?: AbortSignal
}
| ((request: Request) => boolean | Promise<boolean>),
): Promise<Request>
/**
* Emitted when a request fails, for example by timing out. To only listen for failed requests from a particular page,
* 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
* [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<boolean>
timeout?: number
signal?: AbortSignal
}
| ((request: Request) => boolean | Promise<boolean>),
): Promise<Request>
/**
* Emitted when a request finishes successfully after downloading the response body. For a successful response, the
* sequence of events is `request`, `response` and `requestfinished`. To listen for successful requests from a
* particular page, use
* [page.on('requestfinished')](https://playwright.dev/docs/api/class-page#page-event-request-finished).
*/
waitForEvent(
event: 'requestfinished',
optionsOrPredicate?:
| {
predicate?: (request: Request) => boolean | Promise<boolean>
timeout?: number
signal?: AbortSignal
}
| ((request: Request) => boolean | Promise<boolean>),
): Promise<Request>
/**
* Emitted when [response] status and headers are received for a request. For a successful response, the sequence of
* events is `request`, `response` and `requestfinished`. To listen for response events from a particular page, use
* [page.on('response')](https://playwright.dev/docs/api/class-page#page-event-response).
*/
waitForEvent(
event: 'response',
optionsOrPredicate?:
| {
predicate?: (response: Response) => boolean | Promise<boolean>
timeout?: number
signal?: AbortSignal
}
| ((response: Response) => boolean | Promise<boolean>),
): Promise<Response>
/**
* **NOTE** Service workers are only supported on Chromium-based browsers.
*
* Emitted when new service worker is created in the context.
*/
waitForEvent(
event: 'serviceworker',
optionsOrPredicate?:
| {
predicate?: (worker: Worker) => boolean | Promise<boolean>
timeout?: number
signal?: AbortSignal
}
| ((worker: Worker) => boolean | Promise<boolean>),
): Promise<Worker>
/**
* Emitted when exception is unhandled in any of the pages in this context. To listen for errors from a particular
* page, use [page.on('pageerror')](https://playwright.dev/docs/api/class-page#page-event-page-error) instead.
*/
waitForEvent(
event: 'weberror',
optionsOrPredicate?:
| {
predicate?: (webError: WebError) => boolean | Promise<boolean>
timeout?: number
signal?: AbortSignal
}
| ((webError: WebError) => boolean | Promise<boolean>),
): Promise<WebError>
/**
* Playwright has ability to mock clock and passage of time.
*/
clock: Clock
/**
* Virtual WebAuthn authenticator for this context. Lets tests seed credentials and intercept
* `navigator.credentials.create()` / `navigator.credentials.get()` ceremonies.
*/
credentials: Credentials
/**
* Debugger allows to pause and resume the execution.
*/
debugger: Debugger
/**
* API testing helper associated with this context. Requests made with this API will use context cookies.
*/
request: APIRequestContext
tracing: Tracing
[Symbol.asyncDispose](): Promise<void>
}
BrowserType
BrowserType provides methods to launch a specific browser instance or connect to an existing one. The following is a typical example of using Playwright to drive automation:
const { chromium } = require('playwright') // Or 'firefox' or 'webkit'.
;(async () => {
const browser = await chromium.launch()
const page = await browser.newPage()
await page.goto('https://example.com')
// other actions...
await browser.close()
})()
interface BrowserType<Unused = {}> {
/**
* This method attaches Playwright to an existing browser instance using the Chrome DevTools Protocol.
*
* The default browser context is accessible via
* [browser.contexts()](https://playwright.dev/docs/api/class-browser#browser-contexts).
*
* **NOTE** Connecting over the Chrome DevTools Protocol is only supported for Chromium-based browsers.
*
* **NOTE** This connection is significantly lower fidelity than the Playwright protocol connection via
* [browserType.connect(endpoint[, options])](https://playwright.dev/docs/api/class-browsertype#browser-type-connect).
* If you are experiencing issues or attempting to use advanced functionality, you probably want to use
* [browserType.connect(endpoint[, options])](https://playwright.dev/docs/api/class-browsertype#browser-type-connect).
*
* **NOTE** Playwright maintains a curated list of arguments for launching the browser. If you launch the browser
* without Playwright and do not pass the exact same arguments, some of Playwright functionality may be broken upon
* connecting to the browser.
*
* **Usage**
*
* ```js
* const browser = await playwright.chromium.connectOverCDP('http://localhost:9222');
* const defaultContext = browser.contexts()[0];
* const page = defaultContext.pages()[0];
* ```
*
* @param endpointURL A CDP websocket endpoint or http url to connect to. For example `http://localhost:9222/` or
* `ws://127.0.0.1:9222/devtools/browser/387adf4c-243f-4051-a181-46798f4a46f4`.
* @param options
*/
connectOverCDP(endpointURL: string, options?: ConnectOverCDPOptions): Promise<Browser>
/**
* This method attaches Playwright to an existing browser instance using the Chrome DevTools Protocol.
*
* The default browser context is accessible via
* [browser.contexts()](https://playwright.dev/docs/api/class-browser#browser-contexts).
*
* **NOTE** Connecting over the Chrome DevTools Protocol is only supported for Chromium-based browsers.
*
* **NOTE** This connection is significantly lower fidelity than the Playwright protocol connection via
* [browserType.connect(endpoint[, options])](https://playwright.dev/docs/api/class-browsertype#browser-type-connect).
* If you are experiencing issues or attempting to use advanced functionality, you probably want to use
* [browserType.connect(endpoint[, options])](https://playwright.dev/docs/api/class-browsertype#browser-type-connect).
*
* **NOTE** Playwright maintains a curated list of arguments for launching the browser. If you launch the browser
* without Playwright and do not pass the exact same arguments, some of Playwright functionality may be broken upon
* connecting to the browser.
*
* **Usage**
*
* ```js
* const browser = await playwright.chromium.connectOverCDP('http://localhost:9222');
* const defaultContext = browser.contexts()[0];
* const page = defaultContext.pages()[0];
* ```
*
* @param endpointURL A CDP websocket endpoint or http url to connect to. For example `http://localhost:9222/` or
* `ws://127.0.0.1:9222/devtools/browser/387adf4c-243f-4051-a181-46798f4a46f4`.
* @param options
*/
connectOverCDP(
transport: ConnectOverCDPTransport,
options?: ConnectOverCDPOptions,
): Promise<Browser>
/**
* Option `wsEndpoint` is deprecated. Instead use `endpointURL`.
* @deprecated
*/
/**
* This method attaches Playwright to an existing browser instance using the Chrome DevTools Protocol.
*
* The default browser context is accessible via
* [browser.contexts()](https://playwright.dev/docs/api/class-browser#browser-contexts).
*
* **NOTE** Connecting over the Chrome DevTools Protocol is only supported for Chromium-based browsers.
*
* **NOTE** This connection is significantly lower fidelity than the Playwright protocol connection via
* [browserType.connect(endpoint[, options])](https://playwright.dev/docs/api/class-browsertype#browser-type-connect).
* If you are experiencing issues or attempting to use advanced functionality, you probably want to use
* [browserType.connect(endpoint[, options])](https://playwright.dev/docs/api/class-browsertype#browser-type-connect).
*
* **NOTE** Playwright maintains a curated list of arguments for launching the browser. If you launch the browser
* without Playwright and do not pass the exact same arguments, some of Playwright functionality may be broken upon
* connecting to the browser.
*
* **Usage**
*
* ```js
* const browser = await playwright.chromium.connectOverCDP('http://localhost:9222');
* const defaultContext = browser.contexts()[0];
* const page = defaultContext.pages()[0];
* ```
*
* @param endpointURL A CDP websocket endpoint or http url to connect to. For example `http://localhost:9222/` or
* `ws://127.0.0.1:9222/devtools/browser/387adf4c-243f-4051-a181-46798f4a46f4`.
* @param options
*/
connectOverCDP(options: ConnectOverCDPOptions & { wsEndpoint?: string }): Promise<Browser>
/**
* This method attaches Playwright to an existing browser instance created via `BrowserType.launchServer` in Node.js.
*
* **NOTE** The major and minor version of the Playwright instance that connects needs to match the version of
* Playwright that launches the browser (1.2.3 → is compatible with 1.2.x).
*
* @param endpoint A Playwright browser websocket endpoint to connect to. You obtain this endpoint via `BrowserServer.wsEndpoint`.
* @param options
*/
connect(wsEndpoint: string, options?: ConnectOptions): Promise<Browser>
/**
* wsEndpoint in options is deprecated. Instead use `wsEndpoint`.
* @param wsEndpoint A browser websocket endpoint to connect to.
* @param options
* @deprecated
*/
/**
* This method attaches Playwright to an existing browser instance created via `BrowserType.launchServer` in Node.js.
*
* **NOTE** The major and minor version of the Playwright instance that connects needs to match the version of
* Playwright that launches the browser (1.2.3 → is compatible with 1.2.x).
*
* @param endpoint A Playwright browser websocket endpoint to connect to. You obtain this endpoint via `BrowserServer.wsEndpoint`.
* @param options
*/
connect(options: ConnectOptions & { wsEndpoint?: string }): Promise<Browser>
/**
* A path where Playwright expects to find a bundled browser executable.
*/
executablePath(): string
/**
* Returns the browser instance.
*
* **Usage**
*
* You can use
* [`ignoreDefaultArgs`](https://playwright.dev/docs/api/class-browsertype#browser-type-launch-option-ignore-default-args)
* to filter out `--mute-audio` from default arguments:
*
* ```js
* const browser = await chromium.launch({ // Or 'firefox' or 'webkit'.
* ignoreDefaultArgs: ['--mute-audio']
* });
* ```
*
* > **Chromium-only** Playwright can also be used to control the Google Chrome or Microsoft Edge browsers, but it
* works best with the version of Chromium it is bundled with. There is no guarantee it will work with any other
* version. Use
* [`executablePath`](https://playwright.dev/docs/api/class-browsertype#browser-type-launch-option-executable-path)
* option with extreme caution.
* >
* > If Google Chrome (rather than Chromium) is preferred, a
* [Chrome Canary](https://www.google.com/chrome/browser/canary.html) or
* [Dev Channel](https://www.chromium.org/getting-involved/dev-channel) build is suggested.
* >
* > Stock browsers like Google Chrome and Microsoft Edge are suitable for tests that require proprietary media codecs
* for video playback. See
* [this article](https://www.howtogeek.com/202825/what%E2%80%99s-the-difference-between-chromium-and-chrome/) for
* other differences between Chromium and Chrome.
* [This article](https://chromium.googlesource.com/chromium/src/+/lkgr/docs/chromium_browser_vs_google_chrome.md)
* describes some differences for Linux users.
* @param options
*/
launch(options?: LaunchOptions): Promise<Browser>
/**
* Returns the persistent browser context instance.
*
* Launches browser that uses persistent storage located at
* [`userDataDir`](https://playwright.dev/docs/api/class-browsertype#browser-type-launch-persistent-context-option-user-data-dir)
* and returns the only context. Closing this context will automatically close the browser.
* @param userDataDir Path to a User Data Directory, which stores browser session data like cookies and local storage. Pass an empty
* string to create a temporary directory.
*
* More details for
* [Chromium](https://chromium.googlesource.com/chromium/src/+/master/docs/user_data_dir.md#introduction) and
* [Firefox](https://wiki.mozilla.org/Firefox/CommandLineOptions#User_profile). Chromium's user data directory is the
* **parent** directory of the "Profile Path" seen at `chrome://version`.
*
* Note that browsers do not allow launching multiple instances with the same User Data Directory.
*
* **NOTE** Chromium/Chrome: Due to recent Chrome policy changes, automating the default Chrome user profile is not
* supported. Pointing `userDataDir` to Chrome's main "User Data" directory (the profile used for your regular
* browsing) may result in pages not loading or the browser exiting. Create and use a separate directory (for example,
* an empty folder) as your automation profile instead. See https://developer.chrome.com/blog/remote-debugging-port
* for details.
*
* @param options
*/
launchPersistentContext(
userDataDir: string,
options?: {
/**
* Whether to automatically download all the attachments. Defaults to `true` where all the downloads are accepted.
*/
acceptDownloads?: boolean
/**
* **NOTE** Use custom browser args at your own risk, as some of them may break Playwright functionality.
*
* 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/).
*/
args?: Array<string>
/**
* 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.
*/
artifactsDir?: string
/**
* When using [page.goto(url[, options])](https://playwright.dev/docs/api/class-page#page-goto),
* [page.route(url, handler[, options])](https://playwright.dev/docs/api/class-page#page-route),
* [page.waitForURL(url[, options])](https://playwright.dev/docs/api/class-page#page-wait-for-url),
* [page.waitForRequest(urlOrPredicate[, options])](https://playwright.dev/docs/api/class-page#page-wait-for-request),
* or
* [page.waitForResponse(urlOrPredicate[, options])](https://playwright.dev/docs/api/class-page#page-wait-for-response)
* it takes the base URL in consideration by using the
* [`URL()`](https://developer.mozilla.org/en-US/docs/Web/API/URL/URL) constructor for building the corresponding URL.
* Unset by default. Examples:
* - baseURL: `http://localhost:3000` and navigating to `/bar.html` results in `http://localhost:3000/bar.html`
* - baseURL: `http://localhost:3000/foo/` and navigating to `./bar.html` results in
* `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`
*/
baseURL?: string
/**
* Toggles bypassing page's Content-Security-Policy. Defaults to `false`.
*/
bypassCSP?: boolean
/**
* Browser distribution channel.
*
* Use "chromium" to [opt in to new headless mode](https://playwright.dev/docs/browsers#chromium-new-headless-mode).
*
* 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).
*/
channel?: string
/**
* Enable Chromium sandboxing. Defaults to `false`.
*/
chromiumSandbox?: boolean
/**
* TLS Client Authentication allows the server to request a client certificate and verify it.
*
* **Details**
*
* An array of client certificates to be used. Each certificate object must have either both `certPath` and `keyPath`,
* a single `pfxPath`, or their corresponding direct value equivalents (`cert` and `key`, or `pfx`). Optionally,
* `passphrase` property should be provided if the certificate is encrypted. The `origin` property should be provided
* with an exact match to the request origin that the certificate is valid for.
*
* Client certificate authentication is only active when at least one client certificate is provided. If you want to
* reject all client certificates sent by the server, you need to provide a client certificate with an `origin` that
* does not match any of the domains you plan to visit.
*
* **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<{
/**
* Exact origin that the certificate is valid for. Origin includes `https` protocol, a hostname and optionally a port.
*/
origin: string
/**
* Path to the file with the certificate in PEM format.
*/
certPath?: string
/**
* Direct value of the certificate in PEM format.
*/
cert?: Buffer
/**
* Path to the file with the private key in PEM format.
*/
keyPath?: string
/**
* Direct value of the private key in PEM format.
*/
key?: Buffer
/**
* Path to the PFX or PKCS12 encoded private key and certificate chain.
*/
pfxPath?: string
/**
* Direct value of the PFX or PKCS12 encoded private key and certificate chain.
*/
pfx?: Buffer
/**
* Passphrase for the private key (PEM or PFX).
*/
passphrase?: string
}>
/**
* Emulates [prefers-colors-scheme](https://developer.mozilla.org/en-US/docs/Web/CSS/@media/prefers-color-scheme)
* 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'`.
*/
colorScheme?: null | 'light' | 'dark' | 'no-preference'
/**
* 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'`.
*/
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).
*/
deviceScaleFactor?: number
/**
* 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.
*/
downloadsPath?: string
env?: { [key: string]: string | undefined }
/**
* Path to a browser executable to run instead of the bundled one. If
* [`executablePath`](https://playwright.dev/docs/api/class-browsertype#browser-type-launch-persistent-context-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.
*/
executablePath?: string
/**
* An object containing additional HTTP headers to be sent with every request. Defaults to none.
*/
extraHTTPHeaders?: { [key: string]: string }
/**
* Firefox user preferences. Learn more about the Firefox user preferences at
* [`about:config`](https://support.mozilla.org/en-US/kb/about-config-editor-firefox).
*
* 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.
*/
firefoxUserPrefs?: { [key: string]: string | number | boolean }
/**
* 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'`.
*/
forcedColors?: null | 'active' | 'none'
geolocation?: {
/**
* Latitude between -90 and 90.
*/
latitude: number
/**
* Longitude between -180 and 180.
*/
longitude: number
/**
* Non-negative accuracy value. Defaults to `0`.
*/
accuracy?: number
}
/**
* Close the browser process on SIGHUP. Defaults to `true`.
*/
handleSIGHUP?: boolean
/**
* Close the browser process on Ctrl-C. Defaults to `true`.
*/
handleSIGINT?: boolean
/**
* Close the browser process on SIGTERM. Defaults to `true`.
*/
handleSIGTERM?: boolean
/**
* Specifies if viewport supports touch events. Defaults to false. Learn more about
* [mobile emulation](https://playwright.dev/docs/emulation#devices).
*/
hasTouch?: boolean
/**
* 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`.
*/
headless?: 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.
*
* Pass an array to use different credentials for different origins. The first entry that matches the request origin
* is used, and entries with no origin match any request.
*/
httpCredentials?:
| {
username: string
password: string
/**
* Restrain sending http credentials on specific origin (scheme://host:port).
*/
origin?: string
/**
* This option only applies to the requests sent from corresponding
* [APIRequestContext](https://playwright.dev/docs/api/class-apirequestcontext) and does not affect requests sent from
* 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'`.
*/
send?: 'unauthorized' | 'always'
}
| Array<{
username: string
password: string
/**
* Restrain sending http credentials on specific origin (scheme://host:port).
*/
origin?: string
/**
* This option only applies to the requests sent from corresponding
* [APIRequestContext](https://playwright.dev/docs/api/class-apirequestcontext) and does not affect requests sent from
* 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'`.
*/
send?: 'unauthorized' | 'always'
}>
/**
* 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-persistent-context-option-args). If
* an array is given, then filters out the given default arguments. Dangerous option; use with care. Defaults to
* `false`.
*/
ignoreDefaultArgs?: boolean | Array<string>
/**
* Whether to ignore HTTPS errors when sending network requests. Defaults to `false`.
*/
ignoreHTTPSErrors?: boolean
/**
* 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).
*/
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).
*/
javaScriptEnabled?: boolean
/**
* 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).
*/
locale?: string
/**
* Logger sink for Playwright logging.
* @deprecated The logs received by the logger are incomplete. Please use tracing instead.
*/
logger?: Logger
/**
* Whether to emulate network being offline. Defaults to `false`. Learn more about
* [network emulation](https://playwright.dev/docs/emulation#offline).
*/
offline?: boolean
/**
* 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.
*/
permissions?: Array<string>
/**
* Network proxy settings.
*/
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.
*/
server: string
/**
* Optional comma-separated domains to bypass proxy, for example `".com, chromium.org, .domain.com"`.
*/
bypass?: string
/**
* Optional username to use if HTTP proxy requires authentication.
*/
username?: string
/**
* Optional password to use if HTTP proxy requires authentication.
*/
password?: string
}
/**
* Enables [HAR](http://www.softwareishard.com/blog/har-12-spec) recording for all pages into `recordHar.path` file.
* 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.
*/
recordHar?: {
/**
* Optional setting to control whether to omit request content from the HAR. Defaults to `false`. Deprecated, use
* `content` policy instead.
*/
omitContent?: boolean
/**
* Optional setting to control resource content management. If `omit` is specified, content is not persisted. If
* `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.
*/
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.
*/
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`.
*/
mode?: 'full' | 'minimal'
/**
* A glob or regex pattern to filter requests that are stored in the HAR. When a
* [`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.
*/
urlFilter?: string | RegExp
}
/**
* Enables video recording for all pages into `recordVideo.dir` directory. If not specified videos are not recorded.
* Make sure to await
* [browserContext.close([options])](https://playwright.dev/docs/api/class-browsercontext#browser-context-close) for
* videos to be saved.
*/
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).
*/
dir?: string
/**
* 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.
*/
size?: {
/**
* Video frame width.
*/
width: number
/**
* Video frame height.
*/
height: number
}
/**
* If specified, enables visual annotations on interacted elements during video recording.
*/
showActions?: {
/**
* How long each annotation is displayed in milliseconds. Defaults to `500`.
*/
duration?: number
/**
* Position of the action title overlay. Defaults to `"top-right"`.
*/
position?: 'top-left' | 'top' | 'top-right' | 'bottom-left' | 'bottom' | 'bottom-right'
/**
* Font size of the action title in pixels. Defaults to `24`.
*/
fontSize?: number
/**
* Cursor decoration shown for pointer actions. `"pointer"` (the default) renders a mouse pointer that animates from
* the previous action point to the next one. `"none"` disables the cursor decoration.
*/
cursor?: 'none' | 'pointer'
}
}
/**
* 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'`.
*/
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-browsertype#browser-type-launch-persistent-context-option-viewport)
* is set.
*/
screen?: {
/**
* page width in pixels.
*/
width: number
/**
* page height in pixels.
*/
height: number
}
/**
* Whether to allow sites to register Service workers. Defaults to `'allow'`.
* - `'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.
*/
serviceWorkers?: 'allow' | 'block'
/**
* Slows down Playwright operations by the specified amount of milliseconds. Useful so that you can see what is going
* on.
*/
slowMo?: number
/**
* If set to true, enables strict selectors mode for this context. In the strict selectors mode all operations on
* 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.
*/
strictSelectors?: boolean
/**
* Maximum time in milliseconds to wait for the browser instance to start. Defaults to `30000` (30 seconds). Pass `0`
* to disable timeout.
*/
timeout?: number
/**
* 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.
*/
timezoneId?: string
/**
* If specified, traces are saved into this directory.
*/
tracesDir?: string
/**
* Specific user agent to use in this context.
*/
userAgent?: string
/**
* 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.
*
*/
viewport?: null | {
/**
* page width in pixels.
*/
width: number
/**
* page height in pixels.
*/
height: number
}
},
): Promise<BrowserContext>
/**
* Returns the browser app instance. You can connect to it via
* [browserType.connect(endpoint[, options])](https://playwright.dev/docs/api/class-browsertype#browser-type-connect),
* which requires the major/minor client/server version to match (1.2.3 → is compatible with 1.2.x).
*
* **Usage**
*
* Launches browser server that client can connect to. An example of launching a browser executable and connecting to
* it later:
*
* ```js
* const { chromium } = require('playwright'); // Or 'webkit' or 'firefox'.
*
* (async () => {
* const browserServer = await chromium.launchServer();
* const wsEndpoint = browserServer.wsEndpoint();
* // Use web socket endpoint later to establish a connection.
* const browser = await chromium.connect(wsEndpoint);
* // Close browser instance.
* await browserServer.close();
* })();
* ```
*
* @param options
*/
launchServer(options?: {
/**
* **NOTE** Use custom browser args at your own risk, as some of them may break Playwright functionality.
*
* 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/).
*/
args?: Array<string>
/**
* 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.
*/
artifactsDir?: string
/**
* Browser distribution channel.
*
* Use "chromium" to [opt in to new headless mode](https://playwright.dev/docs/browsers#chromium-new-headless-mode).
*
* 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).
*/
channel?: string
/**
* Enable Chromium sandboxing. Defaults to `false`.
*/
chromiumSandbox?: boolean
/**
* 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.
*/
downloadsPath?: string
env?: { [key: string]: string | undefined }
/**
* Path to a browser executable to run instead of the bundled one. If
* [`executablePath`](https://playwright.dev/docs/api/class-browsertype#browser-type-launch-server-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.
*/
executablePath?: string
/**
* Firefox user preferences. Learn more about the Firefox user preferences at
* [`about:config`](https://support.mozilla.org/en-US/kb/about-config-editor-firefox).
*
* 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.
*/
firefoxUserPrefs?: { [key: string]: string | number | boolean }
/**
* Close the browser process on SIGHUP. Defaults to `true`.
*/
handleSIGHUP?: boolean
/**
* Close the browser process on Ctrl-C. Defaults to `true`.
*/
handleSIGINT?: boolean
/**
* Close the browser process on SIGTERM. Defaults to `true`.
*/
handleSIGTERM?: boolean
/**
* 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`.
*/
headless?: boolean
/**
* Host to use for the web socket. It is optional and defaults to `localhost`, accepting connections only from the
* loopback interface. Pass an explicit address (e.g. `0.0.0.0`) to accept connections from the network — be aware
* this exposes the browser RPC to anything that can reach the listening port.
*/
host?: string
/**
* 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-server-option-args). If an array is
* given, then filters out the given default arguments. Dangerous option; use with care. Defaults to `false`.
*/
ignoreDefaultArgs?: boolean | Array<string>
/**
* Logger sink for Playwright logging.
* @deprecated The logs received by the logger are incomplete. Please use tracing instead.
*/
logger?: Logger
/**
* Port to use for the web socket. Defaults to 0 that picks any available port.
*/
port?: number
/**
* Network proxy settings.
*/
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.
*/
server: string
/**
* Optional comma-separated domains to bypass proxy, for example `".com, chromium.org, .domain.com"`.
*/
bypass?: string
/**
* Optional username to use if HTTP proxy requires authentication.
*/
username?: string
/**
* Optional password to use if HTTP proxy requires authentication.
*/
password?: string
}
/**
* Maximum time in milliseconds to wait for the browser instance to start. Defaults to `30000` (30 seconds). Pass `0`
* to disable timeout.
*/
timeout?: number
/**
* If specified, traces are saved into this directory.
*/
tracesDir?: string
/**
* 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.
*
*/
wsPath?: string
}): Promise<BrowserServer>
/**
* Returns browser name. For example: `'chromium'`, `'webkit'` or `'firefox'`.
*/
name(): string
}
ConsoleErrorEntry
One captured browser error.
interface ConsoleErrorEntry {
type: 'pageerror' | 'console.error'
text: string
location?: string
}
ConsoleGuardFixtures
The fixture object withConsoleGuard adds to a test.
interface ConsoleGuardFixtures {
consoleGuard: void
}
ConsoleMessage
ConsoleMessage objects are dispatched by page via the page.on('console') event. For each console message logged in the page there will be corresponding event in the Playwright context.
// Listen for all console logs
page.on('console', (msg) => console.log(msg.text()))
// Listen for all console events and handle errors
page.on('console', (msg) => {
if (msg.type() === 'error') console.log(`Error text: "${msg.text()}"`)
})
// Get the next console log
const msgPromise = page.waitForEvent('console')
await page.evaluate(() => {
console.log('hello', 42, { foo: 'bar' }) // Issue console.log inside the page
})
const msg = await msgPromise
// Deconstruct console log arguments
await msg.args()[0].jsonValue() // hello
await msg.args()[1].jsonValue() // 42
interface ConsoleMessage {
/**
* List of arguments passed to a `console` function call. See also
* [page.on('console')](https://playwright.dev/docs/api/class-page#page-event-console).
*/
args(): Array<JSHandle>
location(): {
/**
* URL of the resource.
*/
url: string
/**
* 0-based line number in the resource.
*/
line: number
/**
* 0-based column number in the resource.
*/
column: number
/**
* 0-based line number in the resource. Deprecated, use `line` instead.
*/
lineNumber: number
/**
* 0-based column number in the resource. Deprecated, use `column` instead.
*/
columnNumber: number
}
/**
* The page that produced this console message, if any.
*/
page(): null | Page
/**
* The text of the console message.
*/
text(): string
/**
* The timestamp of the console message in milliseconds since the Unix epoch.
*/
timestamp(): number
type():
| 'log'
| 'debug'
| 'info'
| 'error'
| 'warning'
| 'dir'
| 'dirxml'
| 'table'
| 'trace'
| 'clear'
| 'startGroup'
| 'startGroupCollapsed'
| 'endGroup'
| 'assert'
| 'profile'
| 'profileEnd'
| 'count'
| 'time'
| 'timeEnd'
/**
* The web worker or service worker that produced this console message, if any. Note that console messages from web
* workers also have non-null
* [consoleMessage.page()](https://playwright.dev/docs/api/class-consolemessage#console-message-page).
*/
worker(): null | Worker
}
Dialog
Dialog objects are dispatched by page via the page.on('dialog') event.
An example of using Dialog class:
const { chromium } = require('playwright') // Or 'firefox' or 'webkit'.
;(async () => {
const browser = await chromium.launch()
const page = await browser.newPage()
page.on('dialog', async (dialog) => {
console.log(dialog.message())
await dialog.dismiss()
})
await page.evaluate(() => alert('1'))
await browser.close()
})()
NOTE Dialogs are dismissed automatically, unless there is a page.on('dialog') listener. When listener is present, it must either dialog.accept([promptText]) or dialog.dismiss() the dialog - otherwise the page will freeze waiting for the dialog, and actions like click will never finish.
interface Dialog {
/**
* Returns when the dialog has been accepted.
* @param promptText A text to enter in prompt. Does not cause any effects if the dialog's `type` is not prompt. Optional.
*/
accept(promptText?: string): Promise<void>
/**
* If dialog is prompt, returns default prompt value. Otherwise, returns empty string.
*/
defaultValue(): string
/**
* Returns when the dialog has been dismissed.
*/
dismiss(): Promise<void>
/**
* A message displayed in the dialog.
*/
message(): string
/**
* The page that initiated this dialog, if available.
*/
page(): null | Page
/**
* Returns dialog's type, can be one of `alert`, `beforeunload`, `confirm` or `prompt`.
*/
type(): string
}
Download
Download objects are dispatched by page via the page.on('download') event.
All the downloaded files belonging to the browser context are deleted when the browser context is closed.
Download event is emitted once the download starts. Download path becomes available once download completes.
// Start waiting for download before clicking. Note no await.
const downloadPromise = page.waitForEvent('download')
await page.getByText('Download file').click()
const download = await downloadPromise
// Wait for the download process to complete and save the downloaded file somewhere.
await download.saveAs('/path/to/save/at/' + download.suggestedFilename())
interface Download {
/**
* Cancels a download. Will not fail if the download is already finished or canceled. Upon successful cancellations,
* `download.failure()` would resolve to `'canceled'`.
*/
cancel(): Promise<void>
/**
* Returns a readable stream for a successful download, or throws for a failed/canceled download.
*
* **NOTE** If you don't need a readable stream, it's usually simpler to read the file from disk after the download
* completed. See [download.path()](https://playwright.dev/docs/api/class-download#download-path).
*
*/
createReadStream(): Promise<Readable>
/**
* Deletes the downloaded file. Will wait for the download to finish if necessary.
*/
delete(): Promise<void>
/**
* Returns download error if any. Will wait for the download to finish if necessary.
*/
failure(): Promise<null | string>
/**
* Get the page that the download belongs to.
*/
page(): Page
/**
* Returns path to the downloaded file for a successful download, or throws for a failed/canceled download. The method
* will wait for the download to finish if necessary. The method throws when connected remotely.
*
* Note that the download's file name is a random GUID, use
* [download.suggestedFilename()](https://playwright.dev/docs/api/class-download#download-suggested-filename) to get
* suggested file name.
*/
path(): Promise<string>
/**
* Copy the download to a user-specified path. It is safe to call this method while the download is still in progress.
* Will wait for the download to finish if necessary.
*
* **Usage**
*
* ```js
* await download.saveAs('/path/to/save/at/' + download.suggestedFilename());
* ```
*
* @param path Path where the download should be copied.
*/
saveAs(path: string): Promise<void>
/**
* Returns suggested filename for this download. It is typically computed by the browser from the
* [`Content-Disposition`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Disposition) response
* header or the `download` attribute. See the spec on [whatwg](https://html.spec.whatwg.org/#downloading-resources).
* Different browsers can use different logic for computing it.
*/
suggestedFilename(): string
/**
* Returns downloaded url.
*/
url(): string
}
ElementHandle
- extends: JSHandle
ElementHandle represents an in-page DOM element. ElementHandles can be created with the page.$(selector[, options]) method.
NOTE The use of ElementHandle is discouraged, use Locator objects and web-first assertions instead.
const hrefElement = await page.$('a')
await hrefElement.click()
ElementHandle prevents DOM element from garbage collection unless the handle is disposed with jsHandle.dispose(). ElementHandles are auto-disposed when their origin frame gets navigated.
ElementHandle instances can be used as an argument in page.$eval(selector, pageFunction[, arg, options]) and page.evaluate(pageFunction[, arg, options]) methods.
The difference between the Locator and ElementHandle is that the ElementHandle points to a particular element, while Locator captures the logic of how to retrieve an element.
In the example below, handle points to a particular DOM element on page. If that element changes text or is used by React to render an entirely different component, handle is still pointing to that very DOM element. This can lead to unexpected behaviors.
const handle = await page.$('text=Submit')
// ...
await handle.hover()
await handle.click()
With the locator, every time the element is used, up-to-date DOM element is located in the page using the
selector. So in the snippet below, underlying DOM element is going to be located twice.
const locator = page.getByText('Submit')
// ...
await locator.hover()
await locator.click()
interface ElementHandle<T = Node> extends JSHandle<T> {
/**
* **NOTE** Use locator-based [page.locator(selector[, options])](https://playwright.dev/docs/api/class-page#page-locator)
* instead. Read more about [locators](https://playwright.dev/docs/locators).
*
* The method finds an element matching the specified selector in the `ElementHandle`'s subtree. If no elements match
* the selector, returns `null`.
* @param selector A selector to query for.
*/
$<K extends keyof HTMLElementTagNameMap>(
selector: K,
options?: { strict: boolean },
): Promise<ElementHandleForTag<K> | null>
/**
* **NOTE** Use locator-based [page.locator(selector[, options])](https://playwright.dev/docs/api/class-page#page-locator)
* instead. Read more about [locators](https://playwright.dev/docs/locators).
*
* The method finds an element matching the specified selector in the `ElementHandle`'s subtree. If no elements match
* the selector, returns `null`.
* @param selector A selector to query for.
*/
$(
selector: string,
options?: { strict: boolean },
): Promise<ElementHandle<SVGElement | HTMLElement> | null>
/**
* **NOTE** Use locator-based [page.locator(selector[, options])](https://playwright.dev/docs/api/class-page#page-locator)
* instead. Read more about [locators](https://playwright.dev/docs/locators).
*
* The method finds all elements matching the specified selector in the `ElementHandle`s subtree. If no elements match
* the selector, returns empty array.
* @param selector A selector to query for.
*/
$$<K extends keyof HTMLElementTagNameMap>(selector: K): Promise<ElementHandleForTag<K>[]>
/**
* **NOTE** Use locator-based [page.locator(selector[, options])](https://playwright.dev/docs/api/class-page#page-locator)
* instead. Read more about [locators](https://playwright.dev/docs/locators).
*
* The method finds all elements matching the specified selector in the `ElementHandle`s subtree. If no elements match
* the selector, returns empty array.
* @param selector A selector to query for.
*/
$$(selector: string): Promise<ElementHandle<SVGElement | HTMLElement>[]>
/**
* **NOTE** This method does not wait for the element to pass actionability checks and therefore can lead to the flaky tests.
* Use
* [locator.evaluate(pageFunction[, arg, options])](https://playwright.dev/docs/api/class-locator#locator-evaluate),
* other [Locator](https://playwright.dev/docs/api/class-locator) helper methods or web-first assertions instead.
*
* Returns the return value of
* [`pageFunction`](https://playwright.dev/docs/api/class-elementhandle#element-handle-eval-on-selector-option-expression).
*
* The method finds an element matching the specified selector in the `ElementHandle`s subtree and passes it as a
* first argument to
* [`pageFunction`](https://playwright.dev/docs/api/class-elementhandle#element-handle-eval-on-selector-option-expression).
* If no elements match the selector, the method throws an error.
*
* If
* [`pageFunction`](https://playwright.dev/docs/api/class-elementhandle#element-handle-eval-on-selector-option-expression)
* returns a [Promise], then
* [elementHandle.$eval(selector, pageFunction[, arg])](https://playwright.dev/docs/api/class-elementhandle#element-handle-eval-on-selector)
* would wait for the promise to resolve and return its value.
*
* **Usage**
*
* ```js
* const tweetHandle = await page.$('.tweet');
* expect(await tweetHandle.$eval('.like', node => node.innerText)).toBe('100');
* expect(await tweetHandle.$eval('.retweets', node => node.innerText)).toBe('10');
* ```
*
* @param selector A selector to query for.
* @param pageFunction Function to be evaluated in the page context.
* @param arg Optional argument to pass to
* [`pageFunction`](https://playwright.dev/docs/api/class-elementhandle#element-handle-eval-on-selector-option-expression).
*/
$eval<K extends keyof HTMLElementTagNameMap, R, Arg>(
selector: K,
pageFunction: PageFunctionOn<HTMLElementTagNameMap[K], Arg, R>,
arg: Arg,
): Promise<R>
/**
* **NOTE** This method does not wait for the element to pass actionability checks and therefore can lead to the flaky tests.
* Use
* [locator.evaluate(pageFunction[, arg, options])](https://playwright.dev/docs/api/class-locator#locator-evaluate),
* other [Locator](https://playwright.dev/docs/api/class-locator) helper methods or web-first assertions instead.
*
* Returns the return value of
* [`pageFunction`](https://playwright.dev/docs/api/class-elementhandle#element-handle-eval-on-selector-option-expression).
*
* The method finds an element matching the specified selector in the `ElementHandle`s subtree and passes it as a
* first argument to
* [`pageFunction`](https://playwright.dev/docs/api/class-elementhandle#element-handle-eval-on-selector-option-expression).
* If no elements match the selector, the method throws an error.
*
* If
* [`pageFunction`](https://playwright.dev/docs/api/class-elementhandle#element-handle-eval-on-selector-option-expression)
* returns a [Promise], then
* [elementHandle.$eval(selector, pageFunction[, arg])](https://playwright.dev/docs/api/class-elementhandle#element-handle-eval-on-selector)
* would wait for the promise to resolve and return its value.
*
* **Usage**
*
* ```js
* const tweetHandle = await page.$('.tweet');
* expect(await tweetHandle.$eval('.like', node => node.innerText)).toBe('100');
* expect(await tweetHandle.$eval('.retweets', node => node.innerText)).toBe('10');
* ```
*
* @param selector A selector to query for.
* @param pageFunction Function to be evaluated in the page context.
* @param arg Optional argument to pass to
* [`pageFunction`](https://playwright.dev/docs/api/class-elementhandle#element-handle-eval-on-selector-option-expression).
*/
$eval<R, Arg, E extends SVGElement | HTMLElement = SVGElement | HTMLElement>(
selector: string,
pageFunction: PageFunctionOn<E, Arg, R>,
arg: Arg,
): Promise<R>
/**
* **NOTE** This method does not wait for the element to pass actionability checks and therefore can lead to the flaky tests.
* Use
* [locator.evaluate(pageFunction[, arg, options])](https://playwright.dev/docs/api/class-locator#locator-evaluate),
* other [Locator](https://playwright.dev/docs/api/class-locator) helper methods or web-first assertions instead.
*
* Returns the return value of
* [`pageFunction`](https://playwright.dev/docs/api/class-elementhandle#element-handle-eval-on-selector-option-expression).
*
* The method finds an element matching the specified selector in the `ElementHandle`s subtree and passes it as a
* first argument to
* [`pageFunction`](https://playwright.dev/docs/api/class-elementhandle#element-handle-eval-on-selector-option-expression).
* If no elements match the selector, the method throws an error.
*
* If
* [`pageFunction`](https://playwright.dev/docs/api/class-elementhandle#element-handle-eval-on-selector-option-expression)
* returns a [Promise], then
* [elementHandle.$eval(selector, pageFunction[, arg])](https://playwright.dev/docs/api/class-elementhandle#element-handle-eval-on-selector)
* would wait for the promise to resolve and return its value.
*
* **Usage**
*
* ```js
* const tweetHandle = await page.$('.tweet');
* expect(await tweetHandle.$eval('.like', node => node.innerText)).toBe('100');
* expect(await tweetHandle.$eval('.retweets', node => node.innerText)).toBe('10');
* ```
*
* @param selector A selector to query for.
* @param pageFunction Function to be evaluated in the page context.
* @param arg Optional argument to pass to
* [`pageFunction`](https://playwright.dev/docs/api/class-elementhandle#element-handle-eval-on-selector-option-expression).
*/
$eval<K extends keyof HTMLElementTagNameMap, R>(
selector: K,
pageFunction: PageFunctionOn<HTMLElementTagNameMap[K], void, R>,
arg?: any,
): Promise<R>
/**
* **NOTE** This method does not wait for the element to pass actionability checks and therefore can lead to the flaky tests.
* Use
* [locator.evaluate(pageFunction[, arg, options])](https://playwright.dev/docs/api/class-locator#locator-evaluate),
* other [Locator](https://playwright.dev/docs/api/class-locator) helper methods or web-first assertions instead.
*
* Returns the return value of
* [`pageFunction`](https://playwright.dev/docs/api/class-elementhandle#element-handle-eval-on-selector-option-expression).
*
* The method finds an element matching the specified selector in the `ElementHandle`s subtree and passes it as a
* first argument to
* [`pageFunction`](https://playwright.dev/docs/api/class-elementhandle#element-handle-eval-on-selector-option-expression).
* If no elements match the selector, the method throws an error.
*
* If
* [`pageFunction`](https://playwright.dev/docs/api/class-elementhandle#element-handle-eval-on-selector-option-expression)
* returns a [Promise], then
* [elementHandle.$eval(selector, pageFunction[, arg])](https://playwright.dev/docs/api/class-elementhandle#element-handle-eval-on-selector)
* would wait for the promise to resolve and return its value.
*
* **Usage**
*
* ```js
* const tweetHandle = await page.$('.tweet');
* expect(await tweetHandle.$eval('.like', node => node.innerText)).toBe('100');
* expect(await tweetHandle.$eval('.retweets', node => node.innerText)).toBe('10');
* ```
*
* @param selector A selector to query for.
* @param pageFunction Function to be evaluated in the page context.
* @param arg Optional argument to pass to
* [`pageFunction`](https://playwright.dev/docs/api/class-elementhandle#element-handle-eval-on-selector-option-expression).
*/
$eval<R, E extends SVGElement | HTMLElement = SVGElement | HTMLElement>(
selector: string,
pageFunction: PageFunctionOn<E, void, R>,
arg?: any,
): Promise<R>
/**
* **NOTE** In most cases,
* [locator.evaluateAll(pageFunction[, arg])](https://playwright.dev/docs/api/class-locator#locator-evaluate-all),
* other [Locator](https://playwright.dev/docs/api/class-locator) helper methods and web-first assertions do a better
* job.
*
* Returns the return value of
* [`pageFunction`](https://playwright.dev/docs/api/class-elementhandle#element-handle-eval-on-selector-all-option-expression).
*
* The method finds all elements matching the specified selector in the `ElementHandle`'s subtree and passes an array
* of matched elements as a first argument to
* [`pageFunction`](https://playwright.dev/docs/api/class-elementhandle#element-handle-eval-on-selector-all-option-expression).
*
* If
* [`pageFunction`](https://playwright.dev/docs/api/class-elementhandle#element-handle-eval-on-selector-all-option-expression)
* returns a [Promise], then
* [elementHandle.$$eval(selector, pageFunction[, arg])](https://playwright.dev/docs/api/class-elementhandle#element-handle-eval-on-selector-all)
* would wait for the promise to resolve and return its value.
*
* **Usage**
*
* ```html
* <div class="feed">
* <div class="tweet">Hello!</div>
* <div class="tweet">Hi!</div>
* </div>
* ```
*
* ```js
* const feedHandle = await page.$('.feed');
* expect(await feedHandle.$$eval('.tweet', nodes =>
* nodes.map(n => n.innerText))).toEqual(['Hello!', 'Hi!'],
* );
* ```
*
* @param selector A selector to query for.
* @param pageFunction Function to be evaluated in the page context.
* @param arg Optional argument to pass to
* [`pageFunction`](https://playwright.dev/docs/api/class-elementhandle#element-handle-eval-on-selector-all-option-expression).
*/
$$eval<K extends keyof HTMLElementTagNameMap, R, Arg>(
selector: K,
pageFunction: PageFunctionOn<HTMLElementTagNameMap[K][], Arg, R>,
arg: Arg,
): Promise<R>
/**
* **NOTE** In most cases,
* [locator.evaluateAll(pageFunction[, arg])](https://playwright.dev/docs/api/class-locator#locator-evaluate-all),
* other [Locator](https://playwright.dev/docs/api/class-locator) helper methods and web-first assertions do a better
* job.
*
* Returns the return value of
* [`pageFunction`](https://playwright.dev/docs/api/class-elementhandle#element-handle-eval-on-selector-all-option-expression).
*
* The method finds all elements matching the specified selector in the `ElementHandle`'s subtree and passes an array
* of matched elements as a first argument to
* [`pageFunction`](https://playwright.dev/docs/api/class-elementhandle#element-handle-eval-on-selector-all-option-expression).
*
* If
* [`pageFunction`](https://playwright.dev/docs/api/class-elementhandle#element-handle-eval-on-selector-all-option-expression)
* returns a [Promise], then
* [elementHandle.$$eval(selector, pageFunction[, arg])](https://playwright.dev/docs/api/class-elementhandle#element-handle-eval-on-selector-all)
* would wait for the promise to resolve and return its value.
*
* **Usage**
*
* ```html
* <div class="feed">
* <div class="tweet">Hello!</div>
* <div class="tweet">Hi!</div>
* </div>
* ```
*
* ```js
* const feedHandle = await page.$('.feed');
* expect(await feedHandle.$$eval('.tweet', nodes =>
* nodes.map(n => n.innerText))).toEqual(['Hello!', 'Hi!'],
* );
* ```
*
* @param selector A selector to query for.
* @param pageFunction Function to be evaluated in the page context.
* @param arg Optional argument to pass to
* [`pageFunction`](https://playwright.dev/docs/api/class-elementhandle#element-handle-eval-on-selector-all-option-expression).
*/
$$eval<R, Arg, E extends SVGElement | HTMLElement = SVGElement | HTMLElement>(
selector: string,
pageFunction: PageFunctionOn<E[], Arg, R>,
arg: Arg,
): Promise<R>
/**
* **NOTE** In most cases,
* [locator.evaluateAll(pageFunction[, arg])](https://playwright.dev/docs/api/class-locator#locator-evaluate-all),
* other [Locator](https://playwright.dev/docs/api/class-locator) helper methods and web-first assertions do a better
* job.
*
* Returns the return value of
* [`pageFunction`](https://playwright.dev/docs/api/class-elementhandle#element-handle-eval-on-selector-all-option-expression).
*
* The method finds all elements matching the specified selector in the `ElementHandle`'s subtree and passes an array
* of matched elements as a first argument to
* [`pageFunction`](https://playwright.dev/docs/api/class-elementhandle#element-handle-eval-on-selector-all-option-expression).
*
* If
* [`pageFunction`](https://playwright.dev/docs/api/class-elementhandle#element-handle-eval-on-selector-all-option-expression)
* returns a [Promise], then
* [elementHandle.$$eval(selector, pageFunction[, arg])](https://playwright.dev/docs/api/class-elementhandle#element-handle-eval-on-selector-all)
* would wait for the promise to resolve and return its value.
*
* **Usage**
*
* ```html
* <div class="feed">
* <div class="tweet">Hello!</div>
* <div class="tweet">Hi!</div>
* </div>
* ```
*
* ```js
* const feedHandle = await page.$('.feed');
* expect(await feedHandle.$$eval('.tweet', nodes =>
* nodes.map(n => n.innerText))).toEqual(['Hello!', 'Hi!'],
* );
* ```
*
* @param selector A selector to query for.
* @param pageFunction Function to be evaluated in the page context.
* @param arg Optional argument to pass to
* [`pageFunction`](https://playwright.dev/docs/api/class-elementhandle#element-handle-eval-on-selector-all-option-expression).
*/
$$eval<K extends keyof HTMLElementTagNameMap, R>(
selector: K,
pageFunction: PageFunctionOn<HTMLElementTagNameMap[K][], void, R>,
arg?: any,
): Promise<R>
/**
* **NOTE** In most cases,
* [locator.evaluateAll(pageFunction[, arg])](https://playwright.dev/docs/api/class-locator#locator-evaluate-all),
* other [Locator](https://playwright.dev/docs/api/class-locator) helper methods and web-first assertions do a better
* job.
*
* Returns the return value of
* [`pageFunction`](https://playwright.dev/docs/api/class-elementhandle#element-handle-eval-on-selector-all-option-expression).
*
* The method finds all elements matching the specified selector in the `ElementHandle`'s subtree and passes an array
* of matched elements as a first argument to
* [`pageFunction`](https://playwright.dev/docs/api/class-elementhandle#element-handle-eval-on-selector-all-option-expression).
*
* If
* [`pageFunction`](https://playwright.dev/docs/api/class-elementhandle#element-handle-eval-on-selector-all-option-expression)
* returns a [Promise], then
* [elementHandle.$$eval(selector, pageFunction[, arg])](https://playwright.dev/docs/api/class-elementhandle#element-handle-eval-on-selector-all)
* would wait for the promise to resolve and return its value.
*
* **Usage**
*
* ```html
* <div class="feed">
* <div class="tweet">Hello!</div>
* <div class="tweet">Hi!</div>
* </div>
* ```
*
* ```js
* const feedHandle = await page.$('.feed');
* expect(await feedHandle.$$eval('.tweet', nodes =>
* nodes.map(n => n.innerText))).toEqual(['Hello!', 'Hi!'],
* );
* ```
*
* @param selector A selector to query for.
* @param pageFunction Function to be evaluated in the page context.
* @param arg Optional argument to pass to
* [`pageFunction`](https://playwright.dev/docs/api/class-elementhandle#element-handle-eval-on-selector-all-option-expression).
*/
$$eval<R, E extends SVGElement | HTMLElement = SVGElement | HTMLElement>(
selector: string,
pageFunction: PageFunctionOn<E[], void, R>,
arg?: any,
): Promise<R>
/**
* **NOTE** Use web assertions that assert visibility or a locator-based
* [locator.waitFor([options])](https://playwright.dev/docs/api/class-locator#locator-wait-for) instead.
*
* Returns element specified by selector when it satisfies
* [`state`](https://playwright.dev/docs/api/class-elementhandle#element-handle-wait-for-selector-option-state)
* option. Returns `null` if waiting for `hidden` or `detached`.
*
* Wait for the
* [`selector`](https://playwright.dev/docs/api/class-elementhandle#element-handle-wait-for-selector-option-selector)
* relative to the element handle to satisfy
* [`state`](https://playwright.dev/docs/api/class-elementhandle#element-handle-wait-for-selector-option-state) option
* (either appear/disappear from dom, or become visible/hidden). If at the moment of calling the method
* [`selector`](https://playwright.dev/docs/api/class-elementhandle#element-handle-wait-for-selector-option-selector)
* already satisfies the condition, the method will return immediately. If the selector doesn't satisfy the condition
* for the
* [`timeout`](https://playwright.dev/docs/api/class-elementhandle#element-handle-wait-for-selector-option-timeout)
* milliseconds, the function will throw.
*
* **Usage**
*
* ```js
* await page.setContent(`<div><span></span></div>`);
* const div = await page.$('div');
* // Waiting for the 'span' selector relative to the div.
* const span = await div.waitForSelector('span', { state: 'attached' });
* ```
*
* **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
*/
waitForSelector<K extends keyof HTMLElementTagNameMap>(
selector: K,
options?: ElementHandleWaitForSelectorOptionsNotHidden,
): Promise<ElementHandleForTag<K>>
/**
* **NOTE** Use web assertions that assert visibility or a locator-based
* [locator.waitFor([options])](https://playwright.dev/docs/api/class-locator#locator-wait-for) instead.
*
* Returns element specified by selector when it satisfies
* [`state`](https://playwright.dev/docs/api/class-elementhandle#element-handle-wait-for-selector-option-state)
* option. Returns `null` if waiting for `hidden` or `detached`.
*
* Wait for the
* [`selector`](https://playwright.dev/docs/api/class-elementhandle#element-handle-wait-for-selector-option-selector)
* relative to the element handle to satisfy
* [`state`](https://playwright.dev/docs/api/class-elementhandle#element-handle-wait-for-selector-option-state) option
* (either appear/disappear from dom, or become visible/hidden). If at the moment of calling the method
* [`selector`](https://playwright.dev/docs/api/class-elementhandle#element-handle-wait-for-selector-option-selector)
* already satisfies the condition, the method will return immediately. If the selector doesn't satisfy the condition
* for the
* [`timeout`](https://playwright.dev/docs/api/class-elementhandle#element-handle-wait-for-selector-option-timeout)
* milliseconds, the function will throw.
*
* **Usage**
*
* ```js
* await page.setContent(`<div><span></span></div>`);
* const div = await page.$('div');
* // Waiting for the 'span' selector relative to the div.
* const span = await div.waitForSelector('span', { state: 'attached' });
* ```
*
* **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
*/
waitForSelector(
selector: string,
options?: ElementHandleWaitForSelectorOptionsNotHidden,
): Promise<ElementHandle<SVGElement | HTMLElement>>
/**
* **NOTE** Use web assertions that assert visibility or a locator-based
* [locator.waitFor([options])](https://playwright.dev/docs/api/class-locator#locator-wait-for) instead.
*
* Returns element specified by selector when it satisfies
* [`state`](https://playwright.dev/docs/api/class-elementhandle#element-handle-wait-for-selector-option-state)
* option. Returns `null` if waiting for `hidden` or `detached`.
*
* Wait for the
* [`selector`](https://playwright.dev/docs/api/class-elementhandle#element-handle-wait-for-selector-option-selector)
* relative to the element handle to satisfy
* [`state`](https://playwright.dev/docs/api/class-elementhandle#element-handle-wait-for-selector-option-state) option
* (either appear/disappear from dom, or become visible/hidden). If at the moment of calling the method
* [`selector`](https://playwright.dev/docs/api/class-elementhandle#element-handle-wait-for-selector-option-selector)
* already satisfies the condition, the method will return immediately. If the selector doesn't satisfy the condition
* for the
* [`timeout`](https://playwright.dev/docs/api/class-elementhandle#element-handle-wait-for-selector-option-timeout)
* milliseconds, the function will throw.
*
* **Usage**
*
* ```js
* await page.setContent(`<div><span></span></div>`);
* const div = await page.$('div');
* // Waiting for the 'span' selector relative to the div.
* const span = await div.waitForSelector('span', { state: 'attached' });
* ```
*
* **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
*/
waitForSelector<K extends keyof HTMLElementTagNameMap>(
selector: K,
options: ElementHandleWaitForSelectorOptions,
): Promise<ElementHandleForTag<K> | null>
/**
* **NOTE** Use web assertions that assert visibility or a locator-based
* [locator.waitFor([options])](https://playwright.dev/docs/api/class-locator#locator-wait-for) instead.
*
* Returns element specified by selector when it satisfies
* [`state`](https://playwright.dev/docs/api/class-elementhandle#element-handle-wait-for-selector-option-state)
* option. Returns `null` if waiting for `hidden` or `detached`.
*
* Wait for the
* [`selector`](https://playwright.dev/docs/api/class-elementhandle#element-handle-wait-for-selector-option-selector)
* relative to the element handle to satisfy
* [`state`](https://playwright.dev/docs/api/class-elementhandle#element-handle-wait-for-selector-option-state) option
* (either appear/disappear from dom, or become visible/hidden). If at the moment of calling the method
* [`selector`](https://playwright.dev/docs/api/class-elementhandle#element-handle-wait-for-selector-option-selector)
* already satisfies the condition, the method will return immediately. If the selector doesn't satisfy the condition
* for the
* [`timeout`](https://playwright.dev/docs/api/class-elementhandle#element-handle-wait-for-selector-option-timeout)
* milliseconds, the function will throw.
*
* **Usage**
*
* ```js
* await page.setContent(`<div><span></span></div>`);
* const div = await page.$('div');
* // Waiting for the 'span' selector relative to the div.
* const span = await div.waitForSelector('span', { state: 'attached' });
* ```
*
* **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
*/
waitForSelector(
selector: string,
options: ElementHandleWaitForSelectorOptions,
): Promise<null | ElementHandle<SVGElement | HTMLElement>>
/**
* This method returns the bounding box of the element, or `null` if the element is not visible. The bounding box is
* calculated relative to the main frame viewport - which is usually the same as the browser window.
*
* Scrolling affects the returned bounding box, similarly to
* [Element.getBoundingClientRect](https://developer.mozilla.org/en-US/docs/Web/API/Element/getBoundingClientRect).
* That means `x` and/or `y` may be negative.
*
* Elements from child frames return the bounding box relative to the main frame, unlike the
* [Element.getBoundingClientRect](https://developer.mozilla.org/en-US/docs/Web/API/Element/getBoundingClientRect).
*
* Assuming the page is static, it is safe to use bounding box coordinates to perform input. For example, the
* following snippet should click the center of the element.
*
* **Usage**
*
* ```js
* const box = await elementHandle.boundingBox();
* await page.mouse.click(box.x + box.width / 2, box.y + box.height / 2);
* ```
*
*/
boundingBox(): Promise<null | {
/**
* the x coordinate of the element in pixels.
*/
x: number
/**
* the y coordinate of the element in pixels.
*/
y: number
/**
* the width of the element in pixels.
*/
width: number
/**
* the height of the element in pixels.
*/
height: number
}>
/**
* **NOTE** Use locator-based [locator.check([options])](https://playwright.dev/docs/api/class-locator#locator-check) instead.
* Read more about [locators](https://playwright.dev/docs/locators).
*
* This method checks the element by performing the following steps:
* 1. Ensure that element is a checkbox or a radio input. If not, this method throws. If the element is already
* checked, this method returns immediately.
* 1. Wait for [actionability](https://playwright.dev/docs/actionability) checks on the element, unless
* [`force`](https://playwright.dev/docs/api/class-elementhandle#element-handle-check-option-force) option is
* set.
* 1. Scroll the element into view if needed.
* 1. Use [page.mouse](https://playwright.dev/docs/api/class-page#page-mouse) to click in the center of the
* element.
* 1. Ensure that the element is now checked. If not, this method throws.
*
* If the element is detached from the DOM at any moment during the action, this method throws.
*
* When all steps combined have not finished during the specified
* [`timeout`](https://playwright.dev/docs/api/class-elementhandle#element-handle-check-option-timeout), this method
* throws a [TimeoutError](https://playwright.dev/docs/api/class-timeouterror). Passing zero timeout disables this.
* @param options
*/
check(options?: {
/**
* Whether to bypass the [actionability](https://playwright.dev/docs/actionability) checks. Defaults to `false`.
*/
force?: boolean
/**
* This option has no effect.
* @deprecated This option has no effect.
*/
noWaitAfter?: boolean
/**
* A point to use relative to the top-left corner of element padding box. If not specified, uses some visible point of
* the element.
*/
position?: {
x: number
y: number
}
/**
* Controls whether Playwright scrolls the element into view before performing the action. Defaults to `"auto"`, which
* scrolls the element into view when necessary, including scrolling nested scrollable containers. When set to
* `"none"`, Playwright does not scroll the element and the action fails if the element is not already in the
* viewport. This is useful to assert that an element is reachable by the user without additional scrolling.
*/
scroll?: 'auto' | 'none'
/**
* Allows to cancel the operation using an
* [`AbortSignal`](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal). If the signal is aborted, the
* operation will be aborted and throw an error. Note that providing a signal does not disable the default timeout,
* which can be changed using
* [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); pass
* `timeout: 0` to disable the timeout entirely.
*/
signal?: AbortSignal
/**
* Maximum time in milliseconds. Defaults to `0` - no timeout. The default value can be changed via `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.
*/
timeout?: number
/**
* When set, this method only performs the [actionability](https://playwright.dev/docs/actionability) checks and skips the action. Defaults
* to `false`. Useful to wait until the element is ready for the action without performing it.
*/
trial?: boolean
}): Promise<void>
/**
* **NOTE** Use locator-based [locator.click([options])](https://playwright.dev/docs/api/class-locator#locator-click) instead.
* Read more about [locators](https://playwright.dev/docs/locators).
*
* This method clicks the element by performing the following steps:
* 1. Wait for [actionability](https://playwright.dev/docs/actionability) checks on the element, unless
* [`force`](https://playwright.dev/docs/api/class-elementhandle#element-handle-click-option-force) option is
* set.
* 1. Scroll the element into view if needed.
* 1. Use [page.mouse](https://playwright.dev/docs/api/class-page#page-mouse) to click in the center of the
* element, or the specified
* [`position`](https://playwright.dev/docs/api/class-elementhandle#element-handle-click-option-position).
* 1. Wait for initiated navigations to either succeed or fail, unless
* [`noWaitAfter`](https://playwright.dev/docs/api/class-elementhandle#element-handle-click-option-no-wait-after)
* option is set.
*
* If the element is detached from the DOM at any moment during the action, this method throws.
*
* When all steps combined have not finished during the specified
* [`timeout`](https://playwright.dev/docs/api/class-elementhandle#element-handle-click-option-timeout), this method
* throws a [TimeoutError](https://playwright.dev/docs/api/class-timeouterror). Passing zero timeout disables this.
* @param options
*/
click(options?: {
/**
* Defaults to `left`.
*/
button?: 'left' | 'right' | 'middle'
/**
* defaults to 1. See [UIEvent.detail].
*/
clickCount?: number
/**
* Time to wait between `mousedown` and `mouseup` in milliseconds. Defaults to 0.
*/
delay?: number
/**
* Whether to bypass the [actionability](https://playwright.dev/docs/actionability) checks. Defaults to `false`.
*/
force?: boolean
/**
* Modifier keys to press. Ensures that only these modifiers are pressed during the operation, and then restores
* current modifiers back. If not specified, currently pressed modifiers are used. "ControlOrMeta" resolves to
* "Control" on Windows and Linux and to "Meta" on macOS.
*/
modifiers?: Array<'Alt' | 'Control' | 'ControlOrMeta' | 'Meta' | 'Shift'>
/**
* Actions that initiate navigations are waiting for these navigations to happen and for pages to start loading. You
* can opt out of waiting via setting this flag. You would only need this option in the exceptional cases such as
* navigating to inaccessible pages. Defaults to `false`.
* @deprecated This option will default to `true` in the future.
*/
noWaitAfter?: boolean
/**
* A point to use relative to the top-left corner of element padding box. If not specified, uses some visible point of
* the element.
*/
position?: {
x: number
y: number
}
/**
* Controls whether Playwright scrolls the element into view before performing the action. Defaults to `"auto"`, which
* scrolls the element into view when necessary, including scrolling nested scrollable containers. When set to
* `"none"`, Playwright does not scroll the element and the action fails if the element is not already in the
* viewport. This is useful to assert that an element is reachable by the user without additional scrolling.
*/
scroll?: 'auto' | 'none'
/**
* Allows to cancel the operation using an
* [`AbortSignal`](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal). If the signal is aborted, the
* operation will be aborted and throw an error. Note that providing a signal does not disable the default timeout,
* which can be changed using
* [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); pass
* `timeout: 0` to disable the timeout entirely.
*/
signal?: AbortSignal
/**
* Defaults to 1. Sends `n` interpolated `mousemove` events to represent travel between Playwright's current cursor
* position and the provided destination. When set to 1, emits a single `mousemove` event at the destination location.
*/
steps?: number
/**
* Maximum time in milliseconds. Defaults to `0` - no timeout. The default value can be changed via `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.
*/
timeout?: number
/**
* When set, this method only performs the [actionability](https://playwright.dev/docs/actionability) checks and skips the action. Defaults
* to `false`. Useful to wait until the element is ready for the action without performing it.
*/
trial?: boolean
}): Promise<void>
/**
* Returns the content frame for element handles referencing iframe nodes, or `null` otherwise
*/
contentFrame(): Promise<null | Frame>
/**
* **NOTE** Use locator-based [locator.dblclick([options])](https://playwright.dev/docs/api/class-locator#locator-dblclick)
* instead. Read more about [locators](https://playwright.dev/docs/locators).
*
* This method double clicks the element by performing the following steps:
* 1. Wait for [actionability](https://playwright.dev/docs/actionability) checks on the element, unless
* [`force`](https://playwright.dev/docs/api/class-elementhandle#element-handle-dblclick-option-force) option is
* set.
* 1. Scroll the element into view if needed.
* 1. Use [page.mouse](https://playwright.dev/docs/api/class-page#page-mouse) to double click in the center of the
* element, or the specified
* [`position`](https://playwright.dev/docs/api/class-elementhandle#element-handle-dblclick-option-position).
*
* If the element is detached from the DOM at any moment during the action, this method throws.
*
* When all steps combined have not finished during the specified
* [`timeout`](https://playwright.dev/docs/api/class-elementhandle#element-handle-dblclick-option-timeout), this
* method throws a [TimeoutError](https://playwright.dev/docs/api/class-timeouterror). Passing zero timeout disables
* this.
*
* **NOTE** `elementHandle.dblclick()` dispatches two `click` events and a single `dblclick` event.
*
* @param options
*/
dblclick(options?: {
/**
* Defaults to `left`.
*/
button?: 'left' | 'right' | 'middle'
/**
* Time to wait between `mousedown` and `mouseup` in milliseconds. Defaults to 0.
*/
delay?: number
/**
* Whether to bypass the [actionability](https://playwright.dev/docs/actionability) checks. Defaults to `false`.
*/
force?: boolean
/**
* Modifier keys to press. Ensures that only these modifiers are pressed during the operation, and then restores
* current modifiers back. If not specified, currently pressed modifiers are used. "ControlOrMeta" resolves to
* "Control" on Windows and Linux and to "Meta" on macOS.
*/
modifiers?: Array<'Alt' | 'Control' | 'ControlOrMeta' | 'Meta' | 'Shift'>
/**
* This option has no effect.
* @deprecated This option has no effect.
*/
noWaitAfter?: boolean
/**
* A point to use relative to the top-left corner of element padding box. If not specified, uses some visible point of
* the element.
*/
position?: {
x: number
y: number
}
/**
* Controls whether Playwright scrolls the element into view before performing the action. Defaults to `"auto"`, which
* scrolls the element into view when necessary, including scrolling nested scrollable containers. When set to
* `"none"`, Playwright does not scroll the element and the action fails if the element is not already in the
* viewport. This is useful to assert that an element is reachable by the user without additional scrolling.
*/
scroll?: 'auto' | 'none'
/**
* Allows to cancel the operation using an
* [`AbortSignal`](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal). If the signal is aborted, the
* operation will be aborted and throw an error. Note that providing a signal does not disable the default timeout,
* which can be changed using
* [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); pass
* `timeout: 0` to disable the timeout entirely.
*/
signal?: AbortSignal
/**
* Defaults to 1. Sends `n` interpolated `mousemove` events to represent travel between Playwright's current cursor
* position and the provided destination. When set to 1, emits a single `mousemove` event at the destination location.
*/
steps?: number
/**
* Maximum time in milliseconds. Defaults to `0` - no timeout. The default value can be changed via `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.
*/
timeout?: number
/**
* When set, this method only performs the [actionability](https://playwright.dev/docs/actionability) checks and skips the action. Defaults
* to `false`. Useful to wait until the element is ready for the action without performing it.
*/
trial?: boolean
}): Promise<void>
/**
* **NOTE** Use locator-based
* [locator.dispatchEvent(type[, eventInit, options])](https://playwright.dev/docs/api/class-locator#locator-dispatch-event)
* instead. Read more about [locators](https://playwright.dev/docs/locators).
*
* The snippet below dispatches the `click` event on the element. Regardless of the visibility state of the element,
* `click` is dispatched. This is equivalent to calling
* [element.click()](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/click).
*
* **Usage**
*
* ```js
* await elementHandle.dispatchEvent('click');
* ```
*
* Under the hood, it creates an instance of an event based on the given
* [`type`](https://playwright.dev/docs/api/class-elementhandle#element-handle-dispatch-event-option-type),
* initializes it with
* [`eventInit`](https://playwright.dev/docs/api/class-elementhandle#element-handle-dispatch-event-option-event-init)
* properties and dispatches it on the element. Events are `composed`, `cancelable` and bubble by default.
*
* Since
* [`eventInit`](https://playwright.dev/docs/api/class-elementhandle#element-handle-dispatch-event-option-event-init)
* is event-specific, please refer to the events documentation for the lists of initial properties:
* - [DeviceMotionEvent](https://developer.mozilla.org/en-US/docs/Web/API/DeviceMotionEvent/DeviceMotionEvent)
* - [DeviceOrientationEvent](https://developer.mozilla.org/en-US/docs/Web/API/DeviceOrientationEvent/DeviceOrientationEvent)
* - [DragEvent](https://developer.mozilla.org/en-US/docs/Web/API/DragEvent/DragEvent)
* - [Event](https://developer.mozilla.org/en-US/docs/Web/API/Event/Event)
* - [FocusEvent](https://developer.mozilla.org/en-US/docs/Web/API/FocusEvent/FocusEvent)
* - [KeyboardEvent](https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/KeyboardEvent)
* - [MouseEvent](https://developer.mozilla.org/en-US/docs/Web/API/MouseEvent/MouseEvent)
* - [PointerEvent](https://developer.mozilla.org/en-US/docs/Web/API/PointerEvent/PointerEvent)
* - [TouchEvent](https://developer.mozilla.org/en-US/docs/Web/API/TouchEvent/TouchEvent)
* - [WheelEvent](https://developer.mozilla.org/en-US/docs/Web/API/WheelEvent/WheelEvent)
*
* You can also specify `JSHandle` as the property value if you want live objects to be passed into the event:
*
* ```js
* // Note you can only create DataTransfer in Chromium and Firefox
* const dataTransfer = await page.evaluateHandle(() => new DataTransfer());
* await elementHandle.dispatchEvent('dragstart', { dataTransfer });
* ```
*
* @param type DOM event type: `"click"`, `"dragstart"`, etc.
* @param eventInit Optional event-specific initialization properties.
*/
dispatchEvent(type: string, eventInit?: EvaluationArgument): Promise<void>
/**
* **NOTE** Use locator-based [locator.fill(value[, options])](https://playwright.dev/docs/api/class-locator#locator-fill)
* instead. Read more about [locators](https://playwright.dev/docs/locators).
*
* This method waits for [actionability](https://playwright.dev/docs/actionability) checks, focuses the element, fills it and triggers an
* `input` event after filling. Note that you can pass an empty string to clear the input field.
*
* If the target element is not an `<input>`, `<textarea>` or `[contenteditable]` element, this method throws an
* error. However, if the element is inside the `<label>` element that has an associated
* [control](https://developer.mozilla.org/en-US/docs/Web/API/HTMLLabelElement/control), the control will be filled
* instead.
*
* To send fine-grained keyboard events, use
* [locator.pressSequentially(text[, options])](https://playwright.dev/docs/api/class-locator#locator-press-sequentially).
* @param value Value to set for the `<input>`, `<textarea>` or `[contenteditable]` element.
* @param options
*/
fill(
value: string,
options?: {
/**
* Whether to bypass the [actionability](https://playwright.dev/docs/actionability) checks. Defaults to `false`.
*/
force?: boolean
/**
* This option has no effect.
* @deprecated This option has no effect.
*/
noWaitAfter?: boolean
/**
* Allows to cancel the operation using an
* [`AbortSignal`](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal). If the signal is aborted, the
* operation will be aborted and throw an error. Note that providing a signal does not disable the default timeout,
* which can be changed using
* [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); pass
* `timeout: 0` to disable the timeout entirely.
*/
signal?: AbortSignal
/**
* Maximum time in milliseconds. Defaults to `0` - no timeout. The default value can be changed via `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.
*/
timeout?: number
},
): Promise<void>
/**
* **NOTE** Use locator-based [locator.focus([options])](https://playwright.dev/docs/api/class-locator#locator-focus) instead.
* Read more about [locators](https://playwright.dev/docs/locators).
*
* Calls [focus](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/focus) on the element.
*/
focus(): Promise<void>
/**
* **NOTE** Use locator-based
* [locator.getAttribute(name[, options])](https://playwright.dev/docs/api/class-locator#locator-get-attribute)
* instead. Read more about [locators](https://playwright.dev/docs/locators).
*
* Returns element attribute value.
* @param name Attribute name to get the value for.
*/
getAttribute(name: string): Promise<null | string>
/**
* **NOTE** Use locator-based [locator.hover([options])](https://playwright.dev/docs/api/class-locator#locator-hover) instead.
* Read more about [locators](https://playwright.dev/docs/locators).
*
* This method hovers over the element by performing the following steps:
* 1. Wait for [actionability](https://playwright.dev/docs/actionability) checks on the element, unless
* [`force`](https://playwright.dev/docs/api/class-elementhandle#element-handle-hover-option-force) option is
* set.
* 1. Scroll the element into view if needed.
* 1. Use [page.mouse](https://playwright.dev/docs/api/class-page#page-mouse) to hover over the center of the
* element, or the specified
* [`position`](https://playwright.dev/docs/api/class-elementhandle#element-handle-hover-option-position).
*
* If the element is detached from the DOM at any moment during the action, this method throws.
*
* When all steps combined have not finished during the specified
* [`timeout`](https://playwright.dev/docs/api/class-elementhandle#element-handle-hover-option-timeout), this method
* throws a [TimeoutError](https://playwright.dev/docs/api/class-timeouterror). Passing zero timeout disables this.
* @param options
*/
hover(options?: {
/**
* Whether to bypass the [actionability](https://playwright.dev/docs/actionability) checks. Defaults to `false`.
*/
force?: boolean
/**
* Modifier keys to press. Ensures that only these modifiers are pressed during the operation, and then restores
* current modifiers back. If not specified, currently pressed modifiers are used. "ControlOrMeta" resolves to
* "Control" on Windows and Linux and to "Meta" on macOS.
*/
modifiers?: Array<'Alt' | 'Control' | 'ControlOrMeta' | 'Meta' | 'Shift'>
/**
* This option has no effect.
* @deprecated This option has no effect.
*/
noWaitAfter?: boolean
/**
* A point to use relative to the top-left corner of element padding box. If not specified, uses some visible point of
* the element.
*/
position?: {
x: number
y: number
}
/**
* Controls whether Playwright scrolls the element into view before performing the action. Defaults to `"auto"`, which
* scrolls the element into view when necessary, including scrolling nested scrollable containers. When set to
* `"none"`, Playwright does not scroll the element and the action fails if the element is not already in the
* viewport. This is useful to assert that an element is reachable by the user without additional scrolling.
*/
scroll?: 'auto' | 'none'
/**
* Allows to cancel the operation using an
* [`AbortSignal`](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal). If the signal is aborted, the
* operation will be aborted and throw an error. Note that providing a signal does not disable the default timeout,
* which can be changed using
* [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); pass
* `timeout: 0` to disable the timeout entirely.
*/
signal?: AbortSignal
/**
* Maximum time in milliseconds. Defaults to `0` - no timeout. The default value can be changed via `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.
*/
timeout?: number
/**
* When set, this method only performs the [actionability](https://playwright.dev/docs/actionability) checks and skips the action. Defaults
* to `false`. Useful to wait until the element is ready for the action without performing it.
*/
trial?: boolean
}): Promise<void>
/**
* **NOTE** Use locator-based [locator.innerHTML([options])](https://playwright.dev/docs/api/class-locator#locator-inner-html)
* instead. Read more about [locators](https://playwright.dev/docs/locators).
*
* Returns the `element.innerHTML`.
*/
innerHTML(): Promise<string>
/**
* **NOTE** Use locator-based [locator.innerText([options])](https://playwright.dev/docs/api/class-locator#locator-inner-text)
* instead. Read more about [locators](https://playwright.dev/docs/locators).
*
* Returns the `element.innerText`.
*/
innerText(): Promise<string>
/**
* **NOTE** Use locator-based
* [locator.inputValue([options])](https://playwright.dev/docs/api/class-locator#locator-input-value) instead. Read
* more about [locators](https://playwright.dev/docs/locators).
*
* Returns `input.value` for the selected `<input>` or `<textarea>` or `<select>` element.
*
* Throws for non-input elements. However, if the element is inside the `<label>` element that has an associated
* [control](https://developer.mozilla.org/en-US/docs/Web/API/HTMLLabelElement/control), returns the value of the
* control.
* @param options
*/
inputValue(options?: {
/**
* @deprecated This option is ignored. The value is returned immediately.
*/
timeout?: number
}): Promise<string>
/**
* **NOTE** Use locator-based [locator.isChecked([options])](https://playwright.dev/docs/api/class-locator#locator-is-checked)
* instead. Read more about [locators](https://playwright.dev/docs/locators).
*
* Returns whether the element is checked. Throws if the element is not a checkbox or radio input.
*/
isChecked(): Promise<boolean>
/**
* **NOTE** Use locator-based
* [locator.isDisabled([options])](https://playwright.dev/docs/api/class-locator#locator-is-disabled) instead. Read
* more about [locators](https://playwright.dev/docs/locators).
*
* Returns whether the element is disabled, the opposite of [enabled](https://playwright.dev/docs/actionability#enabled).
*/
isDisabled(): Promise<boolean>
/**
* **NOTE** Use locator-based
* [locator.isEditable([options])](https://playwright.dev/docs/api/class-locator#locator-is-editable) instead. Read
* more about [locators](https://playwright.dev/docs/locators).
*
* Returns whether the element is [editable](https://playwright.dev/docs/actionability#editable).
*/
isEditable(): Promise<boolean>
/**
* **NOTE** Use locator-based [locator.isEnabled([options])](https://playwright.dev/docs/api/class-locator#locator-is-enabled)
* instead. Read more about [locators](https://playwright.dev/docs/locators).
*
* Returns whether the element is [enabled](https://playwright.dev/docs/actionability#enabled).
*/
isEnabled(): Promise<boolean>
/**
* **NOTE** Use locator-based [locator.isHidden([options])](https://playwright.dev/docs/api/class-locator#locator-is-hidden)
* instead. Read more about [locators](https://playwright.dev/docs/locators).
*
* Returns whether the element is hidden, the opposite of [visible](https://playwright.dev/docs/actionability#visible).
*/
isHidden(): Promise<boolean>
/**
* **NOTE** Use locator-based [locator.isVisible([options])](https://playwright.dev/docs/api/class-locator#locator-is-visible)
* instead. Read more about [locators](https://playwright.dev/docs/locators).
*
* Returns whether the element is [visible](https://playwright.dev/docs/actionability#visible).
*/
isVisible(): Promise<boolean>
/**
* Returns the frame containing the given element.
*/
ownerFrame(): Promise<null | Frame>
/**
* **NOTE** Use locator-based [locator.press(key[, options])](https://playwright.dev/docs/api/class-locator#locator-press)
* instead. Read more about [locators](https://playwright.dev/docs/locators).
*
* Focuses the element, and then uses
* [keyboard.down(key)](https://playwright.dev/docs/api/class-keyboard#keyboard-down) and
* [keyboard.up(key)](https://playwright.dev/docs/api/class-keyboard#keyboard-up).
*
* [`key`](https://playwright.dev/docs/api/class-elementhandle#element-handle-press-option-key) can specify the
* intended [keyboardEvent.key](https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/key) value or a single
* character to generate the text for. A superset of the
* [`key`](https://playwright.dev/docs/api/class-elementhandle#element-handle-press-option-key) values can be found
* [here](https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/key/Key_Values). Examples of the keys are:
*
* `F1` - `F12`, `Digit0`- `Digit9`, `KeyA`- `KeyZ`, `Backquote`, `Minus`, `Equal`, `Backslash`, `Backspace`, `Tab`,
* `Delete`, `Escape`, `ArrowDown`, `End`, `Enter`, `Home`, `Insert`, `PageDown`, `PageUp`, `ArrowRight`, `ArrowUp`,
* etc.
*
* Following modification shortcuts are also supported: `Shift`, `Control`, `Alt`, `Meta`, `ShiftLeft`,
* `ControlOrMeta`.
*
* Holding down `Shift` will type the text that corresponds to the
* [`key`](https://playwright.dev/docs/api/class-elementhandle#element-handle-press-option-key) in the upper case.
*
* If [`key`](https://playwright.dev/docs/api/class-elementhandle#element-handle-press-option-key) is a single
* character, it is case-sensitive, so the values `a` and `A` will generate different respective texts.
*
* Shortcuts such as `key: "Control+o"`, `key: "Control++` or `key: "Control+Shift+T"` are supported as well. When
* specified with the modifier, modifier is pressed and being held while the subsequent key is being pressed.
* @param key Name of the key to press or a character to generate, such as `ArrowLeft` or `a`.
* @param options
*/
press(
key: string,
options?: {
/**
* Time to wait between `keydown` and `keyup` in milliseconds. Defaults to 0.
*/
delay?: number
/**
* Actions that initiate navigations are waiting for these navigations to happen and for pages to start loading. You
* can opt out of waiting via setting this flag. You would only need this option in the exceptional cases such as
* navigating to inaccessible pages. Defaults to `false`.
* @deprecated This option will default to `true` in the future.
*/
noWaitAfter?: boolean
/**
* Allows to cancel the operation using an
* [`AbortSignal`](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal). If the signal is aborted, the
* operation will be aborted and throw an error. Note that providing a signal does not disable the default timeout,
* which can be changed using
* [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); pass
* `timeout: 0` to disable the timeout entirely.
*/
signal?: AbortSignal
/**
* Maximum time in milliseconds. Defaults to `0` - no timeout. The default value can be changed via `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.
*/
timeout?: number
},
): Promise<void>
/**
* **NOTE** Use locator-based [locator.screenshot([options])](https://playwright.dev/docs/api/class-locator#locator-screenshot)
* instead. Read more about [locators](https://playwright.dev/docs/locators).
*
* This method captures a screenshot of the page, clipped to the size and position of this particular element. If the
* element is covered by other elements, it will not be actually visible on the screenshot. If the element is a
* scrollable container, only the currently scrolled content will be visible on the screenshot.
*
* This method waits for the [actionability](https://playwright.dev/docs/actionability) checks, then scrolls element into view before taking
* a screenshot. If the element is detached from DOM, the method throws an error.
*
* Returns the buffer with the captured screenshot.
* @param options
*/
screenshot(options?: {
/**
* When set to `"disabled"`, stops CSS animations, CSS transitions and Web Animations. Animations get different
* treatment depending on their duration:
* - finite animations are fast-forwarded to completion, so they'll fire `transitionend` event.
* - infinite animations are canceled to initial state, and then played over after the screenshot.
*
* Defaults to `"allow"` that leaves animations untouched.
*/
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"`.
*/
caret?: 'hide' | 'initial'
/**
* Specify locators that should be masked when the screenshot is taken. Masked elements will be overlaid with a pink
* box `#FF00FF` (customized by
* [`maskColor`](https://playwright.dev/docs/api/class-elementhandle#element-handle-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.
*/
mask?: Array<Locator>
/**
* 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`.
*/
maskColor?: string
/**
* Hides default white background and allows capturing screenshots with transparency. Not applicable to `jpeg` images.
* Defaults to `false`.
*/
omitBackground?: boolean
/**
* 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-elementhandle#element-handle-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.
*/
path?: string
/**
* The quality of the image, between 0-100. Not applicable to `png` images. For `jpeg` the default is `80`. For
* `webp`, a quality of `100` (the default) produces a lossless image, while lower values use lossy compression.
*/
quality?: number
/**
* When set to `"css"`, screenshot will have a single pixel per each css pixel on the page. For high-dpi devices, this
* will keep screenshots small. Using `"device"` option will produce a single pixel per each device pixel, so
* screenshots of high-dpi devices will be twice as large or even larger.
*
* Defaults to `"device"`.
*/
scale?: 'css' | 'device'
/**
* Allows to cancel the operation using an
* [`AbortSignal`](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal). If the signal is aborted, the
* operation will be aborted and throw an error. Note that providing a signal does not disable the default timeout,
* which can be changed using
* [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); pass
* `timeout: 0` to disable the timeout entirely.
*/
signal?: AbortSignal
/**
* 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.
*/
style?: string
/**
* Maximum time in milliseconds. Defaults to `0` - no timeout. The default value can be changed via `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.
*/
timeout?: number
/**
* Specify screenshot type, defaults to `png`.
*/
type?: 'png' | 'jpeg' | 'webp'
}): Promise<Buffer>
/**
* **NOTE** Use locator-based
* [locator.scrollIntoViewIfNeeded([options])](https://playwright.dev/docs/api/class-locator#locator-scroll-into-view-if-needed)
* instead. Read more about [locators](https://playwright.dev/docs/locators).
*
* This method waits for [actionability](https://playwright.dev/docs/actionability) checks, then tries to scroll element into view, unless
* it is completely visible as defined by
* [IntersectionObserver](https://developer.mozilla.org/en-US/docs/Web/API/Intersection_Observer_API)'s `ratio`.
*
* Throws when `elementHandle` does not point to an element
* [connected](https://developer.mozilla.org/en-US/docs/Web/API/Node/isConnected) to a Document or a ShadowRoot.
*
* See [scrolling](https://playwright.dev/docs/input#scrolling) for alternative ways to scroll.
* @param options
*/
scrollIntoViewIfNeeded(options?: {
/**
* Allows to cancel the operation using an
* [`AbortSignal`](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal). If the signal is aborted, the
* operation will be aborted and throw an error. Note that providing a signal does not disable the default timeout,
* which can be changed using
* [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); pass
* `timeout: 0` to disable the timeout entirely.
*/
signal?: AbortSignal
/**
* Maximum time in milliseconds. Defaults to `0` - no timeout. The default value can be changed via `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.
*/
timeout?: number
}): Promise<void>
/**
* **NOTE** Use locator-based
* [locator.selectOption(values[, options])](https://playwright.dev/docs/api/class-locator#locator-select-option)
* instead. Read more about [locators](https://playwright.dev/docs/locators).
*
* This method waits for [actionability](https://playwright.dev/docs/actionability) checks, waits until all specified options are present in
* the `<select>` element and selects these options.
*
* If the target element is not a `<select>` element, this method throws an error. However, if the element is inside
* the `<label>` element that has an associated
* [control](https://developer.mozilla.org/en-US/docs/Web/API/HTMLLabelElement/control), the control will be used
* instead.
*
* Returns the array of option values that have been successfully selected.
*
* Triggers a `change` and `input` event once all the provided options have been selected.
*
* **Usage**
*
* ```js
* // Single selection matching the value or label
* handle.selectOption('blue');
*
* // single selection matching the label
* handle.selectOption({ label: 'Blue' });
*
* // multiple selection
* handle.selectOption(['red', 'green', 'blue']);
* ```
*
* @param values Options to select. If the `<select>` has the `multiple` attribute, all matching options are selected, otherwise
* only the first option matching one of the passed options is selected. String values are matching both values and
* labels. Option is considered matching if all specified properties match.
* @param options
*/
selectOption(
values:
| null
| string
| ElementHandle
| ReadonlyArray<string>
| {
/**
* Matches by `option.value`. Optional.
*/
value?: string
/**
* Matches by `option.label`. Optional.
*/
label?: string
/**
* Matches by the index. Optional.
*/
index?: number
}
| ReadonlyArray<ElementHandle>
| ReadonlyArray<{
/**
* Matches by `option.value`. Optional.
*/
value?: string
/**
* Matches by `option.label`. Optional.
*/
label?: string
/**
* Matches by the index. Optional.
*/
index?: number
}>,
options?: {
/**
* Whether to bypass the [actionability](https://playwright.dev/docs/actionability) checks. Defaults to `false`.
*/
force?: boolean
/**
* This option has no effect.
* @deprecated This option has no effect.
*/
noWaitAfter?: boolean
/**
* Allows to cancel the operation using an
* [`AbortSignal`](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal). If the signal is aborted, the
* operation will be aborted and throw an error. Note that providing a signal does not disable the default timeout,
* which can be changed using
* [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); pass
* `timeout: 0` to disable the timeout entirely.
*/
signal?: AbortSignal
/**
* Maximum time in milliseconds. Defaults to `0` - no timeout. The default value can be changed via `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.
*/
timeout?: number
},
): Promise<Array<string>>
/**
* **NOTE** Use locator-based
* [locator.selectText([options])](https://playwright.dev/docs/api/class-locator#locator-select-text) instead. Read
* more about [locators](https://playwright.dev/docs/locators).
*
* This method waits for [actionability](https://playwright.dev/docs/actionability) checks, then focuses the element and selects all its
* text content.
*
* If the element is inside the `<label>` element that has an associated
* [control](https://developer.mozilla.org/en-US/docs/Web/API/HTMLLabelElement/control), focuses and selects text in
* the control instead.
* @param options
*/
selectText(options?: {
/**
* Whether to bypass the [actionability](https://playwright.dev/docs/actionability) checks. Defaults to `false`.
*/
force?: boolean
/**
* Allows to cancel the operation using an
* [`AbortSignal`](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal). If the signal is aborted, the
* operation will be aborted and throw an error. Note that providing a signal does not disable the default timeout,
* which can be changed using
* [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); pass
* `timeout: 0` to disable the timeout entirely.
*/
signal?: AbortSignal
/**
* Maximum time in milliseconds. Defaults to `0` - no timeout. The default value can be changed via `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.
*/
timeout?: number
}): Promise<void>
/**
* **NOTE** Use locator-based
* [locator.setChecked(checked[, options])](https://playwright.dev/docs/api/class-locator#locator-set-checked)
* instead. Read more about [locators](https://playwright.dev/docs/locators).
*
* This method checks or unchecks an element by performing the following steps:
* 1. Ensure that element is a checkbox or a radio input. If not, this method throws.
* 1. If the element already has the right checked state, this method returns immediately.
* 1. Wait for [actionability](https://playwright.dev/docs/actionability) checks on the matched element, unless
* [`force`](https://playwright.dev/docs/api/class-elementhandle#element-handle-set-checked-option-force) option
* is set. If the element is detached during the checks, the whole action is retried.
* 1. Scroll the element into view if needed.
* 1. Use [page.mouse](https://playwright.dev/docs/api/class-page#page-mouse) to click in the center of the
* element.
* 1. Ensure that the element is now checked or unchecked. If not, this method throws.
*
* When all steps combined have not finished during the specified
* [`timeout`](https://playwright.dev/docs/api/class-elementhandle#element-handle-set-checked-option-timeout), this
* method throws a [TimeoutError](https://playwright.dev/docs/api/class-timeouterror). Passing zero timeout disables
* this.
* @param checked Whether to check or uncheck the checkbox.
* @param options
*/
setChecked(
checked: boolean,
options?: {
/**
* Whether to bypass the [actionability](https://playwright.dev/docs/actionability) checks. Defaults to `false`.
*/
force?: boolean
/**
* This option has no effect.
* @deprecated This option has no effect.
*/
noWaitAfter?: boolean
/**
* A point to use relative to the top-left corner of element padding box. If not specified, uses some visible point of
* the element.
*/
position?: {
x: number
y: number
}
/**
* Controls whether Playwright scrolls the element into view before performing the action. Defaults to `"auto"`, which
* scrolls the element into view when necessary, including scrolling nested scrollable containers. When set to
* `"none"`, Playwright does not scroll the element and the action fails if the element is not already in the
* viewport. This is useful to assert that an element is reachable by the user without additional scrolling.
*/
scroll?: 'auto' | 'none'
/**
* Allows to cancel the operation using an
* [`AbortSignal`](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal). If the signal is aborted, the
* operation will be aborted and throw an error. Note that providing a signal does not disable the default timeout,
* which can be changed using
* [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); pass
* `timeout: 0` to disable the timeout entirely.
*/
signal?: AbortSignal
/**
* Maximum time in milliseconds. Defaults to `0` - no timeout. The default value can be changed via `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.
*/
timeout?: number
/**
* When set, this method only performs the [actionability](https://playwright.dev/docs/actionability) checks and skips the action. Defaults
* to `false`. Useful to wait until the element is ready for the action without performing it.
*/
trial?: boolean
},
): Promise<void>
/**
* **NOTE** Use locator-based
* [locator.setInputFiles(files[, options])](https://playwright.dev/docs/api/class-locator#locator-set-input-files)
* instead. Read more about [locators](https://playwright.dev/docs/locators).
*
* Sets the value of the file input to these file paths or files. If some of the `filePaths` are relative paths, then
* they are resolved relative to the current working directory. For empty array, clears the selected files. For inputs
* with a `[webkitdirectory]` attribute, only a single directory path is supported.
*
* This method expects [ElementHandle](https://playwright.dev/docs/api/class-elementhandle) to point to an
* [input element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input). However, if the element is inside
* the `<label>` element that has an associated
* [control](https://developer.mozilla.org/en-US/docs/Web/API/HTMLLabelElement/control), targets the control instead.
* @param files
* @param options
*/
setInputFiles(
files:
| string
| ReadonlyArray<string>
| {
/**
* File name
*/
name: string
/**
* File type
*/
mimeType: string
/**
* File content
*/
buffer: Buffer
}
| ReadonlyArray<{
/**
* File name
*/
name: string
/**
* File type
*/
mimeType: string
/**
* File content
*/
buffer: Buffer
}>,
options?: {
/**
* This option has no effect.
* @deprecated This option has no effect.
*/
noWaitAfter?: boolean
/**
* Allows to cancel the operation using an
* [`AbortSignal`](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal). If the signal is aborted, the
* operation will be aborted and throw an error. Note that providing a signal does not disable the default timeout,
* which can be changed using
* [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); pass
* `timeout: 0` to disable the timeout entirely.
*/
signal?: AbortSignal
/**
* Maximum time in milliseconds. Defaults to `0` - no timeout. The default value can be changed via `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.
*/
timeout?: number
},
): Promise<void>
/**
* **NOTE** Use locator-based [locator.tap([options])](https://playwright.dev/docs/api/class-locator#locator-tap) instead. Read
* more about [locators](https://playwright.dev/docs/locators).
*
* This method taps the element by performing the following steps:
* 1. Wait for [actionability](https://playwright.dev/docs/actionability) checks on the element, unless
* [`force`](https://playwright.dev/docs/api/class-elementhandle#element-handle-tap-option-force) option is set.
* 1. Scroll the element into view if needed.
* 1. Use [page.touchscreen](https://playwright.dev/docs/api/class-page#page-touchscreen) to tap the center of the
* element, or the specified
* [`position`](https://playwright.dev/docs/api/class-elementhandle#element-handle-tap-option-position).
*
* If the element is detached from the DOM at any moment during the action, this method throws.
*
* When all steps combined have not finished during the specified
* [`timeout`](https://playwright.dev/docs/api/class-elementhandle#element-handle-tap-option-timeout), this method
* throws a [TimeoutError](https://playwright.dev/docs/api/class-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?: {
/**
* Whether to bypass the [actionability](https://playwright.dev/docs/actionability) checks. Defaults to `false`.
*/
force?: boolean
/**
* Modifier keys to press. Ensures that only these modifiers are pressed during the operation, and then restores
* current modifiers back. If not specified, currently pressed modifiers are used. "ControlOrMeta" resolves to
* "Control" on Windows and Linux and to "Meta" on macOS.
*/
modifiers?: Array<'Alt' | 'Control' | 'ControlOrMeta' | 'Meta' | 'Shift'>
/**
* This option has no effect.
* @deprecated This option has no effect.
*/
noWaitAfter?: boolean
/**
* A point to use relative to the top-left corner of element padding box. If not specified, uses some visible point of
* the element.
*/
position?: {
x: number
y: number
}
/**
* Controls whether Playwright scrolls the element into view before performing the action. Defaults to `"auto"`, which
* scrolls the element into view when necessary, including scrolling nested scrollable containers. When set to
* `"none"`, Playwright does not scroll the element and the action fails if the element is not already in the
* viewport. This is useful to assert that an element is reachable by the user without additional scrolling.
*/
scroll?: 'auto' | 'none'
/**
* Allows to cancel the operation using an
* [`AbortSignal`](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal). If the signal is aborted, the
* operation will be aborted and throw an error. Note that providing a signal does not disable the default timeout,
* which can be changed using
* [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); pass
* `timeout: 0` to disable the timeout entirely.
*/
signal?: AbortSignal
/**
* Maximum time in milliseconds. Defaults to `0` - no timeout. The default value can be changed via `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.
*/
timeout?: number
/**
* When set, this method only performs the [actionability](https://playwright.dev/docs/actionability) checks and skips the action. Defaults
* to `false`. Useful to wait until the element is ready for the action without performing it.
*/
trial?: boolean
}): Promise<void>
/**
* **NOTE** Use locator-based
* [locator.textContent([options])](https://playwright.dev/docs/api/class-locator#locator-text-content) instead. Read
* more about [locators](https://playwright.dev/docs/locators).
*
* Returns the `node.textContent`.
*/
textContent(): Promise<null | string>
/**
* Focuses the element, and then sends a `keydown`, `keypress`/`input`, and `keyup` event for each character in the
* text.
*
* To press a special key, like `Control` or `ArrowDown`, use
* [elementHandle.press(key[, options])](https://playwright.dev/docs/api/class-elementhandle#element-handle-press).
*
* **Usage**
* @deprecated In most cases, you should use
* [locator.fill(value[, options])](https://playwright.dev/docs/api/class-locator#locator-fill) instead. You only need
* to press keys one by one if there is special keyboard handling on the page - in this case use
* [locator.pressSequentially(text[, options])](https://playwright.dev/docs/api/class-locator#locator-press-sequentially).
* @param text A text to type into a focused element.
* @param options
*/
type(
text: string,
options?: {
/**
* Time to wait between key presses in milliseconds. Defaults to 0.
*/
delay?: number
/**
* This option has no effect.
* @deprecated This option has no effect.
*/
noWaitAfter?: boolean
/**
* Allows to cancel the operation using an
* [`AbortSignal`](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal). If the signal is aborted, the
* operation will be aborted and throw an error. Note that providing a signal does not disable the default timeout,
* which can be changed using
* [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); pass
* `timeout: 0` to disable the timeout entirely.
*/
signal?: AbortSignal
/**
* Maximum time in milliseconds. Defaults to `0` - no timeout. The default value can be changed via `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.
*/
timeout?: number
},
): Promise<void>
/**
* **NOTE** Use locator-based [locator.uncheck([options])](https://playwright.dev/docs/api/class-locator#locator-uncheck)
* instead. Read more about [locators](https://playwright.dev/docs/locators).
*
* This method checks the element by performing the following steps:
* 1. Ensure that element is a checkbox or a radio input. If not, this method throws. If the element is already
* unchecked, this method returns immediately.
* 1. Wait for [actionability](https://playwright.dev/docs/actionability) checks on the element, unless
* [`force`](https://playwright.dev/docs/api/class-elementhandle#element-handle-uncheck-option-force) option is
* set.
* 1. Scroll the element into view if needed.
* 1. Use [page.mouse](https://playwright.dev/docs/api/class-page#page-mouse) to click in the center of the
* element.
* 1. Ensure that the element is now unchecked. If not, this method throws.
*
* If the element is detached from the DOM at any moment during the action, this method throws.
*
* When all steps combined have not finished during the specified
* [`timeout`](https://playwright.dev/docs/api/class-elementhandle#element-handle-uncheck-option-timeout), this method
* throws a [TimeoutError](https://playwright.dev/docs/api/class-timeouterror). Passing zero timeout disables this.
* @param options
*/
uncheck(options?: {
/**
* Whether to bypass the [actionability](https://playwright.dev/docs/actionability) checks. Defaults to `false`.
*/
force?: boolean
/**
* This option has no effect.
* @deprecated This option has no effect.
*/
noWaitAfter?: boolean
/**
* A point to use relative to the top-left corner of element padding box. If not specified, uses some visible point of
* the element.
*/
position?: {
x: number
y: number
}
/**
* Controls whether Playwright scrolls the element into view before performing the action. Defaults to `"auto"`, which
* scrolls the element into view when necessary, including scrolling nested scrollable containers. When set to
* `"none"`, Playwright does not scroll the element and the action fails if the element is not already in the
* viewport. This is useful to assert that an element is reachable by the user without additional scrolling.
*/
scroll?: 'auto' | 'none'
/**
* Allows to cancel the operation using an
* [`AbortSignal`](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal). If the signal is aborted, the
* operation will be aborted and throw an error. Note that providing a signal does not disable the default timeout,
* which can be changed using
* [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); pass
* `timeout: 0` to disable the timeout entirely.
*/
signal?: AbortSignal
/**
* Maximum time in milliseconds. Defaults to `0` - no timeout. The default value can be changed via `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.
*/
timeout?: number
/**
* When set, this method only performs the [actionability](https://playwright.dev/docs/actionability) checks and skips the action. Defaults
* to `false`. Useful to wait until the element is ready for the action without performing it.
*/
trial?: boolean
}): Promise<void>
/**
* Returns when the element satisfies the
* [`state`](https://playwright.dev/docs/api/class-elementhandle#element-handle-wait-for-element-state-option-state).
*
* Depending on the
* [`state`](https://playwright.dev/docs/api/class-elementhandle#element-handle-wait-for-element-state-option-state)
* parameter, this method waits for one of the [actionability](https://playwright.dev/docs/actionability) checks to pass. This method throws
* when the element is detached while waiting, unless waiting for the `"hidden"` state.
* - `"visible"` Wait until the element is [visible](https://playwright.dev/docs/actionability#visible).
* - `"hidden"` Wait until the element is [not visible](https://playwright.dev/docs/actionability#visible) or not attached. Note that
* waiting for hidden does not throw when the element detaches.
* - `"stable"` Wait until the element is both [visible](https://playwright.dev/docs/actionability#visible) and
* [stable](https://playwright.dev/docs/actionability#stable).
* - `"enabled"` Wait until the element is [enabled](https://playwright.dev/docs/actionability#enabled).
* - `"disabled"` Wait until the element is [not enabled](https://playwright.dev/docs/actionability#enabled).
* - `"editable"` Wait until the element is [editable](https://playwright.dev/docs/actionability#editable).
*
* If the element does not satisfy the condition for the
* [`timeout`](https://playwright.dev/docs/api/class-elementhandle#element-handle-wait-for-element-state-option-timeout)
* milliseconds, this method will throw.
* @param state A state to wait for, see below for more details.
* @param options
*/
waitForElementState(
state: 'visible' | 'hidden' | 'stable' | 'enabled' | 'disabled' | 'editable',
options?: {
/**
* Allows to cancel the operation using an
* [`AbortSignal`](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal). If the signal is aborted, the
* operation will be aborted and throw an error. Note that providing a signal does not disable the default timeout,
* which can be changed using
* [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); pass
* `timeout: 0` to disable the timeout entirely.
*/
signal?: AbortSignal
/**
* Maximum time in milliseconds. Defaults to `0` - no timeout. The default value can be changed via `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.
*/
timeout?: number
},
): Promise<void>
}
FileChooser
FileChooser objects are dispatched by the page in the page.on('filechooser') event.
// Start waiting for file chooser before clicking. Note no await.
const fileChooserPromise = page.waitForEvent('filechooser')
await page.getByText('Upload file').click()
const fileChooser = await fileChooserPromise
await fileChooser.setFiles(path.join(__dirname, 'myfile.pdf'))
interface FileChooser {
/**
* Returns input element associated with this file chooser.
*/
element(): ElementHandle
/**
* Returns whether this file chooser accepts multiple files.
*/
isMultiple(): boolean
/**
* Returns page this file chooser belongs to.
*/
page(): Page
/**
* Sets the value of the file input this chooser is associated with. If some of the `filePaths` are relative paths,
* then they are resolved relative to the current working directory. For empty array, clears the selected files.
* @param files
* @param options
*/
setFiles(
files:
| string
| ReadonlyArray<string>
| {
/**
* File name
*/
name: string
/**
* File type
*/
mimeType: string
/**
* File content
*/
buffer: Buffer
}
| ReadonlyArray<{
/**
* File name
*/
name: string
/**
* File type
*/
mimeType: string
/**
* File content
*/
buffer: Buffer
}>,
options?: {
/**
* This option has no effect.
* @deprecated This option has no effect.
*/
noWaitAfter?: boolean
/**
* Allows to cancel the operation using an
* [`AbortSignal`](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal). If the signal is aborted, the
* operation will be aborted and throw an error. Note that providing a signal does not disable the default timeout,
* which can be changed using
* [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); pass
* `timeout: 0` to disable the timeout entirely.
*/
signal?: AbortSignal
/**
* Maximum time in milliseconds. Defaults to `0` - no timeout. The default value can be changed via `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.
*/
timeout?: number
},
): Promise<void>
}
Frame
At every point of time, page exposes its current frame tree via the page.mainFrame() and frame.childFrames() methods.
Frame object's lifecycle is controlled by three events, dispatched on the page object:
- page.on('frameattached') - fired when the frame gets attached to the page. A Frame can be attached to the page only once.
- page.on('framenavigated') - fired when the frame commits navigation to a different URL.
- page.on('framedetached') - fired when the frame gets detached from the page. A Frame can be detached from the page only once.
An example of dumping frame tree:
const { firefox } = require('playwright') // Or 'chromium' or 'webkit'.
;(async () => {
const browser = await firefox.launch()
const page = await browser.newPage()
await page.goto('https://www.google.com/chrome/browser/canary.html')
dumpFrameTree(page.mainFrame(), '')
await browser.close()
function dumpFrameTree(frame, indent) {
console.log(indent + frame.url())
for (const child of frame.childFrames()) dumpFrameTree(child, indent + ' ')
}
})()
interface Frame {
/**
* Returns the return value of
* [`pageFunction`](https://playwright.dev/docs/api/class-frame#frame-evaluate-option-expression).
*
* If the function passed to the
* [frame.evaluate(pageFunction[, arg, options])](https://playwright.dev/docs/api/class-frame#frame-evaluate) returns
* a [Promise], then
* [frame.evaluate(pageFunction[, arg, options])](https://playwright.dev/docs/api/class-frame#frame-evaluate) would
* wait for the promise to resolve and return its value.
*
* If the function passed to the
* [frame.evaluate(pageFunction[, arg, options])](https://playwright.dev/docs/api/class-frame#frame-evaluate) returns
* a non-[Serializable] value, then
* [frame.evaluate(pageFunction[, arg, options])](https://playwright.dev/docs/api/class-frame#frame-evaluate) returns
* `undefined`. Playwright also supports transferring some additional values that are not serializable by `JSON`:
* `-0`, `NaN`, `Infinity`, `-Infinity`.
*
* **Usage**
*
* ```js
* const result = await frame.evaluate(([x, y]) => {
* return Promise.resolve(x * y);
* }, [7, 8]);
* console.log(result); // prints "56"
* ```
*
* A string can also be passed in instead of a function.
*
* ```js
* console.log(await frame.evaluate('1 + 2')); // prints "3"
* ```
*
* [ElementHandle](https://playwright.dev/docs/api/class-elementhandle) instances can be passed as an argument to the
* [frame.evaluate(pageFunction[, arg, options])](https://playwright.dev/docs/api/class-frame#frame-evaluate):
*
* ```js
* const bodyHandle = await frame.evaluateHandle('document.body');
* const html = await frame.evaluate(([body, suffix]) =>
* body.innerHTML + suffix, [bodyHandle, 'hello'],
* );
* await bodyHandle.dispose();
* ```
*
* @param pageFunction Function to be evaluated in the page context.
* @param arg Optional argument to pass to
* [`pageFunction`](https://playwright.dev/docs/api/class-frame#frame-evaluate-option-expression).
* @param options
*/
evaluate<R, Arg>(
pageFunction: PageFunction<Arg, R>,
arg: Arg,
options?: { exposeFunctions?: boolean },
): Promise<R>
/**
* Returns the return value of
* [`pageFunction`](https://playwright.dev/docs/api/class-frame#frame-evaluate-option-expression).
*
* If the function passed to the
* [frame.evaluate(pageFunction[, arg, options])](https://playwright.dev/docs/api/class-frame#frame-evaluate) returns
* a [Promise], then
* [frame.evaluate(pageFunction[, arg, options])](https://playwright.dev/docs/api/class-frame#frame-evaluate) would
* wait for the promise to resolve and return its value.
*
* If the function passed to the
* [frame.evaluate(pageFunction[, arg, options])](https://playwright.dev/docs/api/class-frame#frame-evaluate) returns
* a non-[Serializable] value, then
* [frame.evaluate(pageFunction[, arg, options])](https://playwright.dev/docs/api/class-frame#frame-evaluate) returns
* `undefined`. Playwright also supports transferring some additional values that are not serializable by `JSON`:
* `-0`, `NaN`, `Infinity`, `-Infinity`.
*
* **Usage**
*
* ```js
* const result = await frame.evaluate(([x, y]) => {
* return Promise.resolve(x * y);
* }, [7, 8]);
* console.log(result); // prints "56"
* ```
*
* A string can also be passed in instead of a function.
*
* ```js
* console.log(await frame.evaluate('1 + 2')); // prints "3"
* ```
*
* [ElementHandle](https://playwright.dev/docs/api/class-elementhandle) instances can be passed as an argument to the
* [frame.evaluate(pageFunction[, arg, options])](https://playwright.dev/docs/api/class-frame#frame-evaluate):
*
* ```js
* const bodyHandle = await frame.evaluateHandle('document.body');
* const html = await frame.evaluate(([body, suffix]) =>
* body.innerHTML + suffix, [bodyHandle, 'hello'],
* );
* await bodyHandle.dispose();
* ```
*
* @param pageFunction Function to be evaluated in the page context.
* @param arg Optional argument to pass to
* [`pageFunction`](https://playwright.dev/docs/api/class-frame#frame-evaluate-option-expression).
* @param options
*/
evaluate<R>(
pageFunction: PageFunction<void, R>,
arg?: any,
options?: { exposeFunctions?: boolean },
): Promise<R>
/**
* Returns the return value of
* [`pageFunction`](https://playwright.dev/docs/api/class-frame#frame-evaluate-handle-option-expression) as a
* [JSHandle](https://playwright.dev/docs/api/class-jshandle).
*
* The only difference between
* [frame.evaluate(pageFunction[, arg, options])](https://playwright.dev/docs/api/class-frame#frame-evaluate) and
* [frame.evaluateHandle(pageFunction[, arg, options])](https://playwright.dev/docs/api/class-frame#frame-evaluate-handle)
* is that
* [frame.evaluateHandle(pageFunction[, arg, options])](https://playwright.dev/docs/api/class-frame#frame-evaluate-handle)
* returns [JSHandle](https://playwright.dev/docs/api/class-jshandle).
*
* If the function, passed to the
* [frame.evaluateHandle(pageFunction[, arg, options])](https://playwright.dev/docs/api/class-frame#frame-evaluate-handle),
* returns a [Promise], then
* [frame.evaluateHandle(pageFunction[, arg, options])](https://playwright.dev/docs/api/class-frame#frame-evaluate-handle)
* would wait for the promise to resolve and return its value.
*
* **Usage**
*
* ```js
* // Handle for the window object
* const aWindowHandle = await frame.evaluateHandle(() => Promise.resolve(window));
* ```
*
* A string can also be passed in instead of a function.
*
* ```js
* const aHandle = await frame.evaluateHandle('document'); // Handle for the 'document'.
* ```
*
* [JSHandle](https://playwright.dev/docs/api/class-jshandle) instances can be passed as an argument to the
* [frame.evaluateHandle(pageFunction[, arg, options])](https://playwright.dev/docs/api/class-frame#frame-evaluate-handle):
*
* ```js
* const aHandle = await frame.evaluateHandle(() => document.body);
* const resultHandle = await frame.evaluateHandle(([body, suffix]) =>
* body.innerHTML + suffix, [aHandle, 'hello'],
* );
* console.log(await resultHandle.jsonValue());
* await resultHandle.dispose();
* ```
*
* @param pageFunction Function to be evaluated in the page context.
* @param arg Optional argument to pass to
* [`pageFunction`](https://playwright.dev/docs/api/class-frame#frame-evaluate-handle-option-expression).
* @param options
*/
evaluateHandle<R, Arg>(
pageFunction: PageFunction<Arg, R>,
arg: Arg,
options?: { exposeFunctions?: boolean },
): Promise<SmartHandle<R>>
/**
* Returns the return value of
* [`pageFunction`](https://playwright.dev/docs/api/class-frame#frame-evaluate-handle-option-expression) as a
* [JSHandle](https://playwright.dev/docs/api/class-jshandle).
*
* The only difference between
* [frame.evaluate(pageFunction[, arg, options])](https://playwright.dev/docs/api/class-frame#frame-evaluate) and
* [frame.evaluateHandle(pageFunction[, arg, options])](https://playwright.dev/docs/api/class-frame#frame-evaluate-handle)
* is that
* [frame.evaluateHandle(pageFunction[, arg, options])](https://playwright.dev/docs/api/class-frame#frame-evaluate-handle)
* returns [JSHandle](https://playwright.dev/docs/api/class-jshandle).
*
* If the function, passed to the
* [frame.evaluateHandle(pageFunction[, arg, options])](https://playwright.dev/docs/api/class-frame#frame-evaluate-handle),
* returns a [Promise], then
* [frame.evaluateHandle(pageFunction[, arg, options])](https://playwright.dev/docs/api/class-frame#frame-evaluate-handle)
* would wait for the promise to resolve and return its value.
*
* **Usage**
*
* ```js
* // Handle for the window object
* const aWindowHandle = await frame.evaluateHandle(() => Promise.resolve(window));
* ```
*
* A string can also be passed in instead of a function.
*
* ```js
* const aHandle = await frame.evaluateHandle('document'); // Handle for the 'document'.
* ```
*
* [JSHandle](https://playwright.dev/docs/api/class-jshandle) instances can be passed as an argument to the
* [frame.evaluateHandle(pageFunction[, arg, options])](https://playwright.dev/docs/api/class-frame#frame-evaluate-handle):
*
* ```js
* const aHandle = await frame.evaluateHandle(() => document.body);
* const resultHandle = await frame.evaluateHandle(([body, suffix]) =>
* body.innerHTML + suffix, [aHandle, 'hello'],
* );
* console.log(await resultHandle.jsonValue());
* await resultHandle.dispose();
* ```
*
* @param pageFunction Function to be evaluated in the page context.
* @param arg Optional argument to pass to
* [`pageFunction`](https://playwright.dev/docs/api/class-frame#frame-evaluate-handle-option-expression).
* @param options
*/
evaluateHandle<R>(
pageFunction: PageFunction<void, R>,
arg?: any,
options?: { exposeFunctions?: boolean },
): Promise<SmartHandle<R>>
/**
* **NOTE** Use locator-based [frame.locator(selector[, options])](https://playwright.dev/docs/api/class-frame#frame-locator)
* instead. Read more about [locators](https://playwright.dev/docs/locators).
*
* Returns the ElementHandle pointing to the frame element.
*
* **NOTE** The use of [ElementHandle](https://playwright.dev/docs/api/class-elementhandle) is discouraged, use
* [Locator](https://playwright.dev/docs/api/class-locator) objects and web-first assertions instead.
*
* The method finds an element matching the specified selector within the frame. If no elements match the selector,
* returns `null`.
* @param selector A selector to query for.
* @param options
*/
$<K extends keyof HTMLElementTagNameMap>(
selector: K,
options?: { strict: boolean },
): Promise<ElementHandleForTag<K> | null>
/**
* **NOTE** Use locator-based [frame.locator(selector[, options])](https://playwright.dev/docs/api/class-frame#frame-locator)
* instead. Read more about [locators](https://playwright.dev/docs/locators).
*
* Returns the ElementHandle pointing to the frame element.
*
* **NOTE** The use of [ElementHandle](https://playwright.dev/docs/api/class-elementhandle) is discouraged, use
* [Locator](https://playwright.dev/docs/api/class-locator) objects and web-first assertions instead.
*
* The method finds an element matching the specified selector within the frame. If no elements match the selector,
* returns `null`.
* @param selector A selector to query for.
* @param options
*/
$(
selector: string,
options?: { strict: boolean },
): Promise<ElementHandle<SVGElement | HTMLElement> | null>
/**
* **NOTE** Use locator-based [frame.locator(selector[, options])](https://playwright.dev/docs/api/class-frame#frame-locator)
* instead. Read more about [locators](https://playwright.dev/docs/locators).
*
* Returns the ElementHandles pointing to the frame elements.
*
* **NOTE** The use of [ElementHandle](https://playwright.dev/docs/api/class-elementhandle) is discouraged, use
* [Locator](https://playwright.dev/docs/api/class-locator) objects instead.
*
* The method finds all elements matching the specified selector within the frame. If no elements match the selector,
* returns empty array.
* @param selector A selector to query for.
*/
$$<K extends keyof HTMLElementTagNameMap>(selector: K): Promise<ElementHandleForTag<K>[]>
/**
* **NOTE** Use locator-based [frame.locator(selector[, options])](https://playwright.dev/docs/api/class-frame#frame-locator)
* instead. Read more about [locators](https://playwright.dev/docs/locators).
*
* Returns the ElementHandles pointing to the frame elements.
*
* **NOTE** The use of [ElementHandle](https://playwright.dev/docs/api/class-elementhandle) is discouraged, use
* [Locator](https://playwright.dev/docs/api/class-locator) objects instead.
*
* The method finds all elements matching the specified selector within the frame. If no elements match the selector,
* returns empty array.
* @param selector A selector to query for.
*/
$$(selector: string): Promise<ElementHandle<SVGElement | HTMLElement>[]>
/**
* **NOTE** This method does not wait for the element to pass the actionability checks and therefore can lead to the flaky
* tests. Use
* [locator.evaluate(pageFunction[, arg, options])](https://playwright.dev/docs/api/class-locator#locator-evaluate),
* other [Locator](https://playwright.dev/docs/api/class-locator) helper methods or web-first assertions instead.
*
* Returns the return value of
* [`pageFunction`](https://playwright.dev/docs/api/class-frame#frame-eval-on-selector-option-expression).
*
* The method finds an element matching the specified selector within the frame and passes it as a first argument to
* [`pageFunction`](https://playwright.dev/docs/api/class-frame#frame-eval-on-selector-option-expression). If no
* elements match the selector, the method throws an error.
*
* If [`pageFunction`](https://playwright.dev/docs/api/class-frame#frame-eval-on-selector-option-expression) returns a
* [Promise], then
* [frame.$eval(selector, pageFunction[, arg, options])](https://playwright.dev/docs/api/class-frame#frame-eval-on-selector)
* would wait for the promise to resolve and return its value.
*
* **Usage**
*
* ```js
* const searchValue = await frame.$eval('#search', el => el.value);
* const preloadHref = await frame.$eval('link[rel=preload]', el => el.href);
* const html = await frame.$eval('.main-container', (e, suffix) => e.outerHTML + suffix, 'hello');
* ```
*
* @param selector A selector to query for.
* @param pageFunction Function to be evaluated in the page context.
* @param arg Optional argument to pass to
* [`pageFunction`](https://playwright.dev/docs/api/class-frame#frame-eval-on-selector-option-expression).
* @param options
*/
$eval<K extends keyof HTMLElementTagNameMap, R, Arg>(
selector: K,
pageFunction: PageFunctionOn<HTMLElementTagNameMap[K], Arg, R>,
arg: Arg,
): Promise<R>
/**
* **NOTE** This method does not wait for the element to pass the actionability checks and therefore can lead to the flaky
* tests. Use
* [locator.evaluate(pageFunction[, arg, options])](https://playwright.dev/docs/api/class-locator#locator-evaluate),
* other [Locator](https://playwright.dev/docs/api/class-locator) helper methods or web-first assertions instead.
*
* Returns the return value of
* [`pageFunction`](https://playwright.dev/docs/api/class-frame#frame-eval-on-selector-option-expression).
*
* The method finds an element matching the specified selector within the frame and passes it as a first argument to
* [`pageFunction`](https://playwright.dev/docs/api/class-frame#frame-eval-on-selector-option-expression). If no
* elements match the selector, the method throws an error.
*
* If [`pageFunction`](https://playwright.dev/docs/api/class-frame#frame-eval-on-selector-option-expression) returns a
* [Promise], then
* [frame.$eval(selector, pageFunction[, arg, options])](https://playwright.dev/docs/api/class-frame#frame-eval-on-selector)
* would wait for the promise to resolve and return its value.
*
* **Usage**
*
* ```js
* const searchValue = await frame.$eval('#search', el => el.value);
* const preloadHref = await frame.$eval('link[rel=preload]', el => el.href);
* const html = await frame.$eval('.main-container', (e, suffix) => e.outerHTML + suffix, 'hello');
* ```
*
* @param selector A selector to query for.
* @param pageFunction Function to be evaluated in the page context.
* @param arg Optional argument to pass to
* [`pageFunction`](https://playwright.dev/docs/api/class-frame#frame-eval-on-selector-option-expression).
* @param options
*/
$eval<R, Arg, E extends SVGElement | HTMLElement = SVGElement | HTMLElement>(
selector: string,
pageFunction: PageFunctionOn<E, Arg, R>,
arg: Arg,
): Promise<R>
/**
* **NOTE** This method does not wait for the element to pass the actionability checks and therefore can lead to the flaky
* tests. Use
* [locator.evaluate(pageFunction[, arg, options])](https://playwright.dev/docs/api/class-locator#locator-evaluate),
* other [Locator](https://playwright.dev/docs/api/class-locator) helper methods or web-first assertions instead.
*
* Returns the return value of
* [`pageFunction`](https://playwright.dev/docs/api/class-frame#frame-eval-on-selector-option-expression).
*
* The method finds an element matching the specified selector within the frame and passes it as a first argument to
* [`pageFunction`](https://playwright.dev/docs/api/class-frame#frame-eval-on-selector-option-expression). If no
* elements match the selector, the method throws an error.
*
* If [`pageFunction`](https://playwright.dev/docs/api/class-frame#frame-eval-on-selector-option-expression) returns a
* [Promise], then
* [frame.$eval(selector, pageFunction[, arg, options])](https://playwright.dev/docs/api/class-frame#frame-eval-on-selector)
* would wait for the promise to resolve and return its value.
*
* **Usage**
*
* ```js
* const searchValue = await frame.$eval('#search', el => el.value);
* const preloadHref = await frame.$eval('link[rel=preload]', el => el.href);
* const html = await frame.$eval('.main-container', (e, suffix) => e.outerHTML + suffix, 'hello');
* ```
*
* @param selector A selector to query for.
* @param pageFunction Function to be evaluated in the page context.
* @param arg Optional argument to pass to
* [`pageFunction`](https://playwright.dev/docs/api/class-frame#frame-eval-on-selector-option-expression).
* @param options
*/
$eval<K extends keyof HTMLElementTagNameMap, R>(
selector: K,
pageFunction: PageFunctionOn<HTMLElementTagNameMap[K], void, R>,
arg?: any,
): Promise<R>
/**
* **NOTE** This method does not wait for the element to pass the actionability checks and therefore can lead to the flaky
* tests. Use
* [locator.evaluate(pageFunction[, arg, options])](https://playwright.dev/docs/api/class-locator#locator-evaluate),
* other [Locator](https://playwright.dev/docs/api/class-locator) helper methods or web-first assertions instead.
*
* Returns the return value of
* [`pageFunction`](https://playwright.dev/docs/api/class-frame#frame-eval-on-selector-option-expression).
*
* The method finds an element matching the specified selector within the frame and passes it as a first argument to
* [`pageFunction`](https://playwright.dev/docs/api/class-frame#frame-eval-on-selector-option-expression). If no
* elements match the selector, the method throws an error.
*
* If [`pageFunction`](https://playwright.dev/docs/api/class-frame#frame-eval-on-selector-option-expression) returns a
* [Promise], then
* [frame.$eval(selector, pageFunction[, arg, options])](https://playwright.dev/docs/api/class-frame#frame-eval-on-selector)
* would wait for the promise to resolve and return its value.
*
* **Usage**
*
* ```js
* const searchValue = await frame.$eval('#search', el => el.value);
* const preloadHref = await frame.$eval('link[rel=preload]', el => el.href);
* const html = await frame.$eval('.main-container', (e, suffix) => e.outerHTML + suffix, 'hello');
* ```
*
* @param selector A selector to query for.
* @param pageFunction Function to be evaluated in the page context.
* @param arg Optional argument to pass to
* [`pageFunction`](https://playwright.dev/docs/api/class-frame#frame-eval-on-selector-option-expression).
* @param options
*/
$eval<R, E extends SVGElement | HTMLElement = SVGElement | HTMLElement>(
selector: string,
pageFunction: PageFunctionOn<E, void, R>,
arg?: any,
): Promise<R>
/**
* **NOTE** In most cases,
* [locator.evaluateAll(pageFunction[, arg])](https://playwright.dev/docs/api/class-locator#locator-evaluate-all),
* other [Locator](https://playwright.dev/docs/api/class-locator) helper methods and web-first assertions do a better
* job.
*
* Returns the return value of
* [`pageFunction`](https://playwright.dev/docs/api/class-frame#frame-eval-on-selector-all-option-expression).
*
* The method finds all elements matching the specified selector within the frame and passes an array of matched
* elements as a first argument to
* [`pageFunction`](https://playwright.dev/docs/api/class-frame#frame-eval-on-selector-all-option-expression).
*
* If [`pageFunction`](https://playwright.dev/docs/api/class-frame#frame-eval-on-selector-all-option-expression)
* returns a [Promise], then
* [frame.$$eval(selector, pageFunction[, arg])](https://playwright.dev/docs/api/class-frame#frame-eval-on-selector-all)
* would wait for the promise to resolve and return its value.
*
* **Usage**
*
* ```js
* const divsCounts = await frame.$$eval('div', (divs, min) => divs.length >= min, 10);
* ```
*
* @param selector A selector to query for.
* @param pageFunction Function to be evaluated in the page context.
* @param arg Optional argument to pass to
* [`pageFunction`](https://playwright.dev/docs/api/class-frame#frame-eval-on-selector-all-option-expression).
*/
$$eval<K extends keyof HTMLElementTagNameMap, R, Arg>(
selector: K,
pageFunction: PageFunctionOn<HTMLElementTagNameMap[K][], Arg, R>,
arg: Arg,
): Promise<R>
/**
* **NOTE** In most cases,
* [locator.evaluateAll(pageFunction[, arg])](https://playwright.dev/docs/api/class-locator#locator-evaluate-all),
* other [Locator](https://playwright.dev/docs/api/class-locator) helper methods and web-first assertions do a better
* job.
*
* Returns the return value of
* [`pageFunction`](https://playwright.dev/docs/api/class-frame#frame-eval-on-selector-all-option-expression).
*
* The method finds all elements matching the specified selector within the frame and passes an array of matched
* elements as a first argument to
* [`pageFunction`](https://playwright.dev/docs/api/class-frame#frame-eval-on-selector-all-option-expression).
*
* If [`pageFunction`](https://playwright.dev/docs/api/class-frame#frame-eval-on-selector-all-option-expression)
* returns a [Promise], then
* [frame.$$eval(selector, pageFunction[, arg])](https://playwright.dev/docs/api/class-frame#frame-eval-on-selector-all)
* would wait for the promise to resolve and return its value.
*
* **Usage**
*
* ```js
* const divsCounts = await frame.$$eval('div', (divs, min) => divs.length >= min, 10);
* ```
*
* @param selector A selector to query for.
* @param pageFunction Function to be evaluated in the page context.
* @param arg Optional argument to pass to
* [`pageFunction`](https://playwright.dev/docs/api/class-frame#frame-eval-on-selector-all-option-expression).
*/
$$eval<R, Arg, E extends SVGElement | HTMLElement = SVGElement | HTMLElement>(
selector: string,
pageFunction: PageFunctionOn<E[], Arg, R>,
arg: Arg,
): Promise<R>
/**
* **NOTE** In most cases,
* [locator.evaluateAll(pageFunction[, arg])](https://playwright.dev/docs/api/class-locator#locator-evaluate-all),
* other [Locator](https://playwright.dev/docs/api/class-locator) helper methods and web-first assertions do a better
* job.
*
* Returns the return value of
* [`pageFunction`](https://playwright.dev/docs/api/class-frame#frame-eval-on-selector-all-option-expression).
*
* The method finds all elements matching the specified selector within the frame and passes an array of matched
* elements as a first argument to
* [`pageFunction`](https://playwright.dev/docs/api/class-frame#frame-eval-on-selector-all-option-expression).
*
* If [`pageFunction`](https://playwright.dev/docs/api/class-frame#frame-eval-on-selector-all-option-expression)
* returns a [Promise], then
* [frame.$$eval(selector, pageFunction[, arg])](https://playwright.dev/docs/api/class-frame#frame-eval-on-selector-all)
* would wait for the promise to resolve and return its value.
*
* **Usage**
*
* ```js
* const divsCounts = await frame.$$eval('div', (divs, min) => divs.length >= min, 10);
* ```
*
* @param selector A selector to query for.
* @param pageFunction Function to be evaluated in the page context.
* @param arg Optional argument to pass to
* [`pageFunction`](https://playwright.dev/docs/api/class-frame#frame-eval-on-selector-all-option-expression).
*/
$$eval<K extends keyof HTMLElementTagNameMap, R>(
selector: K,
pageFunction: PageFunctionOn<HTMLElementTagNameMap[K][], void, R>,
arg?: any,
): Promise<R>
/**
* **NOTE** In most cases,
* [locator.evaluateAll(pageFunction[, arg])](https://playwright.dev/docs/api/class-locator#locator-evaluate-all),
* other [Locator](https://playwright.dev/docs/api/class-locator) helper methods and web-first assertions do a better
* job.
*
* Returns the return value of
* [`pageFunction`](https://playwright.dev/docs/api/class-frame#frame-eval-on-selector-all-option-expression).
*
* The method finds all elements matching the specified selector within the frame and passes an array of matched
* elements as a first argument to
* [`pageFunction`](https://playwright.dev/docs/api/class-frame#frame-eval-on-selector-all-option-expression).
*
* If [`pageFunction`](https://playwright.dev/docs/api/class-frame#frame-eval-on-selector-all-option-expression)
* returns a [Promise], then
* [frame.$$eval(selector, pageFunction[, arg])](https://playwright.dev/docs/api/class-frame#frame-eval-on-selector-all)
* would wait for the promise to resolve and return its value.
*
* **Usage**
*
* ```js
* const divsCounts = await frame.$$eval('div', (divs, min) => divs.length >= min, 10);
* ```
*
* @param selector A selector to query for.
* @param pageFunction Function to be evaluated in the page context.
* @param arg Optional argument to pass to
* [`pageFunction`](https://playwright.dev/docs/api/class-frame#frame-eval-on-selector-all-option-expression).
*/
$$eval<R, E extends SVGElement | HTMLElement = SVGElement | HTMLElement>(
selector: string,
pageFunction: PageFunctionOn<E[], void, R>,
arg?: any,
): Promise<R>
/**
* Returns when the
* [`pageFunction`](https://playwright.dev/docs/api/class-frame#frame-wait-for-function-option-expression) returns a
* truthy value, returns that value.
*
* **Usage**
*
* The
* [frame.waitForFunction(pageFunction[, arg, options])](https://playwright.dev/docs/api/class-frame#frame-wait-for-function)
* can be used to observe viewport size change:
*
* ```js
* const { firefox } = require('playwright'); // Or 'chromium' or 'webkit'.
*
* (async () => {
* const browser = await firefox.launch();
* const page = await browser.newPage();
* const watchDog = page.mainFrame().waitForFunction('window.innerWidth < 100');
* await page.setViewportSize({ width: 50, height: 50 });
* await watchDog;
* await browser.close();
* })();
* ```
*
* To pass an argument to the predicate of `frame.waitForFunction` function:
*
* ```js
* const selector = '.foo';
* await frame.waitForFunction(selector => !!document.querySelector(selector), selector);
* ```
*
* @param pageFunction Function to be evaluated in the page context.
* @param arg Optional argument to pass to
* [`pageFunction`](https://playwright.dev/docs/api/class-frame#frame-wait-for-function-option-expression).
* @param options
*/
waitForFunction<R, Arg>(
pageFunction: PageFunction<Arg, R>,
arg: Arg,
options?: PageWaitForFunctionOptions,
): Promise<SmartHandle<R>>
/**
* Returns when the
* [`pageFunction`](https://playwright.dev/docs/api/class-frame#frame-wait-for-function-option-expression) returns a
* truthy value, returns that value.
*
* **Usage**
*
* The
* [frame.waitForFunction(pageFunction[, arg, options])](https://playwright.dev/docs/api/class-frame#frame-wait-for-function)
* can be used to observe viewport size change:
*
* ```js
* const { firefox } = require('playwright'); // Or 'chromium' or 'webkit'.
*
* (async () => {
* const browser = await firefox.launch();
* const page = await browser.newPage();
* const watchDog = page.mainFrame().waitForFunction('window.innerWidth < 100');
* await page.setViewportSize({ width: 50, height: 50 });
* await watchDog;
* await browser.close();
* })();
* ```
*
* To pass an argument to the predicate of `frame.waitForFunction` function:
*
* ```js
* const selector = '.foo';
* await frame.waitForFunction(selector => !!document.querySelector(selector), selector);
* ```
*
* @param pageFunction Function to be evaluated in the page context.
* @param arg Optional argument to pass to
* [`pageFunction`](https://playwright.dev/docs/api/class-frame#frame-wait-for-function-option-expression).
* @param options
*/
waitForFunction<R>(
pageFunction: PageFunction<void, R>,
arg?: any,
options?: PageWaitForFunctionOptions,
): Promise<SmartHandle<R>>
/**
* **NOTE** Use web assertions that assert visibility or a locator-based
* [locator.waitFor([options])](https://playwright.dev/docs/api/class-locator#locator-wait-for) instead. Read more
* about [locators](https://playwright.dev/docs/locators).
*
* Returns when element specified by selector satisfies
* [`state`](https://playwright.dev/docs/api/class-frame#frame-wait-for-selector-option-state) option. Returns `null`
* if waiting for `hidden` or `detached`.
*
* **NOTE** Playwright automatically waits for element to be ready before performing an action. Using
* [Locator](https://playwright.dev/docs/api/class-locator) objects and web-first assertions make the code
* wait-for-selector-free.
*
* Wait for the [`selector`](https://playwright.dev/docs/api/class-frame#frame-wait-for-selector-option-selector) to
* satisfy [`state`](https://playwright.dev/docs/api/class-frame#frame-wait-for-selector-option-state) option (either
* appear/disappear from dom, or become visible/hidden). If at the moment of calling the method
* [`selector`](https://playwright.dev/docs/api/class-frame#frame-wait-for-selector-option-selector) already satisfies
* the condition, the method will return immediately. If the selector doesn't satisfy the condition for the
* [`timeout`](https://playwright.dev/docs/api/class-frame#frame-wait-for-selector-option-timeout) milliseconds, the
* function will throw.
*
* **Usage**
*
* This method works across navigations:
*
* ```js
* const { chromium } = require('playwright'); // Or 'firefox' or 'webkit'.
*
* (async () => {
* const browser = await chromium.launch();
* const page = await browser.newPage();
* for (const currentURL of ['https://google.com', 'https://bbc.com']) {
* await page.goto(currentURL);
* const element = await page.mainFrame().waitForSelector('img');
* console.log('Loaded image: ' + await element.getAttribute('src'));
* }
* await browser.close();
* })();
* ```
*
* @param selector A selector to query for.
* @param options
*/
waitForSelector<K extends keyof HTMLElementTagNameMap>(
selector: K,
options?: PageWaitForSelectorOptionsNotHidden,
): Promise<ElementHandleForTag<K>>
/**
* **NOTE** Use web assertions that assert visibility or a locator-based
* [locator.waitFor([options])](https://playwright.dev/docs/api/class-locator#locator-wait-for) instead. Read more
* about [locators](https://playwright.dev/docs/locators).
*
* Returns when element specified by selector satisfies
* [`state`](https://playwright.dev/docs/api/class-frame#frame-wait-for-selector-option-state) option. Returns `null`
* if waiting for `hidden` or `detached`.
*
* **NOTE** Playwright automatically waits for element to be ready before performing an action. Using
* [Locator](https://playwright.dev/docs/api/class-locator) objects and web-first assertions make the code
* wait-for-selector-free.
*
* Wait for the [`selector`](https://playwright.dev/docs/api/class-frame#frame-wait-for-selector-option-selector) to
* satisfy [`state`](https://playwright.dev/docs/api/class-frame#frame-wait-for-selector-option-state) option (either
* appear/disappear from dom, or become visible/hidden). If at the moment of calling the method
* [`selector`](https://playwright.dev/docs/api/class-frame#frame-wait-for-selector-option-selector) already satisfies
* the condition, the method will return immediately. If the selector doesn't satisfy the condition for the
* [`timeout`](https://playwright.dev/docs/api/class-frame#frame-wait-for-selector-option-timeout) milliseconds, the
* function will throw.
*
* **Usage**
*
* This method works across navigations:
*
* ```js
* const { chromium } = require('playwright'); // Or 'firefox' or 'webkit'.
*
* (async () => {
* const browser = await chromium.launch();
* const page = await browser.newPage();
* for (const currentURL of ['https://google.com', 'https://bbc.com']) {
* await page.goto(currentURL);
* const element = await page.mainFrame().waitForSelector('img');
* console.log('Loaded image: ' + await element.getAttribute('src'));
* }
* await browser.close();
* })();
* ```
*
* @param selector A selector to query for.
* @param options
*/
waitForSelector(
selector: string,
options?: PageWaitForSelectorOptionsNotHidden,
): Promise<ElementHandle<SVGElement | HTMLElement>>
/**
* **NOTE** Use web assertions that assert visibility or a locator-based
* [locator.waitFor([options])](https://playwright.dev/docs/api/class-locator#locator-wait-for) instead. Read more
* about [locators](https://playwright.dev/docs/locators).
*
* Returns when element specified by selector satisfies
* [`state`](https://playwright.dev/docs/api/class-frame#frame-wait-for-selector-option-state) option. Returns `null`
* if waiting for `hidden` or `detached`.
*
* **NOTE** Playwright automatically waits for element to be ready before performing an action. Using
* [Locator](https://playwright.dev/docs/api/class-locator) objects and web-first assertions make the code
* wait-for-selector-free.
*
* Wait for the [`selector`](https://playwright.dev/docs/api/class-frame#frame-wait-for-selector-option-selector) to
* satisfy [`state`](https://playwright.dev/docs/api/class-frame#frame-wait-for-selector-option-state) option (either
* appear/disappear from dom, or become visible/hidden). If at the moment of calling the method
* [`selector`](https://playwright.dev/docs/api/class-frame#frame-wait-for-selector-option-selector) already satisfies
* the condition, the method will return immediately. If the selector doesn't satisfy the condition for the
* [`timeout`](https://playwright.dev/docs/api/class-frame#frame-wait-for-selector-option-timeout) milliseconds, the
* function will throw.
*
* **Usage**
*
* This method works across navigations:
*
* ```js
* const { chromium } = require('playwright'); // Or 'firefox' or 'webkit'.
*
* (async () => {
* const browser = await chromium.launch();
* const page = await browser.newPage();
* for (const currentURL of ['https://google.com', 'https://bbc.com']) {
* await page.goto(currentURL);
* const element = await page.mainFrame().waitForSelector('img');
* console.log('Loaded image: ' + await element.getAttribute('src'));
* }
* await browser.close();
* })();
* ```
*
* @param selector A selector to query for.
* @param options
*/
waitForSelector<K extends keyof HTMLElementTagNameMap>(
selector: K,
options: PageWaitForSelectorOptions,
): Promise<ElementHandleForTag<K> | null>
/**
* **NOTE** Use web assertions that assert visibility or a locator-based
* [locator.waitFor([options])](https://playwright.dev/docs/api/class-locator#locator-wait-for) instead. Read more
* about [locators](https://playwright.dev/docs/locators).
*
* Returns when element specified by selector satisfies
* [`state`](https://playwright.dev/docs/api/class-frame#frame-wait-for-selector-option-state) option. Returns `null`
* if waiting for `hidden` or `detached`.
*
* **NOTE** Playwright automatically waits for element to be ready before performing an action. Using
* [Locator](https://playwright.dev/docs/api/class-locator) objects and web-first assertions make the code
* wait-for-selector-free.
*
* Wait for the [`selector`](https://playwright.dev/docs/api/class-frame#frame-wait-for-selector-option-selector) to
* satisfy [`state`](https://playwright.dev/docs/api/class-frame#frame-wait-for-selector-option-state) option (either
* appear/disappear from dom, or become visible/hidden). If at the moment of calling the method
* [`selector`](https://playwright.dev/docs/api/class-frame#frame-wait-for-selector-option-selector) already satisfies
* the condition, the method will return immediately. If the selector doesn't satisfy the condition for the
* [`timeout`](https://playwright.dev/docs/api/class-frame#frame-wait-for-selector-option-timeout) milliseconds, the
* function will throw.
*
* **Usage**
*
* This method works across navigations:
*
* ```js
* const { chromium } = require('playwright'); // Or 'firefox' or 'webkit'.
*
* (async () => {
* const browser = await chromium.launch();
* const page = await browser.newPage();
* for (const currentURL of ['https://google.com', 'https://bbc.com']) {
* await page.goto(currentURL);
* const element = await page.mainFrame().waitForSelector('img');
* console.log('Loaded image: ' + await element.getAttribute('src'));
* }
* await browser.close();
* })();
* ```
*
* @param selector A selector to query for.
* @param options
*/
waitForSelector(
selector: string,
options: PageWaitForSelectorOptions,
): Promise<null | ElementHandle<SVGElement | HTMLElement>>
/**
* Returns the added tag when the script's onload fires or when the script content was injected into frame.
*
* Adds a `<script>` tag into the page with the desired url or content.
* @param options
*/
addScriptTag(options?: {
/**
* Raw JavaScript content to be injected into frame.
*/
content?: string
/**
* Path to the JavaScript file to be injected into frame. If `path` is a relative path, then it is resolved relative
* to the current working directory.
*/
path?: string
/**
* Script type. Use 'module' in order to load a JavaScript ES6 module. See
* [script](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/script) for more details.
*/
type?: string
/**
* URL of a script to be added.
*/
url?: string
}): Promise<ElementHandle>
/**
* Returns the added tag when the stylesheet's onload fires or when the CSS content was injected into frame.
*
* Adds a `<link rel="stylesheet">` tag into the page with the desired url or a `<style type="text/css">` tag with the
* content.
* @param options
*/
addStyleTag(options?: {
/**
* Raw CSS content to be injected into frame.
*/
content?: string
/**
* Path to the CSS file to be injected into frame. If `path` is a relative path, then it is resolved relative to the
* current working directory.
*/
path?: string
/**
* URL of the `<link>` tag.
*/
url?: string
}): Promise<ElementHandle>
/**
* **NOTE** Use locator-based [locator.check([options])](https://playwright.dev/docs/api/class-locator#locator-check) instead.
* Read more about [locators](https://playwright.dev/docs/locators).
*
* This method checks an element matching
* [`selector`](https://playwright.dev/docs/api/class-frame#frame-check-option-selector) by performing the following
* steps:
* 1. Find an element matching
* [`selector`](https://playwright.dev/docs/api/class-frame#frame-check-option-selector). If there is none, wait
* until a matching element is attached to the DOM.
* 1. Ensure that matched element is a checkbox or a radio input. If not, this method throws. If the element is
* already checked, this method returns immediately.
* 1. Wait for [actionability](https://playwright.dev/docs/actionability) checks on the matched element, unless
* [`force`](https://playwright.dev/docs/api/class-frame#frame-check-option-force) option is set. If the element
* is detached during the checks, the whole action is retried.
* 1. Scroll the element into view if needed.
* 1. Use [page.mouse](https://playwright.dev/docs/api/class-page#page-mouse) to click in the center of the
* element.
* 1. Ensure that the element is now checked. If not, this method throws.
*
* When all steps combined have not finished during the specified
* [`timeout`](https://playwright.dev/docs/api/class-frame#frame-check-option-timeout), this method throws a
* [TimeoutError](https://playwright.dev/docs/api/class-timeouterror). Passing zero timeout disables this.
* @param selector A selector to search for an element. If there are multiple elements satisfying the selector, the first will be
* used.
* @param options
*/
check(
selector: string,
options?: {
/**
* Whether to bypass the [actionability](https://playwright.dev/docs/actionability) checks. Defaults to `false`.
*/
force?: boolean
/**
* This option has no effect.
* @deprecated This option has no effect.
*/
noWaitAfter?: boolean
/**
* A point to use relative to the top-left corner of element padding box. If not specified, uses some visible point of
* the element.
*/
position?: {
x: number
y: number
}
/**
* Controls whether Playwright scrolls the element into view before performing the action. Defaults to `"auto"`, which
* scrolls the element into view when necessary, including scrolling nested scrollable containers. When set to
* `"none"`, Playwright does not scroll the element and the action fails if the element is not already in the
* viewport. This is useful to assert that an element is reachable by the user without additional scrolling.
*/
scroll?: 'auto' | 'none'
/**
* Allows to cancel the operation using an
* [`AbortSignal`](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal). If the signal is aborted, the
* operation will be aborted and throw an error. Note that providing a signal does not disable the default timeout,
* which can be changed using
* [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); pass
* `timeout: 0` to disable the timeout entirely.
*/
signal?: AbortSignal
/**
* 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.
*/
strict?: boolean
/**
* Maximum time in milliseconds. Defaults to `0` - no timeout. The default value can be changed via `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.
*/
timeout?: number
/**
* When set, this method only performs the [actionability](https://playwright.dev/docs/actionability) checks and skips the action. Defaults
* to `false`. Useful to wait until the element is ready for the action without performing it.
*/
trial?: boolean
},
): Promise<void>
childFrames(): Array<Frame>
/**
* **NOTE** Use locator-based [locator.click([options])](https://playwright.dev/docs/api/class-locator#locator-click) instead.
* Read more about [locators](https://playwright.dev/docs/locators).
*
* This method clicks an element matching
* [`selector`](https://playwright.dev/docs/api/class-frame#frame-click-option-selector) by performing the following
* steps:
* 1. Find an element matching
* [`selector`](https://playwright.dev/docs/api/class-frame#frame-click-option-selector). If there is none, wait
* until a matching element is attached to the DOM.
* 1. Wait for [actionability](https://playwright.dev/docs/actionability) checks on the matched element, unless
* [`force`](https://playwright.dev/docs/api/class-frame#frame-click-option-force) option is set. If the element
* is detached during the checks, the whole action is retried.
* 1. Scroll the element into view if needed.
* 1. Use [page.mouse](https://playwright.dev/docs/api/class-page#page-mouse) to click in the center of the
* element, or the specified
* [`position`](https://playwright.dev/docs/api/class-frame#frame-click-option-position).
* 1. Wait for initiated navigations to either succeed or fail, unless
* [`noWaitAfter`](https://playwright.dev/docs/api/class-frame#frame-click-option-no-wait-after) option is set.
*
* When all steps combined have not finished during the specified
* [`timeout`](https://playwright.dev/docs/api/class-frame#frame-click-option-timeout), this method throws a
* [TimeoutError](https://playwright.dev/docs/api/class-timeouterror). Passing zero timeout disables this.
* @param selector A selector to search for an element. If there are multiple elements satisfying the selector, the first will be
* used.
* @param options
*/
click(
selector: string,
options?: {
/**
* Defaults to `left`.
*/
button?: 'left' | 'right' | 'middle'
/**
* defaults to 1. See [UIEvent.detail].
*/
clickCount?: number
/**
* Time to wait between `mousedown` and `mouseup` in milliseconds. Defaults to 0.
*/
delay?: number
/**
* Whether to bypass the [actionability](https://playwright.dev/docs/actionability) checks. Defaults to `false`.
*/
force?: boolean
/**
* Modifier keys to press. Ensures that only these modifiers are pressed during the operation, and then restores
* current modifiers back. If not specified, currently pressed modifiers are used. "ControlOrMeta" resolves to
* "Control" on Windows and Linux and to "Meta" on macOS.
*/
modifiers?: Array<'Alt' | 'Control' | 'ControlOrMeta' | 'Meta' | 'Shift'>
/**
* Actions that initiate navigations are waiting for these navigations to happen and for pages to start loading. You
* can opt out of waiting via setting this flag. You would only need this option in the exceptional cases such as
* navigating to inaccessible pages. Defaults to `false`.
* @deprecated This option will default to `true` in the future.
*/
noWaitAfter?: boolean
/**
* A point to use relative to the top-left corner of element padding box. If not specified, uses some visible point of
* the element.
*/
position?: {
x: number
y: number
}
/**
* Controls whether Playwright scrolls the element into view before performing the action. Defaults to `"auto"`, which
* scrolls the element into view when necessary, including scrolling nested scrollable containers. When set to
* `"none"`, Playwright does not scroll the element and the action fails if the element is not already in the
* viewport. This is useful to assert that an element is reachable by the user without additional scrolling.
*/
scroll?: 'auto' | 'none'
/**
* Allows to cancel the operation using an
* [`AbortSignal`](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal). If the signal is aborted, the
* operation will be aborted and throw an error. Note that providing a signal does not disable the default timeout,
* which can be changed using
* [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); pass
* `timeout: 0` to disable the timeout entirely.
*/
signal?: AbortSignal
/**
* 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.
*/
strict?: boolean
/**
* Maximum time in milliseconds. Defaults to `0` - no timeout. The default value can be changed via `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.
*/
timeout?: number
/**
* When set, this method only performs the [actionability](https://playwright.dev/docs/actionability) checks and skips the action. Defaults
* to `false`. Useful to wait until the element is ready for the action without performing it. Note that keyboard
* `modifiers` will be pressed regardless of `trial` to allow testing elements which are only visible when those keys
* are pressed.
*/
trial?: boolean
},
): Promise<void>
/**
* Gets the full HTML contents of the frame, including the doctype.
*/
content(): Promise<string>
/**
* **NOTE** Use locator-based [locator.dblclick([options])](https://playwright.dev/docs/api/class-locator#locator-dblclick)
* instead. Read more about [locators](https://playwright.dev/docs/locators).
*
* This method double clicks an element matching
* [`selector`](https://playwright.dev/docs/api/class-frame#frame-dblclick-option-selector) by performing the
* following steps:
* 1. Find an element matching
* [`selector`](https://playwright.dev/docs/api/class-frame#frame-dblclick-option-selector). If there is none,
* wait until a matching element is attached to the DOM.
* 1. Wait for [actionability](https://playwright.dev/docs/actionability) checks on the matched element, unless
* [`force`](https://playwright.dev/docs/api/class-frame#frame-dblclick-option-force) option is set. If the
* element is detached during the checks, the whole action is retried.
* 1. Scroll the element into view if needed.
* 1. Use [page.mouse](https://playwright.dev/docs/api/class-page#page-mouse) to double click in the center of the
* element, or the specified
* [`position`](https://playwright.dev/docs/api/class-frame#frame-dblclick-option-position). if the first click
* of the `dblclick()` triggers a navigation event, this method will throw.
*
* When all steps combined have not finished during the specified
* [`timeout`](https://playwright.dev/docs/api/class-frame#frame-dblclick-option-timeout), this method throws a
* [TimeoutError](https://playwright.dev/docs/api/class-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
*/
dblclick(
selector: string,
options?: {
/**
* Defaults to `left`.
*/
button?: 'left' | 'right' | 'middle'
/**
* Time to wait between `mousedown` and `mouseup` in milliseconds. Defaults to 0.
*/
delay?: number
/**
* Whether to bypass the [actionability](https://playwright.dev/docs/actionability) checks. Defaults to `false`.
*/
force?: boolean
/**
* Modifier keys to press. Ensures that only these modifiers are pressed during the operation, and then restores
* current modifiers back. If not specified, currently pressed modifiers are used. "ControlOrMeta" resolves to
* "Control" on Windows and Linux and to "Meta" on macOS.
*/
modifiers?: Array<'Alt' | 'Control' | 'ControlOrMeta' | 'Meta' | 'Shift'>
/**
* This option has no effect.
* @deprecated This option has no effect.
*/
noWaitAfter?: boolean
/**
* A point to use relative to the top-left corner of element padding box. If not specified, uses some visible point of
* the element.
*/
position?: {
x: number
y: number
}
/**
* Controls whether Playwright scrolls the element into view before performing the action. Defaults to `"auto"`, which
* scrolls the element into view when necessary, including scrolling nested scrollable containers. When set to
* `"none"`, Playwright does not scroll the element and the action fails if the element is not already in the
* viewport. This is useful to assert that an element is reachable by the user without additional scrolling.
*/
scroll?: 'auto' | 'none'
/**
* Allows to cancel the operation using an
* [`AbortSignal`](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal). If the signal is aborted, the
* operation will be aborted and throw an error. Note that providing a signal does not disable the default timeout,
* which can be changed using
* [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); pass
* `timeout: 0` to disable the timeout entirely.
*/
signal?: AbortSignal
/**
* 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.
*/
strict?: boolean
/**
* Maximum time in milliseconds. Defaults to `0` - no timeout. The default value can be changed via `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.
*/
timeout?: number
/**
* When set, this method only performs the [actionability](https://playwright.dev/docs/actionability) checks and skips the action. Defaults
* to `false`. Useful to wait until the element is ready for the action without performing it. Note that keyboard
* `modifiers` will be pressed regardless of `trial` to allow testing elements which are only visible when those keys
* are pressed.
*/
trial?: boolean
},
): Promise<void>
/**
* **NOTE** Use locator-based
* [locator.dispatchEvent(type[, eventInit, options])](https://playwright.dev/docs/api/class-locator#locator-dispatch-event)
* instead. Read more about [locators](https://playwright.dev/docs/locators).
*
* The snippet below dispatches the `click` event on the element. Regardless of the visibility state of the element,
* `click` is dispatched. This is equivalent to calling
* [element.click()](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/click).
*
* **Usage**
*
* ```js
* await frame.dispatchEvent('button#submit', 'click');
* ```
*
* Under the hood, it creates an instance of an event based on the given
* [`type`](https://playwright.dev/docs/api/class-frame#frame-dispatch-event-option-type), initializes it with
* [`eventInit`](https://playwright.dev/docs/api/class-frame#frame-dispatch-event-option-event-init) properties and
* dispatches it on the element. Events are `composed`, `cancelable` and bubble by default.
*
* Since [`eventInit`](https://playwright.dev/docs/api/class-frame#frame-dispatch-event-option-event-init) is
* event-specific, please refer to the events documentation for the lists of initial properties:
* - [DeviceMotionEvent](https://developer.mozilla.org/en-US/docs/Web/API/DeviceMotionEvent/DeviceMotionEvent)
* - [DeviceOrientationEvent](https://developer.mozilla.org/en-US/docs/Web/API/DeviceOrientationEvent/DeviceOrientationEvent)
* - [DragEvent](https://developer.mozilla.org/en-US/docs/Web/API/DragEvent/DragEvent)
* - [Event](https://developer.mozilla.org/en-US/docs/Web/API/Event/Event)
* - [FocusEvent](https://developer.mozilla.org/en-US/docs/Web/API/FocusEvent/FocusEvent)
* - [KeyboardEvent](https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/KeyboardEvent)
* - [MouseEvent](https://developer.mozilla.org/en-US/docs/Web/API/MouseEvent/MouseEvent)
* - [PointerEvent](https://developer.mozilla.org/en-US/docs/Web/API/PointerEvent/PointerEvent)
* - [TouchEvent](https://developer.mozilla.org/en-US/docs/Web/API/TouchEvent/TouchEvent)
* - [WheelEvent](https://developer.mozilla.org/en-US/docs/Web/API/WheelEvent/WheelEvent)
*
* You can also specify `JSHandle` as the property value if you want live objects to be passed into the event:
*
* ```js
* // Note you can only create DataTransfer in Chromium and Firefox
* const dataTransfer = await frame.evaluateHandle(() => new DataTransfer());
* await frame.dispatchEvent('#source', 'dragstart', { dataTransfer });
* ```
*
* @param selector A selector to search for an element. If there are multiple elements satisfying the selector, the first will be
* used.
* @param type DOM event type: `"click"`, `"dragstart"`, etc.
* @param eventInit Optional event-specific initialization properties.
* @param options
*/
dispatchEvent(
selector: string,
type: string,
eventInit?: EvaluationArgument,
options?: {
/**
* Allows to cancel the operation using an
* [`AbortSignal`](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal). If the signal is aborted, the
* operation will be aborted and throw an error. Note that providing a signal does not disable the default timeout,
* which can be changed using
* [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); pass
* `timeout: 0` to disable the timeout entirely.
*/
signal?: AbortSignal
/**
* 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.
*/
strict?: boolean
/**
* Maximum time in milliseconds. Defaults to `0` - no timeout. The default value can be changed via `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.
*/
timeout?: number
},
): Promise<void>
/**
* @param source A selector to search for an element to drag. If there are multiple elements satisfying the selector, the first will
* be used.
* @param target A selector to search for an element to drop onto. If there are multiple elements satisfying the selector, the first
* will be used.
* @param options
*/
dragAndDrop(
source: string,
target: string,
options?: {
/**
* Whether to bypass the [actionability](https://playwright.dev/docs/actionability) checks. Defaults to `false`.
*/
force?: boolean
/**
* This option has no effect.
* @deprecated This option has no effect.
*/
noWaitAfter?: boolean
/**
* Controls whether Playwright scrolls the element into view before performing the action. Defaults to `"auto"`, which
* scrolls the element into view when necessary, including scrolling nested scrollable containers. When set to
* `"none"`, Playwright does not scroll the element and the action fails if the element is not already in the
* viewport. This is useful to assert that an element is reachable by the user without additional scrolling.
*/
scroll?: 'auto' | 'none'
/**
* Allows to cancel the operation using an
* [`AbortSignal`](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal). If the signal is aborted, the
* operation will be aborted and throw an error. Note that providing a signal does not disable the default timeout,
* which can be changed using
* [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); pass
* `timeout: 0` to disable the timeout entirely.
*/
signal?: AbortSignal
/**
* Clicks on the source element at this point relative to the top-left corner of the element's padding box. If not
* specified, some visible point of the element is used.
*/
sourcePosition?: {
x: number
y: number
}
/**
* Defaults to 1. Sends `n` interpolated `mousemove` events to represent travel between the `mousedown` and `mouseup`
* of the drag. When set to 1, emits a single `mousemove` event at the destination location.
*/
steps?: number
/**
* 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.
*/
strict?: boolean
/**
* Drops on the target element at this point relative to the top-left corner of the element's padding box. If not
* specified, some visible point of the element is used.
*/
targetPosition?: {
x: number
y: number
}
/**
* Maximum time in milliseconds. Defaults to `0` - no timeout. The default value can be changed via `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.
*/
timeout?: number
/**
* When set, this method only performs the [actionability](https://playwright.dev/docs/actionability) checks and skips the action. Defaults
* to `false`. Useful to wait until the element is ready for the action without performing it.
*/
trial?: boolean
},
): Promise<void>
/**
* **NOTE** Use locator-based [locator.fill(value[, options])](https://playwright.dev/docs/api/class-locator#locator-fill)
* instead. Read more about [locators](https://playwright.dev/docs/locators).
*
* This method waits for an element matching
* [`selector`](https://playwright.dev/docs/api/class-frame#frame-fill-option-selector), waits for
* [actionability](https://playwright.dev/docs/actionability) checks, focuses the element, fills it and triggers an `input` event after
* filling. Note that you can pass an empty string to clear the input field.
*
* If the target element is not an `<input>`, `<textarea>` or `[contenteditable]` element, this method throws an
* error. However, if the element is inside the `<label>` element that has an associated
* [control](https://developer.mozilla.org/en-US/docs/Web/API/HTMLLabelElement/control), the control will be filled
* instead.
*
* To send fine-grained keyboard events, use
* [locator.pressSequentially(text[, options])](https://playwright.dev/docs/api/class-locator#locator-press-sequentially).
* @param selector A selector to search for an element. If there are multiple elements satisfying the selector, the first will be
* used.
* @param value Value to fill for the `<input>`, `<textarea>` or `[contenteditable]` element.
* @param options
*/
fill(
selector: string,
value: string,
options?: {
/**
* Whether to bypass the [actionability](https://playwright.dev/docs/actionability) checks. Defaults to `false`.
*/
force?: boolean
/**
* This option has no effect.
* @deprecated This option has no effect.
*/
noWaitAfter?: boolean
/**
* Allows to cancel the operation using an
* [`AbortSignal`](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal). If the signal is aborted, the
* operation will be aborted and throw an error. Note that providing a signal does not disable the default timeout,
* which can be changed using
* [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); pass
* `timeout: 0` to disable the timeout entirely.
*/
signal?: AbortSignal
/**
* 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.
*/
strict?: boolean
/**
* Maximum time in milliseconds. Defaults to `0` - no timeout. The default value can be changed via `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.
*/
timeout?: number
},
): Promise<void>
/**
* **NOTE** Use locator-based [locator.focus([options])](https://playwright.dev/docs/api/class-locator#locator-focus) instead.
* Read more about [locators](https://playwright.dev/docs/locators).
*
* This method fetches an element with
* [`selector`](https://playwright.dev/docs/api/class-frame#frame-focus-option-selector) and focuses it. If there's no
* element matching [`selector`](https://playwright.dev/docs/api/class-frame#frame-focus-option-selector), the method
* waits until a matching element appears in the DOM.
* @param selector A selector to search for an element. If there are multiple elements satisfying the selector, the first will be
* used.
* @param options
*/
focus(
selector: string,
options?: {
/**
* Allows to cancel the operation using an
* [`AbortSignal`](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal). If the signal is aborted, the
* operation will be aborted and throw an error. Note that providing a signal does not disable the default timeout,
* which can be changed using
* [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); pass
* `timeout: 0` to disable the timeout entirely.
*/
signal?: AbortSignal
/**
* 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.
*/
strict?: boolean
/**
* Maximum time in milliseconds. Defaults to `0` - no timeout. The default value can be changed via `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.
*/
timeout?: number
},
): Promise<void>
/**
* Returns the `frame` or `iframe` element handle which corresponds to this frame.
*
* This is an inverse of
* [elementHandle.contentFrame()](https://playwright.dev/docs/api/class-elementhandle#element-handle-content-frame).
* Note that returned handle actually belongs to the parent frame.
*
* This method throws an error if the frame has been detached before `frameElement()` returns.
*
* **Usage**
*
* ```js
* const frameElement = await frame.frameElement();
* const contentFrame = await frameElement.contentFrame();
* console.log(frame === contentFrame); // -> true
* ```
*
*/
frameElement(): Promise<ElementHandle>
/**
* When working with iframes, you can create a frame locator that will enter the iframe and allow selecting elements
* in that iframe.
*
* When called without [`selector`](https://playwright.dev/docs/api/class-frame#frame-frame-locator-option-selector),
* the search starts in this frame or in any of the iframes inside it, so that you don't need to locate each iframe
* first. Note that the rest of the locator is resolved inside a single frame, just like any other locator. If it
* matches elements inside multiple frames, an error is thrown.
*
* **Usage**
*
* Following snippet locates element with text "Submit" in the iframe with id `my-frame`, like `<iframe
* id="my-frame">`:
*
* ```js
* const locator = frame.frameLocator('#my-iframe').getByText('Submit');
* await locator.click();
* ```
*
* Following snippet locates a button, either in the frame or in one of the iframes inside it:
*
* ```js
* const locator = frame.frameLocator().getByRole('button');
* await locator.click();
* ```
*
* @param selector A selector that matches the frame element. When not specified, locator is matched in this frame or in any of the
* iframes inside it.
*/
frameLocator(selector?: string): FrameLocator
/**
* **NOTE** Use locator-based
* [locator.getAttribute(name[, options])](https://playwright.dev/docs/api/class-locator#locator-get-attribute)
* instead. Read more about [locators](https://playwright.dev/docs/locators).
*
* Returns element attribute value.
* @param selector A selector to search for an element. If there are multiple elements satisfying the selector, the first will be
* used.
* @param name Attribute name to get the value for.
* @param options
*/
getAttribute(
selector: string,
name: string,
options?: {
/**
* Allows to cancel the operation using an
* [`AbortSignal`](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal). If the signal is aborted, the
* operation will be aborted and throw an error. Note that providing a signal does not disable the default timeout,
* which can be changed using
* [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); pass
* `timeout: 0` to disable the timeout entirely.
*/
signal?: AbortSignal
/**
* 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.
*/
strict?: boolean
/**
* Maximum time in milliseconds. Defaults to `0` - no timeout. The default value can be changed via `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.
*/
timeout?: number
},
): Promise<null | string>
/**
* Allows locating elements by their alt text.
*
* **Usage**
*
* For example, this method will find the image by alt text "Playwright logo":
*
* ```html
* <img alt='Playwright logo'>
* ```
*
* ```js
* await page.getByAltText('Playwright logo').click();
* ```
*
* @param text Text to locate the element for.
* @param options
*/
getByAltText(
text: string | RegExp,
options?: {
/**
* Whether to find an exact match: case-sensitive and whole-string. Default to false. Ignored when locating by a
* regular expression. Note that exact match still trims whitespace.
*/
exact?: boolean
},
): Locator
/**
* Allows locating input elements by the text of the associated `<label>` or `aria-labelledby` element, or by the
* `aria-label` attribute.
*
* **Usage**
*
* For example, this method will find inputs by label "Username" and "Password" in the following DOM:
*
* ```html
* <input aria-label="Username">
* <label for="password-input">Password:</label>
* <input id="password-input">
* ```
*
* ```js
* await page.getByLabel('Username').fill('john');
* await page.getByLabel('Password').fill('secret');
* ```
*
* @param text Text to locate the element for.
* @param options
*/
getByLabel(
text: string | RegExp,
options?: {
/**
* Whether to find an exact match: case-sensitive and whole-string. Default to false. Ignored when locating by a
* regular expression. Note that exact match still trims whitespace.
*/
exact?: boolean
},
): Locator
/**
* Allows locating input elements by the placeholder text.
*
* **Usage**
*
* For example, consider the following DOM structure.
*
* ```html
* <input type="email" placeholder="name@example.com" />
* ```
*
* You can fill the input after locating it by the placeholder text:
*
* ```js
* await page
* .getByPlaceholder('name@example.com')
* .fill('playwright@microsoft.com');
* ```
*
* @param text Text to locate the element for.
* @param options
*/
getByPlaceholder(
text: string | RegExp,
options?: {
/**
* Whether to find an exact match: case-sensitive and whole-string. Default to false. Ignored when locating by a
* regular expression. Note that exact match still trims whitespace.
*/
exact?: boolean
},
): Locator
/**
* Allows locating elements by their [ARIA role](https://www.w3.org/TR/wai-aria-1.2/#roles),
* [ARIA attributes](https://www.w3.org/TR/wai-aria-1.2/#aria-attributes) and
* [accessible name](https://w3c.github.io/accname/#dfn-accessible-name).
*
* **Usage**
*
* Consider the following DOM structure.
*
* ```html
* <h3>Sign up</h3>
* <label>
* <input type="checkbox" /> Subscribe
* </label>
* <br/>
* <button>Submit</button>
* ```
*
* You can locate each element by its implicit role:
*
* ```js
* await expect(page.getByRole('heading', { name: 'Sign up' })).toBeVisible();
*
* await page.getByRole('checkbox', { name: 'Subscribe' }).check();
*
* await page.getByRole('button', { name: /submit/i }).click();
* ```
*
* **Details**
*
* Role selector **does not replace** accessibility audits and conformance tests, but rather gives early feedback
* about the ARIA guidelines.
*
* Many html elements have an implicitly [defined role](https://w3c.github.io/html-aam/#html-element-role-mappings)
* that is recognized by the role selector. You can find all the
* [supported roles here](https://www.w3.org/TR/wai-aria-1.2/#role_definitions). ARIA guidelines **do not recommend**
* duplicating implicit roles and attributes by setting `role` and/or `aria-*` attributes to default values.
* @param role Required aria role.
* @param options
*/
getByRole(
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?: {
/**
* An attribute that is usually set by `aria-checked` or native `<input type=checkbox>` controls.
*
* Learn more about [`aria-checked`](https://www.w3.org/TR/wai-aria-1.2/#aria-checked).
*/
checked?: boolean
/**
* Option to match the [accessible description](https://w3c.github.io/accname/#dfn-accessible-description). By
* default, matching is case-insensitive and searches for a substring, use
* [`exact`](https://playwright.dev/docs/api/class-frame#frame-get-by-role-option-exact) to control this behavior.
*
* Learn more about [accessible description](https://w3c.github.io/accname/#dfn-accessible-description).
*/
description?: string | RegExp
/**
* 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).
*
*/
disabled?: boolean
/**
* Whether [`name`](https://playwright.dev/docs/api/class-frame#frame-get-by-role-option-name) and
* [`description`](https://playwright.dev/docs/api/class-frame#frame-get-by-role-option-description) are matched
* exactly: case-sensitive and whole-string. Defaults to false. Ignored when the value is a regular expression. Note
* that exact match still trims whitespace.
*/
exact?: boolean
/**
* An attribute that is usually set by `aria-expanded`.
*
* Learn more about [`aria-expanded`](https://www.w3.org/TR/wai-aria-1.2/#aria-expanded).
*/
expanded?: boolean
/**
* Option that controls whether hidden elements are matched. By default, only non-hidden elements, as
* [defined by ARIA](https://www.w3.org/TR/wai-aria-1.2/#tree_exclusion), are matched by role selector.
*
* Learn more about [`aria-hidden`](https://www.w3.org/TR/wai-aria-1.2/#aria-hidden).
*/
includeHidden?: boolean
/**
* A number attribute that is usually present for roles `heading`, `listitem`, `row`, `treeitem`, with default values
* for `<h1>-<h6>` elements.
*
* Learn more about [`aria-level`](https://www.w3.org/TR/wai-aria-1.2/#aria-level).
*/
level?: number
/**
* Option to match the [accessible name](https://w3c.github.io/accname/#dfn-accessible-name). By default, matching is
* case-insensitive and searches for a substring, use
* [`exact`](https://playwright.dev/docs/api/class-frame#frame-get-by-role-option-exact) to control this behavior.
*
* Learn more about [accessible name](https://w3c.github.io/accname/#dfn-accessible-name).
*/
name?: string | RegExp
/**
* An attribute that is usually set by `aria-pressed`.
*
* Learn more about [`aria-pressed`](https://www.w3.org/TR/wai-aria-1.2/#aria-pressed).
*/
pressed?: boolean
/**
* An attribute that is usually set by `aria-selected`.
*
* Learn more about [`aria-selected`](https://www.w3.org/TR/wai-aria-1.2/#aria-selected).
*/
selected?: boolean
},
): Locator
/**
* Locate element by the test id.
*
* **Usage**
*
* Consider the following DOM structure.
*
* ```html
* <button data-testid="directions">Itinéraire</button>
* ```
*
* You can locate the element by its test id:
*
* ```js
* await page.getByTestId('directions').click();
* ```
*
* **Details**
*
* By default, the `data-testid` attribute is used as a test id. Use
* [selectors.setTestIdAttribute(attributeName)](https://playwright.dev/docs/api/class-selectors#selectors-set-test-id-attribute)
* to configure a different test id attribute if necessary.
*
* ```js
* // Set custom test id attribute from @playwright/test config:
* import { defineConfig } from '@playwright/test';
*
* export default defineConfig({
* use: {
* testIdAttribute: 'data-pw'
* },
* });
* ```
*
* @param testId Id to locate the element by.
*/
getByTestId(testId: string | RegExp): Locator
/**
* Allows locating elements that contain given text.
*
* See also [locator.filter([options])](https://playwright.dev/docs/api/class-locator#locator-filter) that allows to
* match by another criteria, like an accessible role, and then filter by the text content.
*
* **Usage**
*
* Consider the following DOM structure:
*
* ```html
* <div>Hello <span>world</span></div>
* <div>Hello</div>
* ```
*
* You can locate by text substring, exact string, or a regular expression:
*
* ```js
* // Matches <span>
* page.getByText('world');
*
* // Matches first <div>
* page.getByText('Hello world');
*
* // Matches second <div>
* page.getByText('Hello', { exact: true });
*
* // Matches both <div>s
* page.getByText(/Hello/);
*
* // Matches second <div>
* page.getByText(/^hello$/i);
* ```
*
* **Details**
*
* Matching by text always normalizes whitespace, even with exact match. For example, it turns multiple spaces into
* one, turns line breaks into spaces and ignores leading and trailing whitespace.
*
* Input elements of the type `button` and `submit` are matched by their `value` instead of the text content. For
* example, locating by text `"Log in"` matches `<input type=button value="Log in">`.
* @param text Text to locate the element for.
* @param options
*/
getByText(
text: string | RegExp,
options?: {
/**
* Whether to find an exact match: case-sensitive and whole-string. Default to false. Ignored when locating by a
* regular expression. Note that exact match still trims whitespace.
*/
exact?: boolean
},
): Locator
/**
* Allows locating elements by their title attribute.
*
* **Usage**
*
* Consider the following DOM structure.
*
* ```html
* <span title='Issues count'>25 issues</span>
* ```
*
* You can check the issues count after locating it by the title text:
*
* ```js
* await expect(page.getByTitle('Issues count')).toHaveText('25 issues');
* ```
*
* @param text Text to locate the element for.
* @param options
*/
getByTitle(
text: string | RegExp,
options?: {
/**
* Whether to find an exact match: case-sensitive and whole-string. Default to false. Ignored when locating by a
* regular expression. Note that exact match still trims whitespace.
*/
exact?: boolean
},
): Locator
/**
* Returns the main resource response. In case of multiple redirects, the navigation will resolve with the response of
* the last redirect.
*
* The method will throw an error if:
* - there's an SSL error (e.g. in case of self-signed certificates).
* - target URL is invalid.
* - the [`timeout`](https://playwright.dev/docs/api/class-frame#frame-goto-option-timeout) is exceeded during
* navigation.
* - the remote server does not respond or is unreachable.
* - the main resource failed to load.
*
* The method will not throw an error when any valid HTTP status code is returned by the remote server, including 404
* "Not Found" and 500 "Internal Server Error". The status code for such responses can be retrieved by calling
* [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`.
*
* **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
*/
goto(
url: string,
options?: {
/**
* Referer header value. If provided it will take preference over the referer header value set by
* [page.setExtraHTTPHeaders(headers)](https://playwright.dev/docs/api/class-page#page-set-extra-http-headers).
*/
referer?: string
/**
* Allows to cancel the operation using an
* [`AbortSignal`](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal). If the signal is aborted, the
* operation will be aborted and throw an error. Note that providing a signal does not disable the default timeout,
* which can be changed using
* [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); pass
* `timeout: 0` to disable the timeout entirely.
*/
signal?: AbortSignal
/**
* Maximum operation time in milliseconds. Defaults to `0` - no timeout. The default value can be changed via
* `navigationTimeout` option in the config, or by using the
* [browserContext.setDefaultNavigationTimeout(timeout)](https://playwright.dev/docs/api/class-browsercontext#browser-context-set-default-navigation-timeout),
* [browserContext.setDefaultTimeout(timeout)](https://playwright.dev/docs/api/class-browsercontext#browser-context-set-default-timeout),
* [page.setDefaultNavigationTimeout(timeout)](https://playwright.dev/docs/api/class-page#page-set-default-navigation-timeout)
* or [page.setDefaultTimeout(timeout)](https://playwright.dev/docs/api/class-page#page-set-default-timeout) methods.
*/
timeout?: number
/**
* When to consider operation succeeded, defaults to `load`. Events can be either:
* - `'domcontentloaded'` - consider operation to be finished when the `DOMContentLoaded` event is fired.
* - `'load'` - consider operation to be finished when the `load` event is fired.
* - `'networkidle'` - **DISCOURAGED** consider operation to be finished when there are no network connections for
* at least `500` ms. Don't use this method for testing, rely on web assertions to assess readiness instead.
* - `'commit'` - consider operation to be finished when network response is received and the document started
* loading.
*/
waitUntil?: 'load' | 'domcontentloaded' | 'networkidle' | 'commit'
},
): Promise<null | Response>
/**
* **NOTE** Use locator-based [locator.hover([options])](https://playwright.dev/docs/api/class-locator#locator-hover) instead.
* Read more about [locators](https://playwright.dev/docs/locators).
*
* This method hovers over an element matching
* [`selector`](https://playwright.dev/docs/api/class-frame#frame-hover-option-selector) by performing the following
* steps:
* 1. Find an element matching
* [`selector`](https://playwright.dev/docs/api/class-frame#frame-hover-option-selector). If there is none, wait
* until a matching element is attached to the DOM.
* 1. Wait for [actionability](https://playwright.dev/docs/actionability) checks on the matched element, unless
* [`force`](https://playwright.dev/docs/api/class-frame#frame-hover-option-force) option is set. If the element
* is detached during the checks, the whole action is retried.
* 1. Scroll the element into view if needed.
* 1. Use [page.mouse](https://playwright.dev/docs/api/class-page#page-mouse) to hover over the center of the
* element, or the specified
* [`position`](https://playwright.dev/docs/api/class-frame#frame-hover-option-position).
*
* When all steps combined have not finished during the specified
* [`timeout`](https://playwright.dev/docs/api/class-frame#frame-hover-option-timeout), this method throws a
* [TimeoutError](https://playwright.dev/docs/api/class-timeouterror). Passing zero timeout disables this.
* @param selector A selector to search for an element. If there are multiple elements satisfying the selector, the first will be
* used.
* @param options
*/
hover(
selector: string,
options?: {
/**
* Whether to bypass the [actionability](https://playwright.dev/docs/actionability) checks. Defaults to `false`.
*/
force?: boolean
/**
* Modifier keys to press. Ensures that only these modifiers are pressed during the operation, and then restores
* current modifiers back. If not specified, currently pressed modifiers are used. "ControlOrMeta" resolves to
* "Control" on Windows and Linux and to "Meta" on macOS.
*/
modifiers?: Array<'Alt' | 'Control' | 'ControlOrMeta' | 'Meta' | 'Shift'>
/**
* This option has no effect.
* @deprecated This option has no effect.
*/
noWaitAfter?: boolean
/**
* A point to use relative to the top-left corner of element padding box. If not specified, uses some visible point of
* the element.
*/
position?: {
x: number
y: number
}
/**
* Controls whether Playwright scrolls the element into view before performing the action. Defaults to `"auto"`, which
* scrolls the element into view when necessary, including scrolling nested scrollable containers. When set to
* `"none"`, Playwright does not scroll the element and the action fails if the element is not already in the
* viewport. This is useful to assert that an element is reachable by the user without additional scrolling.
*/
scroll?: 'auto' | 'none'
/**
* Allows to cancel the operation using an
* [`AbortSignal`](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal). If the signal is aborted, the
* operation will be aborted and throw an error. Note that providing a signal does not disable the default timeout,
* which can be changed using
* [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); pass
* `timeout: 0` to disable the timeout entirely.
*/
signal?: AbortSignal
/**
* 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.
*/
strict?: boolean
/**
* Maximum time in milliseconds. Defaults to `0` - no timeout. The default value can be changed via `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.
*/
timeout?: number
/**
* When set, this method only performs the [actionability](https://playwright.dev/docs/actionability) checks and skips the action. Defaults
* to `false`. Useful to wait until the element is ready for the action without performing it. Note that keyboard
* `modifiers` will be pressed regardless of `trial` to allow testing elements which are only visible when those keys
* are pressed.
*/
trial?: boolean
},
): Promise<void>
/**
* **NOTE** Use locator-based [locator.innerHTML([options])](https://playwright.dev/docs/api/class-locator#locator-inner-html)
* instead. Read more about [locators](https://playwright.dev/docs/locators).
*
* Returns `element.innerHTML`.
* @param selector A selector to search for an element. If there are multiple elements satisfying the selector, the first will be
* used.
* @param options
*/
innerHTML(
selector: string,
options?: {
/**
* Allows to cancel the operation using an
* [`AbortSignal`](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal). If the signal is aborted, the
* operation will be aborted and throw an error. Note that providing a signal does not disable the default timeout,
* which can be changed using
* [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); pass
* `timeout: 0` to disable the timeout entirely.
*/
signal?: AbortSignal
/**
* 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.
*/
strict?: boolean
/**
* Maximum time in milliseconds. Defaults to `0` - no timeout. The default value can be changed via `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.
*/
timeout?: number
},
): Promise<string>
/**
* **NOTE** Use locator-based [locator.innerText([options])](https://playwright.dev/docs/api/class-locator#locator-inner-text)
* instead. Read more about [locators](https://playwright.dev/docs/locators).
*
* Returns `element.innerText`.
* @param selector A selector to search for an element. If there are multiple elements satisfying the selector, the first will be
* used.
* @param options
*/
innerText(
selector: string,
options?: {
/**
* Allows to cancel the operation using an
* [`AbortSignal`](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal). If the signal is aborted, the
* operation will be aborted and throw an error. Note that providing a signal does not disable the default timeout,
* which can be changed using
* [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); pass
* `timeout: 0` to disable the timeout entirely.
*/
signal?: AbortSignal
/**
* 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.
*/
strict?: boolean
/**
* Maximum time in milliseconds. Defaults to `0` - no timeout. The default value can be changed via `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.
*/
timeout?: number
},
): Promise<string>
/**
* **NOTE** Use locator-based
* [locator.inputValue([options])](https://playwright.dev/docs/api/class-locator#locator-input-value) instead. Read
* more about [locators](https://playwright.dev/docs/locators).
*
* Returns `input.value` for the selected `<input>` or `<textarea>` or `<select>` element.
*
* Throws for non-input elements. However, if the element is inside the `<label>` element that has an associated
* [control](https://developer.mozilla.org/en-US/docs/Web/API/HTMLLabelElement/control), returns the value of the
* control.
* @param selector A selector to search for an element. If there are multiple elements satisfying the selector, the first will be
* used.
* @param options
*/
inputValue(
selector: string,
options?: {
/**
* Allows to cancel the operation using an
* [`AbortSignal`](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal). If the signal is aborted, the
* operation will be aborted and throw an error. Note that providing a signal does not disable the default timeout,
* which can be changed using
* [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); pass
* `timeout: 0` to disable the timeout entirely.
*/
signal?: AbortSignal
/**
* 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.
*/
strict?: boolean
/**
* Maximum time in milliseconds. Defaults to `0` - no timeout. The default value can be changed via `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.
*/
timeout?: number
},
): Promise<string>
/**
* **NOTE** Use locator-based [locator.isChecked([options])](https://playwright.dev/docs/api/class-locator#locator-is-checked)
* instead. Read more about [locators](https://playwright.dev/docs/locators).
*
* Returns whether the element is checked. Throws if the element is not a checkbox or radio input.
* @param selector A selector to search for an element. If there are multiple elements satisfying the selector, the first will be
* used.
* @param options
*/
isChecked(
selector: string,
options?: {
/**
* Allows to cancel the operation using an
* [`AbortSignal`](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal). If the signal is aborted, the
* operation will be aborted and throw an error. Note that providing a signal does not disable the default timeout,
* which can be changed using
* [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); pass
* `timeout: 0` to disable the timeout entirely.
*/
signal?: AbortSignal
/**
* 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.
*/
strict?: boolean
/**
* Maximum time in milliseconds. Defaults to `0` - no timeout. The default value can be changed via `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.
*/
timeout?: number
},
): Promise<boolean>
/**
* Returns `true` if the frame has been detached, or `false` otherwise.
*/
isDetached(): boolean
/**
* **NOTE** Use locator-based
* [locator.isDisabled([options])](https://playwright.dev/docs/api/class-locator#locator-is-disabled) instead. Read
* more about [locators](https://playwright.dev/docs/locators).
*
* Returns whether the element is disabled, the opposite of [enabled](https://playwright.dev/docs/actionability#enabled).
* @param selector A selector to search for an element. If there are multiple elements satisfying the selector, the first will be
* used.
* @param options
*/
isDisabled(
selector: string,
options?: {
/**
* Allows to cancel the operation using an
* [`AbortSignal`](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal). If the signal is aborted, the
* operation will be aborted and throw an error. Note that providing a signal does not disable the default timeout,
* which can be changed using
* [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); pass
* `timeout: 0` to disable the timeout entirely.
*/
signal?: AbortSignal
/**
* 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.
*/
strict?: boolean
/**
* Maximum time in milliseconds. Defaults to `0` - no timeout. The default value can be changed via `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.
*/
timeout?: number
},
): Promise<boolean>
/**
* **NOTE** Use locator-based
* [locator.isEditable([options])](https://playwright.dev/docs/api/class-locator#locator-is-editable) instead. Read
* more about [locators](https://playwright.dev/docs/locators).
*
* Returns whether the element is [editable](https://playwright.dev/docs/actionability#editable).
* @param selector A selector to search for an element. If there are multiple elements satisfying the selector, the first will be
* used.
* @param options
*/
isEditable(
selector: string,
options?: {
/**
* Allows to cancel the operation using an
* [`AbortSignal`](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal). If the signal is aborted, the
* operation will be aborted and throw an error. Note that providing a signal does not disable the default timeout,
* which can be changed using
* [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); pass
* `timeout: 0` to disable the timeout entirely.
*/
signal?: AbortSignal
/**
* 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.
*/
strict?: boolean
/**
* Maximum time in milliseconds. Defaults to `0` - no timeout. The default value can be changed via `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.
*/
timeout?: number
},
): Promise<boolean>
/**
* Returns whether the element is [enabled](https://playwright.dev/docs/actionability#enabled).
* @param selector A selector to search for an element. If there are multiple elements satisfying the selector, the first will be
* used.
* @param options
*/
isEnabled(
selector: string,
options?: {
/**
* Allows to cancel the operation using an
* [`AbortSignal`](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal). If the signal is aborted, the
* operation will be aborted and throw an error. Note that providing a signal does not disable the default timeout,
* which can be changed using
* [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); pass
* `timeout: 0` to disable the timeout entirely.
*/
signal?: AbortSignal
/**
* 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.
*/
strict?: boolean
/**
* Maximum time in milliseconds. Defaults to `0` - no timeout. The default value can be changed via `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.
*/
timeout?: number
},
): Promise<boolean>
/**
* **NOTE** Use locator-based [locator.isHidden([options])](https://playwright.dev/docs/api/class-locator#locator-is-hidden)
* instead. Read more about [locators](https://playwright.dev/docs/locators).
*
* Returns whether the element is hidden, the opposite of [visible](https://playwright.dev/docs/actionability#visible).
* [`selector`](https://playwright.dev/docs/api/class-frame#frame-is-hidden-option-selector) that does not match any
* elements is considered hidden.
* @param selector A selector to search for an element. If there are multiple elements satisfying the selector, the first will be
* used.
* @param options
*/
isHidden(
selector: string,
options?: {
/**
* 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.
*/
strict?: boolean
/**
* @deprecated This option is ignored.
* [frame.isHidden(selector[, options])](https://playwright.dev/docs/api/class-frame#frame-is-hidden) does not wait
* for the element to become hidden and returns immediately.
*/
timeout?: number
},
): Promise<boolean>
/**
* **NOTE** Use locator-based [locator.isVisible([options])](https://playwright.dev/docs/api/class-locator#locator-is-visible)
* instead. Read more about [locators](https://playwright.dev/docs/locators).
*
* Returns whether the element is [visible](https://playwright.dev/docs/actionability#visible).
* [`selector`](https://playwright.dev/docs/api/class-frame#frame-is-visible-option-selector) that does not match any
* elements is considered not visible.
* @param selector A selector to search for an element. If there are multiple elements satisfying the selector, the first will be
* used.
* @param options
*/
isVisible(
selector: string,
options?: {
/**
* 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.
*/
strict?: boolean
/**
* @deprecated This option is ignored.
* [frame.isVisible(selector[, options])](https://playwright.dev/docs/api/class-frame#frame-is-visible) does not wait
* for the element to become visible and returns immediately.
*/
timeout?: number
},
): Promise<boolean>
/**
* The method returns an element locator that can be used to perform actions on this page / frame. Locator is resolved
* to the element immediately before performing an action, so a series of actions on the same locator can in fact be
* performed on different DOM elements. That would happen if the DOM structure between those actions has changed.
*
* [Learn more about locators](https://playwright.dev/docs/locators).
*
* [Learn more about locators](https://playwright.dev/docs/locators).
* @param selector A selector to use when resolving DOM element.
* @param options
*/
locator(
selector: string,
options?: {
/**
* Narrows down the results of the method to those which contain elements matching this relative locator. For example,
* `article` that has `text=Playwright` matches `<article><div>Playwright</div></article>`.
*
* Inner locator **must be relative** to the outer locator and is queried starting with the outer locator match, not
* the document root. For example, you can find `content` that has `div` in
* `<article><content><div>Playwright</div></content></article>`. However, looking for `content` that has `article
* div` will fail, because the inner locator must be relative and should not use any elements outside the `content`.
*
* Note that outer and inner locators must belong to the same frame. Inner locator must not contain
* [FrameLocator](https://playwright.dev/docs/api/class-framelocator)s.
*/
has?: Locator
/**
* Matches elements that do not contain an element that matches an inner locator. Inner locator is queried against the
* outer one. For example, `article` that does not have `div` matches `<article><span>Playwright</span></article>`.
*
* Note that outer and inner locators must belong to the same frame. Inner locator must not contain
* [FrameLocator](https://playwright.dev/docs/api/class-framelocator)s.
*/
hasNot?: Locator
/**
* Matches elements that do not contain specified text somewhere inside, possibly in a child or a descendant element.
* When passed a [string], matching is case-insensitive and searches for a substring.
*/
hasNotText?: string | RegExp
/**
* Matches elements containing specified text somewhere inside, possibly in a child or a descendant element. When
* passed a [string], matching is case-insensitive and searches for a substring. For example, `"Playwright"` matches
* `<article><div>Playwright</div></article>`.
*/
hasText?: string | RegExp
},
): Locator
/**
* Returns frame's name attribute as specified in the tag.
*
* If the name is empty, returns the id attribute instead.
*
* **NOTE** This value is calculated once when the frame is created, and will not update if the attribute is changed
* later.
*
*/
name(): string
/**
* Returns the page containing this frame.
*/
page(): Page
/**
* Parent frame, if any. Detached frames and main frames return `null`.
*/
parentFrame(): null | Frame
/**
* **NOTE** Use locator-based [locator.press(key[, options])](https://playwright.dev/docs/api/class-locator#locator-press)
* instead. Read more about [locators](https://playwright.dev/docs/locators).
*
* [`key`](https://playwright.dev/docs/api/class-frame#frame-press-option-key) can specify the intended
* [keyboardEvent.key](https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/key) value or a single character
* to generate the text for. A superset of the
* [`key`](https://playwright.dev/docs/api/class-frame#frame-press-option-key) values can be found
* [here](https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/key/Key_Values). Examples of the keys are:
*
* `F1` - `F12`, `Digit0`- `Digit9`, `KeyA`- `KeyZ`, `Backquote`, `Minus`, `Equal`, `Backslash`, `Backspace`, `Tab`,
* `Delete`, `Escape`, `ArrowDown`, `End`, `Enter`, `Home`, `Insert`, `PageDown`, `PageUp`, `ArrowRight`, `ArrowUp`,
* etc.
*
* Following modification shortcuts are also supported: `Shift`, `Control`, `Alt`, `Meta`, `ShiftLeft`,
* `ControlOrMeta`. `ControlOrMeta` resolves to `Control` on Windows and Linux and to `Meta` on macOS.
*
* Holding down `Shift` will type the text that corresponds to the
* [`key`](https://playwright.dev/docs/api/class-frame#frame-press-option-key) in the upper case.
*
* If [`key`](https://playwright.dev/docs/api/class-frame#frame-press-option-key) is a single character, it is
* case-sensitive, so the values `a` and `A` will generate different respective texts.
*
* Shortcuts such as `key: "Control+o"`, `key: "Control++` or `key: "Control+Shift+T"` are supported as well. When
* specified with the modifier, modifier is pressed and being held while the subsequent key is being pressed.
* @param selector A selector to search for an element. If there are multiple elements satisfying the selector, the first will be
* used.
* @param key Name of the key to press or a character to generate, such as `ArrowLeft` or `a`.
* @param options
*/
press(
selector: string,
key: string,
options?: {
/**
* Time to wait between `keydown` and `keyup` in milliseconds. Defaults to 0.
*/
delay?: number
/**
* Actions that initiate navigations are waiting for these navigations to happen and for pages to start loading. You
* can opt out of waiting via setting this flag. You would only need this option in the exceptional cases such as
* navigating to inaccessible pages. Defaults to `false`.
* @deprecated This option will default to `true` in the future.
*/
noWaitAfter?: boolean
/**
* Allows to cancel the operation using an
* [`AbortSignal`](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal). If the signal is aborted, the
* operation will be aborted and throw an error. Note that providing a signal does not disable the default timeout,
* which can be changed using
* [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); pass
* `timeout: 0` to disable the timeout entirely.
*/
signal?: AbortSignal
/**
* 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.
*/
strict?: boolean
/**
* Maximum time in milliseconds. Defaults to `0` - no timeout. The default value can be changed via `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.
*/
timeout?: number
},
): Promise<void>
/**
* **NOTE** Use locator-based
* [locator.selectOption(values[, options])](https://playwright.dev/docs/api/class-locator#locator-select-option)
* instead. Read more about [locators](https://playwright.dev/docs/locators).
*
* This method waits for an element matching
* [`selector`](https://playwright.dev/docs/api/class-frame#frame-select-option-option-selector), waits for
* [actionability](https://playwright.dev/docs/actionability) checks, waits until all specified options are present in the `<select>`
* element and selects these options.
*
* If the target element is not a `<select>` element, this method throws an error. However, if the element is inside
* the `<label>` element that has an associated
* [control](https://developer.mozilla.org/en-US/docs/Web/API/HTMLLabelElement/control), the control will be used
* instead.
*
* Returns the array of option values that have been successfully selected.
*
* Triggers a `change` and `input` event once all the provided options have been selected.
*
* **Usage**
*
* ```js
* // Single selection matching the value or label
* frame.selectOption('select#colors', 'blue');
*
* // single selection matching both the value and the label
* frame.selectOption('select#colors', { label: 'Blue' });
*
* // multiple selection
* frame.selectOption('select#colors', 'red', 'green', 'blue');
* ```
*
* @param selector A selector to query for.
* @param values Options to select. If the `<select>` has the `multiple` attribute, all matching options are selected, otherwise
* only the first option matching one of the passed options is selected. String values are matching both values and
* labels. Option is considered matching if all specified properties match.
* @param options
*/
selectOption(
selector: string,
values:
| null
| string
| ElementHandle
| ReadonlyArray<string>
| {
/**
* Matches by `option.value`. Optional.
*/
value?: string
/**
* Matches by `option.label`. Optional.
*/
label?: string
/**
* Matches by the index. Optional.
*/
index?: number
}
| ReadonlyArray<ElementHandle>
| ReadonlyArray<{
/**
* Matches by `option.value`. Optional.
*/
value?: string
/**
* Matches by `option.label`. Optional.
*/
label?: string
/**
* Matches by the index. Optional.
*/
index?: number
}>,
options?: {
/**
* Whether to bypass the [actionability](https://playwright.dev/docs/actionability) checks. Defaults to `false`.
*/
force?: boolean
/**
* This option has no effect.
* @deprecated This option has no effect.
*/
noWaitAfter?: boolean
/**
* Allows to cancel the operation using an
* [`AbortSignal`](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal). If the signal is aborted, the
* operation will be aborted and throw an error. Note that providing a signal does not disable the default timeout,
* which can be changed using
* [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); pass
* `timeout: 0` to disable the timeout entirely.
*/
signal?: AbortSignal
/**
* 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.
*/
strict?: boolean
/**
* Maximum time in milliseconds. Defaults to `0` - no timeout. The default value can be changed via `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.
*/
timeout?: number
},
): Promise<Array<string>>
/**
* **NOTE** Use locator-based
* [locator.setChecked(checked[, options])](https://playwright.dev/docs/api/class-locator#locator-set-checked)
* instead. Read more about [locators](https://playwright.dev/docs/locators).
*
* This method checks or unchecks an element matching
* [`selector`](https://playwright.dev/docs/api/class-frame#frame-set-checked-option-selector) by performing the
* following steps:
* 1. Find an element matching
* [`selector`](https://playwright.dev/docs/api/class-frame#frame-set-checked-option-selector). If there is
* none, wait until a matching element is attached to the DOM.
* 1. Ensure that matched element is a checkbox or a radio input. If not, this method throws.
* 1. If the element already has the right checked state, this method returns immediately.
* 1. Wait for [actionability](https://playwright.dev/docs/actionability) checks on the matched element, unless
* [`force`](https://playwright.dev/docs/api/class-frame#frame-set-checked-option-force) option is set. If the
* element is detached during the checks, the whole action is retried.
* 1. Scroll the element into view if needed.
* 1. Use [page.mouse](https://playwright.dev/docs/api/class-page#page-mouse) to click in the center of the
* element.
* 1. Ensure that the element is now checked or unchecked. If not, this method throws.
*
* When all steps combined have not finished during the specified
* [`timeout`](https://playwright.dev/docs/api/class-frame#frame-set-checked-option-timeout), this method throws a
* [TimeoutError](https://playwright.dev/docs/api/class-timeouterror). Passing zero timeout disables this.
* @param selector A selector to search for an element. If there are multiple elements satisfying the selector, the first will be
* used.
* @param checked Whether to check or uncheck the checkbox.
* @param options
*/
setChecked(
selector: string,
checked: boolean,
options?: {
/**
* Whether to bypass the [actionability](https://playwright.dev/docs/actionability) checks. Defaults to `false`.
*/
force?: boolean
/**
* This option has no effect.
* @deprecated This option has no effect.
*/
noWaitAfter?: boolean
/**
* A point to use relative to the top-left corner of element padding box. If not specified, uses some visible point of
* the element.
*/
position?: {
x: number
y: number
}
/**
* Controls whether Playwright scrolls the element into view before performing the action. Defaults to `"auto"`, which
* scrolls the element into view when necessary, including scrolling nested scrollable containers. When set to
* `"none"`, Playwright does not scroll the element and the action fails if the element is not already in the
* viewport. This is useful to assert that an element is reachable by the user without additional scrolling.
*/
scroll?: 'auto' | 'none'
/**
* Allows to cancel the operation using an
* [`AbortSignal`](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal). If the signal is aborted, the
* operation will be aborted and throw an error. Note that providing a signal does not disable the default timeout,
* which can be changed using
* [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); pass
* `timeout: 0` to disable the timeout entirely.
*/
signal?: AbortSignal
/**
* 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.
*/
strict?: boolean
/**
* Maximum time in milliseconds. Defaults to `0` - no timeout. The default value can be changed via `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.
*/
timeout?: number
/**
* When set, this method only performs the [actionability](https://playwright.dev/docs/actionability) checks and skips the action. Defaults
* to `false`. Useful to wait until the element is ready for the action without performing it.
*/
trial?: boolean
},
): Promise<void>
/**
* This method internally calls [document.write()](https://developer.mozilla.org/en-US/docs/Web/API/Document/write),
* inheriting all its specific characteristics and behaviors.
* @param html HTML markup to assign to the page.
* @param options
*/
setContent(
html: string,
options?: {
/**
* Allows to cancel the operation using an
* [`AbortSignal`](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal). If the signal is aborted, the
* operation will be aborted and throw an error. Note that providing a signal does not disable the default timeout,
* which can be changed using
* [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); pass
* `timeout: 0` to disable the timeout entirely.
*/
signal?: AbortSignal
/**
* Maximum operation time in milliseconds. Defaults to `0` - no timeout. The default value can be changed via
* `navigationTimeout` option in the config, or by using the
* [browserContext.setDefaultNavigationTimeout(timeout)](https://playwright.dev/docs/api/class-browsercontext#browser-context-set-default-navigation-timeout),
* [browserContext.setDefaultTimeout(timeout)](https://playwright.dev/docs/api/class-browsercontext#browser-context-set-default-timeout),
* [page.setDefaultNavigationTimeout(timeout)](https://playwright.dev/docs/api/class-page#page-set-default-navigation-timeout)
* or [page.setDefaultTimeout(timeout)](https://playwright.dev/docs/api/class-page#page-set-default-timeout) methods.
*/
timeout?: number
/**
* When to consider operation succeeded, defaults to `load`. Events can be either:
* - `'domcontentloaded'` - consider operation to be finished when the `DOMContentLoaded` event is fired.
* - `'load'` - consider operation to be finished when the `load` event is fired.
* - `'networkidle'` - **DISCOURAGED** consider operation to be finished when there are no network connections for
* at least `500` ms. Don't use this method for testing, rely on web assertions to assess readiness instead.
* - `'commit'` - consider operation to be finished when network response is received and the document started
* loading.
*/
waitUntil?: 'load' | 'domcontentloaded' | 'networkidle' | 'commit'
},
): Promise<void>
/**
* **NOTE** Use locator-based
* [locator.setInputFiles(files[, options])](https://playwright.dev/docs/api/class-locator#locator-set-input-files)
* instead. Read more about [locators](https://playwright.dev/docs/locators).
*
* Sets the value of the file input to these file paths or files. If some of the `filePaths` are relative paths, then
* they are resolved relative to the current working directory. For empty array, clears the selected files.
*
* This method expects [`selector`](https://playwright.dev/docs/api/class-frame#frame-set-input-files-option-selector)
* to point to an [input element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input). However, if the
* element is inside the `<label>` element that has an associated
* [control](https://developer.mozilla.org/en-US/docs/Web/API/HTMLLabelElement/control), targets the control instead.
* @param selector A selector to search for an element. If there are multiple elements satisfying the selector, the first will be
* used.
* @param files
* @param options
*/
setInputFiles(
selector: string,
files:
| string
| ReadonlyArray<string>
| {
/**
* File name
*/
name: string
/**
* File type
*/
mimeType: string
/**
* File content
*/
buffer: Buffer
}
| ReadonlyArray<{
/**
* File name
*/
name: string
/**
* File type
*/
mimeType: string
/**
* File content
*/
buffer: Buffer
}>,
options?: {
/**
* This option has no effect.
* @deprecated This option has no effect.
*/
noWaitAfter?: boolean
/**
* Allows to cancel the operation using an
* [`AbortSignal`](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal). If the signal is aborted, the
* operation will be aborted and throw an error. Note that providing a signal does not disable the default timeout,
* which can be changed using
* [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); pass
* `timeout: 0` to disable the timeout entirely.
*/
signal?: AbortSignal
/**
* 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.
*/
strict?: boolean
/**
* Maximum time in milliseconds. Defaults to `0` - no timeout. The default value can be changed via `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.
*/
timeout?: number
},
): Promise<void>
/**
* **NOTE** Use locator-based [locator.tap([options])](https://playwright.dev/docs/api/class-locator#locator-tap) instead. Read
* more about [locators](https://playwright.dev/docs/locators).
*
* This method taps an element matching
* [`selector`](https://playwright.dev/docs/api/class-frame#frame-tap-option-selector) by performing the following
* steps:
* 1. Find an element matching [`selector`](https://playwright.dev/docs/api/class-frame#frame-tap-option-selector).
* If there is none, wait until a matching element is attached to the DOM.
* 1. Wait for [actionability](https://playwright.dev/docs/actionability) checks on the matched element, unless
* [`force`](https://playwright.dev/docs/api/class-frame#frame-tap-option-force) option is set. If the element
* is detached during the checks, the whole action is retried.
* 1. Scroll the element into view if needed.
* 1. Use [page.touchscreen](https://playwright.dev/docs/api/class-page#page-touchscreen) to tap the center of the
* element, or the specified
* [`position`](https://playwright.dev/docs/api/class-frame#frame-tap-option-position).
*
* When all steps combined have not finished during the specified
* [`timeout`](https://playwright.dev/docs/api/class-frame#frame-tap-option-timeout), this method throws a
* [TimeoutError](https://playwright.dev/docs/api/class-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
*/
tap(
selector: string,
options?: {
/**
* Whether to bypass the [actionability](https://playwright.dev/docs/actionability) checks. Defaults to `false`.
*/
force?: boolean
/**
* Modifier keys to press. Ensures that only these modifiers are pressed during the operation, and then restores
* current modifiers back. If not specified, currently pressed modifiers are used. "ControlOrMeta" resolves to
* "Control" on Windows and Linux and to "Meta" on macOS.
*/
modifiers?: Array<'Alt' | 'Control' | 'ControlOrMeta' | 'Meta' | 'Shift'>
/**
* This option has no effect.
* @deprecated This option has no effect.
*/
noWaitAfter?: boolean
/**
* A point to use relative to the top-left corner of element padding box. If not specified, uses some visible point of
* the element.
*/
position?: {
x: number
y: number
}
/**
* Controls whether Playwright scrolls the element into view before performing the action. Defaults to `"auto"`, which
* scrolls the element into view when necessary, including scrolling nested scrollable containers. When set to
* `"none"`, Playwright does not scroll the element and the action fails if the element is not already in the
* viewport. This is useful to assert that an element is reachable by the user without additional scrolling.
*/
scroll?: 'auto' | 'none'
/**
* Allows to cancel the operation using an
* [`AbortSignal`](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal). If the signal is aborted, the
* operation will be aborted and throw an error. Note that providing a signal does not disable the default timeout,
* which can be changed using
* [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); pass
* `timeout: 0` to disable the timeout entirely.
*/
signal?: AbortSignal
/**
* 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.
*/
strict?: boolean
/**
* Maximum time in milliseconds. Defaults to `0` - no timeout. The default value can be changed via `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.
*/
timeout?: number
/**
* When set, this method only performs the [actionability](https://playwright.dev/docs/actionability) checks and skips the action. Defaults
* to `false`. Useful to wait until the element is ready for the action without performing it. Note that keyboard
* `modifiers` will be pressed regardless of `trial` to allow testing elements which are only visible when those keys
* are pressed.
*/
trial?: boolean
},
): Promise<void>
/**
* **NOTE** Use locator-based
* [locator.textContent([options])](https://playwright.dev/docs/api/class-locator#locator-text-content) instead. Read
* more about [locators](https://playwright.dev/docs/locators).
*
* Returns `element.textContent`.
* @param selector A selector to search for an element. If there are multiple elements satisfying the selector, the first will be
* used.
* @param options
*/
textContent(
selector: string,
options?: {
/**
* Allows to cancel the operation using an
* [`AbortSignal`](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal). If the signal is aborted, the
* operation will be aborted and throw an error. Note that providing a signal does not disable the default timeout,
* which can be changed using
* [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); pass
* `timeout: 0` to disable the timeout entirely.
*/
signal?: AbortSignal
/**
* 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.
*/
strict?: boolean
/**
* Maximum time in milliseconds. Defaults to `0` - no timeout. The default value can be changed via `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.
*/
timeout?: number
},
): Promise<null | string>
/**
* Returns the page title.
*/
title(): Promise<string>
/**
* Sends a `keydown`, `keypress`/`input`, and `keyup` event for each character in the text. `frame.type` can be used
* to send fine-grained keyboard events. To fill values in form fields, use
* [frame.fill(selector, value[, options])](https://playwright.dev/docs/api/class-frame#frame-fill).
*
* To press a special key, like `Control` or `ArrowDown`, use
* [keyboard.press(key[, options])](https://playwright.dev/docs/api/class-keyboard#keyboard-press).
*
* **Usage**
* @deprecated In most cases, you should use
* [locator.fill(value[, options])](https://playwright.dev/docs/api/class-locator#locator-fill) instead. You only need
* to press keys one by one if there is special keyboard handling on the page - in this case use
* [locator.pressSequentially(text[, options])](https://playwright.dev/docs/api/class-locator#locator-press-sequentially).
* @param selector A selector to search for an element. If there are multiple elements satisfying the selector, the first will be
* used.
* @param text A text to type into a focused element.
* @param options
*/
type(
selector: string,
text: string,
options?: {
/**
* Time to wait between key presses in milliseconds. Defaults to 0.
*/
delay?: number
/**
* This option has no effect.
* @deprecated This option has no effect.
*/
noWaitAfter?: boolean
/**
* Allows to cancel the operation using an
* [`AbortSignal`](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal). If the signal is aborted, the
* operation will be aborted and throw an error. Note that providing a signal does not disable the default timeout,
* which can be changed using
* [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); pass
* `timeout: 0` to disable the timeout entirely.
*/
signal?: AbortSignal
/**
* 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.
*/
strict?: boolean
/**
* Maximum time in milliseconds. Defaults to `0` - no timeout. The default value can be changed via `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.
*/
timeout?: number
},
): Promise<void>
/**
* **NOTE** Use locator-based [locator.uncheck([options])](https://playwright.dev/docs/api/class-locator#locator-uncheck)
* instead. Read more about [locators](https://playwright.dev/docs/locators).
*
* This method checks an element matching
* [`selector`](https://playwright.dev/docs/api/class-frame#frame-uncheck-option-selector) by performing the following
* steps:
* 1. Find an element matching
* [`selector`](https://playwright.dev/docs/api/class-frame#frame-uncheck-option-selector). If there is none,
* wait until a matching element is attached to the DOM.
* 1. Ensure that matched element is a checkbox or a radio input. If not, this method throws. If the element is
* already unchecked, this method returns immediately.
* 1. Wait for [actionability](https://playwright.dev/docs/actionability) checks on the matched element, unless
* [`force`](https://playwright.dev/docs/api/class-frame#frame-uncheck-option-force) option is set. If the
* element is detached during the checks, the whole action is retried.
* 1. Scroll the element into view if needed.
* 1. Use [page.mouse](https://playwright.dev/docs/api/class-page#page-mouse) to click in the center of the
* element.
* 1. Ensure that the element is now unchecked. If not, this method throws.
*
* When all steps combined have not finished during the specified
* [`timeout`](https://playwright.dev/docs/api/class-frame#frame-uncheck-option-timeout), this method throws a
* [TimeoutError](https://playwright.dev/docs/api/class-timeouterror). Passing zero timeout disables this.
* @param selector A selector to search for an element. If there are multiple elements satisfying the selector, the first will be
* used.
* @param options
*/
uncheck(
selector: string,
options?: {
/**
* Whether to bypass the [actionability](https://playwright.dev/docs/actionability) checks. Defaults to `false`.
*/
force?: boolean
/**
* This option has no effect.
* @deprecated This option has no effect.
*/
noWaitAfter?: boolean
/**
* A point to use relative to the top-left corner of element padding box. If not specified, uses some visible point of
* the element.
*/
position?: {
x: number
y: number
}
/**
* Controls whether Playwright scrolls the element into view before performing the action. Defaults to `"auto"`, which
* scrolls the element into view when necessary, including scrolling nested scrollable containers. When set to
* `"none"`, Playwright does not scroll the element and the action fails if the element is not already in the
* viewport. This is useful to assert that an element is reachable by the user without additional scrolling.
*/
scroll?: 'auto' | 'none'
/**
* Allows to cancel the operation using an
* [`AbortSignal`](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal). If the signal is aborted, the
* operation will be aborted and throw an error. Note that providing a signal does not disable the default timeout,
* which can be changed using
* [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); pass
* `timeout: 0` to disable the timeout entirely.
*/
signal?: AbortSignal
/**
* 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.
*/
strict?: boolean
/**
* Maximum time in milliseconds. Defaults to `0` - no timeout. The default value can be changed via `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.
*/
timeout?: number
/**
* When set, this method only performs the [actionability](https://playwright.dev/docs/actionability) checks and skips the action. Defaults
* to `false`. Useful to wait until the element is ready for the action without performing it.
*/
trial?: boolean
},
): Promise<void>
/**
* Returns frame's url.
*/
url(): string
/**
* Waits for the required load state to be reached.
*
* This returns when the frame reaches a required load state, `load` by default. The navigation must have been
* committed when this method is called. If current document has already reached the required state, resolves
* immediately.
*
* **NOTE** Most of the time, this method is not needed because Playwright
* [auto-waits before every action](https://playwright.dev/docs/actionability).
*
* **Usage**
*
* ```js
* await frame.click('button'); // Click triggers navigation.
* await frame.waitForLoadState(); // Waits for 'load' state by default.
* ```
*
* @param state Optional load state to wait for, defaults to `load`. If the state has been already reached while loading current
* document, the method resolves immediately. Can be one of:
* - `'load'` - wait for the `load` event to be fired.
* - `'domcontentloaded'` - wait for the `DOMContentLoaded` event to be fired.
* - `'networkidle'` - **DISCOURAGED** wait until there are no network connections for at least `500` ms. Don't use
* this method for testing, rely on web assertions to assess readiness instead.
* @param options
*/
waitForLoadState(
state?: 'load' | 'domcontentloaded' | 'networkidle',
options?: {
/**
* Allows to cancel the waiting using an
* [`AbortSignal`](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal). If the signal is aborted, the
* waiting will be aborted and the operation will throw an error. Note that providing a signal does not disable the
* default timeout, which can be changed using
* [browserContext.setDefaultTimeout(timeout)](https://playwright.dev/docs/api/class-browsercontext#browser-context-set-default-timeout);
* pass `timeout: 0` to disable the timeout entirely.
*/
signal?: AbortSignal
/**
* Maximum operation time in milliseconds. Defaults to `0` - no timeout. The default value can be changed via
* `navigationTimeout` option in the config, or by using the
* [browserContext.setDefaultNavigationTimeout(timeout)](https://playwright.dev/docs/api/class-browsercontext#browser-context-set-default-navigation-timeout),
* [browserContext.setDefaultTimeout(timeout)](https://playwright.dev/docs/api/class-browsercontext#browser-context-set-default-timeout),
* [page.setDefaultNavigationTimeout(timeout)](https://playwright.dev/docs/api/class-page#page-set-default-navigation-timeout)
* or [page.setDefaultTimeout(timeout)](https://playwright.dev/docs/api/class-page#page-set-default-timeout) methods.
*/
timeout?: number
},
): Promise<void>
/**
* Waits for the frame navigation and returns the main resource response. In case of multiple redirects, the
* navigation will resolve with the response of the last redirect. In case of navigation to a different anchor or
* navigation due to History API usage, the navigation will resolve with `null`.
*
* **Usage**
*
* This method waits for the frame to navigate to a new URL. It is useful for when you run code which will indirectly
* cause the frame to navigate. Consider this example:
*
* ```js
* // Start waiting for navigation before clicking. Note no await.
* const navigationPromise = page.waitForNavigation();
* await page.getByText('Navigate after timeout').click();
* await navigationPromise;
* ```
*
* **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.
*
* @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
*/
waitForNavigation(options?: {
/**
* Allows to cancel the waiting using an
* [`AbortSignal`](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal). If the signal is aborted, the
* waiting will be aborted and the operation will throw an error. Note that providing a signal does not disable the
* default timeout, which can be changed using
* [browserContext.setDefaultTimeout(timeout)](https://playwright.dev/docs/api/class-browsercontext#browser-context-set-default-timeout);
* pass `timeout: 0` to disable the timeout entirely.
*/
signal?: AbortSignal
/**
* Maximum operation time in milliseconds. Defaults to `0` - no timeout. The default value can be changed via
* `navigationTimeout` option in the config, or by using the
* [browserContext.setDefaultNavigationTimeout(timeout)](https://playwright.dev/docs/api/class-browsercontext#browser-context-set-default-navigation-timeout),
* [browserContext.setDefaultTimeout(timeout)](https://playwright.dev/docs/api/class-browsercontext#browser-context-set-default-timeout),
* [page.setDefaultNavigationTimeout(timeout)](https://playwright.dev/docs/api/class-page#page-set-default-navigation-timeout)
* or [page.setDefaultTimeout(timeout)](https://playwright.dev/docs/api/class-page#page-set-default-timeout) methods.
*/
timeout?: number
/**
* A glob pattern, regex pattern, URL pattern, or predicate receiving [URL] to match while waiting for the navigation.
* Note that if the parameter is a string without wildcard characters, the method will wait for navigation to URL that
* is exactly equal to the string.
*/
url?: string | RegExp | URLPattern | ((url: URL) => boolean)
/**
* When to consider operation succeeded, defaults to `load`. Events can be either:
* - `'domcontentloaded'` - consider operation to be finished when the `DOMContentLoaded` event is fired.
* - `'load'` - consider operation to be finished when the `load` event is fired.
* - `'networkidle'` - **DISCOURAGED** consider operation to be finished when there are no network connections for
* at least `500` ms. Don't use this method for testing, rely on web assertions to assess readiness instead.
* - `'commit'` - consider operation to be finished when network response is received and the document started
* loading.
*/
waitUntil?: 'load' | 'domcontentloaded' | 'networkidle' | 'commit'
}): Promise<null | Response>
/**
* **NOTE** Never wait for timeout in production. Tests that wait for time are inherently flaky. Use
* [Locator](https://playwright.dev/docs/api/class-locator) actions and web assertions that wait automatically.
*
* Waits for the given [`timeout`](https://playwright.dev/docs/api/class-frame#frame-wait-for-timeout-option-timeout)
* in milliseconds.
*
* Note that `frame.waitForTimeout()` should only be used for debugging. Tests using the timer in production are going
* to be flaky. Use signals such as network events, selectors becoming visible and others instead.
* @param timeout A timeout to wait for
*/
waitForTimeout(timeout: number): Promise<void>
/**
* Waits for the frame to navigate to the given URL.
*
* **Usage**
*
* ```js
* await frame.click('a.delayed-navigation'); // Clicking the link will indirectly cause a navigation
* await frame.waitForURL('**\/target.html');
* ```
*
* @param url A glob pattern, regex pattern, URL pattern, or predicate receiving [URL] to match while waiting for the navigation.
* Note that if the parameter is a string without wildcard characters, the method will wait for navigation to URL that
* is exactly equal to the string.
* @param options
*/
waitForURL(
url: string | RegExp | URLPattern | ((url: URL) => boolean),
options?: {
/**
* Allows to cancel the waiting using an
* [`AbortSignal`](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal). If the signal is aborted, the
* waiting will be aborted and the operation will throw an error. Note that providing a signal does not disable the
* default timeout, which can be changed using
* [browserContext.setDefaultTimeout(timeout)](https://playwright.dev/docs/api/class-browsercontext#browser-context-set-default-timeout);
* pass `timeout: 0` to disable the timeout entirely.
*/
signal?: AbortSignal
/**
* Maximum operation time in milliseconds. Defaults to `0` - no timeout. The default value can be changed via
* `navigationTimeout` option in the config, or by using the
* [browserContext.setDefaultNavigationTimeout(timeout)](https://playwright.dev/docs/api/class-browsercontext#browser-context-set-default-navigation-timeout),
* [browserContext.setDefaultTimeout(timeout)](https://playwright.dev/docs/api/class-browsercontext#browser-context-set-default-timeout),
* [page.setDefaultNavigationTimeout(timeout)](https://playwright.dev/docs/api/class-page#page-set-default-navigation-timeout)
* or [page.setDefaultTimeout(timeout)](https://playwright.dev/docs/api/class-page#page-set-default-timeout) methods.
*/
timeout?: number
/**
* When to consider operation succeeded, defaults to `load`. Events can be either:
* - `'domcontentloaded'` - consider operation to be finished when the `DOMContentLoaded` event is fired.
* - `'load'` - consider operation to be finished when the `load` event is fired.
* - `'networkidle'` - **DISCOURAGED** consider operation to be finished when there are no network connections for
* at least `500` ms. Don't use this method for testing, rely on web assertions to assess readiness instead.
* - `'commit'` - consider operation to be finished when network response is received and the document started
* loading.
*/
waitUntil?: 'load' | 'domcontentloaded' | 'networkidle' | 'commit'
},
): Promise<void>
}
FrameLocator
FrameLocator represents a view to the iframe on the page. It captures the logic sufficient to retrieve the
iframe and locate elements in that iframe. FrameLocator can be created with either
locator.contentFrame(),
page.frameLocator([selector]) or
locator.frameLocator(selector) method.
const locator = page.locator('#my-frame').contentFrame().getByText('Submit')
await locator.click()
Strictness
Frame locators are strict. This means that all operations on frame locators will throw if more than one element matches a given selector.
// Throws if there are several frames in DOM:
await page.locator('.result-frame').contentFrame().getByRole('button').click()
// Works because we explicitly tell locator to pick the first frame:
await page.locator('.result-frame').contentFrame().first().getByRole('button').click()
Any frame
Calling page.frameLocator([selector]) or frame.frameLocator([selector]) without a selector creates a frame locator that starts the search in any frame of the subtree - so that you don't need to locate the iframe first.
// Finds the button in any frame on the page:
await page.frameLocator().getByRole('button').click()
// Finds the iframe with id "my-frame" anywhere on the page, and clicks the button inside it:
await page.frameLocator().locator('#my-frame').contentFrame().getByRole('button').click()
Only the start of the search is affected - the rest of the locator is resolved inside a single frame, just like any other locator. Following the strictness rules above, an error is thrown when elements are matched in multiple frames.
Such a frame locator does not point to a particular iframe, so
frameLocator.owner(),
frameLocator.first(),
frameLocator.last() and
frameLocator.nth(index) are not supported
on it.
Converting Locator to FrameLocator
If you have a Locator object pointing to an iframe it can be
converted to FrameLocator using
locator.contentFrame().
Converting FrameLocator to Locator
If you have a FrameLocator object it can be converted to
Locator pointing to the same iframe using
frameLocator.owner().
interface FrameLocator {
/**
* Returns locator to the first matching frame.
* @deprecated Use [locator.first()](https://playwright.dev/docs/api/class-locator#locator-first) followed by
* [locator.contentFrame()](https://playwright.dev/docs/api/class-locator#locator-content-frame) instead.
*/
first(): FrameLocator
/**
* When working with iframes, you can create a frame locator that will enter the iframe and allow selecting elements
* in that iframe.
* @param selector A selector to use when resolving DOM element.
*/
frameLocator(selector: string): FrameLocator
/**
* Allows locating elements by their alt text.
*
* **Usage**
*
* For example, this method will find the image by alt text "Playwright logo":
*
* ```html
* <img alt='Playwright logo'>
* ```
*
* ```js
* await page.getByAltText('Playwright logo').click();
* ```
*
* @param text Text to locate the element for.
* @param options
*/
getByAltText(
text: string | RegExp,
options?: {
/**
* Whether to find an exact match: case-sensitive and whole-string. Default to false. Ignored when locating by a
* regular expression. Note that exact match still trims whitespace.
*/
exact?: boolean
},
): Locator
/**
* Allows locating input elements by the text of the associated `<label>` or `aria-labelledby` element, or by the
* `aria-label` attribute.
*
* **Usage**
*
* For example, this method will find inputs by label "Username" and "Password" in the following DOM:
*
* ```html
* <input aria-label="Username">
* <label for="password-input">Password:</label>
* <input id="password-input">
* ```
*
* ```js
* await page.getByLabel('Username').fill('john');
* await page.getByLabel('Password').fill('secret');
* ```
*
* @param text Text to locate the element for.
* @param options
*/
getByLabel(
text: string | RegExp,
options?: {
/**
* Whether to find an exact match: case-sensitive and whole-string. Default to false. Ignored when locating by a
* regular expression. Note that exact match still trims whitespace.
*/
exact?: boolean
},
): Locator
/**
* Allows locating input elements by the placeholder text.
*
* **Usage**
*
* For example, consider the following DOM structure.
*
* ```html
* <input type="email" placeholder="name@example.com" />
* ```
*
* You can fill the input after locating it by the placeholder text:
*
* ```js
* await page
* .getByPlaceholder('name@example.com')
* .fill('playwright@microsoft.com');
* ```
*
* @param text Text to locate the element for.
* @param options
*/
getByPlaceholder(
text: string | RegExp,
options?: {
/**
* Whether to find an exact match: case-sensitive and whole-string. Default to false. Ignored when locating by a
* regular expression. Note that exact match still trims whitespace.
*/
exact?: boolean
},
): Locator
/**
* Allows locating elements by their [ARIA role](https://www.w3.org/TR/wai-aria-1.2/#roles),
* [ARIA attributes](https://www.w3.org/TR/wai-aria-1.2/#aria-attributes) and
* [accessible name](https://w3c.github.io/accname/#dfn-accessible-name).
*
* **Usage**
*
* Consider the following DOM structure.
*
* ```html
* <h3>Sign up</h3>
* <label>
* <input type="checkbox" /> Subscribe
* </label>
* <br/>
* <button>Submit</button>
* ```
*
* You can locate each element by its implicit role:
*
* ```js
* await expect(page.getByRole('heading', { name: 'Sign up' })).toBeVisible();
*
* await page.getByRole('checkbox', { name: 'Subscribe' }).check();
*
* await page.getByRole('button', { name: /submit/i }).click();
* ```
*
* **Details**
*
* Role selector **does not replace** accessibility audits and conformance tests, but rather gives early feedback
* about the ARIA guidelines.
*
* Many html elements have an implicitly [defined role](https://w3c.github.io/html-aam/#html-element-role-mappings)
* that is recognized by the role selector. You can find all the
* [supported roles here](https://www.w3.org/TR/wai-aria-1.2/#role_definitions). ARIA guidelines **do not recommend**
* duplicating implicit roles and attributes by setting `role` and/or `aria-*` attributes to default values.
* @param role Required aria role.
* @param options
*/
getByRole(
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?: {
/**
* An attribute that is usually set by `aria-checked` or native `<input type=checkbox>` controls.
*
* Learn more about [`aria-checked`](https://www.w3.org/TR/wai-aria-1.2/#aria-checked).
*/
checked?: boolean
/**
* Option to match the [accessible description](https://w3c.github.io/accname/#dfn-accessible-description). By
* default, matching is case-insensitive and searches for a substring, use
* [`exact`](https://playwright.dev/docs/api/class-framelocator#frame-locator-get-by-role-option-exact) to control
* this behavior.
*
* Learn more about [accessible description](https://w3c.github.io/accname/#dfn-accessible-description).
*/
description?: string | RegExp
/**
* 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).
*
*/
disabled?: boolean
/**
* Whether [`name`](https://playwright.dev/docs/api/class-framelocator#frame-locator-get-by-role-option-name) and
* [`description`](https://playwright.dev/docs/api/class-framelocator#frame-locator-get-by-role-option-description)
* are matched exactly: case-sensitive and whole-string. Defaults to false. Ignored when the value is a regular
* expression. Note that exact match still trims whitespace.
*/
exact?: boolean
/**
* An attribute that is usually set by `aria-expanded`.
*
* Learn more about [`aria-expanded`](https://www.w3.org/TR/wai-aria-1.2/#aria-expanded).
*/
expanded?: boolean
/**
* Option that controls whether hidden elements are matched. By default, only non-hidden elements, as
* [defined by ARIA](https://www.w3.org/TR/wai-aria-1.2/#tree_exclusion), are matched by role selector.
*
* Learn more about [`aria-hidden`](https://www.w3.org/TR/wai-aria-1.2/#aria-hidden).
*/
includeHidden?: boolean
/**
* A number attribute that is usually present for roles `heading`, `listitem`, `row`, `treeitem`, with default values
* for `<h1>-<h6>` elements.
*
* Learn more about [`aria-level`](https://www.w3.org/TR/wai-aria-1.2/#aria-level).
*/
level?: number
/**
* Option to match the [accessible name](https://w3c.github.io/accname/#dfn-accessible-name). By default, matching is
* case-insensitive and searches for a substring, use
* [`exact`](https://playwright.dev/docs/api/class-framelocator#frame-locator-get-by-role-option-exact) to control
* this behavior.
*
* Learn more about [accessible name](https://w3c.github.io/accname/#dfn-accessible-name).
*/
name?: string | RegExp
/**
* An attribute that is usually set by `aria-pressed`.
*
* Learn more about [`aria-pressed`](https://www.w3.org/TR/wai-aria-1.2/#aria-pressed).
*/
pressed?: boolean
/**
* An attribute that is usually set by `aria-selected`.
*
* Learn more about [`aria-selected`](https://www.w3.org/TR/wai-aria-1.2/#aria-selected).
*/
selected?: boolean
},
): Locator
/**
* Locate element by the test id.
*
* **Usage**
*
* Consider the following DOM structure.
*
* ```html
* <button data-testid="directions">Itinéraire</button>
* ```
*
* You can locate the element by its test id:
*
* ```js
* await page.getByTestId('directions').click();
* ```
*
* **Details**
*
* By default, the `data-testid` attribute is used as a test id. Use
* [selectors.setTestIdAttribute(attributeName)](https://playwright.dev/docs/api/class-selectors#selectors-set-test-id-attribute)
* to configure a different test id attribute if necessary.
*
* ```js
* // Set custom test id attribute from @playwright/test config:
* import { defineConfig } from '@playwright/test';
*
* export default defineConfig({
* use: {
* testIdAttribute: 'data-pw'
* },
* });
* ```
*
* @param testId Id to locate the element by.
*/
getByTestId(testId: string | RegExp): Locator
/**
* Allows locating elements that contain given text.
*
* See also [locator.filter([options])](https://playwright.dev/docs/api/class-locator#locator-filter) that allows to
* match by another criteria, like an accessible role, and then filter by the text content.
*
* **Usage**
*
* Consider the following DOM structure:
*
* ```html
* <div>Hello <span>world</span></div>
* <div>Hello</div>
* ```
*
* You can locate by text substring, exact string, or a regular expression:
*
* ```js
* // Matches <span>
* page.getByText('world');
*
* // Matches first <div>
* page.getByText('Hello world');
*
* // Matches second <div>
* page.getByText('Hello', { exact: true });
*
* // Matches both <div>s
* page.getByText(/Hello/);
*
* // Matches second <div>
* page.getByText(/^hello$/i);
* ```
*
* **Details**
*
* Matching by text always normalizes whitespace, even with exact match. For example, it turns multiple spaces into
* one, turns line breaks into spaces and ignores leading and trailing whitespace.
*
* Input elements of the type `button` and `submit` are matched by their `value` instead of the text content. For
* example, locating by text `"Log in"` matches `<input type=button value="Log in">`.
* @param text Text to locate the element for.
* @param options
*/
getByText(
text: string | RegExp,
options?: {
/**
* Whether to find an exact match: case-sensitive and whole-string. Default to false. Ignored when locating by a
* regular expression. Note that exact match still trims whitespace.
*/
exact?: boolean
},
): Locator
/**
* Allows locating elements by their title attribute.
*
* **Usage**
*
* Consider the following DOM structure.
*
* ```html
* <span title='Issues count'>25 issues</span>
* ```
*
* You can check the issues count after locating it by the title text:
*
* ```js
* await expect(page.getByTitle('Issues count')).toHaveText('25 issues');
* ```
*
* @param text Text to locate the element for.
* @param options
*/
getByTitle(
text: string | RegExp,
options?: {
/**
* Whether to find an exact match: case-sensitive and whole-string. Default to false. Ignored when locating by a
* regular expression. Note that exact match still trims whitespace.
*/
exact?: boolean
},
): Locator
/**
* Returns locator to the last matching frame.
* @deprecated Use [locator.last()](https://playwright.dev/docs/api/class-locator#locator-last) followed by
* [locator.contentFrame()](https://playwright.dev/docs/api/class-locator#locator-content-frame) instead.
*/
last(): FrameLocator
/**
* The method finds an element matching the specified selector in the locator's subtree. It also accepts filter
* options, similar to [locator.filter([options])](https://playwright.dev/docs/api/class-locator#locator-filter)
* method.
*
* [Learn more about locators](https://playwright.dev/docs/locators).
* @param selectorOrLocator A selector or locator to use when resolving DOM element.
* @param options
*/
locator(
selectorOrLocator: string | Locator,
options?: {
/**
* Narrows down the results of the method to those which contain elements matching this relative locator. For example,
* `article` that has `text=Playwright` matches `<article><div>Playwright</div></article>`.
*
* Inner locator **must be relative** to the outer locator and is queried starting with the outer locator match, not
* the document root. For example, you can find `content` that has `div` in
* `<article><content><div>Playwright</div></content></article>`. However, looking for `content` that has `article
* div` will fail, because the inner locator must be relative and should not use any elements outside the `content`.
*
* Note that outer and inner locators must belong to the same frame. Inner locator must not contain
* [FrameLocator](https://playwright.dev/docs/api/class-framelocator)s.
*/
has?: Locator
/**
* Matches elements that do not contain an element that matches an inner locator. Inner locator is queried against the
* outer one. For example, `article` that does not have `div` matches `<article><span>Playwright</span></article>`.
*
* Note that outer and inner locators must belong to the same frame. Inner locator must not contain
* [FrameLocator](https://playwright.dev/docs/api/class-framelocator)s.
*/
hasNot?: Locator
/**
* Matches elements that do not contain specified text somewhere inside, possibly in a child or a descendant element.
* When passed a [string], matching is case-insensitive and searches for a substring.
*/
hasNotText?: string | RegExp
/**
* Matches elements containing specified text somewhere inside, possibly in a child or a descendant element. When
* passed a [string], matching is case-insensitive and searches for a substring. For example, `"Playwright"` matches
* `<article><div>Playwright</div></article>`.
*/
hasText?: string | RegExp
},
): Locator
/**
* Returns locator to the n-th matching frame. It's zero based, `nth(0)` selects the first frame.
* @deprecated Use [locator.nth(index)](https://playwright.dev/docs/api/class-locator#locator-nth) followed by
* [locator.contentFrame()](https://playwright.dev/docs/api/class-locator#locator-content-frame) instead.
* @param index
*/
nth(index: number): FrameLocator
/**
* Returns a [Locator](https://playwright.dev/docs/api/class-locator) object pointing to the same `iframe` as this
* frame locator.
*
* Useful when you have a [FrameLocator](https://playwright.dev/docs/api/class-framelocator) object obtained
* somewhere, and later on would like to interact with the `iframe` element.
*
* For a reverse operation, use
* [locator.contentFrame()](https://playwright.dev/docs/api/class-locator#locator-content-frame).
*
* **Usage**
*
* ```js
* const frameLocator = page.locator('iframe[name="embedded"]').contentFrame();
* // ...
* const locator = frameLocator.owner();
* await expect(locator).toBeVisible();
* ```
*
*/
owner(): Locator
}
FullConfig
Resolved configuration which is accessible via testInfo.config and is passed to the test reporters. To see the format of Playwright configuration file, please see TestConfig instead.
interface FullConfig<TestArgs = {}, WorkerArgs = {}> {
/**
* List of resolved projects.
*/
projects: FullProject<TestArgs, WorkerArgs>[]
/**
* See [testConfig.reporter](https://playwright.dev/docs/api/class-testconfig#test-config-reporter).
*/
reporter: ReporterDescription[]
/**
* See [testConfig.webServer](https://playwright.dev/docs/api/class-testconfig#test-config-web-server).
*/
webServer: TestConfigWebServer | null
/**
* Snapshot of [`process.argv`](https://nodejs.org/api/process.html#processargv) captured in the runner process.
* Useful for reading custom command-line arguments — for example, args supplied after the `--` separator (`npx
* playwright test -- --build-path=./out`). Playwright does not parse these; consumers are responsible for slicing and
* interpreting them with any argument-parsing library.
*/
argv: Array<string>
/**
* Path to the configuration file used to run the tests. The value is an empty string if no config file was used.
*/
configFile?: string
/**
* See
* [testConfig.failOnFlakyTests](https://playwright.dev/docs/api/class-testconfig#test-config-fail-on-flaky-tests).
*/
failOnFlakyTests: boolean
/**
* See [testConfig.forbidOnly](https://playwright.dev/docs/api/class-testconfig#test-config-forbid-only).
*/
forbidOnly: boolean
/**
* See [testConfig.fullyParallel](https://playwright.dev/docs/api/class-testconfig#test-config-fully-parallel).
*/
fullyParallel: boolean
/**
* See [testConfig.globalSetup](https://playwright.dev/docs/api/class-testconfig#test-config-global-setup).
*/
globalSetup: null | string
/**
* See [testConfig.globalTeardown](https://playwright.dev/docs/api/class-testconfig#test-config-global-teardown).
*/
globalTeardown: null | string
/**
* See [testConfig.globalTimeout](https://playwright.dev/docs/api/class-testconfig#test-config-global-timeout).
*/
globalTimeout: number
/**
* See [testConfig.grep](https://playwright.dev/docs/api/class-testconfig#test-config-grep).
*/
grep: RegExp | Array<RegExp>
/**
* See [testConfig.grepInvert](https://playwright.dev/docs/api/class-testconfig#test-config-grep-invert).
*/
grepInvert: null | RegExp | Array<RegExp>
/**
* See [testConfig.maxFailures](https://playwright.dev/docs/api/class-testconfig#test-config-max-failures).
*/
maxFailures: number
/**
* See [testConfig.metadata](https://playwright.dev/docs/api/class-testconfig#test-config-metadata).
*/
metadata: Metadata
/**
* See [testConfig.preserveOutput](https://playwright.dev/docs/api/class-testconfig#test-config-preserve-output).
*/
preserveOutput: 'always' | 'never' | 'failures-only'
/**
* See [testConfig.quiet](https://playwright.dev/docs/api/class-testconfig#test-config-quiet).
*/
quiet: boolean
/**
* See [testConfig.reportSlowTests](https://playwright.dev/docs/api/class-testconfig#test-config-report-slow-tests).
*/
reportSlowTests: null | {
/**
* The maximum number of slow test files to report.
*/
max: number
/**
* Test file duration in milliseconds that is considered slow.
*/
threshold: number
}
/**
* Base directory for all relative paths used in the reporters.
*/
rootDir: string
/**
* See [testConfig.shard](https://playwright.dev/docs/api/class-testconfig#test-config-shard).
*/
shard: null | {
/**
* The total number of shards.
*/
total: number
/**
* The index of the shard to execute, one-based.
*/
current: number
}
/**
* Resolved global tags. See [testConfig.tag](https://playwright.dev/docs/api/class-testconfig#test-config-tag).
*/
tags: Array<string>
/**
* See [testConfig.updateSnapshots](https://playwright.dev/docs/api/class-testconfig#test-config-update-snapshots).
*/
updateSnapshots: 'all' | 'changed' | 'missing' | 'none'
/**
* See
* [testConfig.updateSourceMethod](https://playwright.dev/docs/api/class-testconfig#test-config-update-source-method).
*/
updateSourceMethod: 'overwrite' | '3way' | 'patch'
/**
* Playwright version.
*/
version: string
/**
* See [testConfig.workers](https://playwright.dev/docs/api/class-testconfig#test-config-workers).
*/
workers: number
}
FullProject
Runtime representation of the test project configuration. It is accessible in the tests via testInfo.project and workerInfo.project and is passed to the test reporters. To see the format of the project in the Playwright configuration file please see TestProject instead.
interface FullProject<TestArgs = {}, WorkerArgs = {}> {
/**
* See [testProject.use](https://playwright.dev/docs/api/class-testproject#test-project-use).
*/
use: UseOptions<PlaywrightTestOptions & TestArgs, PlaywrightWorkerOptions & WorkerArgs>
/**
* See [testProject.dependencies](https://playwright.dev/docs/api/class-testproject#test-project-dependencies).
*/
dependencies: Array<string>
/**
* See [testProject.grep](https://playwright.dev/docs/api/class-testproject#test-project-grep).
*/
grep: RegExp | Array<RegExp>
/**
* See [testProject.grepInvert](https://playwright.dev/docs/api/class-testproject#test-project-grep-invert).
*/
grepInvert: null | RegExp | Array<RegExp>
/**
* See [testProject.ignoreSnapshots](https://playwright.dev/docs/api/class-testproject#test-project-ignore-snapshots).
*/
ignoreSnapshots: boolean
/**
* See [testProject.metadata](https://playwright.dev/docs/api/class-testproject#test-project-metadata).
*/
metadata: Metadata
/**
* See [testProject.name](https://playwright.dev/docs/api/class-testproject#test-project-name).
*/
name: string
/**
* See [testProject.outputDir](https://playwright.dev/docs/api/class-testproject#test-project-output-dir).
*/
outputDir: string
/**
* See [testProject.repeatEach](https://playwright.dev/docs/api/class-testproject#test-project-repeat-each).
*/
repeatEach: number
/**
* See [testProject.retries](https://playwright.dev/docs/api/class-testproject#test-project-retries).
*/
retries: number
/**
* See [testProject.snapshotDir](https://playwright.dev/docs/api/class-testproject#test-project-snapshot-dir).
*/
snapshotDir: string
/**
* See [testProject.teardown](https://playwright.dev/docs/api/class-testproject#test-project-teardown).
*/
teardown?: string
/**
* See [testProject.testDir](https://playwright.dev/docs/api/class-testproject#test-project-test-dir).
*/
testDir: string
/**
* See [testProject.testIgnore](https://playwright.dev/docs/api/class-testproject#test-project-test-ignore).
*/
testIgnore: string | RegExp | Array<string | RegExp>
/**
* See [testProject.testMatch](https://playwright.dev/docs/api/class-testproject#test-project-test-match).
*/
testMatch: string | RegExp | Array<string | RegExp>
/**
* See [testProject.timeout](https://playwright.dev/docs/api/class-testproject#test-project-timeout).
*/
timeout: number
}
JSHandle
JSHandle represents an in-page JavaScript object. JSHandles can be created with the page.evaluateHandle(pageFunction[, arg, options]) method.
const windowHandle = await page.evaluateHandle(() => window)
// ...
JSHandle prevents the referenced JavaScript object being garbage collected unless the handle is exposed with jsHandle.dispose(). JSHandles are auto-disposed when their origin frame gets navigated or the parent context gets destroyed.
JSHandle instances can be used as an argument in page.$eval(selector, pageFunction[, arg, options]), page.evaluate(pageFunction[, arg, options]) and page.evaluateHandle(pageFunction[, arg, options]) methods.
interface JSHandle<T = any> {
/**
* Returns the return value of
* [`pageFunction`](https://playwright.dev/docs/api/class-elementhandle#element-handle-evaluate-option-expression).
*
* This method passes this handle as the first argument to
* [`pageFunction`](https://playwright.dev/docs/api/class-elementhandle#element-handle-evaluate-option-expression).
*
* If [`pageFunction`](https://playwright.dev/docs/api/class-elementhandle#element-handle-evaluate-option-expression)
* returns a [Promise], then `handle.evaluate` would wait for the promise to resolve and return its value.
*
* **Usage**
*
* ```js
* const tweetHandle = await page.$('.tweet .retweets');
* expect(await tweetHandle.evaluate(node => node.innerText)).toBe('10 retweets');
* ```
*
* @param pageFunction Function to be evaluated in the page context.
* @param arg Optional argument to pass to
* [`pageFunction`](https://playwright.dev/docs/api/class-elementhandle#element-handle-evaluate-option-expression).
* @param options
*/
evaluate<R, Arg, O extends T = T>(
pageFunction: PageFunctionOn<O, Arg, R>,
arg: Arg,
options?: { exposeFunctions?: boolean },
): Promise<R>
/**
* Returns the return value of
* [`pageFunction`](https://playwright.dev/docs/api/class-elementhandle#element-handle-evaluate-option-expression).
*
* This method passes this handle as the first argument to
* [`pageFunction`](https://playwright.dev/docs/api/class-elementhandle#element-handle-evaluate-option-expression).
*
* If [`pageFunction`](https://playwright.dev/docs/api/class-elementhandle#element-handle-evaluate-option-expression)
* returns a [Promise], then `handle.evaluate` would wait for the promise to resolve and return its value.
*
* **Usage**
*
* ```js
* const tweetHandle = await page.$('.tweet .retweets');
* expect(await tweetHandle.evaluate(node => node.innerText)).toBe('10 retweets');
* ```
*
* @param pageFunction Function to be evaluated in the page context.
* @param arg Optional argument to pass to
* [`pageFunction`](https://playwright.dev/docs/api/class-elementhandle#element-handle-evaluate-option-expression).
* @param options
*/
evaluate<R, O extends T = T>(
pageFunction: PageFunctionOn<O, void, R>,
arg?: any,
options?: { exposeFunctions?: boolean },
): Promise<R>
/**
* Returns the return value of
* [`pageFunction`](https://playwright.dev/docs/api/class-elementhandle#element-handle-evaluate-handle-option-expression)
* as a [JSHandle](https://playwright.dev/docs/api/class-jshandle).
*
* This method passes this handle as the first argument to
* [`pageFunction`](https://playwright.dev/docs/api/class-elementhandle#element-handle-evaluate-handle-option-expression).
*
* The only difference between `jsHandle.evaluate` and `jsHandle.evaluateHandle` is that `jsHandle.evaluateHandle`
* returns [JSHandle](https://playwright.dev/docs/api/class-jshandle).
*
* If the function passed to the `jsHandle.evaluateHandle` returns a [Promise], then `jsHandle.evaluateHandle` would
* wait for the promise to resolve and return its value.
*
* See
* [page.evaluateHandle(pageFunction[, arg, options])](https://playwright.dev/docs/api/class-page#page-evaluate-handle)
* for more details.
* @param pageFunction Function to be evaluated in the page context.
* @param arg Optional argument to pass to
* [`pageFunction`](https://playwright.dev/docs/api/class-elementhandle#element-handle-evaluate-handle-option-expression).
* @param options
*/
evaluateHandle<R, Arg, O extends T = T>(
pageFunction: PageFunctionOn<O, Arg, R>,
arg: Arg,
options?: { exposeFunctions?: boolean },
): Promise<SmartHandle<R>>
/**
* Returns the return value of
* [`pageFunction`](https://playwright.dev/docs/api/class-elementhandle#element-handle-evaluate-handle-option-expression)
* as a [JSHandle](https://playwright.dev/docs/api/class-jshandle).
*
* This method passes this handle as the first argument to
* [`pageFunction`](https://playwright.dev/docs/api/class-elementhandle#element-handle-evaluate-handle-option-expression).
*
* The only difference between `jsHandle.evaluate` and `jsHandle.evaluateHandle` is that `jsHandle.evaluateHandle`
* returns [JSHandle](https://playwright.dev/docs/api/class-jshandle).
*
* If the function passed to the `jsHandle.evaluateHandle` returns a [Promise], then `jsHandle.evaluateHandle` would
* wait for the promise to resolve and return its value.
*
* See
* [page.evaluateHandle(pageFunction[, arg, options])](https://playwright.dev/docs/api/class-page#page-evaluate-handle)
* for more details.
* @param pageFunction Function to be evaluated in the page context.
* @param arg Optional argument to pass to
* [`pageFunction`](https://playwright.dev/docs/api/class-elementhandle#element-handle-evaluate-handle-option-expression).
* @param options
*/
evaluateHandle<R, O extends T = T>(
pageFunction: PageFunctionOn<O, void, R>,
arg?: any,
options?: { exposeFunctions?: boolean },
): Promise<SmartHandle<R>>
/**
* 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.
*
*/
jsonValue(): Promise<T>
/**
* Returns either `null` or the object handle itself, if the object handle is an instance of
* [ElementHandle](https://playwright.dev/docs/api/class-elementhandle).
*/
asElement(): T extends Node ? ElementHandle<T> : null
/**
* The `jsHandle.dispose` method stops referencing the element handle.
*/
dispose(): Promise<void>
/**
* The method returns a map with **own property names** as keys and JSHandle instances for the property values.
*
* **Usage**
*
* ```js
* const handle = await page.evaluateHandle(() => ({ window, document }));
* const properties = await handle.getProperties();
* const windowHandle = properties.get('window');
* const documentHandle = properties.get('document');
* await handle.dispose();
* ```
*
*/
getProperties(): Promise<Map<string, JSHandle>>
/**
* Fetches a single property from the referenced object.
* @param propertyName property to get
*/
getProperty(propertyName: string): Promise<JSHandle>
[Symbol.asyncDispose](): Promise<void>
}
Keyboard
Keyboard provides an api for managing a virtual keyboard. The high level api is
keyboard.type(text[, options]), which takes raw
characters and generates proper keydown, keypress/input, and keyup events on your page.
For finer control, you can use keyboard.down(key), keyboard.up(key), and keyboard.insertText(text) to manually fire events as if they were generated from a real keyboard.
An example of holding down Shift in order to select and delete some text:
await page.keyboard.type('Hello World!')
await page.keyboard.press('ArrowLeft')
await page.keyboard.down('Shift')
for (let i = 0; i < ' World'.length; i++) await page.keyboard.press('ArrowLeft')
await page.keyboard.up('Shift')
await page.keyboard.press('Backspace')
// Result text will end up saying 'Hello!'
An example of pressing uppercase A
await page.keyboard.press('Shift+KeyA')
// or
await page.keyboard.press('Shift+A')
An example to trigger select-all with the keyboard
await page.keyboard.press('ControlOrMeta+A')
interface Keyboard {
/**
* Dispatches a `keydown` event.
*
* [`key`](https://playwright.dev/docs/api/class-keyboard#keyboard-down-option-key) can specify the intended
* [keyboardEvent.key](https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/key) value or a single character
* to generate the text for. A superset of the
* [`key`](https://playwright.dev/docs/api/class-keyboard#keyboard-down-option-key) values can be found
* [here](https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/key/Key_Values). Examples of the keys are:
*
* `F1` - `F12`, `Digit0`- `Digit9`, `KeyA`- `KeyZ`, `Backquote`, `Minus`, `Equal`, `Backslash`, `Backspace`, `Tab`,
* `Delete`, `Escape`, `ArrowDown`, `End`, `Enter`, `Home`, `Insert`, `PageDown`, `PageUp`, `ArrowRight`, `ArrowUp`,
* etc.
*
* Following modification shortcuts are also supported: `Shift`, `Control`, `Alt`, `Meta`, `ShiftLeft`,
* `ControlOrMeta`. `ControlOrMeta` resolves to `Control` on Windows and Linux and to `Meta` on macOS.
*
* Holding down `Shift` will type the text that corresponds to the
* [`key`](https://playwright.dev/docs/api/class-keyboard#keyboard-down-option-key) in the upper case.
*
* If [`key`](https://playwright.dev/docs/api/class-keyboard#keyboard-down-option-key) is a single character, it is
* case-sensitive, so the values `a` and `A` will generate different respective texts.
*
* If [`key`](https://playwright.dev/docs/api/class-keyboard#keyboard-down-option-key) is a modifier key, `Shift`,
* `Meta`, `Control`, or `Alt`, subsequent key presses will be sent with that modifier active. To release the modifier
* key, use [keyboard.up(key)](https://playwright.dev/docs/api/class-keyboard#keyboard-up).
*
* After the key is pressed once, subsequent calls to
* [keyboard.down(key)](https://playwright.dev/docs/api/class-keyboard#keyboard-down) will have
* [repeat](https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/repeat) set to true. To release the key,
* use [keyboard.up(key)](https://playwright.dev/docs/api/class-keyboard#keyboard-up).
*
* **NOTE** Modifier keys DO influence `keyboard.down`. Holding down `Shift` will type the text in upper case.
*
* @param key Name of the key to press or a character to generate, such as `ArrowLeft` or `a`.
*/
down(key: string): Promise<void>
/**
* Dispatches only `input` event, does not emit the `keydown`, `keyup` or `keypress` events.
*
* **Usage**
*
* ```js
* page.keyboard.insertText('嗨');
* ```
*
* **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<void>
/**
* **NOTE** In most cases, you should use
* [locator.press(key[, options])](https://playwright.dev/docs/api/class-locator#locator-press) instead.
*
* [`key`](https://playwright.dev/docs/api/class-keyboard#keyboard-press-option-key) can specify the intended
* [keyboardEvent.key](https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/key) value or a single character
* to generate the text for. A superset of the
* [`key`](https://playwright.dev/docs/api/class-keyboard#keyboard-press-option-key) values can be found
* [here](https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/key/Key_Values). Examples of the keys are:
*
* `F1` - `F12`, `Digit0`- `Digit9`, `KeyA`- `KeyZ`, `Backquote`, `Minus`, `Equal`, `Backslash`, `Backspace`, `Tab`,
* `Delete`, `Escape`, `ArrowDown`, `End`, `Enter`, `Home`, `Insert`, `PageDown`, `PageUp`, `ArrowRight`, `ArrowUp`,
* etc.
*
* Following modification shortcuts are also supported: `Shift`, `Control`, `Alt`, `Meta`, `ShiftLeft`,
* `ControlOrMeta`. `ControlOrMeta` resolves to `Control` on Windows and Linux and to `Meta` on macOS.
*
* Holding down `Shift` will type the text that corresponds to the
* [`key`](https://playwright.dev/docs/api/class-keyboard#keyboard-press-option-key) in the upper case.
*
* If [`key`](https://playwright.dev/docs/api/class-keyboard#keyboard-press-option-key) is a single character, it is
* case-sensitive, so the values `a` and `A` will generate different respective texts.
*
* Shortcuts such as `key: "Control+o"`, `key: "Control++` or `key: "Control+Shift+T"` are supported as well. When
* specified with the modifier, modifier is pressed and being held while the subsequent key is being pressed.
*
* **Usage**
*
* ```js
* const page = await browser.newPage();
* await page.goto('https://keycode.info');
* await page.keyboard.press('A');
* await page.screenshot({ path: 'A.png' });
* await page.keyboard.press('ArrowLeft');
* await page.screenshot({ path: 'ArrowLeft.png' });
* await page.keyboard.press('Shift+O');
* await page.screenshot({ path: 'O.png' });
* await browser.close();
* ```
*
* Shortcut for [keyboard.down(key)](https://playwright.dev/docs/api/class-keyboard#keyboard-down) and
* [keyboard.up(key)](https://playwright.dev/docs/api/class-keyboard#keyboard-up).
* @param key Name of the key to press or a character to generate, such as `ArrowLeft` or `a`.
* @param options
*/
press(
key: string,
options?: {
/**
* Time to wait between `keydown` and `keyup` in milliseconds. Defaults to 0.
*/
delay?: number
},
): Promise<void>
/**
* **NOTE** In most cases, you should use
* [locator.fill(value[, options])](https://playwright.dev/docs/api/class-locator#locator-fill) instead. You only need
* to press keys one by one if there is special keyboard handling on the page - in this case use
* [locator.pressSequentially(text[, options])](https://playwright.dev/docs/api/class-locator#locator-press-sequentially).
*
* Sends a `keydown`, `keypress`/`input`, and `keyup` event for each character in the text.
*
* To press a special key, like `Control` or `ArrowDown`, use
* [keyboard.press(key[, options])](https://playwright.dev/docs/api/class-keyboard#keyboard-press).
*
* **Usage**
*
* ```js
* await page.keyboard.type('Hello'); // Types instantly
* await page.keyboard.type('World', { delay: 100 }); // Types slower, like a user
* ```
*
* **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
*/
type(
text: string,
options?: {
/**
* Time to wait between key presses in milliseconds. Defaults to 0.
*/
delay?: number
},
): Promise<void>
/**
* Dispatches a `keyup` event.
* @param key Name of the key to press or a character to generate, such as `ArrowLeft` or `a`.
*/
up(key: string): Promise<void>
}
Locator
Locators are the central piece of Playwright's auto-waiting and retry-ability. In a nutshell, locators represent a way to find element(s) on the page at any moment. A locator can be created with the page.locator(selector[, options]) method.
interface Locator {
/**
* Execute JavaScript code in the page, taking the matching element as an argument.
*
* **Details**
*
* Returns the return value of
* [`pageFunction`](https://playwright.dev/docs/api/class-locator#locator-evaluate-option-expression), called with the
* matching element as a first argument, and
* [`arg`](https://playwright.dev/docs/api/class-locator#locator-evaluate-option-arg) as a second argument.
*
* If [`pageFunction`](https://playwright.dev/docs/api/class-locator#locator-evaluate-option-expression) returns a
* [Promise], this method will wait for the promise to resolve and return its value.
*
* If [`pageFunction`](https://playwright.dev/docs/api/class-locator#locator-evaluate-option-expression) throws or
* rejects, this method throws.
*
* **Usage**
*
* Passing argument to
* [`pageFunction`](https://playwright.dev/docs/api/class-locator#locator-evaluate-option-expression):
*
* ```js
* const result = await page.getByTestId('myId').evaluate((element, [x, y]) => {
* return element.textContent + ' ' + x * y;
* }, [7, 8]);
* console.log(result); // prints "myId text 56"
* ```
*
* @param pageFunction Function to be evaluated in the page context.
* @param arg Optional argument to pass to
* [`pageFunction`](https://playwright.dev/docs/api/class-locator#locator-evaluate-option-expression).
* @param options
*/
evaluate<R, Arg, E extends SVGElement | HTMLElement = SVGElement | HTMLElement>(
pageFunction: PageFunctionOn<E, Arg, R>,
arg?: Arg,
options?: { timeout?: number; signal?: AbortSignal; exposeFunctions?: boolean },
): Promise<R>
/**
* Execute JavaScript code in the page, taking the matching element as an argument, and return a
* [JSHandle](https://playwright.dev/docs/api/class-jshandle) with the result.
*
* **Details**
*
* Returns the return value of
* [`pageFunction`](https://playwright.dev/docs/api/class-locator#locator-evaluate-handle-option-expression) as
* a[JSHandle](https://playwright.dev/docs/api/class-jshandle), called with the matching element as a first argument,
* and [`arg`](https://playwright.dev/docs/api/class-locator#locator-evaluate-handle-option-arg) as a second argument.
*
* The only difference between
* [locator.evaluate(pageFunction[, arg, options])](https://playwright.dev/docs/api/class-locator#locator-evaluate)
* and
* [locator.evaluateHandle(pageFunction[, arg, options])](https://playwright.dev/docs/api/class-locator#locator-evaluate-handle)
* is that
* [locator.evaluateHandle(pageFunction[, arg, options])](https://playwright.dev/docs/api/class-locator#locator-evaluate-handle)
* returns [JSHandle](https://playwright.dev/docs/api/class-jshandle).
*
* If [`pageFunction`](https://playwright.dev/docs/api/class-locator#locator-evaluate-handle-option-expression)
* returns a [Promise], this method will wait for the promise to resolve and return its value.
*
* If [`pageFunction`](https://playwright.dev/docs/api/class-locator#locator-evaluate-handle-option-expression) throws
* or rejects, this method throws.
*
* See
* [page.evaluateHandle(pageFunction[, arg, options])](https://playwright.dev/docs/api/class-page#page-evaluate-handle)
* for more details.
* @param pageFunction Function to be evaluated in the page context.
* @param arg Optional argument to pass to
* [`pageFunction`](https://playwright.dev/docs/api/class-locator#locator-evaluate-handle-option-expression).
* @param options
*/
evaluateHandle<R, Arg, E extends SVGElement | HTMLElement = SVGElement | HTMLElement>(
pageFunction: PageFunctionOn<E, Arg, R>,
arg?: Arg,
options?: { timeout?: number; signal?: AbortSignal; exposeFunctions?: boolean },
): Promise<SmartHandle<R>>
/**
* Execute JavaScript code in the page, taking all matching elements as an argument.
*
* **Details**
*
* Returns the return value of
* [`pageFunction`](https://playwright.dev/docs/api/class-locator#locator-evaluate-all-option-expression), called with
* an array of all matching elements as a first argument, and
* [`arg`](https://playwright.dev/docs/api/class-locator#locator-evaluate-all-option-arg) as a second argument.
*
* If [`pageFunction`](https://playwright.dev/docs/api/class-locator#locator-evaluate-all-option-expression) returns a
* [Promise], this method will wait for the promise to resolve and return its value.
*
* If [`pageFunction`](https://playwright.dev/docs/api/class-locator#locator-evaluate-all-option-expression) throws or
* rejects, this method throws.
*
* **Usage**
*
* ```js
* const locator = page.locator('div');
* const moreThanTen = await locator.evaluateAll((divs, min) => divs.length > min, 10);
* ```
*
* @param pageFunction Function to be evaluated in the page context.
* @param arg Optional argument to pass to
* [`pageFunction`](https://playwright.dev/docs/api/class-locator#locator-evaluate-all-option-expression).
*/
evaluateAll<R, Arg, E extends SVGElement | HTMLElement = SVGElement | HTMLElement>(
pageFunction: PageFunctionOn<E[], Arg, R>,
arg?: Arg,
): Promise<R>
/**
* Returns when
* [`pageFunction`](https://playwright.dev/docs/api/class-locator#locator-wait-for-function-option-expression) returns
* a truthy value, called with the matching element as a first argument, and
* [`arg`](https://playwright.dev/docs/api/class-locator#locator-wait-for-function-option-arg) as a second argument.
*
* This is a generic way to wait for an element to reach a custom condition without asserting it. The locator is
* re-resolved on each retry, so it tolerates the element being re-rendered while waiting.
*
* If [`pageFunction`](https://playwright.dev/docs/api/class-locator#locator-wait-for-function-option-expression)
* returns a [Promise], this method will wait for the promise to resolve before checking its value.
*
* If [`pageFunction`](https://playwright.dev/docs/api/class-locator#locator-wait-for-function-option-expression)
* throws or rejects, this method throws.
*
* **Usage**
*
* Wait for an attribute to appear:
*
* ```js
* const toggle = page.getByRole('button', { name: 'Menu' });
* await toggle.click();
* await toggle.waitForFunction(element => element.hasAttribute('aria-expanded'));
* ```
*
* Passing argument to
* [`pageFunction`](https://playwright.dev/docs/api/class-locator#locator-wait-for-function-option-expression):
*
* ```js
* await page.getByTestId('status').waitForFunction((element, value) => {
* return element.textContent === value;
* }, 'Ready');
* ```
*
* @param pageFunction Function to be evaluated in the page context.
* @param arg Optional argument to pass to
* [`pageFunction`](https://playwright.dev/docs/api/class-locator#locator-wait-for-function-option-expression).
* @param options
*/
waitForFunction<Arg, E extends SVGElement | HTMLElement = SVGElement | HTMLElement>(
pageFunction: PageFunctionOn<E, Arg, any>,
arg?: Arg,
options?: { timeout?: number; signal?: AbortSignal },
): Promise<void>
/**
* **NOTE** Always prefer using [Locator](https://playwright.dev/docs/api/class-locator)s and web assertions over
* [ElementHandle](https://playwright.dev/docs/api/class-elementhandle)s because latter are inherently racy.
*
* Resolves given locator to the first matching DOM element. If there are no matching elements, waits for one. If
* multiple elements match the locator, throws.
* @param options
*/
elementHandle(options?: { timeout?: number }): Promise<ElementHandle<SVGElement | HTMLElement>>
/**
* Highlight the corresponding element(s) on the screen. Useful for debugging, don't commit the code that uses
* [locator.highlight([options])](https://playwright.dev/docs/api/class-locator#locator-highlight).
* @param options
*/
highlight(options?: { style?: string | { [key: string]: string | number } }): Promise<Disposable>
/**
* Returns a human-readable representation of the locator, using the
* [locator.description()](https://playwright.dev/docs/api/class-locator#locator-description) if one exists;
* otherwise, it generates a string based on the locator's selector.
*/
toString(): string
/**
* When the locator points to a list of elements, this returns an array of locators, pointing to their respective
* 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).
*
* **Usage**
*
* ```js
* for (const li of await page.getByRole('listitem').all())
* await li.click();
* ```
*
*/
all(): Promise<Array<Locator>>
/**
* Returns an array of `node.innerText` values for all matching nodes.
*
* **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`](https://playwright.dev/docs/api/class-locatorassertions#locator-assertions-to-have-text-option-use-inner-text)
* option to avoid flakiness. See [assertions guide](https://playwright.dev/docs/test-assertions) for more details.
*
* **Usage**
*
* ```js
* const texts = await page.getByRole('link').allInnerTexts();
* ```
*
*/
allInnerTexts(): Promise<Array<string>>
/**
* Returns an array of `node.textContent` values for all matching nodes.
*
* **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.
*
* **Usage**
*
* ```js
* const texts = await page.getByRole('link').allTextContents();
* ```
*
*/
allTextContents(): Promise<Array<string>>
/**
* Creates a locator that matches both this locator and the argument locator.
*
* **Usage**
*
* The following example finds a button with a specific title.
*
* ```js
* const button = page.getByRole('button').and(page.getByTitle('Subscribe'));
* ```
*
* @param locator Additional locator to match.
*/
and(locator: Locator): Locator
/**
* Captures the aria snapshot of the given element. Read more about [aria snapshots](https://playwright.dev/docs/aria-snapshots) and
* [expect(locator).toMatchAriaSnapshot(expected[, options])](https://playwright.dev/docs/api/class-locatorassertions#locator-assertions-to-match-aria-snapshot)
* for the corresponding assertion.
*
* **Usage**
*
* ```js
* await page.getByRole('link').ariaSnapshot();
* ```
*
* **Details**
*
* This method captures the aria snapshot of the given element. The snapshot is a string that represents the state of
* the element and its children. The snapshot can be used to assert the state of the element in the test, or to
* compare it to state in the future.
*
* The ARIA snapshot is represented using [YAML](https://yaml.org/spec/1.2.2/) markup language:
* - The keys of the objects are the roles and optional accessible names of the elements.
* - The values are either text content or an array of child elements.
* - Generic static text can be represented with the `text` key.
*
* Below is the HTML markup and the respective ARIA snapshot:
*
* ```html
* <ul aria-label="Links">
* <li><a href="/">Home</a></li>
* <li><a href="/about">About</a></li>
* <ul>
* ```
*
* ```yml
* - list "Links":
* - listitem:
* - link "Home"
* - listitem:
* - link "About"
* ```
*
* An AI-optimized snapshot, controlled by
* [`mode`](https://playwright.dev/docs/api/class-locator#locator-aria-snapshot-option-mode), is different from a
* default snapshot:
* 1. Includes element references `[ref=e2]`. 2. Does not wait for an element matching the locator, and throws when
* no elements match. 3. Includes snapshots of `<iframe>`s inside the target.
* @param options
*/
ariaSnapshot(options?: {
/**
* When `true`, appends each element's bounding box as `[box=x,y,width,height]` to the snapshot. Coordinates are
* relative to the viewport, in CSS pixels, as returned by
* [`Element.getBoundingClientRect()`](https://developer.mozilla.org/en-US/docs/Web/API/Element/getBoundingClientRect).
* Defaults to `false`.
*/
boxes?: boolean
/**
* When specified, limits the depth of the snapshot.
*/
depth?: number
/**
* When set to `"ai"`, returns a snapshot optimized for AI consumption. Defaults to `"default"`. See details for more
* information.
*/
mode?: 'ai' | 'default'
/**
* Allows to cancel the operation using an
* [`AbortSignal`](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal). If the signal is aborted, the
* operation will be aborted and throw an error. Note that providing a signal does not disable the default timeout,
* which can be changed using
* [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); pass
* `timeout: 0` to disable the timeout entirely.
*/
signal?: AbortSignal
/**
* Maximum time in milliseconds. Defaults to `0` - no timeout. The default value can be changed via `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.
*/
timeout?: number
}): Promise<string>
/**
* Captures the aria snapshot of the given element as a free form JSON object.
*
* **Usage**
*
* ```js
* await page.getByRole('list').ariaSnapshotJSON();
* ```
*
* **Details**
*
* This method returns the same tree as
* [locator.ariaSnapshot([options])](https://playwright.dev/docs/api/class-locator#locator-aria-snapshot), serialized
* as a JSON value instead of YAML markup. The result is a list of nodes, each node being an object with the following
* properties:
* - `role` Aria role of the element, or `"text"` for a static text fragment.
* - `name` Accessible name of the element, if any.
* - `text` Text content of the element when it is the only child, or the content of a static text fragment.
* - `children` Child nodes and text fragments.
* - Boolean and value properties for element state flags: `checked`, `disabled`, `expanded`, `active`, `invalid`,
* `level`, `pressed` and `selected`.
* - Additional element properties, for example `url` for links and `placeholder` for text boxes.
* - `ref` Element reference for AI-optimized snapshots.
* - `cursor` Set to `"pointer"` for clickable elements in AI-optimized snapshots.
* - `box` Bounding box of the element when
* [`boxes`](https://playwright.dev/docs/api/class-locator#locator-aria-snapshot-json-option-boxes) is set.
* @param options
*/
ariaSnapshotJSON(options?: {
/**
* When `true`, includes each element's bounding box as a `box` property with `x`, `y`, `width` and `height`.
* Coordinates are relative to the viewport, in CSS pixels, as returned by
* [`Element.getBoundingClientRect()`](https://developer.mozilla.org/en-US/docs/Web/API/Element/getBoundingClientRect).
* Defaults to `false`.
*/
boxes?: boolean
/**
* When specified, limits the depth of the snapshot.
*/
depth?: number
/**
* When set to `"ai"`, returns a snapshot optimized for AI consumption. Defaults to `"default"`. See details in
* [locator.ariaSnapshot([options])](https://playwright.dev/docs/api/class-locator#locator-aria-snapshot).
*/
mode?: 'ai' | 'default'
/**
* Allows to cancel the operation using an
* [`AbortSignal`](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal). If the signal is aborted, the
* operation will be aborted and throw an error. Note that providing a signal does not disable the default timeout,
* which can be changed using
* [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); pass
* `timeout: 0` to disable the timeout entirely.
*/
signal?: AbortSignal
/**
* Maximum time in milliseconds. Defaults to `0` - no timeout. The default value can be changed via `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.
*/
timeout?: number
}): Promise<Serializable>
/**
* Calls [blur](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/blur) on the element.
* @param options
*/
blur(options?: {
/**
* Allows to cancel the operation using an
* [`AbortSignal`](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal). If the signal is aborted, the
* operation will be aborted and throw an error. Note that providing a signal does not disable the default timeout,
* which can be changed using
* [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); pass
* `timeout: 0` to disable the timeout entirely.
*/
signal?: AbortSignal
/**
* Maximum time in milliseconds. Defaults to `0` - no timeout. The default value can be changed via `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.
*/
timeout?: number
}): Promise<void>
/**
* This method returns the bounding box of the element matching the locator, or `null` if the element is not visible.
* The bounding box is calculated relative to the main frame viewport - which is usually the same as the browser
* window.
*
* **Details**
*
* Scrolling affects the returned bounding box, similarly to
* [Element.getBoundingClientRect](https://developer.mozilla.org/en-US/docs/Web/API/Element/getBoundingClientRect).
* That means `x` and/or `y` may be negative.
*
* Elements from child frames return the bounding box relative to the main frame, unlike the
* [Element.getBoundingClientRect](https://developer.mozilla.org/en-US/docs/Web/API/Element/getBoundingClientRect).
*
* Assuming the page is static, it is safe to use bounding box coordinates to perform input. For example, the
* following snippet should click the center of the element.
*
* **Usage**
*
* ```js
* const box = await page.getByRole('button').boundingBox();
* await page.mouse.click(box.x + box.width / 2, box.y + box.height / 2);
* ```
*
* @param options
*/
boundingBox(options?: {
/**
* Allows to cancel the operation using an
* [`AbortSignal`](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal). If the signal is aborted, the
* operation will be aborted and throw an error. Note that providing a signal does not disable the default timeout,
* which can be changed using
* [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); pass
* `timeout: 0` to disable the timeout entirely.
*/
signal?: AbortSignal
/**
* Maximum time in milliseconds. Defaults to `0` - no timeout. The default value can be changed via `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.
*/
timeout?: number
}): Promise<null | {
/**
* the x coordinate of the element in pixels.
*/
x: number
/**
* the y coordinate of the element in pixels.
*/
y: number
/**
* the width of the element in pixels.
*/
width: number
/**
* the height of the element in pixels.
*/
height: number
}>
/**
* Ensure that checkbox or radio element is checked.
*
* **Details**
*
* Performs the following steps:
* 1. Ensure that element is a checkbox or a radio input. If not, this method throws. If the element is already
* checked, this method returns immediately.
* 1. Wait for [actionability](https://playwright.dev/docs/actionability) checks on the element, unless
* [`force`](https://playwright.dev/docs/api/class-locator#locator-check-option-force) option is set.
* 1. Scroll the element into view if needed.
* 1. Use [page.mouse](https://playwright.dev/docs/api/class-page#page-mouse) to click in the center of the
* element.
* 1. Ensure that the element is now checked. If not, this method throws.
*
* If the element is detached from the DOM at any moment during the action, this method throws.
*
* When all steps combined have not finished during the specified
* [`timeout`](https://playwright.dev/docs/api/class-locator#locator-check-option-timeout), this method throws a
* [TimeoutError](https://playwright.dev/docs/api/class-timeouterror). Passing zero timeout disables this.
*
* **Usage**
*
* ```js
* await page.getByRole('checkbox').check();
* ```
*
* @param options
*/
check(options?: {
/**
* Whether to bypass the [actionability](https://playwright.dev/docs/actionability) checks. Defaults to `false`.
*/
force?: boolean
/**
* This option has no effect.
* @deprecated This option has no effect.
*/
noWaitAfter?: boolean
/**
* A point to use relative to the top-left corner of element padding box. If not specified, uses some visible point of
* the element.
*/
position?: {
x: number
y: number
}
/**
* Controls whether Playwright scrolls the element into view before performing the action. Defaults to `"auto"`, which
* scrolls the element into view when necessary, including scrolling nested scrollable containers. When set to
* `"none"`, Playwright does not scroll the element and the action fails if the element is not already in the
* viewport. This is useful to assert that an element is reachable by the user without additional scrolling.
*/
scroll?: 'auto' | 'none'
/**
* Allows to cancel the operation using an
* [`AbortSignal`](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal). If the signal is aborted, the
* operation will be aborted and throw an error. Note that providing a signal does not disable the default timeout,
* which can be changed using
* [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); pass
* `timeout: 0` to disable the timeout entirely.
*/
signal?: AbortSignal
/**
* Maximum time in milliseconds. Defaults to `0` - no timeout. The default value can be changed via `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.
*/
timeout?: number
/**
* When set, this method only performs the [actionability](https://playwright.dev/docs/actionability) checks and skips the action. Defaults
* to `false`. Useful to wait until the element is ready for the action without performing it.
*/
trial?: boolean
}): Promise<void>
/**
* Clear the input field.
*
* **Details**
*
* This method waits for [actionability](https://playwright.dev/docs/actionability) checks, focuses the element, clears it and triggers an
* `input` event after clearing.
*
* If the target element is not an `<input>`, `<textarea>` or `[contenteditable]` element, this method throws an
* error. However, if the element is inside the `<label>` element that has an associated
* [control](https://developer.mozilla.org/en-US/docs/Web/API/HTMLLabelElement/control), the control will be cleared
* instead.
*
* **Usage**
*
* ```js
* await page.getByRole('textbox').clear();
* ```
*
* @param options
*/
clear(options?: {
/**
* Whether to bypass the [actionability](https://playwright.dev/docs/actionability) checks. Defaults to `false`.
*/
force?: boolean
/**
* This option has no effect.
* @deprecated This option has no effect.
*/
noWaitAfter?: boolean
/**
* Allows to cancel the operation using an
* [`AbortSignal`](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal). If the signal is aborted, the
* operation will be aborted and throw an error. Note that providing a signal does not disable the default timeout,
* which can be changed using
* [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); pass
* `timeout: 0` to disable the timeout entirely.
*/
signal?: AbortSignal
/**
* Maximum time in milliseconds. Defaults to `0` - no timeout. The default value can be changed via `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.
*/
timeout?: number
}): Promise<void>
/**
* Click an element.
*
* **Details**
*
* This method clicks the element by performing the following steps:
* 1. Wait for [actionability](https://playwright.dev/docs/actionability) checks on the element, unless
* [`force`](https://playwright.dev/docs/api/class-locator#locator-click-option-force) option is set.
* 1. Scroll the element into view if needed.
* 1. Use [page.mouse](https://playwright.dev/docs/api/class-page#page-mouse) to click in the center of the
* element, or the specified
* [`position`](https://playwright.dev/docs/api/class-locator#locator-click-option-position).
* 1. Wait for initiated navigations to either succeed or fail, unless
* [`noWaitAfter`](https://playwright.dev/docs/api/class-locator#locator-click-option-no-wait-after) option is
* set.
*
* If the element is detached from the DOM at any moment during the action, this method throws.
*
* When all steps combined have not finished during the specified
* [`timeout`](https://playwright.dev/docs/api/class-locator#locator-click-option-timeout), this method throws a
* [TimeoutError](https://playwright.dev/docs/api/class-timeouterror). Passing zero timeout disables this.
*
* **Usage**
*
* Click a button:
*
* ```js
* await page.getByRole('button').click();
* ```
*
* Shift-right-click at a specific position on a canvas:
*
* ```js
* await page.locator('canvas').click({
* button: 'right',
* modifiers: ['Shift'],
* position: { x: 23, y: 32 },
* });
* ```
*
* @param options
*/
click(options?: {
/**
* Defaults to `left`.
*/
button?: 'left' | 'right' | 'middle'
/**
* defaults to 1. See [UIEvent.detail].
*/
clickCount?: number
/**
* Time to wait between `mousedown` and `mouseup` in milliseconds. Defaults to 0.
*/
delay?: number
/**
* Whether to bypass the [actionability](https://playwright.dev/docs/actionability) checks. Defaults to `false`.
*/
force?: boolean
/**
* Modifier keys to press. Ensures that only these modifiers are pressed during the operation, and then restores
* current modifiers back. If not specified, currently pressed modifiers are used. "ControlOrMeta" resolves to
* "Control" on Windows and Linux and to "Meta" on macOS.
*/
modifiers?: Array<'Alt' | 'Control' | 'ControlOrMeta' | 'Meta' | 'Shift'>
/**
* Actions that initiate navigations are waiting for these navigations to happen and for pages to start loading. You
* can opt out of waiting via setting this flag. You would only need this option in the exceptional cases such as
* navigating to inaccessible pages. Defaults to `false`.
* @deprecated This option will default to `true` in the future.
*/
noWaitAfter?: boolean
/**
* A point to use relative to the top-left corner of element padding box. If not specified, uses some visible point of
* the element.
*/
position?: {
x: number
y: number
}
/**
* Controls whether Playwright scrolls the element into view before performing the action. Defaults to `"auto"`, which
* scrolls the element into view when necessary, including scrolling nested scrollable containers. When set to
* `"none"`, Playwright does not scroll the element and the action fails if the element is not already in the
* viewport. This is useful to assert that an element is reachable by the user without additional scrolling.
*/
scroll?: 'auto' | 'none'
/**
* Allows to cancel the operation using an
* [`AbortSignal`](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal). If the signal is aborted, the
* operation will be aborted and throw an error. Note that providing a signal does not disable the default timeout,
* which can be changed using
* [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); pass
* `timeout: 0` to disable the timeout entirely.
*/
signal?: AbortSignal
/**
* Defaults to 1. Sends `n` interpolated `mousemove` events to represent travel between Playwright's current cursor
* position and the provided destination. When set to 1, emits a single `mousemove` event at the destination location.
*/
steps?: number
/**
* Maximum time in milliseconds. Defaults to `0` - no timeout. The default value can be changed via `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.
*/
timeout?: number
/**
* When set, this method only performs the [actionability](https://playwright.dev/docs/actionability) checks and skips the action. Defaults
* to `false`. Useful to wait until the element is ready for the action without performing it. Note that keyboard
* `modifiers` will be pressed regardless of `trial` to allow testing elements which are only visible when those keys
* are pressed.
*/
trial?: boolean
}): Promise<void>
/**
* Returns a [FrameLocator](https://playwright.dev/docs/api/class-framelocator) object pointing to the same `iframe`
* as this locator.
*
* Useful when you have a [Locator](https://playwright.dev/docs/api/class-locator) object obtained somewhere, and
* later on would like to interact with the content inside the frame.
*
* For a reverse operation, use
* [frameLocator.owner()](https://playwright.dev/docs/api/class-framelocator#frame-locator-owner).
*
* **Usage**
*
* ```js
* const locator = page.locator('iframe[name="embedded"]');
* // ...
* const frameLocator = locator.contentFrame();
* await frameLocator.getByRole('button').click();
* ```
*
*/
contentFrame(): FrameLocator
/**
* Returns the number of elements matching the locator.
*
* **NOTE** If you need to assert the number of elements on the page, prefer
* [expect(locator).toHaveCount(count[, options])](https://playwright.dev/docs/api/class-locatorassertions#locator-assertions-to-have-count)
* to avoid flakiness. See [assertions guide](https://playwright.dev/docs/test-assertions) for more details.
*
* **Usage**
*
* ```js
* const count = await page.getByRole('listitem').count();
* ```
*
*/
count(): Promise<number>
/**
* Double-click an element.
*
* **Details**
*
* This method double clicks the element by performing the following steps:
* 1. Wait for [actionability](https://playwright.dev/docs/actionability) checks on the element, unless
* [`force`](https://playwright.dev/docs/api/class-locator#locator-dblclick-option-force) option is set.
* 1. Scroll the element into view if needed.
* 1. Use [page.mouse](https://playwright.dev/docs/api/class-page#page-mouse) to double click in the center of the
* element, or the specified
* [`position`](https://playwright.dev/docs/api/class-locator#locator-dblclick-option-position).
*
* If the element is detached from the DOM at any moment during the action, this method throws.
*
* When all steps combined have not finished during the specified
* [`timeout`](https://playwright.dev/docs/api/class-locator#locator-dblclick-option-timeout), this method throws a
* [TimeoutError](https://playwright.dev/docs/api/class-timeouterror). Passing zero timeout disables this.
*
* **NOTE** `element.dblclick()` dispatches two `click` events and a single `dblclick` event.
*
* @param options
*/
dblclick(options?: {
/**
* Defaults to `left`.
*/
button?: 'left' | 'right' | 'middle'
/**
* Time to wait between `mousedown` and `mouseup` in milliseconds. Defaults to 0.
*/
delay?: number
/**
* Whether to bypass the [actionability](https://playwright.dev/docs/actionability) checks. Defaults to `false`.
*/
force?: boolean
/**
* Modifier keys to press. Ensures that only these modifiers are pressed during the operation, and then restores
* current modifiers back. If not specified, currently pressed modifiers are used. "ControlOrMeta" resolves to
* "Control" on Windows and Linux and to "Meta" on macOS.
*/
modifiers?: Array<'Alt' | 'Control' | 'ControlOrMeta' | 'Meta' | 'Shift'>
/**
* This option has no effect.
* @deprecated This option has no effect.
*/
noWaitAfter?: boolean
/**
* A point to use relative to the top-left corner of element padding box. If not specified, uses some visible point of
* the element.
*/
position?: {
x: number
y: number
}
/**
* Controls whether Playwright scrolls the element into view before performing the action. Defaults to `"auto"`, which
* scrolls the element into view when necessary, including scrolling nested scrollable containers. When set to
* `"none"`, Playwright does not scroll the element and the action fails if the element is not already in the
* viewport. This is useful to assert that an element is reachable by the user without additional scrolling.
*/
scroll?: 'auto' | 'none'
/**
* Allows to cancel the operation using an
* [`AbortSignal`](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal). If the signal is aborted, the
* operation will be aborted and throw an error. Note that providing a signal does not disable the default timeout,
* which can be changed using
* [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); pass
* `timeout: 0` to disable the timeout entirely.
*/
signal?: AbortSignal
/**
* Defaults to 1. Sends `n` interpolated `mousemove` events to represent travel between Playwright's current cursor
* position and the provided destination. When set to 1, emits a single `mousemove` event at the destination location.
*/
steps?: number
/**
* Maximum time in milliseconds. Defaults to `0` - no timeout. The default value can be changed via `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.
*/
timeout?: number
/**
* When set, this method only performs the [actionability](https://playwright.dev/docs/actionability) checks and skips the action. Defaults
* to `false`. Useful to wait until the element is ready for the action without performing it. Note that keyboard
* `modifiers` will be pressed regardless of `trial` to allow testing elements which are only visible when those keys
* are pressed.
*/
trial?: boolean
}): Promise<void>
/**
* Describes the locator, description is used in the trace viewer and reports. Returns the locator pointing to the
* same element.
*
* **Usage**
*
* ```js
* const button = page.getByTestId('btn-sub').describe('Subscribe button');
* await button.click();
* ```
*
* @param description Locator description.
*/
describe(description: string): Locator
/**
* Returns locator description previously set with
* [locator.describe(description)](https://playwright.dev/docs/api/class-locator#locator-describe). Returns `null` if
* no custom description has been set. Prefer
* [locator.toString()](https://playwright.dev/docs/api/class-locator#locator-to-string) for a human-readable
* representation, as it uses the description when available.
*
* **Usage**
*
* ```js
* const button = page.getByRole('button').describe('Subscribe button');
* console.log(button.description()); // "Subscribe button"
*
* const input = page.getByRole('textbox');
* console.log(input.description()); // null
* ```
*
*/
description(): null | string
/**
* Programmatically dispatch an event on the matching element.
*
* **Usage**
*
* ```js
* await locator.dispatchEvent('click');
* ```
*
* **Details**
*
* The snippet above dispatches the `click` event on the element. Regardless of the visibility state of the element,
* `click` is dispatched. This is equivalent to calling
* [element.click()](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/click).
*
* Under the hood, it creates an instance of an event based on the given
* [`type`](https://playwright.dev/docs/api/class-locator#locator-dispatch-event-option-type), initializes it with
* [`eventInit`](https://playwright.dev/docs/api/class-locator#locator-dispatch-event-option-event-init) properties
* and dispatches it on the element. Events are `composed`, `cancelable` and bubble by default.
*
* Since [`eventInit`](https://playwright.dev/docs/api/class-locator#locator-dispatch-event-option-event-init) is
* event-specific, please refer to the events documentation for the lists of initial properties:
* - [DeviceMotionEvent](https://developer.mozilla.org/en-US/docs/Web/API/DeviceMotionEvent/DeviceMotionEvent)
* - [DeviceOrientationEvent](https://developer.mozilla.org/en-US/docs/Web/API/DeviceOrientationEvent/DeviceOrientationEvent)
* - [DragEvent](https://developer.mozilla.org/en-US/docs/Web/API/DragEvent/DragEvent)
* - [Event](https://developer.mozilla.org/en-US/docs/Web/API/Event/Event)
* - [FocusEvent](https://developer.mozilla.org/en-US/docs/Web/API/FocusEvent/FocusEvent)
* - [KeyboardEvent](https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/KeyboardEvent)
* - [MouseEvent](https://developer.mozilla.org/en-US/docs/Web/API/MouseEvent/MouseEvent)
* - [PointerEvent](https://developer.mozilla.org/en-US/docs/Web/API/PointerEvent/PointerEvent)
* - [TouchEvent](https://developer.mozilla.org/en-US/docs/Web/API/TouchEvent/TouchEvent)
* - [WheelEvent](https://developer.mozilla.org/en-US/docs/Web/API/WheelEvent/WheelEvent)
*
* You can also specify [JSHandle](https://playwright.dev/docs/api/class-jshandle) as the property value if you want
* live objects to be passed into the event:
*
* ```js
* const dataTransfer = await page.evaluateHandle(() => new DataTransfer());
* await locator.dispatchEvent('dragstart', { dataTransfer });
* ```
*
* @param type DOM event type: `"click"`, `"dragstart"`, etc.
* @param eventInit Optional event-specific initialization properties.
* @param options
*/
dispatchEvent(
type: string,
eventInit?: EvaluationArgument,
options?: {
/**
* Allows to cancel the operation using an
* [`AbortSignal`](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal). If the signal is aborted, the
* operation will be aborted and throw an error. Note that providing a signal does not disable the default timeout,
* which can be changed using
* [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); pass
* `timeout: 0` to disable the timeout entirely.
*/
signal?: AbortSignal
/**
* Maximum time in milliseconds. Defaults to `0` - no timeout. The default value can be changed via `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.
*/
timeout?: number
},
): Promise<void>
/**
* Drag the source element towards the target element and drop it.
*
* **Details**
*
* This method drags the locator to another target locator or target position. It will first move to the source
* element, perform a `mousedown`, then move to the target element or position and perform a `mouseup`.
*
* **Usage**
*
* ```js
* const source = page.locator('#source');
* const target = page.locator('#target');
*
* await source.dragTo(target);
* // or specify exact positions relative to the top-left corners of the elements:
* await source.dragTo(target, {
* sourcePosition: { x: 34, y: 7 },
* targetPosition: { x: 10, y: 20 },
* });
* ```
*
* @param target Locator of the element to drag to.
* @param options
*/
dragTo(
target: Locator,
options?: {
/**
* Whether to bypass the [actionability](https://playwright.dev/docs/actionability) checks. Defaults to `false`.
*/
force?: boolean
/**
* This option has no effect.
* @deprecated This option has no effect.
*/
noWaitAfter?: boolean
/**
* Controls whether Playwright scrolls the element into view before performing the action. Defaults to `"auto"`, which
* scrolls the element into view when necessary, including scrolling nested scrollable containers. When set to
* `"none"`, Playwright does not scroll the element and the action fails if the element is not already in the
* viewport. This is useful to assert that an element is reachable by the user without additional scrolling.
*/
scroll?: 'auto' | 'none'
/**
* Allows to cancel the operation using an
* [`AbortSignal`](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal). If the signal is aborted, the
* operation will be aborted and throw an error. Note that providing a signal does not disable the default timeout,
* which can be changed using
* [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); pass
* `timeout: 0` to disable the timeout entirely.
*/
signal?: AbortSignal
/**
* Clicks on the source element at this point relative to the top-left corner of the element's padding box. If not
* specified, some visible point of the element is used.
*/
sourcePosition?: {
x: number
y: number
}
/**
* Defaults to 1. Sends `n` interpolated `mousemove` events to represent travel between the `mousedown` and `mouseup`
* of the drag. When set to 1, emits a single `mousemove` event at the destination location.
*/
steps?: number
/**
* Drops on the target element at this point relative to the top-left corner of the element's padding box. If not
* specified, some visible point of the element is used.
*/
targetPosition?: {
x: number
y: number
}
/**
* Maximum time in milliseconds. Defaults to `0` - no timeout. The default value can be changed via `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.
*/
timeout?: number
/**
* When set, this method only performs the [actionability](https://playwright.dev/docs/actionability) checks and skips the action. Defaults
* to `false`. Useful to wait until the element is ready for the action without performing it.
*/
trial?: boolean
},
): Promise<void>
/**
* Simulate an external drag-and-drop of files or clipboard-like data onto this locator.
*
* **Details**
*
* Dispatches the native `dragenter`, `dragover`, and `drop` events at the center of the target element with a
* synthetic [DataTransfer] carrying the provided files and/or data entries. Works cross-browser by constructing the
* [DataTransfer] in the page context.
*
* If the target element's `dragover` listener does not call `preventDefault()`, the target is considered to have
* rejected the drop: Playwright dispatches `dragleave` and this method throws.
*
* **Usage**
*
* Drop a file buffer onto an upload area:
*
* ```js
* await page.locator('#dropzone').drop({
* files: { name: 'note.txt', mimeType: 'text/plain', buffer: Buffer.from('hello') },
* });
* ```
*
* Drop plain text and a URL together:
*
* ```js
* await page.locator('#dropzone').drop({
* data: {
* 'text/plain': 'hello world',
* 'text/uri-list': 'https://example.com',
* },
* });
* ```
*
* @param payload Data to drop onto the target. Provide `files` (file paths or in-memory buffers), `data` (a mime-type → string map
* for clipboard-like content such as `text/plain`, `text/html`, `text/uri-list`), or both.
* @param options
*/
drop(
payload: {
files?:
| string
| Array<string>
| {
/**
* File name
*/
name: string
/**
* File type
*/
mimeType: string
/**
* File content
*/
buffer: Buffer
}
| Array<{
/**
* File name
*/
name: string
/**
* File type
*/
mimeType: string
/**
* File content
*/
buffer: Buffer
}>
data?: { [key: string]: string }
},
options?: {
/**
* A point to use relative to the top-left corner of element padding box. If not specified, uses some visible point of
* the element.
*/
position?: {
x: number
y: number
}
/**
* Allows to cancel the operation using an
* [`AbortSignal`](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal). If the signal is aborted, the
* operation will be aborted and throw an error. Note that providing a signal does not disable the default timeout,
* which can be changed using
* [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); pass
* `timeout: 0` to disable the timeout entirely.
*/
signal?: AbortSignal
/**
* Maximum time in milliseconds. Defaults to `0` - no timeout. The default value can be changed via `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.
*/
timeout?: number
},
): Promise<void>
/**
* **NOTE** Always prefer using [Locator](https://playwright.dev/docs/api/class-locator)s and web assertions over
* [ElementHandle](https://playwright.dev/docs/api/class-elementhandle)s because latter are inherently racy.
*
* Resolves given locator to all matching DOM elements. If there are no matching elements, returns an empty list.
*/
elementHandles(): Promise<Array<ElementHandle>>
/**
* Set a value to the input field.
*
* **Usage**
*
* ```js
* await page.getByRole('textbox').fill('example value');
* ```
*
* **Details**
*
* This method waits for [actionability](https://playwright.dev/docs/actionability) checks, focuses the element, fills it and triggers an
* `input` event after filling. Note that you can pass an empty string to clear the input field.
*
* If the target element is not an `<input>`, `<textarea>` or `[contenteditable]` element, this method throws an
* error. However, if the element is inside the `<label>` element that has an associated
* [control](https://developer.mozilla.org/en-US/docs/Web/API/HTMLLabelElement/control), the control will be filled
* instead.
*
* To send fine-grained keyboard events, use
* [locator.pressSequentially(text[, options])](https://playwright.dev/docs/api/class-locator#locator-press-sequentially).
* @param value Value to set for the `<input>`, `<textarea>` or `[contenteditable]` element.
* @param options
*/
fill(
value: string,
options?: {
/**
* Whether to bypass the [actionability](https://playwright.dev/docs/actionability) checks. Defaults to `false`.
*/
force?: boolean
/**
* This option has no effect.
* @deprecated This option has no effect.
*/
noWaitAfter?: boolean
/**
* Allows to cancel the operation using an
* [`AbortSignal`](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal). If the signal is aborted, the
* operation will be aborted and throw an error. Note that providing a signal does not disable the default timeout,
* which can be changed using
* [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); pass
* `timeout: 0` to disable the timeout entirely.
*/
signal?: AbortSignal
/**
* Maximum time in milliseconds. Defaults to `0` - no timeout. The default value can be changed via `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.
*/
timeout?: number
},
): Promise<void>
/**
* This method narrows existing locator according to the options, for example filters by text. It can be chained to
* filter multiple times.
*
* **Usage**
*
* ```js
* const rowLocator = page.locator('tr');
* // ...
* await rowLocator
* .filter({ hasText: 'text in column 1' })
* .filter({ has: page.getByRole('button', { name: 'column 2 button' }) })
* .screenshot();
* ```
*
* @param options
*/
filter(options?: {
/**
* Narrows down the results of the method to those which contain elements matching this relative locator. For example,
* `article` that has `text=Playwright` matches `<article><div>Playwright</div></article>`.
*
* Inner locator **must be relative** to the outer locator and is queried starting with the outer locator match, not
* the document root. For example, you can find `content` that has `div` in
* `<article><content><div>Playwright</div></content></article>`. However, looking for `content` that has `article
* div` will fail, because the inner locator must be relative and should not use any elements outside the `content`.
*
* Note that outer and inner locators must belong to the same frame. Inner locator must not contain
* [FrameLocator](https://playwright.dev/docs/api/class-framelocator)s.
*/
has?: Locator
/**
* Matches elements that do not contain an element that matches an inner locator. Inner locator is queried against the
* outer one. For example, `article` that does not have `div` matches `<article><span>Playwright</span></article>`.
*
* Note that outer and inner locators must belong to the same frame. Inner locator must not contain
* [FrameLocator](https://playwright.dev/docs/api/class-framelocator)s.
*/
hasNot?: Locator
/**
* Matches elements that do not contain specified text somewhere inside, possibly in a child or a descendant element.
* When passed a [string], matching is case-insensitive and searches for a substring.
*/
hasNotText?: string | RegExp
/**
* Matches elements containing specified text somewhere inside, possibly in a child or a descendant element. When
* passed a [string], matching is case-insensitive and searches for a substring. For example, `"Playwright"` matches
* `<article><div>Playwright</div></article>`.
*/
hasText?: string | RegExp
/**
* Only matches visible or invisible elements. Prefer the
* [locator.visible()](https://playwright.dev/docs/api/class-locator#locator-visible) shortcut when matching only
* visible elements.
*/
visible?: boolean
}): Locator
/**
* Returns locator to the first matching element.
*/
first(): Locator
/**
* Calls [focus](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/focus) on the matching element.
* @param options
*/
focus(options?: {
/**
* Allows to cancel the operation using an
* [`AbortSignal`](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal). If the signal is aborted, the
* operation will be aborted and throw an error. Note that providing a signal does not disable the default timeout,
* which can be changed using
* [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); pass
* `timeout: 0` to disable the timeout entirely.
*/
signal?: AbortSignal
/**
* Maximum time in milliseconds. Defaults to `0` - no timeout. The default value can be changed via `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.
*/
timeout?: number
}): Promise<void>
/**
* When working with iframes, you can create a frame locator that will enter the iframe and allow locating elements in
* that iframe:
*
* **Usage**
*
* ```js
* const locator = page.frameLocator('iframe').getByText('Submit');
* await locator.click();
* ```
*
* @param selector A selector to use when resolving DOM element.
*/
frameLocator(selector: string): FrameLocator
/**
* Returns the matching element's attribute value.
*
* **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
*/
getAttribute(
name: string,
options?: {
/**
* Allows to cancel the operation using an
* [`AbortSignal`](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal). If the signal is aborted, the
* operation will be aborted and throw an error. Note that providing a signal does not disable the default timeout,
* which can be changed using
* [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); pass
* `timeout: 0` to disable the timeout entirely.
*/
signal?: AbortSignal
/**
* Maximum time in milliseconds. Defaults to `0` - no timeout. The default value can be changed via `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.
*/
timeout?: number
},
): Promise<null | string>
/**
* Allows locating elements by their alt text.
*
* **Usage**
*
* For example, this method will find the image by alt text "Playwright logo":
*
* ```html
* <img alt='Playwright logo'>
* ```
*
* ```js
* await page.getByAltText('Playwright logo').click();
* ```
*
* @param text Text to locate the element for.
* @param options
*/
getByAltText(
text: string | RegExp,
options?: {
/**
* Whether to find an exact match: case-sensitive and whole-string. Default to false. Ignored when locating by a
* regular expression. Note that exact match still trims whitespace.
*/
exact?: boolean
},
): Locator
/**
* Allows locating input elements by the text of the associated `<label>` or `aria-labelledby` element, or by the
* `aria-label` attribute.
*
* **Usage**
*
* For example, this method will find inputs by label "Username" and "Password" in the following DOM:
*
* ```html
* <input aria-label="Username">
* <label for="password-input">Password:</label>
* <input id="password-input">
* ```
*
* ```js
* await page.getByLabel('Username').fill('john');
* await page.getByLabel('Password').fill('secret');
* ```
*
* @param text Text to locate the element for.
* @param options
*/
getByLabel(
text: string | RegExp,
options?: {
/**
* Whether to find an exact match: case-sensitive and whole-string. Default to false. Ignored when locating by a
* regular expression. Note that exact match still trims whitespace.
*/
exact?: boolean
},
): Locator
/**
* Allows locating input elements by the placeholder text.
*
* **Usage**
*
* For example, consider the following DOM structure.
*
* ```html
* <input type="email" placeholder="name@example.com" />
* ```
*
* You can fill the input after locating it by the placeholder text:
*
* ```js
* await page
* .getByPlaceholder('name@example.com')
* .fill('playwright@microsoft.com');
* ```
*
* @param text Text to locate the element for.
* @param options
*/
getByPlaceholder(
text: string | RegExp,
options?: {
/**
* Whether to find an exact match: case-sensitive and whole-string. Default to false. Ignored when locating by a
* regular expression. Note that exact match still trims whitespace.
*/
exact?: boolean
},
): Locator
/**
* Allows locating elements by their [ARIA role](https://www.w3.org/TR/wai-aria-1.2/#roles),
* [ARIA attributes](https://www.w3.org/TR/wai-aria-1.2/#aria-attributes) and
* [accessible name](https://w3c.github.io/accname/#dfn-accessible-name).
*
* **Usage**
*
* Consider the following DOM structure.
*
* ```html
* <h3>Sign up</h3>
* <label>
* <input type="checkbox" /> Subscribe
* </label>
* <br/>
* <button>Submit</button>
* ```
*
* You can locate each element by its implicit role:
*
* ```js
* await expect(page.getByRole('heading', { name: 'Sign up' })).toBeVisible();
*
* await page.getByRole('checkbox', { name: 'Subscribe' }).check();
*
* await page.getByRole('button', { name: /submit/i }).click();
* ```
*
* **Details**
*
* Role selector **does not replace** accessibility audits and conformance tests, but rather gives early feedback
* about the ARIA guidelines.
*
* Many html elements have an implicitly [defined role](https://w3c.github.io/html-aam/#html-element-role-mappings)
* that is recognized by the role selector. You can find all the
* [supported roles here](https://www.w3.org/TR/wai-aria-1.2/#role_definitions). ARIA guidelines **do not recommend**
* duplicating implicit roles and attributes by setting `role` and/or `aria-*` attributes to default values.
* @param role Required aria role.
* @param options
*/
getByRole(
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?: {
/**
* An attribute that is usually set by `aria-checked` or native `<input type=checkbox>` controls.
*
* Learn more about [`aria-checked`](https://www.w3.org/TR/wai-aria-1.2/#aria-checked).
*/
checked?: boolean
/**
* Option to match the [accessible description](https://w3c.github.io/accname/#dfn-accessible-description). By
* default, matching is case-insensitive and searches for a substring, use
* [`exact`](https://playwright.dev/docs/api/class-locator#locator-get-by-role-option-exact) to control this behavior.
*
* Learn more about [accessible description](https://w3c.github.io/accname/#dfn-accessible-description).
*/
description?: string | RegExp
/**
* 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).
*
*/
disabled?: boolean
/**
* Whether [`name`](https://playwright.dev/docs/api/class-locator#locator-get-by-role-option-name) and
* [`description`](https://playwright.dev/docs/api/class-locator#locator-get-by-role-option-description) are matched
* exactly: case-sensitive and whole-string. Defaults to false. Ignored when the value is a regular expression. Note
* that exact match still trims whitespace.
*/
exact?: boolean
/**
* An attribute that is usually set by `aria-expanded`.
*
* Learn more about [`aria-expanded`](https://www.w3.org/TR/wai-aria-1.2/#aria-expanded).
*/
expanded?: boolean
/**
* Option that controls whether hidden elements are matched. By default, only non-hidden elements, as
* [defined by ARIA](https://www.w3.org/TR/wai-aria-1.2/#tree_exclusion), are matched by role selector.
*
* Learn more about [`aria-hidden`](https://www.w3.org/TR/wai-aria-1.2/#aria-hidden).
*/
includeHidden?: boolean
/**
* A number attribute that is usually present for roles `heading`, `listitem`, `row`, `treeitem`, with default values
* for `<h1>-<h6>` elements.
*
* Learn more about [`aria-level`](https://www.w3.org/TR/wai-aria-1.2/#aria-level).
*/
level?: number
/**
* Option to match the [accessible name](https://w3c.github.io/accname/#dfn-accessible-name). By default, matching is
* case-insensitive and searches for a substring, use
* [`exact`](https://playwright.dev/docs/api/class-locator#locator-get-by-role-option-exact) to control this behavior.
*
* Learn more about [accessible name](https://w3c.github.io/accname/#dfn-accessible-name).
*/
name?: string | RegExp
/**
* An attribute that is usually set by `aria-pressed`.
*
* Learn more about [`aria-pressed`](https://www.w3.org/TR/wai-aria-1.2/#aria-pressed).
*/
pressed?: boolean
/**
* An attribute that is usually set by `aria-selected`.
*
* Learn more about [`aria-selected`](https://www.w3.org/TR/wai-aria-1.2/#aria-selected).
*/
selected?: boolean
},
): Locator
/**
* Locate element by the test id.
*
* **Usage**
*
* Consider the following DOM structure.
*
* ```html
* <button data-testid="directions">Itinéraire</button>
* ```
*
* You can locate the element by its test id:
*
* ```js
* await page.getByTestId('directions').click();
* ```
*
* **Details**
*
* By default, the `data-testid` attribute is used as a test id. Use
* [selectors.setTestIdAttribute(attributeName)](https://playwright.dev/docs/api/class-selectors#selectors-set-test-id-attribute)
* to configure a different test id attribute if necessary.
*
* ```js
* // Set custom test id attribute from @playwright/test config:
* import { defineConfig } from '@playwright/test';
*
* export default defineConfig({
* use: {
* testIdAttribute: 'data-pw'
* },
* });
* ```
*
* @param testId Id to locate the element by.
*/
getByTestId(testId: string | RegExp): Locator
/**
* Allows locating elements that contain given text.
*
* See also [locator.filter([options])](https://playwright.dev/docs/api/class-locator#locator-filter) that allows to
* match by another criteria, like an accessible role, and then filter by the text content.
*
* **Usage**
*
* Consider the following DOM structure:
*
* ```html
* <div>Hello <span>world</span></div>
* <div>Hello</div>
* ```
*
* You can locate by text substring, exact string, or a regular expression:
*
* ```js
* // Matches <span>
* page.getByText('world');
*
* // Matches first <div>
* page.getByText('Hello world');
*
* // Matches second <div>
* page.getByText('Hello', { exact: true });
*
* // Matches both <div>s
* page.getByText(/Hello/);
*
* // Matches second <div>
* page.getByText(/^hello$/i);
* ```
*
* **Details**
*
* Matching by text always normalizes whitespace, even with exact match. For example, it turns multiple spaces into
* one, turns line breaks into spaces and ignores leading and trailing whitespace.
*
* Input elements of the type `button` and `submit` are matched by their `value` instead of the text content. For
* example, locating by text `"Log in"` matches `<input type=button value="Log in">`.
* @param text Text to locate the element for.
* @param options
*/
getByText(
text: string | RegExp,
options?: {
/**
* Whether to find an exact match: case-sensitive and whole-string. Default to false. Ignored when locating by a
* regular expression. Note that exact match still trims whitespace.
*/
exact?: boolean
},
): Locator
/**
* Allows locating elements by their title attribute.
*
* **Usage**
*
* Consider the following DOM structure.
*
* ```html
* <span title='Issues count'>25 issues</span>
* ```
*
* You can check the issues count after locating it by the title text:
*
* ```js
* await expect(page.getByTitle('Issues count')).toHaveText('25 issues');
* ```
*
* @param text Text to locate the element for.
* @param options
*/
getByTitle(
text: string | RegExp,
options?: {
/**
* Whether to find an exact match: case-sensitive and whole-string. Default to false. Ignored when locating by a
* regular expression. Note that exact match still trims whitespace.
*/
exact?: boolean
},
): Locator
/**
* Hides the element highlight previously added by
* [locator.highlight([options])](https://playwright.dev/docs/api/class-locator#locator-highlight).
*/
hideHighlight(): Promise<void>
/**
* Hover over the matching element.
*
* **Usage**
*
* ```js
* await page.getByRole('link').hover();
* ```
*
* **Details**
*
* This method hovers over the element by performing the following steps:
* 1. Wait for [actionability](https://playwright.dev/docs/actionability) checks on the element, unless
* [`force`](https://playwright.dev/docs/api/class-locator#locator-hover-option-force) option is set.
* 1. Scroll the element into view if needed.
* 1. Use [page.mouse](https://playwright.dev/docs/api/class-page#page-mouse) to hover over the center of the
* element, or the specified
* [`position`](https://playwright.dev/docs/api/class-locator#locator-hover-option-position).
*
* If the element is detached from the DOM at any moment during the action, this method throws.
*
* When all steps combined have not finished during the specified
* [`timeout`](https://playwright.dev/docs/api/class-locator#locator-hover-option-timeout), this method throws a
* [TimeoutError](https://playwright.dev/docs/api/class-timeouterror). Passing zero timeout disables this.
* @param options
*/
hover(options?: {
/**
* Whether to bypass the [actionability](https://playwright.dev/docs/actionability) checks. Defaults to `false`.
*/
force?: boolean
/**
* Modifier keys to press. Ensures that only these modifiers are pressed during the operation, and then restores
* current modifiers back. If not specified, currently pressed modifiers are used. "ControlOrMeta" resolves to
* "Control" on Windows and Linux and to "Meta" on macOS.
*/
modifiers?: Array<'Alt' | 'Control' | 'ControlOrMeta' | 'Meta' | 'Shift'>
/**
* This option has no effect.
* @deprecated This option has no effect.
*/
noWaitAfter?: boolean
/**
* A point to use relative to the top-left corner of element padding box. If not specified, uses some visible point of
* the element.
*/
position?: {
x: number
y: number
}
/**
* Controls whether Playwright scrolls the element into view before performing the action. Defaults to `"auto"`, which
* scrolls the element into view when necessary, including scrolling nested scrollable containers. When set to
* `"none"`, Playwright does not scroll the element and the action fails if the element is not already in the
* viewport. This is useful to assert that an element is reachable by the user without additional scrolling.
*/
scroll?: 'auto' | 'none'
/**
* Allows to cancel the operation using an
* [`AbortSignal`](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal). If the signal is aborted, the
* operation will be aborted and throw an error. Note that providing a signal does not disable the default timeout,
* which can be changed using
* [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); pass
* `timeout: 0` to disable the timeout entirely.
*/
signal?: AbortSignal
/**
* Maximum time in milliseconds. Defaults to `0` - no timeout. The default value can be changed via `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.
*/
timeout?: number
/**
* When set, this method only performs the [actionability](https://playwright.dev/docs/actionability) checks and skips the action. Defaults
* to `false`. Useful to wait until the element is ready for the action without performing it. Note that keyboard
* `modifiers` will be pressed regardless of `trial` to allow testing elements which are only visible when those keys
* are pressed.
*/
trial?: boolean
}): Promise<void>
/**
* Returns the [`element.innerHTML`](https://developer.mozilla.org/en-US/docs/Web/API/Element/innerHTML).
* @param options
*/
innerHTML(options?: {
/**
* Allows to cancel the operation using an
* [`AbortSignal`](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal). If the signal is aborted, the
* operation will be aborted and throw an error. Note that providing a signal does not disable the default timeout,
* which can be changed using
* [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); pass
* `timeout: 0` to disable the timeout entirely.
*/
signal?: AbortSignal
/**
* Maximum time in milliseconds. Defaults to `0` - no timeout. The default value can be changed via `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.
*/
timeout?: number
}): Promise<string>
/**
* Returns the [`element.innerText`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/innerText).
*
* **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`](https://playwright.dev/docs/api/class-locatorassertions#locator-assertions-to-have-text-option-use-inner-text)
* option to avoid flakiness. See [assertions guide](https://playwright.dev/docs/test-assertions) for more details.
*
* @param options
*/
innerText(options?: {
/**
* Allows to cancel the operation using an
* [`AbortSignal`](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal). If the signal is aborted, the
* operation will be aborted and throw an error. Note that providing a signal does not disable the default timeout,
* which can be changed using
* [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); pass
* `timeout: 0` to disable the timeout entirely.
*/
signal?: AbortSignal
/**
* Maximum time in milliseconds. Defaults to `0` - no timeout. The default value can be changed via `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.
*/
timeout?: number
}): Promise<string>
/**
* Returns the value for the matching `<input>` or `<textarea>` or `<select>` element.
*
* **NOTE** If you need to assert input value, prefer
* [expect(locator).toHaveValue(value[, options])](https://playwright.dev/docs/api/class-locatorassertions#locator-assertions-to-have-value)
* to avoid flakiness. See [assertions guide](https://playwright.dev/docs/test-assertions) for more details.
*
* **Usage**
*
* ```js
* const value = await page.getByRole('textbox').inputValue();
* ```
*
* **Details**
*
* Throws elements that are not an input, textarea or a select. However, if the element is inside the `<label>`
* element that has an associated
* [control](https://developer.mozilla.org/en-US/docs/Web/API/HTMLLabelElement/control), returns the value of the
* control.
* @param options
*/
inputValue(options?: {
/**
* Allows to cancel the operation using an
* [`AbortSignal`](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal). If the signal is aborted, the
* operation will be aborted and throw an error. Note that providing a signal does not disable the default timeout,
* which can be changed using
* [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); pass
* `timeout: 0` to disable the timeout entirely.
*/
signal?: AbortSignal
/**
* Maximum time in milliseconds. Defaults to `0` - no timeout. The default value can be changed via `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.
*/
timeout?: number
}): Promise<string>
/**
* Returns whether the element is checked. Throws if the element is not a checkbox or radio input.
*
* **NOTE** If you need to assert that checkbox is checked, prefer
* [expect(locator).toBeChecked([options])](https://playwright.dev/docs/api/class-locatorassertions#locator-assertions-to-be-checked)
* to avoid flakiness. See [assertions guide](https://playwright.dev/docs/test-assertions) for more details.
*
* **Usage**
*
* ```js
* const checked = await page.getByRole('checkbox').isChecked();
* ```
*
* @param options
*/
isChecked(options?: {
/**
* Allows to cancel the operation using an
* [`AbortSignal`](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal). If the signal is aborted, the
* operation will be aborted and throw an error. Note that providing a signal does not disable the default timeout,
* which can be changed using
* [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); pass
* `timeout: 0` to disable the timeout entirely.
*/
signal?: AbortSignal
/**
* Maximum time in milliseconds. Defaults to `0` - no timeout. The default value can be changed via `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.
*/
timeout?: number
}): Promise<boolean>
/**
* Returns whether the element is disabled, the opposite of [enabled](https://playwright.dev/docs/actionability#enabled).
*
* **NOTE** If you need to assert that an element is disabled, prefer
* [expect(locator).toBeDisabled([options])](https://playwright.dev/docs/api/class-locatorassertions#locator-assertions-to-be-disabled)
* to avoid flakiness. See [assertions guide](https://playwright.dev/docs/test-assertions) for more details.
*
* **Usage**
*
* ```js
* const disabled = await page.getByRole('button').isDisabled();
* ```
*
* @param options
*/
isDisabled(options?: {
/**
* Allows to cancel the operation using an
* [`AbortSignal`](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal). If the signal is aborted, the
* operation will be aborted and throw an error. Note that providing a signal does not disable the default timeout,
* which can be changed using
* [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); pass
* `timeout: 0` to disable the timeout entirely.
*/
signal?: AbortSignal
/**
* Maximum time in milliseconds. Defaults to `0` - no timeout. The default value can be changed via `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.
*/
timeout?: number
}): Promise<boolean>
/**
* Returns whether the element is [editable](https://playwright.dev/docs/actionability#editable). If the target element is not an `<input>`,
* `<textarea>`, `<select>`, `[contenteditable]` and does not have a role allowing `[aria-readonly]`, this method
* throws an error.
*
* **NOTE** If you need to assert that an element is editable, prefer
* [expect(locator).toBeEditable([options])](https://playwright.dev/docs/api/class-locatorassertions#locator-assertions-to-be-editable)
* to avoid flakiness. See [assertions guide](https://playwright.dev/docs/test-assertions) for more details.
*
* **Usage**
*
* ```js
* const editable = await page.getByRole('textbox').isEditable();
* ```
*
* @param options
*/
isEditable(options?: {
/**
* Allows to cancel the operation using an
* [`AbortSignal`](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal). If the signal is aborted, the
* operation will be aborted and throw an error. Note that providing a signal does not disable the default timeout,
* which can be changed using
* [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); pass
* `timeout: 0` to disable the timeout entirely.
*/
signal?: AbortSignal
/**
* Maximum time in milliseconds. Defaults to `0` - no timeout. The default value can be changed via `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.
*/
timeout?: number
}): Promise<boolean>
/**
* Returns whether the element is [enabled](https://playwright.dev/docs/actionability#enabled).
*
* **NOTE** If you need to assert that an element is enabled, prefer
* [expect(locator).toBeEnabled([options])](https://playwright.dev/docs/api/class-locatorassertions#locator-assertions-to-be-enabled)
* to avoid flakiness. See [assertions guide](https://playwright.dev/docs/test-assertions) for more details.
*
* **Usage**
*
* ```js
* const enabled = await page.getByRole('button').isEnabled();
* ```
*
* @param options
*/
isEnabled(options?: {
/**
* Allows to cancel the operation using an
* [`AbortSignal`](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal). If the signal is aborted, the
* operation will be aborted and throw an error. Note that providing a signal does not disable the default timeout,
* which can be changed using
* [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); pass
* `timeout: 0` to disable the timeout entirely.
*/
signal?: AbortSignal
/**
* Maximum time in milliseconds. Defaults to `0` - no timeout. The default value can be changed via `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.
*/
timeout?: number
}): Promise<boolean>
/**
* Returns whether the element is hidden, the opposite of [visible](https://playwright.dev/docs/actionability#visible).
*
* **NOTE** If you need to assert that element is hidden, prefer
* [expect(locator).toBeHidden([options])](https://playwright.dev/docs/api/class-locatorassertions#locator-assertions-to-be-hidden)
* to avoid flakiness. See [assertions guide](https://playwright.dev/docs/test-assertions) for more details.
*
* **Usage**
*
* ```js
* const hidden = await page.getByRole('button').isHidden();
* ```
*
* @param options
*/
isHidden(options?: {
/**
* @deprecated This option is ignored.
* [locator.isHidden([options])](https://playwright.dev/docs/api/class-locator#locator-is-hidden) does not wait for
* the element to become hidden and returns immediately.
*/
timeout?: number
}): Promise<boolean>
/**
* Returns whether the element is [visible](https://playwright.dev/docs/actionability#visible).
*
* **NOTE** If you need to assert that element is visible, prefer
* [expect(locator).toBeVisible([options])](https://playwright.dev/docs/api/class-locatorassertions#locator-assertions-to-be-visible)
* to avoid flakiness. See [assertions guide](https://playwright.dev/docs/test-assertions) for more details.
*
* **Usage**
*
* ```js
* const visible = await page.getByRole('button').isVisible();
* ```
*
* @param options
*/
isVisible(options?: {
/**
* @deprecated This option is ignored.
* [locator.isVisible([options])](https://playwright.dev/docs/api/class-locator#locator-is-visible) does not wait for
* the element to become visible and returns immediately.
*/
timeout?: number
}): Promise<boolean>
/**
* Returns locator to the last matching element.
*
* **Usage**
*
* ```js
* const banana = await page.getByRole('listitem').last();
* ```
*
*/
last(): Locator
/**
* The method finds an element matching the specified selector in the locator's subtree. It also accepts filter
* options, similar to [locator.filter([options])](https://playwright.dev/docs/api/class-locator#locator-filter)
* method.
*
* [Learn more about locators](https://playwright.dev/docs/locators).
* @param selectorOrLocator A selector or locator to use when resolving DOM element.
* @param options
*/
locator(
selectorOrLocator: string | Locator,
options?: {
/**
* Narrows down the results of the method to those which contain elements matching this relative locator. For example,
* `article` that has `text=Playwright` matches `<article><div>Playwright</div></article>`.
*
* Inner locator **must be relative** to the outer locator and is queried starting with the outer locator match, not
* the document root. For example, you can find `content` that has `div` in
* `<article><content><div>Playwright</div></content></article>`. However, looking for `content` that has `article
* div` will fail, because the inner locator must be relative and should not use any elements outside the `content`.
*
* Note that outer and inner locators must belong to the same frame. Inner locator must not contain
* [FrameLocator](https://playwright.dev/docs/api/class-framelocator)s.
*/
has?: Locator
/**
* Matches elements that do not contain an element that matches an inner locator. Inner locator is queried against the
* outer one. For example, `article` that does not have `div` matches `<article><span>Playwright</span></article>`.
*
* Note that outer and inner locators must belong to the same frame. Inner locator must not contain
* [FrameLocator](https://playwright.dev/docs/api/class-framelocator)s.
*/
hasNot?: Locator
/**
* Matches elements that do not contain specified text somewhere inside, possibly in a child or a descendant element.
* When passed a [string], matching is case-insensitive and searches for a substring.
*/
hasNotText?: string | RegExp
/**
* Matches elements containing specified text somewhere inside, possibly in a child or a descendant element. When
* passed a [string], matching is case-insensitive and searches for a substring. For example, `"Playwright"` matches
* `<article><div>Playwright</div></article>`.
*/
hasText?: string | RegExp
},
): Locator
/**
* Returns a new locator that uses best practices for referencing the matched element, prioritizing test ids, aria
* roles, and other user-facing attributes over CSS selectors. This is useful for converting implementation-detail
* selectors into more resilient, human-readable locators.
*/
normalize(): Promise<Locator>
/**
* Returns locator to the n-th matching element. It's zero based, `nth(0)` selects the first element.
*
* **Usage**
*
* ```js
* const banana = await page.getByRole('listitem').nth(2);
* ```
*
* @param index
*/
nth(index: number): Locator
/**
* Creates a locator matching all elements that match one or both of the two locators.
*
* Note that when both locators match something, the resulting locator will have multiple matches, potentially causing
* a [locator strictness](https://playwright.dev/docs/locators#strictness) violation.
*
* **Usage**
*
* Consider a scenario where you'd like to click on a "New email" button, but sometimes a security settings dialog
* shows up instead. In this case, you can wait for either a "New email" button, or a dialog and act accordingly.
*
* **NOTE** If both "New email" button and security dialog appear on screen, the "or" locator will match both of them,
* possibly throwing the ["strict mode violation" error](https://playwright.dev/docs/locators#strictness). In this case, you can use
* [locator.first()](https://playwright.dev/docs/api/class-locator#locator-first) to only match one of them.
*
* ```js
* const newEmail = page.getByRole('button', { name: 'New' });
* const dialog = page.getByText('Confirm security settings');
* await expect(newEmail.or(dialog).first()).toBeVisible();
* if (await dialog.isVisible())
* await page.getByRole('button', { name: 'Dismiss' }).click();
* await newEmail.click();
* ```
*
* @param locator Alternative locator to match.
*/
or(locator: Locator): Locator
/**
* A page this locator belongs to.
*/
page(): Page
/**
* Focuses the matching element and presses a combination of the keys.
*
* **Usage**
*
* ```js
* await page.getByRole('textbox').press('Backspace');
* ```
*
* **Details**
*
* Focuses the element, and then uses
* [keyboard.down(key)](https://playwright.dev/docs/api/class-keyboard#keyboard-down) and
* [keyboard.up(key)](https://playwright.dev/docs/api/class-keyboard#keyboard-up).
*
* [`key`](https://playwright.dev/docs/api/class-locator#locator-press-option-key) can specify the intended
* [keyboardEvent.key](https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/key) value or a single character
* to generate the text for. A superset of the
* [`key`](https://playwright.dev/docs/api/class-locator#locator-press-option-key) values can be found
* [here](https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/key/Key_Values). Examples of the keys are:
*
* `F1` - `F12`, `Digit0`- `Digit9`, `KeyA`- `KeyZ`, `Backquote`, `Minus`, `Equal`, `Backslash`, `Backspace`, `Tab`,
* `Delete`, `Escape`, `ArrowDown`, `End`, `Enter`, `Home`, `Insert`, `PageDown`, `PageUp`, `ArrowRight`, `ArrowUp`,
* etc.
*
* Following modification shortcuts are also supported: `Shift`, `Control`, `Alt`, `Meta`, `ShiftLeft`,
* `ControlOrMeta`. `ControlOrMeta` resolves to `Control` on Windows and Linux and to `Meta` on macOS.
*
* Holding down `Shift` will type the text that corresponds to the
* [`key`](https://playwright.dev/docs/api/class-locator#locator-press-option-key) in the upper case.
*
* If [`key`](https://playwright.dev/docs/api/class-locator#locator-press-option-key) is a single character, it is
* case-sensitive, so the values `a` and `A` will generate different respective texts.
*
* Shortcuts such as `key: "Control+o"`, `key: "Control++` or `key: "Control+Shift+T"` are supported as well. When
* specified with the modifier, modifier is pressed and being held while the subsequent key is being pressed.
* @param key Name of the key to press or a character to generate, such as `ArrowLeft` or `a`.
* @param options
*/
press(
key: string,
options?: {
/**
* Time to wait between `keydown` and `keyup` in milliseconds. Defaults to 0.
*/
delay?: number
/**
* Actions that initiate navigations are waiting for these navigations to happen and for pages to start loading. You
* can opt out of waiting via setting this flag. You would only need this option in the exceptional cases such as
* navigating to inaccessible pages. Defaults to `false`.
* @deprecated This option will default to `true` in the future.
*/
noWaitAfter?: boolean
/**
* Allows to cancel the operation using an
* [`AbortSignal`](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal). If the signal is aborted, the
* operation will be aborted and throw an error. Note that providing a signal does not disable the default timeout,
* which can be changed using
* [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); pass
* `timeout: 0` to disable the timeout entirely.
*/
signal?: AbortSignal
/**
* Maximum time in milliseconds. Defaults to `0` - no timeout. The default value can be changed via `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.
*/
timeout?: number
},
): Promise<void>
/**
* **NOTE** In most cases, you should use
* [locator.fill(value[, options])](https://playwright.dev/docs/api/class-locator#locator-fill) instead. You only need
* to press keys one by one if there is special keyboard handling on the page.
*
* Focuses the element, and then sends a `keydown`, `keypress`/`input`, and `keyup` event for each character in the
* text.
*
* To press a special key, like `Control` or `ArrowDown`, use
* [locator.press(key[, options])](https://playwright.dev/docs/api/class-locator#locator-press).
*
* **Usage**
*
* ```js
* await locator.pressSequentially('Hello'); // Types instantly
* await locator.pressSequentially('World', { delay: 100 }); // Types slower, like a user
* ```
*
* An example of typing into a text field and then submitting the form:
*
* ```js
* const locator = page.getByLabel('Password');
* await locator.pressSequentially('my password');
* await locator.press('Enter');
* ```
*
* @param text String of characters to sequentially press into a focused element.
* @param options
*/
pressSequentially(
text: string,
options?: {
/**
* Time to wait between key presses in milliseconds. Defaults to 0.
*/
delay?: number
/**
* This option has no effect.
* @deprecated This option has no effect.
*/
noWaitAfter?: boolean
/**
* Allows to cancel the operation using an
* [`AbortSignal`](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal). If the signal is aborted, the
* operation will be aborted and throw an error. Note that providing a signal does not disable the default timeout,
* which can be changed using
* [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); pass
* `timeout: 0` to disable the timeout entirely.
*/
signal?: AbortSignal
/**
* Maximum time in milliseconds. Defaults to `0` - no timeout. The default value can be changed via `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.
*/
timeout?: number
},
): Promise<void>
/**
* Take a screenshot of the element matching the locator.
*
* **Usage**
*
* ```js
* await page.getByRole('link').screenshot();
* ```
*
* Disable animations and save screenshot to a file:
*
* ```js
* await page.getByRole('link').screenshot({ animations: 'disabled', path: 'link.png' });
* ```
*
* **Details**
*
* This method captures a screenshot of the page, clipped to the size and position of a particular element matching
* the locator. If the element is covered by other elements, it will not be actually visible on the screenshot. If the
* element is a scrollable container, only the currently scrolled content will be visible on the screenshot.
*
* This method waits for the [actionability](https://playwright.dev/docs/actionability) checks, then scrolls element into view before taking
* a screenshot. If the element is detached from DOM, the method throws an error.
*
* Returns the buffer with the captured screenshot.
* @param options
*/
screenshot(options?: LocatorScreenshotOptions): Promise<Buffer>
/**
* This method waits for [actionability](https://playwright.dev/docs/actionability) checks, then tries to scroll element into view, unless
* it is completely visible as defined by
* [IntersectionObserver](https://developer.mozilla.org/en-US/docs/Web/API/Intersection_Observer_API)'s `ratio`.
*
* See [scrolling](https://playwright.dev/docs/input#scrolling) for alternative ways to scroll.
* @param options
*/
scrollIntoViewIfNeeded(options?: {
/**
* Allows to cancel the operation using an
* [`AbortSignal`](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal). If the signal is aborted, the
* operation will be aborted and throw an error. Note that providing a signal does not disable the default timeout,
* which can be changed using
* [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); pass
* `timeout: 0` to disable the timeout entirely.
*/
signal?: AbortSignal
/**
* Maximum time in milliseconds. Defaults to `0` - no timeout. The default value can be changed via `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.
*/
timeout?: number
}): Promise<void>
/**
* Selects option or options in `<select>`.
*
* **Details**
*
* This method waits for [actionability](https://playwright.dev/docs/actionability) checks, waits until all specified options are present in
* the `<select>` element and selects these options.
*
* If the target element is not a `<select>` element, this method throws an error. However, if the element is inside
* the `<label>` element that has an associated
* [control](https://developer.mozilla.org/en-US/docs/Web/API/HTMLLabelElement/control), the control will be used
* instead.
*
* Returns the array of option values that have been successfully selected.
*
* Triggers a `change` and `input` event once all the provided options have been selected.
*
* **Usage**
*
* ```html
* <select multiple>
* <option value="red">Red</option>
* <option value="green">Green</option>
* <option value="blue">Blue</option>
* </select>
* ```
*
* ```js
* // single selection matching the value or label
* element.selectOption('blue');
*
* // single selection matching the label
* element.selectOption({ label: 'Blue' });
*
* // multiple selection for red, green and blue options
* element.selectOption(['red', 'green', 'blue']);
* ```
*
* @param values Options to select. If the `<select>` has the `multiple` attribute, all matching options are selected, otherwise
* only the first option matching one of the passed options is selected. String values are matching both values and
* labels. Option is considered matching if all specified properties match.
* @param options
*/
selectOption(
values:
| null
| string
| ElementHandle
| ReadonlyArray<string>
| {
/**
* Matches by `option.value`. Optional.
*/
value?: string
/**
* Matches by `option.label`. Optional.
*/
label?: string
/**
* Matches by the index. Optional.
*/
index?: number
}
| ReadonlyArray<ElementHandle>
| ReadonlyArray<{
/**
* Matches by `option.value`. Optional.
*/
value?: string
/**
* Matches by `option.label`. Optional.
*/
label?: string
/**
* Matches by the index. Optional.
*/
index?: number
}>,
options?: {
/**
* Whether to bypass the [actionability](https://playwright.dev/docs/actionability) checks. Defaults to `false`.
*/
force?: boolean
/**
* This option has no effect.
* @deprecated This option has no effect.
*/
noWaitAfter?: boolean
/**
* Allows to cancel the operation using an
* [`AbortSignal`](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal). If the signal is aborted, the
* operation will be aborted and throw an error. Note that providing a signal does not disable the default timeout,
* which can be changed using
* [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); pass
* `timeout: 0` to disable the timeout entirely.
*/
signal?: AbortSignal
/**
* Maximum time in milliseconds. Defaults to `0` - no timeout. The default value can be changed via `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.
*/
timeout?: number
},
): Promise<Array<string>>
/**
* This method waits for [actionability](https://playwright.dev/docs/actionability) checks, then focuses the element and selects all its
* text content.
*
* If the element is inside the `<label>` element that has an associated
* [control](https://developer.mozilla.org/en-US/docs/Web/API/HTMLLabelElement/control), focuses and selects text in
* the control instead.
* @param options
*/
selectText(options?: {
/**
* Whether to bypass the [actionability](https://playwright.dev/docs/actionability) checks. Defaults to `false`.
*/
force?: boolean
/**
* Allows to cancel the operation using an
* [`AbortSignal`](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal). If the signal is aborted, the
* operation will be aborted and throw an error. Note that providing a signal does not disable the default timeout,
* which can be changed using
* [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); pass
* `timeout: 0` to disable the timeout entirely.
*/
signal?: AbortSignal
/**
* Maximum time in milliseconds. Defaults to `0` - no timeout. The default value can be changed via `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.
*/
timeout?: number
}): Promise<void>
/**
* Set the state of a checkbox or a radio element.
*
* **Usage**
*
* ```js
* await page.getByRole('checkbox').setChecked(true);
* ```
*
* **Details**
*
* This method checks or unchecks an element by performing the following steps:
* 1. Ensure that matched element is a checkbox or a radio input. If not, this method throws.
* 1. If the element already has the right checked state, this method returns immediately.
* 1. Wait for [actionability](https://playwright.dev/docs/actionability) checks on the matched element, unless
* [`force`](https://playwright.dev/docs/api/class-locator#locator-set-checked-option-force) option is set. If
* the element is detached during the checks, the whole action is retried.
* 1. Scroll the element into view if needed.
* 1. Use [page.mouse](https://playwright.dev/docs/api/class-page#page-mouse) to click in the center of the
* element.
* 1. Ensure that the element is now checked or unchecked. If not, this method throws.
*
* When all steps combined have not finished during the specified
* [`timeout`](https://playwright.dev/docs/api/class-locator#locator-set-checked-option-timeout), this method throws a
* [TimeoutError](https://playwright.dev/docs/api/class-timeouterror). Passing zero timeout disables this.
* @param checked Whether to check or uncheck the checkbox.
* @param options
*/
setChecked(
checked: boolean,
options?: {
/**
* Whether to bypass the [actionability](https://playwright.dev/docs/actionability) checks. Defaults to `false`.
*/
force?: boolean
/**
* This option has no effect.
* @deprecated This option has no effect.
*/
noWaitAfter?: boolean
/**
* A point to use relative to the top-left corner of element padding box. If not specified, uses some visible point of
* the element.
*/
position?: {
x: number
y: number
}
/**
* Controls whether Playwright scrolls the element into view before performing the action. Defaults to `"auto"`, which
* scrolls the element into view when necessary, including scrolling nested scrollable containers. When set to
* `"none"`, Playwright does not scroll the element and the action fails if the element is not already in the
* viewport. This is useful to assert that an element is reachable by the user without additional scrolling.
*/
scroll?: 'auto' | 'none'
/**
* Allows to cancel the operation using an
* [`AbortSignal`](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal). If the signal is aborted, the
* operation will be aborted and throw an error. Note that providing a signal does not disable the default timeout,
* which can be changed using
* [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); pass
* `timeout: 0` to disable the timeout entirely.
*/
signal?: AbortSignal
/**
* Maximum time in milliseconds. Defaults to `0` - no timeout. The default value can be changed via `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.
*/
timeout?: number
/**
* When set, this method only performs the [actionability](https://playwright.dev/docs/actionability) checks and skips the action. Defaults
* to `false`. Useful to wait until the element is ready for the action without performing it.
*/
trial?: boolean
},
): Promise<void>
/**
* Upload file or multiple files into `<input type=file>`. For inputs with a `[webkitdirectory]` attribute, only a
* single directory path is supported.
*
* **Usage**
*
* ```js
* // Select one file
* await page.getByLabel('Upload file').setInputFiles(path.join(__dirname, 'myfile.pdf'));
*
* // Select multiple files
* await page.getByLabel('Upload files').setInputFiles([
* path.join(__dirname, 'file1.txt'),
* path.join(__dirname, 'file2.txt'),
* ]);
*
* // Select a directory
* await page.getByLabel('Upload directory').setInputFiles(path.join(__dirname, 'mydir'));
*
* // Remove all the selected files
* await page.getByLabel('Upload file').setInputFiles([]);
*
* // Upload buffer from memory
* await page.getByLabel('Upload file').setInputFiles({
* name: 'file.txt',
* mimeType: 'text/plain',
* buffer: Buffer.from('this is test')
* });
* ```
*
* **Details**
*
* Sets the value of the file input to these file paths or files. If some of the `filePaths` are relative paths, then
* they are resolved relative to the current working directory. For empty array, clears the selected files.
*
* This method expects [Locator](https://playwright.dev/docs/api/class-locator) to point to an
* [input element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input). However, if the element is inside
* the `<label>` element that has an associated
* [control](https://developer.mozilla.org/en-US/docs/Web/API/HTMLLabelElement/control), targets the control instead.
* @param files
* @param options
*/
setInputFiles(
files:
| string
| ReadonlyArray<string>
| {
/**
* File name
*/
name: string
/**
* File type
*/
mimeType: string
/**
* File content
*/
buffer: Buffer
}
| ReadonlyArray<{
/**
* File name
*/
name: string
/**
* File type
*/
mimeType: string
/**
* File content
*/
buffer: Buffer
}>,
options?: {
/**
* This option has no effect.
* @deprecated This option has no effect.
*/
noWaitAfter?: boolean
/**
* Allows to cancel the operation using an
* [`AbortSignal`](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal). If the signal is aborted, the
* operation will be aborted and throw an error. Note that providing a signal does not disable the default timeout,
* which can be changed using
* [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); pass
* `timeout: 0` to disable the timeout entirely.
*/
signal?: AbortSignal
/**
* Maximum time in milliseconds. Defaults to `0` - no timeout. The default value can be changed via `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.
*/
timeout?: number
},
): Promise<void>
/**
* Perform a tap gesture on the element matching the locator. For examples of emulating other gestures by manually
* dispatching touch events, see the [emulating legacy touch events](https://playwright.dev/docs/touch-events) page.
*
* **Details**
*
* This method taps the element by performing the following steps:
* 1. Wait for [actionability](https://playwright.dev/docs/actionability) checks on the element, unless
* [`force`](https://playwright.dev/docs/api/class-locator#locator-tap-option-force) option is set.
* 1. Scroll the element into view if needed.
* 1. Use [page.touchscreen](https://playwright.dev/docs/api/class-page#page-touchscreen) to tap the center of the
* element, or the specified
* [`position`](https://playwright.dev/docs/api/class-locator#locator-tap-option-position).
*
* If the element is detached from the DOM at any moment during the action, this method throws.
*
* When all steps combined have not finished during the specified
* [`timeout`](https://playwright.dev/docs/api/class-locator#locator-tap-option-timeout), this method throws a
* [TimeoutError](https://playwright.dev/docs/api/class-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?: {
/**
* Whether to bypass the [actionability](https://playwright.dev/docs/actionability) checks. Defaults to `false`.
*/
force?: boolean
/**
* Modifier keys to press. Ensures that only these modifiers are pressed during the operation, and then restores
* current modifiers back. If not specified, currently pressed modifiers are used. "ControlOrMeta" resolves to
* "Control" on Windows and Linux and to "Meta" on macOS.
*/
modifiers?: Array<'Alt' | 'Control' | 'ControlOrMeta' | 'Meta' | 'Shift'>
/**
* This option has no effect.
* @deprecated This option has no effect.
*/
noWaitAfter?: boolean
/**
* A point to use relative to the top-left corner of element padding box. If not specified, uses some visible point of
* the element.
*/
position?: {
x: number
y: number
}
/**
* Controls whether Playwright scrolls the element into view before performing the action. Defaults to `"auto"`, which
* scrolls the element into view when necessary, including scrolling nested scrollable containers. When set to
* `"none"`, Playwright does not scroll the element and the action fails if the element is not already in the
* viewport. This is useful to assert that an element is reachable by the user without additional scrolling.
*/
scroll?: 'auto' | 'none'
/**
* Allows to cancel the operation using an
* [`AbortSignal`](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal). If the signal is aborted, the
* operation will be aborted and throw an error. Note that providing a signal does not disable the default timeout,
* which can be changed using
* [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); pass
* `timeout: 0` to disable the timeout entirely.
*/
signal?: AbortSignal
/**
* Maximum time in milliseconds. Defaults to `0` - no timeout. The default value can be changed via `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.
*/
timeout?: number
/**
* When set, this method only performs the [actionability](https://playwright.dev/docs/actionability) checks and skips the action. Defaults
* to `false`. Useful to wait until the element is ready for the action without performing it. Note that keyboard
* `modifiers` will be pressed regardless of `trial` to allow testing elements which are only visible when those keys
* are pressed.
*/
trial?: boolean
}): Promise<void>
/**
* Returns the [`node.textContent`](https://developer.mozilla.org/en-US/docs/Web/API/Node/textContent).
*
* **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?: {
/**
* Allows to cancel the operation using an
* [`AbortSignal`](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal). If the signal is aborted, the
* operation will be aborted and throw an error. Note that providing a signal does not disable the default timeout,
* which can be changed using
* [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); pass
* `timeout: 0` to disable the timeout entirely.
*/
signal?: AbortSignal
/**
* Maximum time in milliseconds. Defaults to `0` - no timeout. The default value can be changed via `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.
*/
timeout?: number
}): Promise<null | string>
/**
* Focuses the element, and then sends a `keydown`, `keypress`/`input`, and `keyup` event for each character in the
* text.
*
* To press a special key, like `Control` or `ArrowDown`, use
* [locator.press(key[, options])](https://playwright.dev/docs/api/class-locator#locator-press).
*
* **Usage**
* @deprecated In most cases, you should use
* [locator.fill(value[, options])](https://playwright.dev/docs/api/class-locator#locator-fill) instead. You only need
* to press keys one by one if there is special keyboard handling on the page - in this case use
* [locator.pressSequentially(text[, options])](https://playwright.dev/docs/api/class-locator#locator-press-sequentially).
* @param text A text to type into a focused element.
* @param options
*/
type(
text: string,
options?: {
/**
* Time to wait between key presses in milliseconds. Defaults to 0.
*/
delay?: number
/**
* This option has no effect.
* @deprecated This option has no effect.
*/
noWaitAfter?: boolean
/**
* Allows to cancel the operation using an
* [`AbortSignal`](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal). If the signal is aborted, the
* operation will be aborted and throw an error. Note that providing a signal does not disable the default timeout,
* which can be changed using
* [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); pass
* `timeout: 0` to disable the timeout entirely.
*/
signal?: AbortSignal
/**
* Maximum time in milliseconds. Defaults to `0` - no timeout. The default value can be changed via `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.
*/
timeout?: number
},
): Promise<void>
/**
* Ensure that checkbox or radio element is unchecked.
*
* **Usage**
*
* ```js
* await page.getByRole('checkbox').uncheck();
* ```
*
* **Details**
*
* This method unchecks the element by performing the following steps:
* 1. Ensure that element is a checkbox or a radio input. If not, this method throws. If the element is already
* unchecked, this method returns immediately.
* 1. Wait for [actionability](https://playwright.dev/docs/actionability) checks on the element, unless
* [`force`](https://playwright.dev/docs/api/class-locator#locator-uncheck-option-force) option is set.
* 1. Scroll the element into view if needed.
* 1. Use [page.mouse](https://playwright.dev/docs/api/class-page#page-mouse) to click in the center of the
* element.
* 1. Ensure that the element is now unchecked. If not, this method throws.
*
* If the element is detached from the DOM at any moment during the action, this method throws.
*
* When all steps combined have not finished during the specified
* [`timeout`](https://playwright.dev/docs/api/class-locator#locator-uncheck-option-timeout), this method throws a
* [TimeoutError](https://playwright.dev/docs/api/class-timeouterror). Passing zero timeout disables this.
* @param options
*/
uncheck(options?: {
/**
* Whether to bypass the [actionability](https://playwright.dev/docs/actionability) checks. Defaults to `false`.
*/
force?: boolean
/**
* This option has no effect.
* @deprecated This option has no effect.
*/
noWaitAfter?: boolean
/**
* A point to use relative to the top-left corner of element padding box. If not specified, uses some visible point of
* the element.
*/
position?: {
x: number
y: number
}
/**
* Controls whether Playwright scrolls the element into view before performing the action. Defaults to `"auto"`, which
* scrolls the element into view when necessary, including scrolling nested scrollable containers. When set to
* `"none"`, Playwright does not scroll the element and the action fails if the element is not already in the
* viewport. This is useful to assert that an element is reachable by the user without additional scrolling.
*/
scroll?: 'auto' | 'none'
/**
* Allows to cancel the operation using an
* [`AbortSignal`](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal). If the signal is aborted, the
* operation will be aborted and throw an error. Note that providing a signal does not disable the default timeout,
* which can be changed using
* [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); pass
* `timeout: 0` to disable the timeout entirely.
*/
signal?: AbortSignal
/**
* Maximum time in milliseconds. Defaults to `0` - no timeout. The default value can be changed via `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.
*/
timeout?: number
/**
* When set, this method only performs the [actionability](https://playwright.dev/docs/actionability) checks and skips the action. Defaults
* to `false`. Useful to wait until the element is ready for the action without performing it.
*/
trial?: boolean
}): Promise<void>
/**
* Returns a locator that matches only [visible](https://playwright.dev/docs/actionability#visible) elements, ignoring the invisible ones.
* This is the recommended way to distinguish elements by visibility, as opposed to the `:visible` CSS pseudo-class.
*
* Note that visibility is checked every time the locator is used, and not at the moment of the
* [locator.visible()](https://playwright.dev/docs/api/class-locator#locator-visible) call.
*
* **Usage**
*
* Consider a page with two buttons, the first invisible and the second visible.
*
* ```html
* <button style='display: none'>Invisible</button>
* <button>Visible</button>
* ```
*
* This will only find the second button, because it is visible, and then click it.
*
* ```js
* await page.locator('button').visible().click();
* ```
*
* To match invisible elements instead, use
* [locator.filter([options])](https://playwright.dev/docs/api/class-locator#locator-filter) with the
* [`visible`](https://playwright.dev/docs/api/class-locator#locator-filter-option-visible) option set to `false`.
*/
visible(): Locator
/**
* Returns when element specified by locator satisfies the
* [`state`](https://playwright.dev/docs/api/class-locator#locator-wait-for-option-state) option.
*
* If target element already satisfies the condition, the method returns immediately. Otherwise, waits for up to
* [`timeout`](https://playwright.dev/docs/api/class-locator#locator-wait-for-option-timeout) milliseconds until the
* condition is met.
*
* **Usage**
*
* ```js
* const orderSent = page.locator('#order-sent');
* await orderSent.waitFor();
* ```
*
* @param options
*/
waitFor(options?: {
/**
* Allows to cancel the operation using an
* [`AbortSignal`](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal). If the signal is aborted, the
* operation will be aborted and throw an error. Note that providing a signal does not disable the default timeout,
* which can be changed using
* [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); pass
* `timeout: 0` to disable the timeout entirely.
*/
signal?: AbortSignal
/**
* Defaults to `'visible'`. Can be either:
* - `'attached'` - wait for element to be present in DOM.
* - `'detached'` - wait for element to not be present in DOM.
* - `'visible'` - wait for element to have non-empty bounding box and no `visibility:hidden`. Note that element
* 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.
*/
state?: 'attached' | 'detached' | 'visible' | 'hidden'
/**
* Maximum time in milliseconds. Defaults to `0` - no timeout. The default value can be changed via `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.
*/
timeout?: number
}): Promise<void>
}
Mouse
The Mouse class operates in main-frame CSS pixels relative to the top-left corner of the viewport.
NOTE If you want to debug where the mouse moved, you can use the Trace viewer or Playwright Inspector. A red dot showing the location of the mouse will be shown for every mouse action.
Every page object has its own Mouse, accessible with
page.mouse.
// Using ‘page.mouse’ to trace a 100x100 square.
await page.mouse.move(0, 0)
await page.mouse.down()
await page.mouse.move(0, 100)
await page.mouse.move(100, 100)
await page.mouse.move(100, 0)
await page.mouse.move(0, 0)
await page.mouse.up()
interface Mouse {
/**
* Shortcut for [mouse.move(x, y[, options])](https://playwright.dev/docs/api/class-mouse#mouse-move),
* [mouse.down([options])](https://playwright.dev/docs/api/class-mouse#mouse-down),
* [mouse.up([options])](https://playwright.dev/docs/api/class-mouse#mouse-up).
* @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.
* @param options
*/
click(
x: number,
y: number,
options?: {
/**
* Defaults to `left`.
*/
button?: 'left' | 'right' | 'middle'
/**
* defaults to 1. See [UIEvent.detail].
*/
clickCount?: number
/**
* Time to wait between `mousedown` and `mouseup` in milliseconds. Defaults to 0.
*/
delay?: number
},
): Promise<void>
/**
* Shortcut for [mouse.move(x, y[, options])](https://playwright.dev/docs/api/class-mouse#mouse-move),
* [mouse.down([options])](https://playwright.dev/docs/api/class-mouse#mouse-down),
* [mouse.up([options])](https://playwright.dev/docs/api/class-mouse#mouse-up),
* [mouse.down([options])](https://playwright.dev/docs/api/class-mouse#mouse-down) and
* [mouse.up([options])](https://playwright.dev/docs/api/class-mouse#mouse-up).
* @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.
* @param options
*/
dblclick(
x: number,
y: number,
options?: {
/**
* Defaults to `left`.
*/
button?: 'left' | 'right' | 'middle'
/**
* Time to wait between `mousedown` and `mouseup` in milliseconds. Defaults to 0.
*/
delay?: number
},
): Promise<void>
/**
* Dispatches a `mousedown` event.
* @param options
*/
down(options?: {
/**
* Defaults to `left`.
*/
button?: 'left' | 'right' | 'middle'
/**
* defaults to 1. See [UIEvent.detail].
*/
clickCount?: number
}): Promise<void>
/**
* Dispatches a `mousemove` event.
* @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.
* @param options
*/
move(
x: number,
y: number,
options?: {
/**
* Defaults to 1. Sends `n` interpolated `mousemove` events to represent travel between Playwright's current cursor
* position and the provided destination. When set to 1, emits a single `mousemove` event at the destination location.
*/
steps?: number
},
): Promise<void>
/**
* Dispatches a `mouseup` event.
* @param options
*/
up(options?: {
/**
* Defaults to `left`.
*/
button?: 'left' | 'right' | 'middle'
/**
* defaults to 1. See [UIEvent.detail].
*/
clickCount?: number
}): Promise<void>
/**
* 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.
*
* @param deltaX Pixels to scroll horizontally.
* @param deltaY Pixels to scroll vertically.
*/
wheel(deltaX: number, deltaY: number): Promise<void>
}
Page
Page provides methods to interact with a single tab in a Browser, or an extension background page in Chromium. One Browser instance might have multiple Page instances.
This example creates a page, navigates it to a URL, and then saves a screenshot:
const { webkit } = require('playwright') // Or 'chromium' or 'firefox'.
;(async () => {
const browser = await webkit.launch()
const context = await browser.newContext()
const page = await context.newPage()
await page.goto('https://example.com')
await page.screenshot({ path: 'screenshot.png' })
await browser.close()
})()
The Page class emits various events (described below) which can be handled using any of Node's native
EventEmitter methods, such as on, once or
removeListener.
This example logs a message for a single page load event:
page.once('load', () => console.log('Page loaded!'))
To unsubscribe from events use the removeListener method:
function logRequest(interceptedRequest) {
console.log('A request was made:', interceptedRequest.url())
}
page.on('request', logRequest)
// Sometime later...
page.removeListener('request', logRequest)
interface Page {
/**
* Returns the value of the
* [`pageFunction`](https://playwright.dev/docs/api/class-page#page-evaluate-option-expression) invocation.
*
* If the function passed to the
* [page.evaluate(pageFunction[, arg, options])](https://playwright.dev/docs/api/class-page#page-evaluate) returns a
* [Promise], then
* [page.evaluate(pageFunction[, arg, options])](https://playwright.dev/docs/api/class-page#page-evaluate) would wait
* for the promise to resolve and return its value.
*
* If the function passed to the
* [page.evaluate(pageFunction[, arg, options])](https://playwright.dev/docs/api/class-page#page-evaluate) returns a
* non-[Serializable] value, then
* [page.evaluate(pageFunction[, arg, options])](https://playwright.dev/docs/api/class-page#page-evaluate) resolves to
* `undefined`. Playwright also supports transferring some additional values that are not serializable by `JSON`:
* `-0`, `NaN`, `Infinity`, `-Infinity`.
*
* **Usage**
*
* Passing argument to [`pageFunction`](https://playwright.dev/docs/api/class-page#page-evaluate-option-expression):
*
* ```js
* const result = await page.evaluate(([x, y]) => {
* return Promise.resolve(x * y);
* }, [7, 8]);
* console.log(result); // prints "56"
* ```
*
* A string can also be passed in instead of a function:
*
* ```js
* console.log(await page.evaluate('1 + 2')); // prints "3"
* const x = 10;
* console.log(await page.evaluate(`1 + ${x}`)); // prints "11"
* ```
*
* [ElementHandle](https://playwright.dev/docs/api/class-elementhandle) instances can be passed as an argument to the
* [page.evaluate(pageFunction[, arg, options])](https://playwright.dev/docs/api/class-page#page-evaluate):
*
* ```js
* const bodyHandle = await page.evaluateHandle('document.body');
* const html = await page.evaluate<string, HTMLElement>(([body, suffix]) =>
* body.innerHTML + suffix, [bodyHandle, 'hello']
* );
* await bodyHandle.dispose();
* ```
*
* @param pageFunction Function to be evaluated in the page context.
* @param arg Optional argument to pass to
* [`pageFunction`](https://playwright.dev/docs/api/class-page#page-evaluate-option-expression).
* @param options
*/
evaluate<R, Arg>(
pageFunction: PageFunction<Arg, R>,
arg: Arg,
options?: { exposeFunctions?: boolean },
): Promise<R>
/**
* Returns the value of the
* [`pageFunction`](https://playwright.dev/docs/api/class-page#page-evaluate-option-expression) invocation.
*
* If the function passed to the
* [page.evaluate(pageFunction[, arg, options])](https://playwright.dev/docs/api/class-page#page-evaluate) returns a
* [Promise], then
* [page.evaluate(pageFunction[, arg, options])](https://playwright.dev/docs/api/class-page#page-evaluate) would wait
* for the promise to resolve and return its value.
*
* If the function passed to the
* [page.evaluate(pageFunction[, arg, options])](https://playwright.dev/docs/api/class-page#page-evaluate) returns a
* non-[Serializable] value, then
* [page.evaluate(pageFunction[, arg, options])](https://playwright.dev/docs/api/class-page#page-evaluate) resolves to
* `undefined`. Playwright also supports transferring some additional values that are not serializable by `JSON`:
* `-0`, `NaN`, `Infinity`, `-Infinity`.
*
* **Usage**
*
* Passing argument to [`pageFunction`](https://playwright.dev/docs/api/class-page#page-evaluate-option-expression):
*
* ```js
* const result = await page.evaluate(([x, y]) => {
* return Promise.resolve(x * y);
* }, [7, 8]);
* console.log(result); // prints "56"
* ```
*
* A string can also be passed in instead of a function:
*
* ```js
* console.log(await page.evaluate('1 + 2')); // prints "3"
* const x = 10;
* console.log(await page.evaluate(`1 + ${x}`)); // prints "11"
* ```
*
* [ElementHandle](https://playwright.dev/docs/api/class-elementhandle) instances can be passed as an argument to the
* [page.evaluate(pageFunction[, arg, options])](https://playwright.dev/docs/api/class-page#page-evaluate):
*
* ```js
* const bodyHandle = await page.evaluateHandle('document.body');
* const html = await page.evaluate<string, HTMLElement>(([body, suffix]) =>
* body.innerHTML + suffix, [bodyHandle, 'hello']
* );
* await bodyHandle.dispose();
* ```
*
* @param pageFunction Function to be evaluated in the page context.
* @param arg Optional argument to pass to
* [`pageFunction`](https://playwright.dev/docs/api/class-page#page-evaluate-option-expression).
* @param options
*/
evaluate<R>(
pageFunction: PageFunction<void, R>,
arg?: any,
options?: { exposeFunctions?: boolean },
): Promise<R>
/**
* Returns the value of the
* [`pageFunction`](https://playwright.dev/docs/api/class-page#page-evaluate-handle-option-expression) invocation as a
* [JSHandle](https://playwright.dev/docs/api/class-jshandle).
*
* The only difference between
* [page.evaluate(pageFunction[, arg, options])](https://playwright.dev/docs/api/class-page#page-evaluate) and
* [page.evaluateHandle(pageFunction[, arg, options])](https://playwright.dev/docs/api/class-page#page-evaluate-handle)
* is that
* [page.evaluateHandle(pageFunction[, arg, options])](https://playwright.dev/docs/api/class-page#page-evaluate-handle)
* returns [JSHandle](https://playwright.dev/docs/api/class-jshandle).
*
* If the function passed to the
* [page.evaluateHandle(pageFunction[, arg, options])](https://playwright.dev/docs/api/class-page#page-evaluate-handle)
* returns a [Promise], then
* [page.evaluateHandle(pageFunction[, arg, options])](https://playwright.dev/docs/api/class-page#page-evaluate-handle)
* would wait for the promise to resolve and return its value.
*
* **Usage**
*
* ```js
* // Handle for the window object.
* const aWindowHandle = await page.evaluateHandle(() => Promise.resolve(window));
* ```
*
* A string can also be passed in instead of a function:
*
* ```js
* const aHandle = await page.evaluateHandle('document'); // Handle for the 'document'
* ```
*
* [JSHandle](https://playwright.dev/docs/api/class-jshandle) instances can be passed as an argument to the
* [page.evaluateHandle(pageFunction[, arg, options])](https://playwright.dev/docs/api/class-page#page-evaluate-handle):
*
* ```js
* const aHandle = await page.evaluateHandle(() => document.body);
* const resultHandle = await page.evaluateHandle(body => body.innerHTML, aHandle);
* console.log(await resultHandle.jsonValue());
* await resultHandle.dispose();
* ```
*
* @param pageFunction Function to be evaluated in the page context.
* @param arg Optional argument to pass to
* [`pageFunction`](https://playwright.dev/docs/api/class-page#page-evaluate-handle-option-expression).
* @param options
*/
evaluateHandle<R, Arg>(
pageFunction: PageFunction<Arg, R>,
arg: Arg,
options?: { exposeFunctions?: boolean },
): Promise<SmartHandle<R>>
/**
* Returns the value of the
* [`pageFunction`](https://playwright.dev/docs/api/class-page#page-evaluate-handle-option-expression) invocation as a
* [JSHandle](https://playwright.dev/docs/api/class-jshandle).
*
* The only difference between
* [page.evaluate(pageFunction[, arg, options])](https://playwright.dev/docs/api/class-page#page-evaluate) and
* [page.evaluateHandle(pageFunction[, arg, options])](https://playwright.dev/docs/api/class-page#page-evaluate-handle)
* is that
* [page.evaluateHandle(pageFunction[, arg, options])](https://playwright.dev/docs/api/class-page#page-evaluate-handle)
* returns [JSHandle](https://playwright.dev/docs/api/class-jshandle).
*
* If the function passed to the
* [page.evaluateHandle(pageFunction[, arg, options])](https://playwright.dev/docs/api/class-page#page-evaluate-handle)
* returns a [Promise], then
* [page.evaluateHandle(pageFunction[, arg, options])](https://playwright.dev/docs/api/class-page#page-evaluate-handle)
* would wait for the promise to resolve and return its value.
*
* **Usage**
*
* ```js
* // Handle for the window object.
* const aWindowHandle = await page.evaluateHandle(() => Promise.resolve(window));
* ```
*
* A string can also be passed in instead of a function:
*
* ```js
* const aHandle = await page.evaluateHandle('document'); // Handle for the 'document'
* ```
*
* [JSHandle](https://playwright.dev/docs/api/class-jshandle) instances can be passed as an argument to the
* [page.evaluateHandle(pageFunction[, arg, options])](https://playwright.dev/docs/api/class-page#page-evaluate-handle):
*
* ```js
* const aHandle = await page.evaluateHandle(() => document.body);
* const resultHandle = await page.evaluateHandle(body => body.innerHTML, aHandle);
* console.log(await resultHandle.jsonValue());
* await resultHandle.dispose();
* ```
*
* @param pageFunction Function to be evaluated in the page context.
* @param arg Optional argument to pass to
* [`pageFunction`](https://playwright.dev/docs/api/class-page#page-evaluate-handle-option-expression).
* @param options
*/
evaluateHandle<R>(
pageFunction: PageFunction<void, R>,
arg?: any,
options?: { exposeFunctions?: boolean },
): Promise<SmartHandle<R>>
/**
* Adds a script which would be evaluated in one of the following scenarios:
* - Whenever the page is navigated.
* - Whenever the child frame is attached or navigated. In this case, the script is evaluated in the context of the
* newly attached frame.
*
* The script is evaluated after the document was created but before any of its scripts were run. This is useful to
* amend the JavaScript environment, e.g. to seed `Math.random`.
*
* **Usage**
*
* An example of overriding `Math.random` before the page loads:
*
* ```js
* // preload.js
* Math.random = () => 42;
* ```
*
* ```js
* // In your playwright script, assuming the preload.js file is in same directory
* await page.addInitScript({ path: './preload.js' });
* ```
*
* ```js
* await page.addInitScript(mock => {
* window.mock = mock;
* }, mock);
* ```
*
* **NOTE** The order of evaluation of multiple scripts installed via
* [browserContext.addInitScript(script[, arg, options])](https://playwright.dev/docs/api/class-browsercontext#browser-context-add-init-script)
* and [page.addInitScript(script[, arg, options])](https://playwright.dev/docs/api/class-page#page-add-init-script)
* is not defined.
*
* @param script Script to be evaluated in the page.
* @param arg Optional argument to pass to
* [`script`](https://playwright.dev/docs/api/class-page#page-add-init-script-option-script) (only supported when
* passing a function).
* @param options
*/
addInitScript<Arg>(
script: PageFunction<Arg, any> | { path?: string; content?: string },
arg?: Arg,
options?: { exposeFunctions?: boolean },
): Promise<Disposable>
/**
* **NOTE** Use locator-based [page.locator(selector[, options])](https://playwright.dev/docs/api/class-page#page-locator)
* instead. Read more about [locators](https://playwright.dev/docs/locators).
*
* The method finds an element matching the specified selector within the page. If no elements match the selector, the
* return value resolves to `null`. To wait for an element on the page, use
* [locator.waitFor([options])](https://playwright.dev/docs/api/class-locator#locator-wait-for).
* @param selector A selector to query for.
* @param options
*/
$<K extends keyof HTMLElementTagNameMap>(
selector: K,
options?: { strict: boolean },
): Promise<ElementHandleForTag<K> | null>
/**
* **NOTE** Use locator-based [page.locator(selector[, options])](https://playwright.dev/docs/api/class-page#page-locator)
* instead. Read more about [locators](https://playwright.dev/docs/locators).
*
* The method finds an element matching the specified selector within the page. If no elements match the selector, the
* return value resolves to `null`. To wait for an element on the page, use
* [locator.waitFor([options])](https://playwright.dev/docs/api/class-locator#locator-wait-for).
* @param selector A selector to query for.
* @param options
*/
$(
selector: string,
options?: { strict: boolean },
): Promise<ElementHandle<SVGElement | HTMLElement> | null>
/**
* **NOTE** Use locator-based [page.locator(selector[, options])](https://playwright.dev/docs/api/class-page#page-locator)
* instead. Read more about [locators](https://playwright.dev/docs/locators).
*
* The method finds all elements matching the specified selector within the page. If no elements match the selector,
* the return value resolves to `[]`.
* @param selector A selector to query for.
*/
$$<K extends keyof HTMLElementTagNameMap>(selector: K): Promise<ElementHandleForTag<K>[]>
/**
* **NOTE** Use locator-based [page.locator(selector[, options])](https://playwright.dev/docs/api/class-page#page-locator)
* instead. Read more about [locators](https://playwright.dev/docs/locators).
*
* The method finds all elements matching the specified selector within the page. If no elements match the selector,
* the return value resolves to `[]`.
* @param selector A selector to query for.
*/
$$(selector: string): Promise<ElementHandle<SVGElement | HTMLElement>[]>
/**
* **NOTE** This method does not wait for the element to pass actionability checks and therefore can lead to the flaky tests.
* Use
* [locator.evaluate(pageFunction[, arg, options])](https://playwright.dev/docs/api/class-locator#locator-evaluate),
* other [Locator](https://playwright.dev/docs/api/class-locator) helper methods or web-first assertions instead.
*
* The method finds an element matching the specified selector within the page and passes it as a first argument to
* [`pageFunction`](https://playwright.dev/docs/api/class-page#page-eval-on-selector-option-expression). If no
* elements match the selector, the method throws an error. Returns the value of
* [`pageFunction`](https://playwright.dev/docs/api/class-page#page-eval-on-selector-option-expression).
*
* If [`pageFunction`](https://playwright.dev/docs/api/class-page#page-eval-on-selector-option-expression) returns a
* [Promise], then
* [page.$eval(selector, pageFunction[, arg, options])](https://playwright.dev/docs/api/class-page#page-eval-on-selector)
* would wait for the promise to resolve and return its value.
*
* **Usage**
*
* ```js
* const searchValue = await page.$eval('#search', el => el.value);
* const preloadHref = await page.$eval('link[rel=preload]', el => el.href);
* const html = await page.$eval('.main-container', (e, suffix) => e.outerHTML + suffix, 'hello');
* // In TypeScript, this example requires an explicit type annotation (HTMLLinkElement) on el:
* const preloadHrefTS = await page.$eval('link[rel=preload]', (el: HTMLLinkElement) => el.href);
* ```
*
* @param selector A selector to query for.
* @param pageFunction Function to be evaluated in the page context.
* @param arg Optional argument to pass to
* [`pageFunction`](https://playwright.dev/docs/api/class-page#page-eval-on-selector-option-expression).
* @param options
*/
$eval<K extends keyof HTMLElementTagNameMap, R, Arg>(
selector: K,
pageFunction: PageFunctionOn<HTMLElementTagNameMap[K], Arg, R>,
arg: Arg,
): Promise<R>
/**
* **NOTE** This method does not wait for the element to pass actionability checks and therefore can lead to the flaky tests.
* Use
* [locator.evaluate(pageFunction[, arg, options])](https://playwright.dev/docs/api/class-locator#locator-evaluate),
* other [Locator](https://playwright.dev/docs/api/class-locator) helper methods or web-first assertions instead.
*
* The method finds an element matching the specified selector within the page and passes it as a first argument to
* [`pageFunction`](https://playwright.dev/docs/api/class-page#page-eval-on-selector-option-expression). If no
* elements match the selector, the method throws an error. Returns the value of
* [`pageFunction`](https://playwright.dev/docs/api/class-page#page-eval-on-selector-option-expression).
*
* If [`pageFunction`](https://playwright.dev/docs/api/class-page#page-eval-on-selector-option-expression) returns a
* [Promise], then
* [page.$eval(selector, pageFunction[, arg, options])](https://playwright.dev/docs/api/class-page#page-eval-on-selector)
* would wait for the promise to resolve and return its value.
*
* **Usage**
*
* ```js
* const searchValue = await page.$eval('#search', el => el.value);
* const preloadHref = await page.$eval('link[rel=preload]', el => el.href);
* const html = await page.$eval('.main-container', (e, suffix) => e.outerHTML + suffix, 'hello');
* // In TypeScript, this example requires an explicit type annotation (HTMLLinkElement) on el:
* const preloadHrefTS = await page.$eval('link[rel=preload]', (el: HTMLLinkElement) => el.href);
* ```
*
* @param selector A selector to query for.
* @param pageFunction Function to be evaluated in the page context.
* @param arg Optional argument to pass to
* [`pageFunction`](https://playwright.dev/docs/api/class-page#page-eval-on-selector-option-expression).
* @param options
*/
$eval<R, Arg, E extends SVGElement | HTMLElement = SVGElement | HTMLElement>(
selector: string,
pageFunction: PageFunctionOn<E, Arg, R>,
arg: Arg,
): Promise<R>
/**
* **NOTE** This method does not wait for the element to pass actionability checks and therefore can lead to the flaky tests.
* Use
* [locator.evaluate(pageFunction[, arg, options])](https://playwright.dev/docs/api/class-locator#locator-evaluate),
* other [Locator](https://playwright.dev/docs/api/class-locator) helper methods or web-first assertions instead.
*
* The method finds an element matching the specified selector within the page and passes it as a first argument to
* [`pageFunction`](https://playwright.dev/docs/api/class-page#page-eval-on-selector-option-expression). If no
* elements match the selector, the method throws an error. Returns the value of
* [`pageFunction`](https://playwright.dev/docs/api/class-page#page-eval-on-selector-option-expression).
*
* If [`pageFunction`](https://playwright.dev/docs/api/class-page#page-eval-on-selector-option-expression) returns a
* [Promise], then
* [page.$eval(selector, pageFunction[, arg, options])](https://playwright.dev/docs/api/class-page#page-eval-on-selector)
* would wait for the promise to resolve and return its value.
*
* **Usage**
*
* ```js
* const searchValue = await page.$eval('#search', el => el.value);
* const preloadHref = await page.$eval('link[rel=preload]', el => el.href);
* const html = await page.$eval('.main-container', (e, suffix) => e.outerHTML + suffix, 'hello');
* // In TypeScript, this example requires an explicit type annotation (HTMLLinkElement) on el:
* const preloadHrefTS = await page.$eval('link[rel=preload]', (el: HTMLLinkElement) => el.href);
* ```
*
* @param selector A selector to query for.
* @param pageFunction Function to be evaluated in the page context.
* @param arg Optional argument to pass to
* [`pageFunction`](https://playwright.dev/docs/api/class-page#page-eval-on-selector-option-expression).
* @param options
*/
$eval<K extends keyof HTMLElementTagNameMap, R>(
selector: K,
pageFunction: PageFunctionOn<HTMLElementTagNameMap[K], void, R>,
arg?: any,
): Promise<R>
/**
* **NOTE** This method does not wait for the element to pass actionability checks and therefore can lead to the flaky tests.
* Use
* [locator.evaluate(pageFunction[, arg, options])](https://playwright.dev/docs/api/class-locator#locator-evaluate),
* other [Locator](https://playwright.dev/docs/api/class-locator) helper methods or web-first assertions instead.
*
* The method finds an element matching the specified selector within the page and passes it as a first argument to
* [`pageFunction`](https://playwright.dev/docs/api/class-page#page-eval-on-selector-option-expression). If no
* elements match the selector, the method throws an error. Returns the value of
* [`pageFunction`](https://playwright.dev/docs/api/class-page#page-eval-on-selector-option-expression).
*
* If [`pageFunction`](https://playwright.dev/docs/api/class-page#page-eval-on-selector-option-expression) returns a
* [Promise], then
* [page.$eval(selector, pageFunction[, arg, options])](https://playwright.dev/docs/api/class-page#page-eval-on-selector)
* would wait for the promise to resolve and return its value.
*
* **Usage**
*
* ```js
* const searchValue = await page.$eval('#search', el => el.value);
* const preloadHref = await page.$eval('link[rel=preload]', el => el.href);
* const html = await page.$eval('.main-container', (e, suffix) => e.outerHTML + suffix, 'hello');
* // In TypeScript, this example requires an explicit type annotation (HTMLLinkElement) on el:
* const preloadHrefTS = await page.$eval('link[rel=preload]', (el: HTMLLinkElement) => el.href);
* ```
*
* @param selector A selector to query for.
* @param pageFunction Function to be evaluated in the page context.
* @param arg Optional argument to pass to
* [`pageFunction`](https://playwright.dev/docs/api/class-page#page-eval-on-selector-option-expression).
* @param options
*/
$eval<R, E extends SVGElement | HTMLElement = SVGElement | HTMLElement>(
selector: string,
pageFunction: PageFunctionOn<E, void, R>,
arg?: any,
): Promise<R>
/**
* **NOTE** In most cases,
* [locator.evaluateAll(pageFunction[, arg])](https://playwright.dev/docs/api/class-locator#locator-evaluate-all),
* other [Locator](https://playwright.dev/docs/api/class-locator) helper methods and web-first assertions do a better
* job.
*
* The method finds all elements matching the specified selector within the page and passes an array of matched
* elements as a first argument to
* [`pageFunction`](https://playwright.dev/docs/api/class-page#page-eval-on-selector-all-option-expression). Returns
* the result of
* [`pageFunction`](https://playwright.dev/docs/api/class-page#page-eval-on-selector-all-option-expression)
* invocation.
*
* If [`pageFunction`](https://playwright.dev/docs/api/class-page#page-eval-on-selector-all-option-expression) returns
* a [Promise], then
* [page.$$eval(selector, pageFunction[, arg])](https://playwright.dev/docs/api/class-page#page-eval-on-selector-all)
* would wait for the promise to resolve and return its value.
*
* **Usage**
*
* ```js
* const divCounts = await page.$$eval('div', (divs, min) => divs.length >= min, 10);
* ```
*
* @param selector A selector to query for.
* @param pageFunction Function to be evaluated in the page context.
* @param arg Optional argument to pass to
* [`pageFunction`](https://playwright.dev/docs/api/class-page#page-eval-on-selector-all-option-expression).
*/
$$eval<K extends keyof HTMLElementTagNameMap, R, Arg>(
selector: K,
pageFunction: PageFunctionOn<HTMLElementTagNameMap[K][], Arg, R>,
arg: Arg,
): Promise<R>
/**
* **NOTE** In most cases,
* [locator.evaluateAll(pageFunction[, arg])](https://playwright.dev/docs/api/class-locator#locator-evaluate-all),
* other [Locator](https://playwright.dev/docs/api/class-locator) helper methods and web-first assertions do a better
* job.
*
* The method finds all elements matching the specified selector within the page and passes an array of matched
* elements as a first argument to
* [`pageFunction`](https://playwright.dev/docs/api/class-page#page-eval-on-selector-all-option-expression). Returns
* the result of
* [`pageFunction`](https://playwright.dev/docs/api/class-page#page-eval-on-selector-all-option-expression)
* invocation.
*
* If [`pageFunction`](https://playwright.dev/docs/api/class-page#page-eval-on-selector-all-option-expression) returns
* a [Promise], then
* [page.$$eval(selector, pageFunction[, arg])](https://playwright.dev/docs/api/class-page#page-eval-on-selector-all)
* would wait for the promise to resolve and return its value.
*
* **Usage**
*
* ```js
* const divCounts = await page.$$eval('div', (divs, min) => divs.length >= min, 10);
* ```
*
* @param selector A selector to query for.
* @param pageFunction Function to be evaluated in the page context.
* @param arg Optional argument to pass to
* [`pageFunction`](https://playwright.dev/docs/api/class-page#page-eval-on-selector-all-option-expression).
*/
$$eval<R, Arg, E extends SVGElement | HTMLElement = SVGElement | HTMLElement>(
selector: string,
pageFunction: PageFunctionOn<E[], Arg, R>,
arg: Arg,
): Promise<R>
/**
* **NOTE** In most cases,
* [locator.evaluateAll(pageFunction[, arg])](https://playwright.dev/docs/api/class-locator#locator-evaluate-all),
* other [Locator](https://playwright.dev/docs/api/class-locator) helper methods and web-first assertions do a better
* job.
*
* The method finds all elements matching the specified selector within the page and passes an array of matched
* elements as a first argument to
* [`pageFunction`](https://playwright.dev/docs/api/class-page#page-eval-on-selector-all-option-expression). Returns
* the result of
* [`pageFunction`](https://playwright.dev/docs/api/class-page#page-eval-on-selector-all-option-expression)
* invocation.
*
* If [`pageFunction`](https://playwright.dev/docs/api/class-page#page-eval-on-selector-all-option-expression) returns
* a [Promise], then
* [page.$$eval(selector, pageFunction[, arg])](https://playwright.dev/docs/api/class-page#page-eval-on-selector-all)
* would wait for the promise to resolve and return its value.
*
* **Usage**
*
* ```js
* const divCounts = await page.$$eval('div', (divs, min) => divs.length >= min, 10);
* ```
*
* @param selector A selector to query for.
* @param pageFunction Function to be evaluated in the page context.
* @param arg Optional argument to pass to
* [`pageFunction`](https://playwright.dev/docs/api/class-page#page-eval-on-selector-all-option-expression).
*/
$$eval<K extends keyof HTMLElementTagNameMap, R>(
selector: K,
pageFunction: PageFunctionOn<HTMLElementTagNameMap[K][], void, R>,
arg?: any,
): Promise<R>
/**
* **NOTE** In most cases,
* [locator.evaluateAll(pageFunction[, arg])](https://playwright.dev/docs/api/class-locator#locator-evaluate-all),
* other [Locator](https://playwright.dev/docs/api/class-locator) helper methods and web-first assertions do a better
* job.
*
* The method finds all elements matching the specified selector within the page and passes an array of matched
* elements as a first argument to
* [`pageFunction`](https://playwright.dev/docs/api/class-page#page-eval-on-selector-all-option-expression). Returns
* the result of
* [`pageFunction`](https://playwright.dev/docs/api/class-page#page-eval-on-selector-all-option-expression)
* invocation.
*
* If [`pageFunction`](https://playwright.dev/docs/api/class-page#page-eval-on-selector-all-option-expression) returns
* a [Promise], then
* [page.$$eval(selector, pageFunction[, arg])](https://playwright.dev/docs/api/class-page#page-eval-on-selector-all)
* would wait for the promise to resolve and return its value.
*
* **Usage**
*
* ```js
* const divCounts = await page.$$eval('div', (divs, min) => divs.length >= min, 10);
* ```
*
* @param selector A selector to query for.
* @param pageFunction Function to be evaluated in the page context.
* @param arg Optional argument to pass to
* [`pageFunction`](https://playwright.dev/docs/api/class-page#page-eval-on-selector-all-option-expression).
*/
$$eval<R, E extends SVGElement | HTMLElement = SVGElement | HTMLElement>(
selector: string,
pageFunction: PageFunctionOn<E[], void, R>,
arg?: any,
): Promise<R>
/**
* Returns when the
* [`pageFunction`](https://playwright.dev/docs/api/class-page#page-wait-for-function-option-expression) returns a
* truthy value. It resolves to a JSHandle of the truthy value.
*
* **Usage**
*
* The
* [page.waitForFunction(pageFunction[, arg, options])](https://playwright.dev/docs/api/class-page#page-wait-for-function)
* can be used to observe viewport size change:
*
* ```js
* const { webkit } = require('playwright'); // Or 'chromium' or 'firefox'.
*
* (async () => {
* const browser = await webkit.launch();
* const page = await browser.newPage();
* const watchDog = page.waitForFunction(() => window.innerWidth < 100);
* await page.setViewportSize({ width: 50, height: 50 });
* await watchDog;
* await browser.close();
* })();
* ```
*
* To pass an argument to the predicate of
* [page.waitForFunction(pageFunction[, arg, options])](https://playwright.dev/docs/api/class-page#page-wait-for-function)
* function:
*
* ```js
* const selector = '.foo';
* await page.waitForFunction(selector => !!document.querySelector(selector), selector);
* ```
*
* @param pageFunction Function to be evaluated in the page context.
* @param arg Optional argument to pass to
* [`pageFunction`](https://playwright.dev/docs/api/class-page#page-wait-for-function-option-expression).
* @param options
*/
waitForFunction<R, Arg>(
pageFunction: PageFunction<Arg, R>,
arg: Arg,
options?: PageWaitForFunctionOptions,
): Promise<SmartHandle<R>>
/**
* Returns when the
* [`pageFunction`](https://playwright.dev/docs/api/class-page#page-wait-for-function-option-expression) returns a
* truthy value. It resolves to a JSHandle of the truthy value.
*
* **Usage**
*
* The
* [page.waitForFunction(pageFunction[, arg, options])](https://playwright.dev/docs/api/class-page#page-wait-for-function)
* can be used to observe viewport size change:
*
* ```js
* const { webkit } = require('playwright'); // Or 'chromium' or 'firefox'.
*
* (async () => {
* const browser = await webkit.launch();
* const page = await browser.newPage();
* const watchDog = page.waitForFunction(() => window.innerWidth < 100);
* await page.setViewportSize({ width: 50, height: 50 });
* await watchDog;
* await browser.close();
* })();
* ```
*
* To pass an argument to the predicate of
* [page.waitForFunction(pageFunction[, arg, options])](https://playwright.dev/docs/api/class-page#page-wait-for-function)
* function:
*
* ```js
* const selector = '.foo';
* await page.waitForFunction(selector => !!document.querySelector(selector), selector);
* ```
*
* @param pageFunction Function to be evaluated in the page context.
* @param arg Optional argument to pass to
* [`pageFunction`](https://playwright.dev/docs/api/class-page#page-wait-for-function-option-expression).
* @param options
*/
waitForFunction<R>(
pageFunction: PageFunction<void, R>,
arg?: any,
options?: PageWaitForFunctionOptions,
): Promise<SmartHandle<R>>
/**
* **NOTE** Use web assertions that assert visibility or a locator-based
* [locator.waitFor([options])](https://playwright.dev/docs/api/class-locator#locator-wait-for) instead. Read more
* about [locators](https://playwright.dev/docs/locators).
*
* Returns when element specified by selector satisfies
* [`state`](https://playwright.dev/docs/api/class-page#page-wait-for-selector-option-state) option. Returns `null` if
* waiting for `hidden` or `detached`.
*
* **NOTE** Playwright automatically waits for element to be ready before performing an action. Using
* [Locator](https://playwright.dev/docs/api/class-locator) objects and web-first assertions makes the code
* wait-for-selector-free.
*
* Wait for the [`selector`](https://playwright.dev/docs/api/class-page#page-wait-for-selector-option-selector) to
* satisfy [`state`](https://playwright.dev/docs/api/class-page#page-wait-for-selector-option-state) option (either
* appear/disappear from dom, or become visible/hidden). If at the moment of calling the method
* [`selector`](https://playwright.dev/docs/api/class-page#page-wait-for-selector-option-selector) already satisfies
* the condition, the method will return immediately. If the selector doesn't satisfy the condition for the
* [`timeout`](https://playwright.dev/docs/api/class-page#page-wait-for-selector-option-timeout) milliseconds, the
* function will throw.
*
* **Usage**
*
* This method works across navigations:
*
* ```js
* const { chromium } = require('playwright'); // Or 'firefox' or 'webkit'.
*
* (async () => {
* const browser = await chromium.launch();
* const page = await browser.newPage();
* for (const currentURL of ['https://google.com', 'https://bbc.com']) {
* await page.goto(currentURL);
* const element = await page.waitForSelector('img');
* console.log('Loaded image: ' + await element.getAttribute('src'));
* }
* await browser.close();
* })();
* ```
*
* @param selector A selector to query for.
* @param options
*/
waitForSelector<K extends keyof HTMLElementTagNameMap>(
selector: K,
options?: PageWaitForSelectorOptionsNotHidden,
): Promise<ElementHandleForTag<K>>
/**
* **NOTE** Use web assertions that assert visibility or a locator-based
* [locator.waitFor([options])](https://playwright.dev/docs/api/class-locator#locator-wait-for) instead. Read more
* about [locators](https://playwright.dev/docs/locators).
*
* Returns when element specified by selector satisfies
* [`state`](https://playwright.dev/docs/api/class-page#page-wait-for-selector-option-state) option. Returns `null` if
* waiting for `hidden` or `detached`.
*
* **NOTE** Playwright automatically waits for element to be ready before performing an action. Using
* [Locator](https://playwright.dev/docs/api/class-locator) objects and web-first assertions makes the code
* wait-for-selector-free.
*
* Wait for the [`selector`](https://playwright.dev/docs/api/class-page#page-wait-for-selector-option-selector) to
* satisfy [`state`](https://playwright.dev/docs/api/class-page#page-wait-for-selector-option-state) option (either
* appear/disappear from dom, or become visible/hidden). If at the moment of calling the method
* [`selector`](https://playwright.dev/docs/api/class-page#page-wait-for-selector-option-selector) already satisfies
* the condition, the method will return immediately. If the selector doesn't satisfy the condition for the
* [`timeout`](https://playwright.dev/docs/api/class-page#page-wait-for-selector-option-timeout) milliseconds, the
* function will throw.
*
* **Usage**
*
* This method works across navigations:
*
* ```js
* const { chromium } = require('playwright'); // Or 'firefox' or 'webkit'.
*
* (async () => {
* const browser = await chromium.launch();
* const page = await browser.newPage();
* for (const currentURL of ['https://google.com', 'https://bbc.com']) {
* await page.goto(currentURL);
* const element = await page.waitForSelector('img');
* console.log('Loaded image: ' + await element.getAttribute('src'));
* }
* await browser.close();
* })();
* ```
*
* @param selector A selector to query for.
* @param options
*/
waitForSelector(
selector: string,
options?: PageWaitForSelectorOptionsNotHidden,
): Promise<ElementHandle<SVGElement | HTMLElement>>
/**
* **NOTE** Use web assertions that assert visibility or a locator-based
* [locator.waitFor([options])](https://playwright.dev/docs/api/class-locator#locator-wait-for) instead. Read more
* about [locators](https://playwright.dev/docs/locators).
*
* Returns when element specified by selector satisfies
* [`state`](https://playwright.dev/docs/api/class-page#page-wait-for-selector-option-state) option. Returns `null` if
* waiting for `hidden` or `detached`.
*
* **NOTE** Playwright automatically waits for element to be ready before performing an action. Using
* [Locator](https://playwright.dev/docs/api/class-locator) objects and web-first assertions makes the code
* wait-for-selector-free.
*
* Wait for the [`selector`](https://playwright.dev/docs/api/class-page#page-wait-for-selector-option-selector) to
* satisfy [`state`](https://playwright.dev/docs/api/class-page#page-wait-for-selector-option-state) option (either
* appear/disappear from dom, or become visible/hidden). If at the moment of calling the method
* [`selector`](https://playwright.dev/docs/api/class-page#page-wait-for-selector-option-selector) already satisfies
* the condition, the method will return immediately. If the selector doesn't satisfy the condition for the
* [`timeout`](https://playwright.dev/docs/api/class-page#page-wait-for-selector-option-timeout) milliseconds, the
* function will throw.
*
* **Usage**
*
* This method works across navigations:
*
* ```js
* const { chromium } = require('playwright'); // Or 'firefox' or 'webkit'.
*
* (async () => {
* const browser = await chromium.launch();
* const page = await browser.newPage();
* for (const currentURL of ['https://google.com', 'https://bbc.com']) {
* await page.goto(currentURL);
* const element = await page.waitForSelector('img');
* console.log('Loaded image: ' + await element.getAttribute('src'));
* }
* await browser.close();
* })();
* ```
*
* @param selector A selector to query for.
* @param options
*/
waitForSelector<K extends keyof HTMLElementTagNameMap>(
selector: K,
options: PageWaitForSelectorOptions,
): Promise<ElementHandleForTag<K> | null>
/**
* **NOTE** Use web assertions that assert visibility or a locator-based
* [locator.waitFor([options])](https://playwright.dev/docs/api/class-locator#locator-wait-for) instead. Read more
* about [locators](https://playwright.dev/docs/locators).
*
* Returns when element specified by selector satisfies
* [`state`](https://playwright.dev/docs/api/class-page#page-wait-for-selector-option-state) option. Returns `null` if
* waiting for `hidden` or `detached`.
*
* **NOTE** Playwright automatically waits for element to be ready before performing an action. Using
* [Locator](https://playwright.dev/docs/api/class-locator) objects and web-first assertions makes the code
* wait-for-selector-free.
*
* Wait for the [`selector`](https://playwright.dev/docs/api/class-page#page-wait-for-selector-option-selector) to
* satisfy [`state`](https://playwright.dev/docs/api/class-page#page-wait-for-selector-option-state) option (either
* appear/disappear from dom, or become visible/hidden). If at the moment of calling the method
* [`selector`](https://playwright.dev/docs/api/class-page#page-wait-for-selector-option-selector) already satisfies
* the condition, the method will return immediately. If the selector doesn't satisfy the condition for the
* [`timeout`](https://playwright.dev/docs/api/class-page#page-wait-for-selector-option-timeout) milliseconds, the
* function will throw.
*
* **Usage**
*
* This method works across navigations:
*
* ```js
* const { chromium } = require('playwright'); // Or 'firefox' or 'webkit'.
*
* (async () => {
* const browser = await chromium.launch();
* const page = await browser.newPage();
* for (const currentURL of ['https://google.com', 'https://bbc.com']) {
* await page.goto(currentURL);
* const element = await page.waitForSelector('img');
* console.log('Loaded image: ' + await element.getAttribute('src'));
* }
* await browser.close();
* })();
* ```
*
* @param selector A selector to query for.
* @param options
*/
waitForSelector(
selector: string,
options: PageWaitForSelectorOptions,
): Promise<null | ElementHandle<SVGElement | HTMLElement>>
/**
* The method adds a function called
* [`name`](https://playwright.dev/docs/api/class-page#page-expose-binding-option-name) on the `window` object of
* every frame in this page. When called, the function executes
* [`callback`](https://playwright.dev/docs/api/class-page#page-expose-binding-option-callback) and returns a
* [Promise] which resolves to the return value of
* [`callback`](https://playwright.dev/docs/api/class-page#page-expose-binding-option-callback). If the
* [`callback`](https://playwright.dev/docs/api/class-page#page-expose-binding-option-callback) returns a [Promise],
* it will be awaited.
*
* The first argument of the
* [`callback`](https://playwright.dev/docs/api/class-page#page-expose-binding-option-callback) function contains
* information about the caller: `{ browserContext: BrowserContext, page: Page, frame: Frame }`.
*
* See
* [browserContext.exposeBinding(name, callback)](https://playwright.dev/docs/api/class-browsercontext#browser-context-expose-binding)
* for the context-wide version.
*
* **NOTE** Functions installed via
* [page.exposeBinding(name, callback)](https://playwright.dev/docs/api/class-page#page-expose-binding) survive
* navigations.
*
* **Usage**
*
* An example of exposing page URL to all frames in a page:
*
* ```js
* const { webkit } = require('playwright'); // Or 'chromium' or 'firefox'.
*
* (async () => {
* const browser = await webkit.launch({ headless: false });
* const context = await browser.newContext();
* const page = await context.newPage();
* await page.exposeBinding('pageURL', ({ page }) => page.url());
* await page.setContent(`
* <script>
* async function onClick() {
* document.querySelector('div').textContent = await window.pageURL();
* }
* </script>
* <button onclick="onClick()">Click me</button>
* <div></div>
* `);
* await page.click('button');
* })();
* ```
*
* @param name Name of the function on the window object.
* @param callback Callback function that will be called in the Playwright's context.
*/
exposeBinding(
name: string,
playwrightBinding: (source: BindingSource, ...args: any[]) => any,
): Promise<Disposable>
/**
* Removes all the listeners of the given type (or all registered listeners if no type given). Allows to wait for
* async listeners to complete or to ignore subsequent errors from these listeners.
*
* **Usage**
*
* ```js
* page.on('request', async request => {
* const response = await request.response();
* const body = await response.body();
* console.log(body.byteLength);
* });
* await page.goto('https://playwright.dev', { waitUntil: 'domcontentloaded' });
* // Waits for all the reported 'request' events to resolve.
* await page.removeAllListeners('request', { behavior: 'wait' });
* ```
*
* @param type
* @param options
*/
removeAllListeners(type?: string): this
/**
* Removes all the listeners of the given type (or all registered listeners if no type given). Allows to wait for
* async listeners to complete or to ignore subsequent errors from these listeners.
*
* **Usage**
*
* ```js
* page.on('request', async request => {
* const response = await request.response();
* const body = await response.body();
* console.log(body.byteLength);
* });
* await page.goto('https://playwright.dev', { waitUntil: 'domcontentloaded' });
* // Waits for all the reported 'request' events to resolve.
* await page.removeAllListeners('request', { behavior: 'wait' });
* ```
*
* @param type
* @param options
*/
removeAllListeners(
type: string | undefined,
options: {
/**
* Specifies whether to wait for already running listeners and what to do if they throw errors:
* - `'default'` - do not wait for current listener calls (if any) to finish, if the listener throws, it may result in unhandled error
* - `'wait'` - wait for current listener calls (if any) to finish
* - `'ignoreErrors'` - do not wait for current listener calls (if any) to finish, all errors thrown by the listeners after removal are silently caught
*/
behavior?: 'wait' | 'ignoreErrors' | 'default'
},
): Promise<void>
/**
* Emitted when the page closes.
*/
on(event: 'close', listener: (page: Page) => any): this
/**
* Emitted when JavaScript within the page calls one of console API methods, e.g. `console.log` or `console.dir`.
*
* The arguments passed into `console.log` are available on the
* [ConsoleMessage](https://playwright.dev/docs/api/class-consolemessage) event handler argument.
*
* **Usage**
*
* ```js
* page.on('console', async msg => {
* const values = [];
* for (const arg of msg.args())
* values.push(await arg.jsonValue());
* console.log(...values);
* });
* await page.evaluate(() => console.log('hello', 5, { foo: 'bar' }));
* ```
*
*/
on(event: 'console', listener: (consoleMessage: ConsoleMessage) => any): this
/**
* Emitted when the page crashes. Browser pages might crash if they try to allocate too much memory. When the page
* crashes, ongoing and subsequent operations will throw.
*
* The most common way to deal with crashes is to catch an exception:
*
* ```js
* try {
* // Crash might happen during a click.
* await page.click('button');
* // Or while waiting for an event.
* await page.waitForEvent('popup');
* } catch (e) {
* // When the page crashes, exception message contains 'crash'.
* }
* ```
*
*/
on(event: 'crash', listener: (page: Page) => any): this
/**
* Emitted when a JavaScript dialog appears, such as `alert`, `prompt`, `confirm` or `beforeunload`. Listener **must**
* either [dialog.accept([promptText])](https://playwright.dev/docs/api/class-dialog#dialog-accept) or
* [dialog.dismiss()](https://playwright.dev/docs/api/class-dialog#dialog-dismiss) the dialog - otherwise the page
* will [freeze](https://developer.mozilla.org/en-US/docs/Web/JavaScript/EventLoop#never_blocking) waiting for the
* dialog, and actions like click will never finish.
*
* **Usage**
*
* ```js
* page.on('dialog', dialog => dialog.accept());
* ```
*
* **NOTE** When no [page.on('dialog')](https://playwright.dev/docs/api/class-page#page-event-dialog) or
* [browserContext.on('dialog')](https://playwright.dev/docs/api/class-browsercontext#browser-context-event-dialog)
* listeners are present, all dialogs are automatically dismissed.
*
*/
on(event: 'dialog', listener: (dialog: Dialog) => any): this
/**
* Emitted when a JavaScript dialog has been closed, either by
* [dialog.accept([promptText])](https://playwright.dev/docs/api/class-dialog#dialog-accept), by
* [dialog.dismiss()](https://playwright.dev/docs/api/class-dialog#dialog-dismiss), or manually by the user in the
* headed browser.
*/
on(event: 'dialogclosed', listener: (dialog: Dialog) => any): this
/**
* Emitted when the JavaScript
* [`DOMContentLoaded`](https://developer.mozilla.org/en-US/docs/Web/Events/DOMContentLoaded) event is dispatched.
*/
on(event: 'domcontentloaded', listener: (page: Page) => any): this
/**
* Emitted when attachment download started. User can access basic file operations on downloaded content via the
* passed [Download](https://playwright.dev/docs/api/class-download) instance.
*/
on(event: 'download', listener: (download: Download) => any): this
/**
* Emitted when a file chooser is supposed to appear, such as after clicking the `<input type=file>`. Playwright can
* respond to it via setting the input files using
* [fileChooser.setFiles(files[, options])](https://playwright.dev/docs/api/class-filechooser#file-chooser-set-files)
* that can be uploaded after that.
*
* ```js
* page.on('filechooser', async fileChooser => {
* await fileChooser.setFiles(path.join(__dirname, '/tmp/myfile.pdf'));
* });
* ```
*
*/
on(event: 'filechooser', listener: (fileChooser: FileChooser) => any): this
/**
* Emitted when a frame is attached.
*/
on(event: 'frameattached', listener: (frame: Frame) => any): this
/**
* Emitted when a frame is detached.
*/
on(event: 'framedetached', listener: (frame: Frame) => any): this
/**
* Emitted when a frame is navigated to a new url.
*/
on(event: 'framenavigated', listener: (frame: Frame) => any): this
/**
* Emitted when the JavaScript [`load`](https://developer.mozilla.org/en-US/docs/Web/Events/load) event is dispatched.
*/
on(event: 'load', listener: (page: Page) => any): this
/**
* Emitted when an uncaught exception happens within the page.
*
* ```js
* // Log all uncaught errors to the terminal
* page.on('pageerror', exception => {
* console.log(`Uncaught exception: "${exception}"`);
* });
*
* // Navigate to a page with an exception.
* await page.goto('data:text/html,<script>throw new Error("Test")</script>');
* ```
*
*/
on(event: 'pageerror', listener: (error: Error) => any): this
/**
* Emitted when the page opens a new tab or window. This event is emitted in addition to the
* [browserContext.on('page')](https://playwright.dev/docs/api/class-browsercontext#browser-context-event-page), but
* only for popups relevant to this page.
*
* The earliest moment that page is available is when it has navigated to the initial url. For example, when opening a
* popup with `window.open('http://example.com')`, this event will fire when the network request to
* "http://example.com" is done and its response has started loading in the popup. If you would like to route/listen
* to this network request, use
* [browserContext.route(url, handler[, options])](https://playwright.dev/docs/api/class-browsercontext#browser-context-route)
* and
* [browserContext.on('request')](https://playwright.dev/docs/api/class-browsercontext#browser-context-event-request)
* respectively instead of similar methods on the [Page](https://playwright.dev/docs/api/class-page).
*
* ```js
* // Start waiting for popup before clicking. Note no await.
* const popupPromise = page.waitForEvent('popup');
* await page.getByText('open the popup').click();
* const popup = await popupPromise;
* console.log(await popup.evaluate('location.href'));
* ```
*
* **NOTE** Use
* [page.waitForLoadState([state, options])](https://playwright.dev/docs/api/class-page#page-wait-for-load-state) to
* wait until the page gets to a particular state (you should not need it in most cases).
*
*/
on(event: 'popup', listener: (page: Page) => any): this
/**
* Emitted when a page issues a request. The [request] object is read-only. In order to intercept and mutate requests,
* see [page.route(url, handler[, options])](https://playwright.dev/docs/api/class-page#page-route) or
* [browserContext.route(url, handler[, options])](https://playwright.dev/docs/api/class-browsercontext#browser-context-route).
*/
on(event: 'request', listener: (request: Request) => any): this
/**
* Emitted when a request fails, for example by timing out.
*
* ```js
* page.on('requestfailed', request => {
* console.log(request.url() + ' ' + request.failure().errorText);
* });
* ```
*
* **NOTE** HTTP Error responses, such as 404 or 503, are still successful responses from HTTP standpoint, so request
* will complete with
* [page.on('requestfinished')](https://playwright.dev/docs/api/class-page#page-event-request-finished) event and not
* with [page.on('requestfailed')](https://playwright.dev/docs/api/class-page#page-event-request-failed). A request
* will only be considered failed when the client cannot get an HTTP response from the server, e.g. due to network
* error net::ERR_FAILED.
*
*/
on(event: 'requestfailed', listener: (request: Request) => any): this
/**
* Emitted when a request finishes successfully after downloading the response body. For a successful response, the
* sequence of events is `request`, `response` and `requestfinished`.
*/
on(event: 'requestfinished', listener: (request: Request) => any): this
/**
* Emitted when [response] status and headers are received for a request. For a successful response, the sequence of
* events is `request`, `response` and `requestfinished`.
*/
on(event: 'response', listener: (response: Response) => any): this
/**
* Emitted when [WebSocket](https://playwright.dev/docs/api/class-websocket) request is sent.
*/
on(event: 'websocket', listener: (webSocket: WebSocket) => any): this
/**
* Emitted when a dedicated [WebWorker](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API) is spawned
* by the page.
*/
on(event: 'worker', listener: (worker: Worker) => any): this
/**
* Adds an event listener that will be automatically removed after it is triggered once. See `addListener` for more information about this event.
*/
once(event: 'close', listener: (page: Page) => any): this
/**
* Adds an event listener that will be automatically removed after it is triggered once. See `addListener` for more information about this event.
*/
once(event: 'console', listener: (consoleMessage: ConsoleMessage) => any): this
/**
* Adds an event listener that will be automatically removed after it is triggered once. See `addListener` for more information about this event.
*/
once(event: 'crash', listener: (page: Page) => any): this
/**
* Adds an event listener that will be automatically removed after it is triggered once. See `addListener` for more information about this event.
*/
once(event: 'dialog', listener: (dialog: Dialog) => any): this
/**
* Adds an event listener that will be automatically removed after it is triggered once. See `addListener` for more information about this event.
*/
once(event: 'dialogclosed', listener: (dialog: Dialog) => any): this
/**
* Adds an event listener that will be automatically removed after it is triggered once. See `addListener` for more information about this event.
*/
once(event: 'domcontentloaded', listener: (page: Page) => any): this
/**
* Adds an event listener that will be automatically removed after it is triggered once. See `addListener` for more information about this event.
*/
once(event: 'download', listener: (download: Download) => any): this
/**
* Adds an event listener that will be automatically removed after it is triggered once. See `addListener` for more information about this event.
*/
once(event: 'filechooser', listener: (fileChooser: FileChooser) => any): this
/**
* Adds an event listener that will be automatically removed after it is triggered once. See `addListener` for more information about this event.
*/
once(event: 'frameattached', listener: (frame: Frame) => any): this
/**
* Adds an event listener that will be automatically removed after it is triggered once. See `addListener` for more information about this event.
*/
once(event: 'framedetached', listener: (frame: Frame) => any): this
/**
* Adds an event listener that will be automatically removed after it is triggered once. See `addListener` for more information about this event.
*/
once(event: 'framenavigated', listener: (frame: Frame) => any): this
/**
* Adds an event listener that will be automatically removed after it is triggered once. See `addListener` for more information about this event.
*/
once(event: 'load', listener: (page: Page) => any): this
/**
* Adds an event listener that will be automatically removed after it is triggered once. See `addListener` for more information about this event.
*/
once(event: 'pageerror', listener: (error: Error) => any): this
/**
* Adds an event listener that will be automatically removed after it is triggered once. See `addListener` for more information about this event.
*/
once(event: 'popup', listener: (page: Page) => any): this
/**
* Adds an event listener that will be automatically removed after it is triggered once. See `addListener` for more information about this event.
*/
once(event: 'request', listener: (request: Request) => any): this
/**
* Adds an event listener that will be automatically removed after it is triggered once. See `addListener` for more information about this event.
*/
once(event: 'requestfailed', listener: (request: Request) => any): this
/**
* Adds an event listener that will be automatically removed after it is triggered once. See `addListener` for more information about this event.
*/
once(event: 'requestfinished', listener: (request: Request) => any): this
/**
* Adds an event listener that will be automatically removed after it is triggered once. See `addListener` for more information about this event.
*/
once(event: 'response', listener: (response: Response) => any): this
/**
* Adds an event listener that will be automatically removed after it is triggered once. See `addListener` for more information about this event.
*/
once(event: 'websocket', listener: (webSocket: WebSocket) => any): this
/**
* Adds an event listener that will be automatically removed after it is triggered once. See `addListener` for more information about this event.
*/
once(event: 'worker', listener: (worker: Worker) => any): this
/**
* Emitted when the page closes.
*/
addListener(event: 'close', listener: (page: Page) => any): this
/**
* Emitted when JavaScript within the page calls one of console API methods, e.g. `console.log` or `console.dir`.
*
* The arguments passed into `console.log` are available on the
* [ConsoleMessage](https://playwright.dev/docs/api/class-consolemessage) event handler argument.
*
* **Usage**
*
* ```js
* page.on('console', async msg => {
* const values = [];
* for (const arg of msg.args())
* values.push(await arg.jsonValue());
* console.log(...values);
* });
* await page.evaluate(() => console.log('hello', 5, { foo: 'bar' }));
* ```
*
*/
addListener(event: 'console', listener: (consoleMessage: ConsoleMessage) => any): this
/**
* Emitted when the page crashes. Browser pages might crash if they try to allocate too much memory. When the page
* crashes, ongoing and subsequent operations will throw.
*
* The most common way to deal with crashes is to catch an exception:
*
* ```js
* try {
* // Crash might happen during a click.
* await page.click('button');
* // Or while waiting for an event.
* await page.waitForEvent('popup');
* } catch (e) {
* // When the page crashes, exception message contains 'crash'.
* }
* ```
*
*/
addListener(event: 'crash', listener: (page: Page) => any): this
/**
* Emitted when a JavaScript dialog appears, such as `alert`, `prompt`, `confirm` or `beforeunload`. Listener **must**
* either [dialog.accept([promptText])](https://playwright.dev/docs/api/class-dialog#dialog-accept) or
* [dialog.dismiss()](https://playwright.dev/docs/api/class-dialog#dialog-dismiss) the dialog - otherwise the page
* will [freeze](https://developer.mozilla.org/en-US/docs/Web/JavaScript/EventLoop#never_blocking) waiting for the
* dialog, and actions like click will never finish.
*
* **Usage**
*
* ```js
* page.on('dialog', dialog => dialog.accept());
* ```
*
* **NOTE** When no [page.on('dialog')](https://playwright.dev/docs/api/class-page#page-event-dialog) or
* [browserContext.on('dialog')](https://playwright.dev/docs/api/class-browsercontext#browser-context-event-dialog)
* listeners are present, all dialogs are automatically dismissed.
*
*/
addListener(event: 'dialog', listener: (dialog: Dialog) => any): this
/**
* Emitted when a JavaScript dialog has been closed, either by
* [dialog.accept([promptText])](https://playwright.dev/docs/api/class-dialog#dialog-accept), by
* [dialog.dismiss()](https://playwright.dev/docs/api/class-dialog#dialog-dismiss), or manually by the user in the
* headed browser.
*/
addListener(event: 'dialogclosed', listener: (dialog: Dialog) => any): this
/**
* Emitted when the JavaScript
* [`DOMContentLoaded`](https://developer.mozilla.org/en-US/docs/Web/Events/DOMContentLoaded) event is dispatched.
*/
addListener(event: 'domcontentloaded', listener: (page: Page) => any): this
/**
* Emitted when attachment download started. User can access basic file operations on downloaded content via the
* passed [Download](https://playwright.dev/docs/api/class-download) instance.
*/
addListener(event: 'download', listener: (download: Download) => any): this
/**
* Emitted when a file chooser is supposed to appear, such as after clicking the `<input type=file>`. Playwright can
* respond to it via setting the input files using
* [fileChooser.setFiles(files[, options])](https://playwright.dev/docs/api/class-filechooser#file-chooser-set-files)
* that can be uploaded after that.
*
* ```js
* page.on('filechooser', async fileChooser => {
* await fileChooser.setFiles(path.join(__dirname, '/tmp/myfile.pdf'));
* });
* ```
*
*/
addListener(event: 'filechooser', listener: (fileChooser: FileChooser) => any): this
/**
* Emitted when a frame is attached.
*/
addListener(event: 'frameattached', listener: (frame: Frame) => any): this
/**
* Emitted when a frame is detached.
*/
addListener(event: 'framedetached', listener: (frame: Frame) => any): this
/**
* Emitted when a frame is navigated to a new url.
*/
addListener(event: 'framenavigated', listener: (frame: Frame) => any): this
/**
* Emitted when the JavaScript [`load`](https://developer.mozilla.org/en-US/docs/Web/Events/load) event is dispatched.
*/
addListener(event: 'load', listener: (page: Page) => any): this
/**
* Emitted when an uncaught exception happens within the page.
*
* ```js
* // Log all uncaught errors to the terminal
* page.on('pageerror', exception => {
* console.log(`Uncaught exception: "${exception}"`);
* });
*
* // Navigate to a page with an exception.
* await page.goto('data:text/html,<script>throw new Error("Test")</script>');
* ```
*
*/
addListener(event: 'pageerror', listener: (error: Error) => any): this
/**
* Emitted when the page opens a new tab or window. This event is emitted in addition to the
* [browserContext.on('page')](https://playwright.dev/docs/api/class-browsercontext#browser-context-event-page), but
* only for popups relevant to this page.
*
* The earliest moment that page is available is when it has navigated to the initial url. For example, when opening a
* popup with `window.open('http://example.com')`, this event will fire when the network request to
* "http://example.com" is done and its response has started loading in the popup. If you would like to route/listen
* to this network request, use
* [browserContext.route(url, handler[, options])](https://playwright.dev/docs/api/class-browsercontext#browser-context-route)
* and
* [browserContext.on('request')](https://playwright.dev/docs/api/class-browsercontext#browser-context-event-request)
* respectively instead of similar methods on the [Page](https://playwright.dev/docs/api/class-page).
*
* ```js
* // Start waiting for popup before clicking. Note no await.
* const popupPromise = page.waitForEvent('popup');
* await page.getByText('open the popup').click();
* const popup = await popupPromise;
* console.log(await popup.evaluate('location.href'));
* ```
*
* **NOTE** Use
* [page.waitForLoadState([state, options])](https://playwright.dev/docs/api/class-page#page-wait-for-load-state) to
* wait until the page gets to a particular state (you should not need it in most cases).
*
*/
addListener(event: 'popup', listener: (page: Page) => any): this
/**
* Emitted when a page issues a request. The [request] object is read-only. In order to intercept and mutate requests,
* see [page.route(url, handler[, options])](https://playwright.dev/docs/api/class-page#page-route) or
* [browserContext.route(url, handler[, options])](https://playwright.dev/docs/api/class-browsercontext#browser-context-route).
*/
addListener(event: 'request', listener: (request: Request) => any): this
/**
* Emitted when a request fails, for example by timing out.
*
* ```js
* page.on('requestfailed', request => {
* console.log(request.url() + ' ' + request.failure().errorText);
* });
* ```
*
* **NOTE** HTTP Error responses, such as 404 or 503, are still successful responses from HTTP standpoint, so request
* will complete with
* [page.on('requestfinished')](https://playwright.dev/docs/api/class-page#page-event-request-finished) event and not
* with [page.on('requestfailed')](https://playwright.dev/docs/api/class-page#page-event-request-failed). A request
* will only be considered failed when the client cannot get an HTTP response from the server, e.g. due to network
* error net::ERR_FAILED.
*
*/
addListener(event: 'requestfailed', listener: (request: Request) => any): this
/**
* Emitted when a request finishes successfully after downloading the response body. For a successful response, the
* sequence of events is `request`, `response` and `requestfinished`.
*/
addListener(event: 'requestfinished', listener: (request: Request) => any): this
/**
* Emitted when [response] status and headers are received for a request. For a successful response, the sequence of
* events is `request`, `response` and `requestfinished`.
*/
addListener(event: 'response', listener: (response: Response) => any): this
/**
* Emitted when [WebSocket](https://playwright.dev/docs/api/class-websocket) request is sent.
*/
addListener(event: 'websocket', listener: (webSocket: WebSocket) => any): this
/**
* Emitted when a dedicated [WebWorker](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API) is spawned
* by the page.
*/
addListener(event: 'worker', listener: (worker: Worker) => any): this
/**
* Removes an event listener added by `on` or `addListener`.
*/
removeListener(event: 'close', listener: (page: Page) => any): this
/**
* Removes an event listener added by `on` or `addListener`.
*/
removeListener(event: 'console', listener: (consoleMessage: ConsoleMessage) => any): this
/**
* Removes an event listener added by `on` or `addListener`.
*/
removeListener(event: 'crash', listener: (page: Page) => any): this
/**
* Removes an event listener added by `on` or `addListener`.
*/
removeListener(event: 'dialog', listener: (dialog: Dialog) => any): this
/**
* Removes an event listener added by `on` or `addListener`.
*/
removeListener(event: 'dialogclosed', listener: (dialog: Dialog) => any): this
/**
* Removes an event listener added by `on` or `addListener`.
*/
removeListener(event: 'domcontentloaded', listener: (page: Page) => any): this
/**
* Removes an event listener added by `on` or `addListener`.
*/
removeListener(event: 'download', listener: (download: Download) => any): this
/**
* Removes an event listener added by `on` or `addListener`.
*/
removeListener(event: 'filechooser', listener: (fileChooser: FileChooser) => any): this
/**
* Removes an event listener added by `on` or `addListener`.
*/
removeListener(event: 'frameattached', listener: (frame: Frame) => any): this
/**
* Removes an event listener added by `on` or `addListener`.
*/
removeListener(event: 'framedetached', listener: (frame: Frame) => any): this
/**
* Removes an event listener added by `on` or `addListener`.
*/
removeListener(event: 'framenavigated', listener: (frame: Frame) => any): this
/**
* Removes an event listener added by `on` or `addListener`.
*/
removeListener(event: 'load', listener: (page: Page) => any): this
/**
* Removes an event listener added by `on` or `addListener`.
*/
removeListener(event: 'pageerror', listener: (error: Error) => any): this
/**
* Removes an event listener added by `on` or `addListener`.
*/
removeListener(event: 'popup', listener: (page: Page) => any): this
/**
* Removes an event listener added by `on` or `addListener`.
*/
removeListener(event: 'request', listener: (request: Request) => any): this
/**
* Removes an event listener added by `on` or `addListener`.
*/
removeListener(event: 'requestfailed', listener: (request: Request) => any): this
/**
* Removes an event listener added by `on` or `addListener`.
*/
removeListener(event: 'requestfinished', listener: (request: Request) => any): this
/**
* Removes an event listener added by `on` or `addListener`.
*/
removeListener(event: 'response', listener: (response: Response) => any): this
/**
* Removes an event listener added by `on` or `addListener`.
*/
removeListener(event: 'websocket', listener: (webSocket: WebSocket) => any): this
/**
* Removes an event listener added by `on` or `addListener`.
*/
removeListener(event: 'worker', listener: (worker: Worker) => any): this
/**
* Removes an event listener added by `on` or `addListener`.
*/
off(event: 'close', listener: (page: Page) => any): this
/**
* Removes an event listener added by `on` or `addListener`.
*/
off(event: 'console', listener: (consoleMessage: ConsoleMessage) => any): this
/**
* Removes an event listener added by `on` or `addListener`.
*/
off(event: 'crash', listener: (page: Page) => any): this
/**
* Removes an event listener added by `on` or `addListener`.
*/
off(event: 'dialog', listener: (dialog: Dialog) => any): this
/**
* Removes an event listener added by `on` or `addListener`.
*/
off(event: 'dialogclosed', listener: (dialog: Dialog) => any): this
/**
* Removes an event listener added by `on` or `addListener`.
*/
off(event: 'domcontentloaded', listener: (page: Page) => any): this
/**
* Removes an event listener added by `on` or `addListener`.
*/
off(event: 'download', listener: (download: Download) => any): this
/**
* Removes an event listener added by `on` or `addListener`.
*/
off(event: 'filechooser', listener: (fileChooser: FileChooser) => any): this
/**
* Removes an event listener added by `on` or `addListener`.
*/
off(event: 'frameattached', listener: (frame: Frame) => any): this
/**
* Removes an event listener added by `on` or `addListener`.
*/
off(event: 'framedetached', listener: (frame: Frame) => any): this
/**
* Removes an event listener added by `on` or `addListener`.
*/
off(event: 'framenavigated', listener: (frame: Frame) => any): this
/**
* Removes an event listener added by `on` or `addListener`.
*/
off(event: 'load', listener: (page: Page) => any): this
/**
* Removes an event listener added by `on` or `addListener`.
*/
off(event: 'pageerror', listener: (error: Error) => any): this
/**
* Removes an event listener added by `on` or `addListener`.
*/
off(event: 'popup', listener: (page: Page) => any): this
/**
* Removes an event listener added by `on` or `addListener`.
*/
off(event: 'request', listener: (request: Request) => any): this
/**
* Removes an event listener added by `on` or `addListener`.
*/
off(event: 'requestfailed', listener: (request: Request) => any): this
/**
* Removes an event listener added by `on` or `addListener`.
*/
off(event: 'requestfinished', listener: (request: Request) => any): this
/**
* Removes an event listener added by `on` or `addListener`.
*/
off(event: 'response', listener: (response: Response) => any): this
/**
* Removes an event listener added by `on` or `addListener`.
*/
off(event: 'websocket', listener: (webSocket: WebSocket) => any): this
/**
* Removes an event listener added by `on` or `addListener`.
*/
off(event: 'worker', listener: (worker: Worker) => any): this
/**
* Emitted when the page closes.
*/
prependListener(event: 'close', listener: (page: Page) => any): this
/**
* Emitted when JavaScript within the page calls one of console API methods, e.g. `console.log` or `console.dir`.
*
* The arguments passed into `console.log` are available on the
* [ConsoleMessage](https://playwright.dev/docs/api/class-consolemessage) event handler argument.
*
* **Usage**
*
* ```js
* page.on('console', async msg => {
* const values = [];
* for (const arg of msg.args())
* values.push(await arg.jsonValue());
* console.log(...values);
* });
* await page.evaluate(() => console.log('hello', 5, { foo: 'bar' }));
* ```
*
*/
prependListener(event: 'console', listener: (consoleMessage: ConsoleMessage) => any): this
/**
* Emitted when the page crashes. Browser pages might crash if they try to allocate too much memory. When the page
* crashes, ongoing and subsequent operations will throw.
*
* The most common way to deal with crashes is to catch an exception:
*
* ```js
* try {
* // Crash might happen during a click.
* await page.click('button');
* // Or while waiting for an event.
* await page.waitForEvent('popup');
* } catch (e) {
* // When the page crashes, exception message contains 'crash'.
* }
* ```
*
*/
prependListener(event: 'crash', listener: (page: Page) => any): this
/**
* Emitted when a JavaScript dialog appears, such as `alert`, `prompt`, `confirm` or `beforeunload`. Listener **must**
* either [dialog.accept([promptText])](https://playwright.dev/docs/api/class-dialog#dialog-accept) or
* [dialog.dismiss()](https://playwright.dev/docs/api/class-dialog#dialog-dismiss) the dialog - otherwise the page
* will [freeze](https://developer.mozilla.org/en-US/docs/Web/JavaScript/EventLoop#never_blocking) waiting for the
* dialog, and actions like click will never finish.
*
* **Usage**
*
* ```js
* page.on('dialog', dialog => dialog.accept());
* ```
*
* **NOTE** When no [page.on('dialog')](https://playwright.dev/docs/api/class-page#page-event-dialog) or
* [browserContext.on('dialog')](https://playwright.dev/docs/api/class-browsercontext#browser-context-event-dialog)
* listeners are present, all dialogs are automatically dismissed.
*
*/
prependListener(event: 'dialog', listener: (dialog: Dialog) => any): this
/**
* Emitted when a JavaScript dialog has been closed, either by
* [dialog.accept([promptText])](https://playwright.dev/docs/api/class-dialog#dialog-accept), by
* [dialog.dismiss()](https://playwright.dev/docs/api/class-dialog#dialog-dismiss), or manually by the user in the
* headed browser.
*/
prependListener(event: 'dialogclosed', listener: (dialog: Dialog) => any): this
/**
* Emitted when the JavaScript
* [`DOMContentLoaded`](https://developer.mozilla.org/en-US/docs/Web/Events/DOMContentLoaded) event is dispatched.
*/
prependListener(event: 'domcontentloaded', listener: (page: Page) => any): this
/**
* Emitted when attachment download started. User can access basic file operations on downloaded content via the
* passed [Download](https://playwright.dev/docs/api/class-download) instance.
*/
prependListener(event: 'download', listener: (download: Download) => any): this
/**
* Emitted when a file chooser is supposed to appear, such as after clicking the `<input type=file>`. Playwright can
* respond to it via setting the input files using
* [fileChooser.setFiles(files[, options])](https://playwright.dev/docs/api/class-filechooser#file-chooser-set-files)
* that can be uploaded after that.
*
* ```js
* page.on('filechooser', async fileChooser => {
* await fileChooser.setFiles(path.join(__dirname, '/tmp/myfile.pdf'));
* });
* ```
*
*/
prependListener(event: 'filechooser', listener: (fileChooser: FileChooser) => any): this
/**
* Emitted when a frame is attached.
*/
prependListener(event: 'frameattached', listener: (frame: Frame) => any): this
/**
* Emitted when a frame is detached.
*/
prependListener(event: 'framedetached', listener: (frame: Frame) => any): this
/**
* Emitted when a frame is navigated to a new url.
*/
prependListener(event: 'framenavigated', listener: (frame: Frame) => any): this
/**
* Emitted when the JavaScript [`load`](https://developer.mozilla.org/en-US/docs/Web/Events/load) event is dispatched.
*/
prependListener(event: 'load', listener: (page: Page) => any): this
/**
* Emitted when an uncaught exception happens within the page.
*
* ```js
* // Log all uncaught errors to the terminal
* page.on('pageerror', exception => {
* console.log(`Uncaught exception: "${exception}"`);
* });
*
* // Navigate to a page with an exception.
* await page.goto('data:text/html,<script>throw new Error("Test")</script>');
* ```
*
*/
prependListener(event: 'pageerror', listener: (error: Error) => any): this
/**
* Emitted when the page opens a new tab or window. This event is emitted in addition to the
* [browserContext.on('page')](https://playwright.dev/docs/api/class-browsercontext#browser-context-event-page), but
* only for popups relevant to this page.
*
* The earliest moment that page is available is when it has navigated to the initial url. For example, when opening a
* popup with `window.open('http://example.com')`, this event will fire when the network request to
* "http://example.com" is done and its response has started loading in the popup. If you would like to route/listen
* to this network request, use
* [browserContext.route(url, handler[, options])](https://playwright.dev/docs/api/class-browsercontext#browser-context-route)
* and
* [browserContext.on('request')](https://playwright.dev/docs/api/class-browsercontext#browser-context-event-request)
* respectively instead of similar methods on the [Page](https://playwright.dev/docs/api/class-page).
*
* ```js
* // Start waiting for popup before clicking. Note no await.
* const popupPromise = page.waitForEvent('popup');
* await page.getByText('open the popup').click();
* const popup = await popupPromise;
* console.log(await popup.evaluate('location.href'));
* ```
*
* **NOTE** Use
* [page.waitForLoadState([state, options])](https://playwright.dev/docs/api/class-page#page-wait-for-load-state) to
* wait until the page gets to a particular state (you should not need it in most cases).
*
*/
prependListener(event: 'popup', listener: (page: Page) => any): this
/**
* Emitted when a page issues a request. The [request] object is read-only. In order to intercept and mutate requests,
* see [page.route(url, handler[, options])](https://playwright.dev/docs/api/class-page#page-route) or
* [browserContext.route(url, handler[, options])](https://playwright.dev/docs/api/class-browsercontext#browser-context-route).
*/
prependListener(event: 'request', listener: (request: Request) => any): this
/**
* Emitted when a request fails, for example by timing out.
*
* ```js
* page.on('requestfailed', request => {
* console.log(request.url() + ' ' + request.failure().errorText);
* });
* ```
*
* **NOTE** HTTP Error responses, such as 404 or 503, are still successful responses from HTTP standpoint, so request
* will complete with
* [page.on('requestfinished')](https://playwright.dev/docs/api/class-page#page-event-request-finished) event and not
* with [page.on('requestfailed')](https://playwright.dev/docs/api/class-page#page-event-request-failed). A request
* will only be considered failed when the client cannot get an HTTP response from the server, e.g. due to network
* error net::ERR_FAILED.
*
*/
prependListener(event: 'requestfailed', listener: (request: Request) => any): this
/**
* Emitted when a request finishes successfully after downloading the response body. For a successful response, the
* sequence of events is `request`, `response` and `requestfinished`.
*/
prependListener(event: 'requestfinished', listener: (request: Request) => any): this
/**
* Emitted when [response] status and headers are received for a request. For a successful response, the sequence of
* events is `request`, `response` and `requestfinished`.
*/
prependListener(event: 'response', listener: (response: Response) => any): this
/**
* Emitted when [WebSocket](https://playwright.dev/docs/api/class-websocket) request is sent.
*/
prependListener(event: 'websocket', listener: (webSocket: WebSocket) => any): this
/**
* Emitted when a dedicated [WebWorker](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API) is spawned
* by the page.
*/
prependListener(event: 'worker', listener: (worker: Worker) => any): this
/**
* When testing a web page, sometimes unexpected overlays like a "Sign up" dialog appear and block actions you want to
* automate, e.g. clicking a button. These overlays don't always show up in the same way or at the same time, making
* them tricky to handle in automated tests.
*
* This method lets you set up a special function, called a handler, that activates when it detects that overlay is
* visible. The handler's job is to remove the overlay, allowing your test to continue as if the overlay wasn't there.
*
* Things to keep in mind:
* - When an overlay is shown predictably, we recommend explicitly waiting for it in your test and dismissing it as
* a part of your normal test flow, instead of using
* [page.addLocatorHandler(locator, handler[, options])](https://playwright.dev/docs/api/class-page#page-add-locator-handler).
* - Playwright checks for the overlay every time before executing or retrying an action that requires an
* [actionability check](https://playwright.dev/docs/actionability), or before performing an auto-waiting assertion check. When overlay
* is visible, Playwright calls the handler first, and then proceeds with the action/assertion. Note that the
* handler is only called when you perform an action/assertion - if the overlay becomes visible but you don't
* perform any actions, the handler will not be triggered.
* - After executing the handler, Playwright will ensure that overlay that triggered the handler is not visible
* anymore. You can opt-out of this behavior with
* [`noWaitAfter`](https://playwright.dev/docs/api/class-page#page-add-locator-handler-option-no-wait-after).
* - The execution time of the handler counts towards the timeout of the action/assertion that executed the handler.
* If your handler takes too long, it might cause timeouts.
* - You can register multiple handlers. However, only a single handler will be running at a time. Make sure the
* actions within a handler don't depend on another handler.
*
* **NOTE** Running the handler will alter your page state mid-test. For example it will change the currently focused
* element and move the mouse. Make sure that actions that run after the handler are self-contained and do not rely on
* the focus and mouse state being unchanged.
*
* For example, consider a test that calls
* [locator.focus([options])](https://playwright.dev/docs/api/class-locator#locator-focus) followed by
* [keyboard.press(key[, options])](https://playwright.dev/docs/api/class-keyboard#keyboard-press). If your handler
* clicks a button between these two actions, the focused element most likely will be wrong, and key press will happen
* on the unexpected element. Use
* [locator.press(key[, options])](https://playwright.dev/docs/api/class-locator#locator-press) instead to avoid this
* problem.
*
* Another example is a series of mouse actions, where
* [mouse.move(x, y[, options])](https://playwright.dev/docs/api/class-mouse#mouse-move) is followed by
* [mouse.down([options])](https://playwright.dev/docs/api/class-mouse#mouse-down). Again, when the handler runs
* between these two actions, the mouse position will be wrong during the mouse down. Prefer self-contained actions
* like [locator.click([options])](https://playwright.dev/docs/api/class-locator#locator-click) that do not rely on
* the state being unchanged by a handler.
*
* **Usage**
*
* An example that closes a "Sign up to the newsletter" dialog when it appears:
*
* ```js
* // Setup the handler.
* await page.addLocatorHandler(page.getByText('Sign up to the newsletter'), async () => {
* await page.getByRole('button', { name: 'No thanks' }).click();
* });
*
* // Write the test as usual.
* await page.goto('https://example.com');
* await page.getByRole('button', { name: 'Start here' }).click();
* ```
*
* An example that skips the "Confirm your security details" page when it is shown:
*
* ```js
* // Setup the handler.
* await page.addLocatorHandler(page.getByText('Confirm your security details'), async () => {
* await page.getByRole('button', { name: 'Remind me later' }).click();
* });
*
* // Write the test as usual.
* await page.goto('https://example.com');
* await page.getByRole('button', { name: 'Start here' }).click();
* ```
*
* An example with a custom callback on every actionability check. It uses a `<body>` locator that is always visible,
* so the handler is called before every actionability check. It is important to specify
* [`noWaitAfter`](https://playwright.dev/docs/api/class-page#page-add-locator-handler-option-no-wait-after), because
* the handler does not hide the `<body>` element.
*
* ```js
* // Setup the handler.
* await page.addLocatorHandler(page.locator('body'), async () => {
* await page.evaluate(() => window.removeObstructionsForTestIfNeeded());
* }, { noWaitAfter: true });
*
* // Write the test as usual.
* await page.goto('https://example.com');
* await page.getByRole('button', { name: 'Start here' }).click();
* ```
*
* Handler takes the original locator as an argument. You can also automatically remove the handler after a number of
* invocations by setting [`times`](https://playwright.dev/docs/api/class-page#page-add-locator-handler-option-times):
*
* ```js
* await page.addLocatorHandler(page.getByLabel('Close'), async locator => {
* await locator.click();
* }, { times: 1 });
* ```
*
* @param locator Locator that triggers the handler.
* @param handler Function that should be run once
* [`locator`](https://playwright.dev/docs/api/class-page#page-add-locator-handler-option-locator) appears. This
* function should get rid of the element that blocks actions like click.
* @param options
*/
addLocatorHandler(
locator: Locator,
handler: (locator: Locator) => Promise<any>,
options?: {
/**
* By default, after calling the handler Playwright will wait until the overlay becomes hidden, and only then
* Playwright will continue with the action/assertion that triggered the handler. This option allows to opt-out of
* this behavior, so that overlay can stay visible after the handler has run.
*/
noWaitAfter?: boolean
/**
* Specifies the maximum number of times this handler should be called. Unlimited by default.
*/
times?: number
},
): Promise<void>
/**
* Adds a `<script>` tag into the page with the desired url or content. Returns the added tag when the script's onload
* fires or when the script content was injected into frame.
* @param options
*/
addScriptTag(options?: {
/**
* Raw JavaScript content to be injected into frame.
*/
content?: string
/**
* Path to the JavaScript file to be injected into frame. If `path` is a relative path, then it is resolved relative
* to the current working directory.
*/
path?: string
/**
* Script type. Use 'module' in order to load a JavaScript ES6 module. See
* [script](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/script) for more details.
*/
type?: string
/**
* URL of a script to be added.
*/
url?: string
}): Promise<ElementHandle>
/**
* Adds a `<link rel="stylesheet">` tag into the page with the desired url or a `<style type="text/css">` tag with the
* content. Returns the added tag when the stylesheet's onload fires or when the CSS content was injected into frame.
* @param options
*/
addStyleTag(options?: {
/**
* Raw CSS content to be injected into frame.
*/
content?: string
/**
* Path to the CSS file to be injected into frame. If `path` is a relative path, then it is resolved relative to the
* current working directory.
*/
path?: string
/**
* URL of the `<link>` tag.
*/
url?: string
}): Promise<ElementHandle>
/**
* Captures the aria snapshot of the page. Read more about [aria snapshots](https://playwright.dev/docs/aria-snapshots).
* @param options
*/
ariaSnapshot(options?: {
/**
* When `true`, appends each element's bounding box as `[box=x,y,width,height]` to the snapshot. Coordinates are
* relative to the viewport, in CSS pixels, as returned by
* [`Element.getBoundingClientRect()`](https://developer.mozilla.org/en-US/docs/Web/API/Element/getBoundingClientRect).
* Defaults to `false`.
*/
boxes?: boolean
/**
* When specified, limits the depth of the snapshot.
*/
depth?: number
/**
* When set to `"ai"`, returns a snapshot optimized for AI consumption: including element references like `[ref=e2]`
* and snapshots of `<iframe>`s. Defaults to `"default"`.
*/
mode?: 'ai' | 'default'
/**
* Allows to cancel the operation using an
* [`AbortSignal`](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal). If the signal is aborted, the
* operation will be aborted and throw an error. Note that providing a signal does not disable the default timeout,
* which can be changed using
* [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); pass
* `timeout: 0` to disable the timeout entirely.
*/
signal?: AbortSignal
/**
* Maximum time in milliseconds. Defaults to `0` - no timeout. The default value can be changed via `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.
*/
timeout?: number
}): Promise<string>
/**
* Captures the aria snapshot of the page as a free form JSON object. Returns the same tree as
* [page.ariaSnapshot([options])](https://playwright.dev/docs/api/class-page#page-aria-snapshot), serialized as a JSON
* value instead of YAML markup. See
* [locator.ariaSnapshotJSON([options])](https://playwright.dev/docs/api/class-locator#locator-aria-snapshot-json) for
* the details of the format.
* @param options
*/
ariaSnapshotJSON(options?: {
/**
* When `true`, includes each element's bounding box as a `box` property with `x`, `y`, `width` and `height`.
* Coordinates are relative to the viewport, in CSS pixels, as returned by
* [`Element.getBoundingClientRect()`](https://developer.mozilla.org/en-US/docs/Web/API/Element/getBoundingClientRect).
* Defaults to `false`.
*/
boxes?: boolean
/**
* When specified, limits the depth of the snapshot.
*/
depth?: number
/**
* When set to `"ai"`, returns a snapshot optimized for AI consumption: including element references like `[ref=e2]`
* and snapshots of `<iframe>`s. Defaults to `"default"`.
*/
mode?: 'ai' | 'default'
/**
* Allows to cancel the operation using an
* [`AbortSignal`](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal). If the signal is aborted, the
* operation will be aborted and throw an error. Note that providing a signal does not disable the default timeout,
* which can be changed using
* [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); pass
* `timeout: 0` to disable the timeout entirely.
*/
signal?: AbortSignal
/**
* Maximum time in milliseconds. Defaults to `0` - no timeout. The default value can be changed via `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.
*/
timeout?: number
}): Promise<Serializable>
/**
* Brings page to front (activates tab).
*/
bringToFront(): Promise<void>
/**
* Cancels an ongoing [page.pickLocator()](https://playwright.dev/docs/api/class-page#page-pick-locator) call by
* deactivating pick locator mode. If no pick locator mode is active, this method is a no-op.
*/
cancelPickLocator(): Promise<void>
/**
* **NOTE** Use locator-based [locator.check([options])](https://playwright.dev/docs/api/class-locator#locator-check) instead.
* Read more about [locators](https://playwright.dev/docs/locators).
*
* This method checks an element matching
* [`selector`](https://playwright.dev/docs/api/class-page#page-check-option-selector) by performing the following
* steps:
* 1. Find an element matching [`selector`](https://playwright.dev/docs/api/class-page#page-check-option-selector).
* If there is none, wait until a matching element is attached to the DOM.
* 1. Ensure that matched element is a checkbox or a radio input. If not, this method throws. If the element is
* already checked, this method returns immediately.
* 1. Wait for [actionability](https://playwright.dev/docs/actionability) checks on the matched element, unless
* [`force`](https://playwright.dev/docs/api/class-page#page-check-option-force) option is set. If the element
* is detached during the checks, the whole action is retried.
* 1. Scroll the element into view if needed.
* 1. Use [page.mouse](https://playwright.dev/docs/api/class-page#page-mouse) to click in the center of the
* element.
* 1. Ensure that the element is now checked. If not, this method throws.
*
* When all steps combined have not finished during the specified
* [`timeout`](https://playwright.dev/docs/api/class-page#page-check-option-timeout), this method throws a
* [TimeoutError](https://playwright.dev/docs/api/class-timeouterror). Passing zero timeout disables this.
* @param selector A selector to search for an element. If there are multiple elements satisfying the selector, the first will be
* used.
* @param options
*/
check(
selector: string,
options?: {
/**
* Whether to bypass the [actionability](https://playwright.dev/docs/actionability) checks. Defaults to `false`.
*/
force?: boolean
/**
* This option has no effect.
* @deprecated This option has no effect.
*/
noWaitAfter?: boolean
/**
* A point to use relative to the top-left corner of element padding box. If not specified, uses some visible point of
* the element.
*/
position?: {
x: number
y: number
}
/**
* Controls whether Playwright scrolls the element into view before performing the action. Defaults to `"auto"`, which
* scrolls the element into view when necessary, including scrolling nested scrollable containers. When set to
* `"none"`, Playwright does not scroll the element and the action fails if the element is not already in the
* viewport. This is useful to assert that an element is reachable by the user without additional scrolling.
*/
scroll?: 'auto' | 'none'
/**
* Allows to cancel the operation using an
* [`AbortSignal`](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal). If the signal is aborted, the
* operation will be aborted and throw an error. Note that providing a signal does not disable the default timeout,
* which can be changed using
* [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); pass
* `timeout: 0` to disable the timeout entirely.
*/
signal?: AbortSignal
/**
* 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.
*/
strict?: boolean
/**
* Maximum time in milliseconds. Defaults to `0` - no timeout. The default value can be changed via `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.
*/
timeout?: number
/**
* When set, this method only performs the [actionability](https://playwright.dev/docs/actionability) checks and skips the action. Defaults
* to `false`. Useful to wait until the element is ready for the action without performing it.
*/
trial?: boolean
},
): Promise<void>
/**
* Clears all stored console messages from this page. Subsequent calls to
* [page.consoleMessages([options])](https://playwright.dev/docs/api/class-page#page-console-messages) will only
* return messages logged after the clear.
*/
clearConsoleMessages(): Promise<void>
/**
* Clears all stored page errors from this page. Subsequent calls to
* [page.pageErrors([options])](https://playwright.dev/docs/api/class-page#page-page-errors) will only return errors
* thrown after the clear.
*/
clearPageErrors(): Promise<void>
/**
* **NOTE** Use locator-based [locator.click([options])](https://playwright.dev/docs/api/class-locator#locator-click) instead.
* Read more about [locators](https://playwright.dev/docs/locators).
*
* This method clicks an element matching
* [`selector`](https://playwright.dev/docs/api/class-page#page-click-option-selector) by performing the following
* steps:
* 1. Find an element matching [`selector`](https://playwright.dev/docs/api/class-page#page-click-option-selector).
* If there is none, wait until a matching element is attached to the DOM.
* 1. Wait for [actionability](https://playwright.dev/docs/actionability) checks on the matched element, unless
* [`force`](https://playwright.dev/docs/api/class-page#page-click-option-force) option is set. If the element
* is detached during the checks, the whole action is retried.
* 1. Scroll the element into view if needed.
* 1. Use [page.mouse](https://playwright.dev/docs/api/class-page#page-mouse) to click in the center of the
* element, or the specified
* [`position`](https://playwright.dev/docs/api/class-page#page-click-option-position).
* 1. Wait for initiated navigations to either succeed or fail, unless
* [`noWaitAfter`](https://playwright.dev/docs/api/class-page#page-click-option-no-wait-after) option is set.
*
* When all steps combined have not finished during the specified
* [`timeout`](https://playwright.dev/docs/api/class-page#page-click-option-timeout), this method throws a
* [TimeoutError](https://playwright.dev/docs/api/class-timeouterror). Passing zero timeout disables this.
* @param selector A selector to search for an element. If there are multiple elements satisfying the selector, the first will be
* used.
* @param options
*/
click(
selector: string,
options?: {
/**
* Defaults to `left`.
*/
button?: 'left' | 'right' | 'middle'
/**
* defaults to 1. See [UIEvent.detail].
*/
clickCount?: number
/**
* Time to wait between `mousedown` and `mouseup` in milliseconds. Defaults to 0.
*/
delay?: number
/**
* Whether to bypass the [actionability](https://playwright.dev/docs/actionability) checks. Defaults to `false`.
*/
force?: boolean
/**
* Modifier keys to press. Ensures that only these modifiers are pressed during the operation, and then restores
* current modifiers back. If not specified, currently pressed modifiers are used. "ControlOrMeta" resolves to
* "Control" on Windows and Linux and to "Meta" on macOS.
*/
modifiers?: Array<'Alt' | 'Control' | 'ControlOrMeta' | 'Meta' | 'Shift'>
/**
* Actions that initiate navigations are waiting for these navigations to happen and for pages to start loading. You
* can opt out of waiting via setting this flag. You would only need this option in the exceptional cases such as
* navigating to inaccessible pages. Defaults to `false`.
* @deprecated This option will default to `true` in the future.
*/
noWaitAfter?: boolean
/**
* A point to use relative to the top-left corner of element padding box. If not specified, uses some visible point of
* the element.
*/
position?: {
x: number
y: number
}
/**
* Controls whether Playwright scrolls the element into view before performing the action. Defaults to `"auto"`, which
* scrolls the element into view when necessary, including scrolling nested scrollable containers. When set to
* `"none"`, Playwright does not scroll the element and the action fails if the element is not already in the
* viewport. This is useful to assert that an element is reachable by the user without additional scrolling.
*/
scroll?: 'auto' | 'none'
/**
* Allows to cancel the operation using an
* [`AbortSignal`](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal). If the signal is aborted, the
* operation will be aborted and throw an error. Note that providing a signal does not disable the default timeout,
* which can be changed using
* [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); pass
* `timeout: 0` to disable the timeout entirely.
*/
signal?: AbortSignal
/**
* 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.
*/
strict?: boolean
/**
* Maximum time in milliseconds. Defaults to `0` - no timeout. The default value can be changed via `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.
*/
timeout?: number
/**
* When set, this method only performs the [actionability](https://playwright.dev/docs/actionability) checks and skips the action. Defaults
* to `false`. Useful to wait until the element is ready for the action without performing it. Note that keyboard
* `modifiers` will be pressed regardless of `trial` to allow testing elements which are only visible when those keys
* are pressed.
*/
trial?: boolean
},
): Promise<void>
/**
* If [`runBeforeUnload`](https://playwright.dev/docs/api/class-page#page-close-option-run-before-unload) is `false`,
* does not run any unload handlers and waits for the page to be closed. If
* [`runBeforeUnload`](https://playwright.dev/docs/api/class-page#page-close-option-run-before-unload) is `true` the
* method will run unload handlers, but will **not** wait for the page to close.
*
* By default, `page.close()` **does not** run `beforeunload` handlers.
*
* **NOTE** if [`runBeforeUnload`](https://playwright.dev/docs/api/class-page#page-close-option-run-before-unload) 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?: {
/**
* The reason to be reported to the operations interrupted by the page closure.
*/
reason?: string
/**
* Defaults to `false`. Whether to run the
* [before unload](https://developer.mozilla.org/en-US/docs/Web/Events/beforeunload) page handlers.
*/
runBeforeUnload?: boolean
}): Promise<void>
/**
* Returns up to (currently) 200 last console messages from this page. See
* [page.on('console')](https://playwright.dev/docs/api/class-page#page-event-console) for more details.
* @param options
*/
consoleMessages(options?: {
/**
* Controls which messages are returned:
*/
filter?: 'all' | 'since-navigation'
}): Promise<Array<ConsoleMessage>>
/**
* Gets the full HTML contents of the page, including the doctype.
*/
content(): Promise<string>
/**
* Get the browser context that the page belongs to.
*/
context(): BrowserContext
/**
* **NOTE** Use locator-based [locator.dblclick([options])](https://playwright.dev/docs/api/class-locator#locator-dblclick)
* instead. Read more about [locators](https://playwright.dev/docs/locators).
*
* This method double clicks an element matching
* [`selector`](https://playwright.dev/docs/api/class-page#page-dblclick-option-selector) by performing the following
* steps:
* 1. Find an element matching
* [`selector`](https://playwright.dev/docs/api/class-page#page-dblclick-option-selector). If there is none,
* wait until a matching element is attached to the DOM.
* 1. Wait for [actionability](https://playwright.dev/docs/actionability) checks on the matched element, unless
* [`force`](https://playwright.dev/docs/api/class-page#page-dblclick-option-force) option is set. If the
* element is detached during the checks, the whole action is retried.
* 1. Scroll the element into view if needed.
* 1. Use [page.mouse](https://playwright.dev/docs/api/class-page#page-mouse) to double click in the center of the
* element, or the specified
* [`position`](https://playwright.dev/docs/api/class-page#page-dblclick-option-position).
*
* When all steps combined have not finished during the specified
* [`timeout`](https://playwright.dev/docs/api/class-page#page-dblclick-option-timeout), this method throws a
* [TimeoutError](https://playwright.dev/docs/api/class-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
*/
dblclick(
selector: string,
options?: {
/**
* Defaults to `left`.
*/
button?: 'left' | 'right' | 'middle'
/**
* Time to wait between `mousedown` and `mouseup` in milliseconds. Defaults to 0.
*/
delay?: number
/**
* Whether to bypass the [actionability](https://playwright.dev/docs/actionability) checks. Defaults to `false`.
*/
force?: boolean
/**
* Modifier keys to press. Ensures that only these modifiers are pressed during the operation, and then restores
* current modifiers back. If not specified, currently pressed modifiers are used. "ControlOrMeta" resolves to
* "Control" on Windows and Linux and to "Meta" on macOS.
*/
modifiers?: Array<'Alt' | 'Control' | 'ControlOrMeta' | 'Meta' | 'Shift'>
/**
* This option has no effect.
* @deprecated This option has no effect.
*/
noWaitAfter?: boolean
/**
* A point to use relative to the top-left corner of element padding box. If not specified, uses some visible point of
* the element.
*/
position?: {
x: number
y: number
}
/**
* Controls whether Playwright scrolls the element into view before performing the action. Defaults to `"auto"`, which
* scrolls the element into view when necessary, including scrolling nested scrollable containers. When set to
* `"none"`, Playwright does not scroll the element and the action fails if the element is not already in the
* viewport. This is useful to assert that an element is reachable by the user without additional scrolling.
*/
scroll?: 'auto' | 'none'
/**
* Allows to cancel the operation using an
* [`AbortSignal`](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal). If the signal is aborted, the
* operation will be aborted and throw an error. Note that providing a signal does not disable the default timeout,
* which can be changed using
* [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); pass
* `timeout: 0` to disable the timeout entirely.
*/
signal?: AbortSignal
/**
* 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.
*/
strict?: boolean
/**
* Maximum time in milliseconds. Defaults to `0` - no timeout. The default value can be changed via `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.
*/
timeout?: number
/**
* When set, this method only performs the [actionability](https://playwright.dev/docs/actionability) checks and skips the action. Defaults
* to `false`. Useful to wait until the element is ready for the action without performing it. Note that keyboard
* `modifiers` will be pressed regardless of `trial` to allow testing elements which are only visible when those keys
* are pressed.
*/
trial?: boolean
},
): Promise<void>
/**
* **NOTE** Use locator-based
* [locator.dispatchEvent(type[, eventInit, options])](https://playwright.dev/docs/api/class-locator#locator-dispatch-event)
* instead. Read more about [locators](https://playwright.dev/docs/locators).
*
* The snippet below dispatches the `click` event on the element. Regardless of the visibility state of the element,
* `click` is dispatched. This is equivalent to calling
* [element.click()](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/click).
*
* **Usage**
*
* ```js
* await page.dispatchEvent('button#submit', 'click');
* ```
*
* Under the hood, it creates an instance of an event based on the given
* [`type`](https://playwright.dev/docs/api/class-page#page-dispatch-event-option-type), initializes it with
* [`eventInit`](https://playwright.dev/docs/api/class-page#page-dispatch-event-option-event-init) properties and
* dispatches it on the element. Events are `composed`, `cancelable` and bubble by default.
*
* Since [`eventInit`](https://playwright.dev/docs/api/class-page#page-dispatch-event-option-event-init) is
* event-specific, please refer to the events documentation for the lists of initial properties:
* - [DeviceMotionEvent](https://developer.mozilla.org/en-US/docs/Web/API/DeviceMotionEvent/DeviceMotionEvent)
* - [DeviceOrientationEvent](https://developer.mozilla.org/en-US/docs/Web/API/DeviceOrientationEvent/DeviceOrientationEvent)
* - [DragEvent](https://developer.mozilla.org/en-US/docs/Web/API/DragEvent/DragEvent)
* - [Event](https://developer.mozilla.org/en-US/docs/Web/API/Event/Event)
* - [FocusEvent](https://developer.mozilla.org/en-US/docs/Web/API/FocusEvent/FocusEvent)
* - [KeyboardEvent](https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/KeyboardEvent)
* - [MouseEvent](https://developer.mozilla.org/en-US/docs/Web/API/MouseEvent/MouseEvent)
* - [PointerEvent](https://developer.mozilla.org/en-US/docs/Web/API/PointerEvent/PointerEvent)
* - [TouchEvent](https://developer.mozilla.org/en-US/docs/Web/API/TouchEvent/TouchEvent)
* - [WheelEvent](https://developer.mozilla.org/en-US/docs/Web/API/WheelEvent/WheelEvent)
*
* You can also specify `JSHandle` as the property value if you want live objects to be passed into the event:
*
* ```js
* // Note you can only create DataTransfer in Chromium and Firefox
* const dataTransfer = await page.evaluateHandle(() => new DataTransfer());
* await page.dispatchEvent('#source', 'dragstart', { dataTransfer });
* ```
*
* @param selector A selector to search for an element. If there are multiple elements satisfying the selector, the first will be
* used.
* @param type DOM event type: `"click"`, `"dragstart"`, etc.
* @param eventInit Optional event-specific initialization properties.
* @param options
*/
dispatchEvent(
selector: string,
type: string,
eventInit?: EvaluationArgument,
options?: {
/**
* Allows to cancel the operation using an
* [`AbortSignal`](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal). If the signal is aborted, the
* operation will be aborted and throw an error. Note that providing a signal does not disable the default timeout,
* which can be changed using
* [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); pass
* `timeout: 0` to disable the timeout entirely.
*/
signal?: AbortSignal
/**
* 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.
*/
strict?: boolean
/**
* Maximum time in milliseconds. Defaults to `0` - no timeout. The default value can be changed via `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.
*/
timeout?: number
},
): Promise<void>
/**
* This method drags the source element to the target element. It will first move to the source element, perform a
* `mousedown`, then move to the target element and perform a `mouseup`.
*
* **Usage**
*
* ```js
* await page.dragAndDrop('#source', '#target');
* // or specify exact positions relative to the top-left corners of the elements:
* await page.dragAndDrop('#source', '#target', {
* sourcePosition: { x: 34, y: 7 },
* targetPosition: { x: 10, y: 20 },
* });
* ```
*
* @param source A selector to search for an element to drag. If there are multiple elements satisfying the selector, the first will
* be used.
* @param target A selector to search for an element to drop onto. If there are multiple elements satisfying the selector, the first
* will be used.
* @param options
*/
dragAndDrop(
source: string,
target: string,
options?: {
/**
* Whether to bypass the [actionability](https://playwright.dev/docs/actionability) checks. Defaults to `false`.
*/
force?: boolean
/**
* This option has no effect.
* @deprecated This option has no effect.
*/
noWaitAfter?: boolean
/**
* Controls whether Playwright scrolls the element into view before performing the action. Defaults to `"auto"`, which
* scrolls the element into view when necessary, including scrolling nested scrollable containers. When set to
* `"none"`, Playwright does not scroll the element and the action fails if the element is not already in the
* viewport. This is useful to assert that an element is reachable by the user without additional scrolling.
*/
scroll?: 'auto' | 'none'
/**
* Allows to cancel the operation using an
* [`AbortSignal`](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal). If the signal is aborted, the
* operation will be aborted and throw an error. Note that providing a signal does not disable the default timeout,
* which can be changed using
* [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); pass
* `timeout: 0` to disable the timeout entirely.
*/
signal?: AbortSignal
/**
* Clicks on the source element at this point relative to the top-left corner of the element's padding box. If not
* specified, some visible point of the element is used.
*/
sourcePosition?: {
x: number
y: number
}
/**
* Defaults to 1. Sends `n` interpolated `mousemove` events to represent travel between the `mousedown` and `mouseup`
* of the drag. When set to 1, emits a single `mousemove` event at the destination location.
*/
steps?: number
/**
* 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.
*/
strict?: boolean
/**
* Drops on the target element at this point relative to the top-left corner of the element's padding box. If not
* specified, some visible point of the element is used.
*/
targetPosition?: {
x: number
y: number
}
/**
* Maximum time in milliseconds. Defaults to `0` - no timeout. The default value can be changed via `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.
*/
timeout?: number
/**
* When set, this method only performs the [actionability](https://playwright.dev/docs/actionability) checks and skips the action. Defaults
* to `false`. Useful to wait until the element is ready for the action without performing it.
*/
trial?: boolean
},
): Promise<void>
/**
* This method changes the `CSS media type` through the `media` argument, and/or the `'prefers-colors-scheme'` media
* feature, using the `colorScheme` argument.
*
* **Usage**
*
* ```js
* await page.evaluate(() => matchMedia('screen').matches);
* // → true
* await page.evaluate(() => matchMedia('print').matches);
* // → false
*
* await page.emulateMedia({ media: 'print' });
* await page.evaluate(() => matchMedia('screen').matches);
* // → false
* await page.evaluate(() => matchMedia('print').matches);
* // → true
*
* await page.emulateMedia({});
* await page.evaluate(() => matchMedia('screen').matches);
* // → true
* await page.evaluate(() => matchMedia('print').matches);
* // → false
* ```
*
* ```js
* await page.emulateMedia({ colorScheme: 'dark' });
* await page.evaluate(() => matchMedia('(prefers-color-scheme: dark)').matches);
* // → true
* await page.evaluate(() => matchMedia('(prefers-color-scheme: light)').matches);
* // → false
* ```
*
* @param options
*/
emulateMedia(options?: {
/**
* Emulates [prefers-colors-scheme](https://developer.mozilla.org/en-US/docs/Web/CSS/@media/prefers-color-scheme)
* media feature, supported values are `'light'` and `'dark'`. Passing `null` disables color scheme emulation.
* `'no-preference'` is deprecated.
*/
colorScheme?: null | 'light' | 'dark' | 'no-preference'
/**
* Emulates `'prefers-contrast'` media feature, supported values are `'no-preference'`, `'more'`. Passing `null`
* disables contrast emulation.
*/
contrast?: null | 'no-preference' | 'more'
/**
* Emulates `'forced-colors'` media feature, supported values are `'active'` and `'none'`. Passing `null` disables
* forced colors emulation.
*/
forcedColors?: null | 'active' | 'none'
/**
* Changes the CSS media type of the page. The only allowed values are `'screen'`, `'print'` and `null`. Passing
* `null` disables CSS media emulation.
*/
media?: null | 'screen' | 'print'
/**
* Emulates `'prefers-reduced-motion'` media feature, supported values are `'reduce'`, `'no-preference'`. Passing
* `null` disables reduced motion emulation.
*/
reducedMotion?: null | 'reduce' | 'no-preference'
}): Promise<void>
/**
* The method adds a function called
* [`name`](https://playwright.dev/docs/api/class-page#page-expose-function-option-name) on the `window` object of
* every frame in the page. When called, the function executes
* [`callback`](https://playwright.dev/docs/api/class-page#page-expose-function-option-callback) and returns a
* [Promise] which resolves to the return value of
* [`callback`](https://playwright.dev/docs/api/class-page#page-expose-function-option-callback).
*
* If the [`callback`](https://playwright.dev/docs/api/class-page#page-expose-function-option-callback) returns a
* [Promise], it will be awaited.
*
* See
* [browserContext.exposeFunction(name, callback)](https://playwright.dev/docs/api/class-browsercontext#browser-context-expose-function)
* for context-wide exposed function.
*
* **NOTE** Functions installed via
* [page.exposeFunction(name, callback)](https://playwright.dev/docs/api/class-page#page-expose-function) survive
* navigations.
*
* **Usage**
*
* An example of adding a `sha256` function to the page:
*
* ```js
* const { webkit } = require('playwright'); // Or 'chromium' or 'firefox'.
* const crypto = require('crypto');
*
* (async () => {
* const browser = await webkit.launch({ headless: false });
* const page = await browser.newPage();
* await page.exposeFunction('sha256', text =>
* crypto.createHash('sha256').update(text).digest('hex'),
* );
* await page.setContent(`
* <script>
* async function onClick() {
* document.querySelector('div').textContent = await window.sha256('PLAYWRIGHT');
* }
* </script>
* <button onclick="onClick()">Click me</button>
* <div></div>
* `);
* await page.click('button');
* })();
* ```
*
* @param name Name of the function on the window object
* @param callback Callback function which will be called in Playwright's context.
*/
exposeFunction(name: string, callback: Function): Promise<Disposable>
/**
* **NOTE** Use locator-based [locator.fill(value[, options])](https://playwright.dev/docs/api/class-locator#locator-fill)
* instead. Read more about [locators](https://playwright.dev/docs/locators).
*
* This method waits for an element matching
* [`selector`](https://playwright.dev/docs/api/class-page#page-fill-option-selector), waits for
* [actionability](https://playwright.dev/docs/actionability) checks, focuses the element, fills it and triggers an `input` event after
* filling. Note that you can pass an empty string to clear the input field.
*
* If the target element is not an `<input>`, `<textarea>` or `[contenteditable]` element, this method throws an
* error. However, if the element is inside the `<label>` element that has an associated
* [control](https://developer.mozilla.org/en-US/docs/Web/API/HTMLLabelElement/control), the control will be filled
* instead.
*
* To send fine-grained keyboard events, use
* [locator.pressSequentially(text[, options])](https://playwright.dev/docs/api/class-locator#locator-press-sequentially).
* @param selector A selector to search for an element. If there are multiple elements satisfying the selector, the first will be
* used.
* @param value Value to fill for the `<input>`, `<textarea>` or `[contenteditable]` element.
* @param options
*/
fill(
selector: string,
value: string,
options?: {
/**
* Whether to bypass the [actionability](https://playwright.dev/docs/actionability) checks. Defaults to `false`.
*/
force?: boolean
/**
* This option has no effect.
* @deprecated This option has no effect.
*/
noWaitAfter?: boolean
/**
* Allows to cancel the operation using an
* [`AbortSignal`](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal). If the signal is aborted, the
* operation will be aborted and throw an error. Note that providing a signal does not disable the default timeout,
* which can be changed using
* [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); pass
* `timeout: 0` to disable the timeout entirely.
*/
signal?: AbortSignal
/**
* 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.
*/
strict?: boolean
/**
* Maximum time in milliseconds. Defaults to `0` - no timeout. The default value can be changed via `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.
*/
timeout?: number
},
): Promise<void>
/**
* **NOTE** Use locator-based [locator.focus([options])](https://playwright.dev/docs/api/class-locator#locator-focus) instead.
* Read more about [locators](https://playwright.dev/docs/locators).
*
* This method fetches an element with
* [`selector`](https://playwright.dev/docs/api/class-page#page-focus-option-selector) and focuses it. If there's no
* element matching [`selector`](https://playwright.dev/docs/api/class-page#page-focus-option-selector), the method
* waits until a matching element appears in the DOM.
* @param selector A selector to search for an element. If there are multiple elements satisfying the selector, the first will be
* used.
* @param options
*/
focus(
selector: string,
options?: {
/**
* Allows to cancel the operation using an
* [`AbortSignal`](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal). If the signal is aborted, the
* operation will be aborted and throw an error. Note that providing a signal does not disable the default timeout,
* which can be changed using
* [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); pass
* `timeout: 0` to disable the timeout entirely.
*/
signal?: AbortSignal
/**
* 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.
*/
strict?: boolean
/**
* Maximum time in milliseconds. Defaults to `0` - no timeout. The default value can be changed via `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.
*/
timeout?: number
},
): Promise<void>
/**
* Returns frame matching the specified criteria. Either `name` or `url` must be specified.
*
* **Usage**
*
* ```js
* const frame = page.frame('frame-name');
* ```
*
* ```js
* const frame = page.frame({ url: /.*domain.*\/ });
* ```
*
* @param frameSelector Frame name or other frame lookup options.
*/
frame(
frameSelector:
| string
| {
/**
* Frame name specified in the `iframe`'s `name` attribute. Optional.
*/
name?: string
/**
* A glob pattern, regex pattern, URL pattern, or predicate receiving frame's `url` as a [URL] object. Optional.
*/
url?: string | RegExp | URLPattern | ((url: URL) => boolean)
},
): null | Frame
/**
* When working with iframes, you can create a frame locator that will enter the iframe and allow selecting elements
* in that iframe.
*
* When called without [`selector`](https://playwright.dev/docs/api/class-page#page-frame-locator-option-selector),
* the search starts in any frame on the page - the main frame or any of the iframes - so that you don't need to
* locate each iframe first. Note that the rest of the locator is resolved inside a single frame, just like any other
* locator. If it matches elements inside multiple frames, an error is thrown.
*
* **Usage**
*
* Following snippet locates element with text "Submit" in the iframe with id `my-frame`, like `<iframe
* id="my-frame">`:
*
* ```js
* const locator = page.frameLocator('#my-iframe').getByText('Submit');
* await locator.click();
* ```
*
* Following snippet locates a button, either in the main frame or in one of the iframes:
*
* ```js
* const locator = page.frameLocator().getByRole('button');
* await locator.click();
* ```
*
* @param selector A selector that matches the frame element. When not specified, locator is matched in any frame on the page.
*/
frameLocator(selector?: string): FrameLocator
/**
* An array of all frames attached to the page.
*/
frames(): Array<Frame>
/**
* **NOTE** Use locator-based
* [locator.getAttribute(name[, options])](https://playwright.dev/docs/api/class-locator#locator-get-attribute)
* instead. Read more about [locators](https://playwright.dev/docs/locators).
*
* Returns element attribute value.
* @param selector A selector to search for an element. If there are multiple elements satisfying the selector, the first will be
* used.
* @param name Attribute name to get the value for.
* @param options
*/
getAttribute(
selector: string,
name: string,
options?: {
/**
* Allows to cancel the operation using an
* [`AbortSignal`](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal). If the signal is aborted, the
* operation will be aborted and throw an error. Note that providing a signal does not disable the default timeout,
* which can be changed using
* [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); pass
* `timeout: 0` to disable the timeout entirely.
*/
signal?: AbortSignal
/**
* 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.
*/
strict?: boolean
/**
* Maximum time in milliseconds. Defaults to `0` - no timeout. The default value can be changed via `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.
*/
timeout?: number
},
): Promise<null | string>
/**
* Allows locating elements by their alt text.
*
* **Usage**
*
* For example, this method will find the image by alt text "Playwright logo":
*
* ```html
* <img alt='Playwright logo'>
* ```
*
* ```js
* await page.getByAltText('Playwright logo').click();
* ```
*
* @param text Text to locate the element for.
* @param options
*/
getByAltText(
text: string | RegExp,
options?: {
/**
* Whether to find an exact match: case-sensitive and whole-string. Default to false. Ignored when locating by a
* regular expression. Note that exact match still trims whitespace.
*/
exact?: boolean
},
): Locator
/**
* Allows locating input elements by the text of the associated `<label>` or `aria-labelledby` element, or by the
* `aria-label` attribute.
*
* **Usage**
*
* For example, this method will find inputs by label "Username" and "Password" in the following DOM:
*
* ```html
* <input aria-label="Username">
* <label for="password-input">Password:</label>
* <input id="password-input">
* ```
*
* ```js
* await page.getByLabel('Username').fill('john');
* await page.getByLabel('Password').fill('secret');
* ```
*
* @param text Text to locate the element for.
* @param options
*/
getByLabel(
text: string | RegExp,
options?: {
/**
* Whether to find an exact match: case-sensitive and whole-string. Default to false. Ignored when locating by a
* regular expression. Note that exact match still trims whitespace.
*/
exact?: boolean
},
): Locator
/**
* Allows locating input elements by the placeholder text.
*
* **Usage**
*
* For example, consider the following DOM structure.
*
* ```html
* <input type="email" placeholder="name@example.com" />
* ```
*
* You can fill the input after locating it by the placeholder text:
*
* ```js
* await page
* .getByPlaceholder('name@example.com')
* .fill('playwright@microsoft.com');
* ```
*
* @param text Text to locate the element for.
* @param options
*/
getByPlaceholder(
text: string | RegExp,
options?: {
/**
* Whether to find an exact match: case-sensitive and whole-string. Default to false. Ignored when locating by a
* regular expression. Note that exact match still trims whitespace.
*/
exact?: boolean
},
): Locator
/**
* Allows locating elements by their [ARIA role](https://www.w3.org/TR/wai-aria-1.2/#roles),
* [ARIA attributes](https://www.w3.org/TR/wai-aria-1.2/#aria-attributes) and
* [accessible name](https://w3c.github.io/accname/#dfn-accessible-name).
*
* **Usage**
*
* Consider the following DOM structure.
*
* ```html
* <h3>Sign up</h3>
* <label>
* <input type="checkbox" /> Subscribe
* </label>
* <br/>
* <button>Submit</button>
* ```
*
* You can locate each element by its implicit role:
*
* ```js
* await expect(page.getByRole('heading', { name: 'Sign up' })).toBeVisible();
*
* await page.getByRole('checkbox', { name: 'Subscribe' }).check();
*
* await page.getByRole('button', { name: /submit/i }).click();
* ```
*
* **Details**
*
* Role selector **does not replace** accessibility audits and conformance tests, but rather gives early feedback
* about the ARIA guidelines.
*
* Many html elements have an implicitly [defined role](https://w3c.github.io/html-aam/#html-element-role-mappings)
* that is recognized by the role selector. You can find all the
* [supported roles here](https://www.w3.org/TR/wai-aria-1.2/#role_definitions). ARIA guidelines **do not recommend**
* duplicating implicit roles and attributes by setting `role` and/or `aria-*` attributes to default values.
* @param role Required aria role.
* @param options
*/
getByRole(
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?: {
/**
* An attribute that is usually set by `aria-checked` or native `<input type=checkbox>` controls.
*
* Learn more about [`aria-checked`](https://www.w3.org/TR/wai-aria-1.2/#aria-checked).
*/
checked?: boolean
/**
* Option to match the [accessible description](https://w3c.github.io/accname/#dfn-accessible-description). By
* default, matching is case-insensitive and searches for a substring, use
* [`exact`](https://playwright.dev/docs/api/class-page#page-get-by-role-option-exact) to control this behavior.
*
* Learn more about [accessible description](https://w3c.github.io/accname/#dfn-accessible-description).
*/
description?: string | RegExp
/**
* 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).
*
*/
disabled?: boolean
/**
* Whether [`name`](https://playwright.dev/docs/api/class-page#page-get-by-role-option-name) and
* [`description`](https://playwright.dev/docs/api/class-page#page-get-by-role-option-description) are matched
* exactly: case-sensitive and whole-string. Defaults to false. Ignored when the value is a regular expression. Note
* that exact match still trims whitespace.
*/
exact?: boolean
/**
* An attribute that is usually set by `aria-expanded`.
*
* Learn more about [`aria-expanded`](https://www.w3.org/TR/wai-aria-1.2/#aria-expanded).
*/
expanded?: boolean
/**
* Option that controls whether hidden elements are matched. By default, only non-hidden elements, as
* [defined by ARIA](https://www.w3.org/TR/wai-aria-1.2/#tree_exclusion), are matched by role selector.
*
* Learn more about [`aria-hidden`](https://www.w3.org/TR/wai-aria-1.2/#aria-hidden).
*/
includeHidden?: boolean
/**
* A number attribute that is usually present for roles `heading`, `listitem`, `row`, `treeitem`, with default values
* for `<h1>-<h6>` elements.
*
* Learn more about [`aria-level`](https://www.w3.org/TR/wai-aria-1.2/#aria-level).
*/
level?: number
/**
* Option to match the [accessible name](https://w3c.github.io/accname/#dfn-accessible-name). By default, matching is
* case-insensitive and searches for a substring, use
* [`exact`](https://playwright.dev/docs/api/class-page#page-get-by-role-option-exact) to control this behavior.
*
* Learn more about [accessible name](https://w3c.github.io/accname/#dfn-accessible-name).
*/
name?: string | RegExp
/**
* An attribute that is usually set by `aria-pressed`.
*
* Learn more about [`aria-pressed`](https://www.w3.org/TR/wai-aria-1.2/#aria-pressed).
*/
pressed?: boolean
/**
* An attribute that is usually set by `aria-selected`.
*
* Learn more about [`aria-selected`](https://www.w3.org/TR/wai-aria-1.2/#aria-selected).
*/
selected?: boolean
},
): Locator
/**
* Locate element by the test id.
*
* **Usage**
*
* Consider the following DOM structure.
*
* ```html
* <button data-testid="directions">Itinéraire</button>
* ```
*
* You can locate the element by its test id:
*
* ```js
* await page.getByTestId('directions').click();
* ```
*
* **Details**
*
* By default, the `data-testid` attribute is used as a test id. Use
* [selectors.setTestIdAttribute(attributeName)](https://playwright.dev/docs/api/class-selectors#selectors-set-test-id-attribute)
* to configure a different test id attribute if necessary.
*
* ```js
* // Set custom test id attribute from @playwright/test config:
* import { defineConfig } from '@playwright/test';
*
* export default defineConfig({
* use: {
* testIdAttribute: 'data-pw'
* },
* });
* ```
*
* @param testId Id to locate the element by.
*/
getByTestId(testId: string | RegExp): Locator
/**
* Allows locating elements that contain given text.
*
* See also [locator.filter([options])](https://playwright.dev/docs/api/class-locator#locator-filter) that allows to
* match by another criteria, like an accessible role, and then filter by the text content.
*
* **Usage**
*
* Consider the following DOM structure:
*
* ```html
* <div>Hello <span>world</span></div>
* <div>Hello</div>
* ```
*
* You can locate by text substring, exact string, or a regular expression:
*
* ```js
* // Matches <span>
* page.getByText('world');
*
* // Matches first <div>
* page.getByText('Hello world');
*
* // Matches second <div>
* page.getByText('Hello', { exact: true });
*
* // Matches both <div>s
* page.getByText(/Hello/);
*
* // Matches second <div>
* page.getByText(/^hello$/i);
* ```
*
* **Details**
*
* Matching by text always normalizes whitespace, even with exact match. For example, it turns multiple spaces into
* one, turns line breaks into spaces and ignores leading and trailing whitespace.
*
* Input elements of the type `button` and `submit` are matched by their `value` instead of the text content. For
* example, locating by text `"Log in"` matches `<input type=button value="Log in">`.
* @param text Text to locate the element for.
* @param options
*/
getByText(
text: string | RegExp,
options?: {
/**
* Whether to find an exact match: case-sensitive and whole-string. Default to false. Ignored when locating by a
* regular expression. Note that exact match still trims whitespace.
*/
exact?: boolean
},
): Locator
/**
* Allows locating elements by their title attribute.
*
* **Usage**
*
* Consider the following DOM structure.
*
* ```html
* <span title='Issues count'>25 issues</span>
* ```
*
* You can check the issues count after locating it by the title text:
*
* ```js
* await expect(page.getByTitle('Issues count')).toHaveText('25 issues');
* ```
*
* @param text Text to locate the element for.
* @param options
*/
getByTitle(
text: string | RegExp,
options?: {
/**
* Whether to find an exact match: case-sensitive and whole-string. Default to false. Ignored when locating by a
* regular expression. Note that exact match still trims whitespace.
*/
exact?: boolean
},
): Locator
/**
* Returns the main resource response. In case of multiple redirects, the navigation will resolve with the response of
* the last redirect. If cannot go back, returns `null`.
*
* Navigate to the previous page in history.
*
* **NOTE** **Testing Back/Forward Cache (BFCache) is not supported.** By default, Playwright disables the
* Back/Forward Cache across all browsers. Even if explicitly enabled, Playwright's internal state relies on
* network-level navigation events. Because BFCache restores unfreeze the DOM without firing these events, using
* `page.goBack()` or `page.goForward()` to trigger a BFCache restore will result in timeouts and a desynchronized
* `Page` state.
*
* @param options
*/
goBack(options?: {
/**
* Allows to cancel the operation using an
* [`AbortSignal`](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal). If the signal is aborted, the
* operation will be aborted and throw an error. Note that providing a signal does not disable the default timeout,
* which can be changed using
* [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); pass
* `timeout: 0` to disable the timeout entirely.
*/
signal?: AbortSignal
/**
* Maximum operation time in milliseconds. Defaults to `0` - no timeout. The default value can be changed via
* `navigationTimeout` option in the config, or by using the
* [browserContext.setDefaultNavigationTimeout(timeout)](https://playwright.dev/docs/api/class-browsercontext#browser-context-set-default-navigation-timeout),
* [browserContext.setDefaultTimeout(timeout)](https://playwright.dev/docs/api/class-browsercontext#browser-context-set-default-timeout),
* [page.setDefaultNavigationTimeout(timeout)](https://playwright.dev/docs/api/class-page#page-set-default-navigation-timeout)
* or [page.setDefaultTimeout(timeout)](https://playwright.dev/docs/api/class-page#page-set-default-timeout) methods.
*/
timeout?: number
/**
* When to consider operation succeeded, defaults to `load`. Events can be either:
* - `'domcontentloaded'` - consider operation to be finished when the `DOMContentLoaded` event is fired.
* - `'load'` - consider operation to be finished when the `load` event is fired.
* - `'networkidle'` - **DISCOURAGED** consider operation to be finished when there are no network connections for
* at least `500` ms. Don't use this method for testing, rely on web assertions to assess readiness instead.
* - `'commit'` - consider operation to be finished when network response is received and the document started
* loading.
*/
waitUntil?: 'load' | 'domcontentloaded' | 'networkidle' | 'commit'
}): Promise<null | Response>
/**
* Returns the main resource response. In case of multiple redirects, the navigation will resolve with the response of
* the last redirect. If cannot go forward, returns `null`.
*
* Navigate to the next page in history.
*
* **NOTE** **Testing Back/Forward Cache (BFCache) is not supported.** By default, Playwright disables the
* Back/Forward Cache across all browsers. Even if explicitly enabled, Playwright's internal state relies on
* network-level navigation events. Because BFCache restores unfreeze the DOM without firing these events, using
* `page.goBack()` or `page.goForward()` to trigger a BFCache restore will result in timeouts and a desynchronized
* `Page` state.
*
* @param options
*/
goForward(options?: {
/**
* Allows to cancel the operation using an
* [`AbortSignal`](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal). If the signal is aborted, the
* operation will be aborted and throw an error. Note that providing a signal does not disable the default timeout,
* which can be changed using
* [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); pass
* `timeout: 0` to disable the timeout entirely.
*/
signal?: AbortSignal
/**
* Maximum operation time in milliseconds. Defaults to `0` - no timeout. The default value can be changed via
* `navigationTimeout` option in the config, or by using the
* [browserContext.setDefaultNavigationTimeout(timeout)](https://playwright.dev/docs/api/class-browsercontext#browser-context-set-default-navigation-timeout),
* [browserContext.setDefaultTimeout(timeout)](https://playwright.dev/docs/api/class-browsercontext#browser-context-set-default-timeout),
* [page.setDefaultNavigationTimeout(timeout)](https://playwright.dev/docs/api/class-page#page-set-default-navigation-timeout)
* or [page.setDefaultTimeout(timeout)](https://playwright.dev/docs/api/class-page#page-set-default-timeout) methods.
*/
timeout?: number
/**
* When to consider operation succeeded, defaults to `load`. Events can be either:
* - `'domcontentloaded'` - consider operation to be finished when the `DOMContentLoaded` event is fired.
* - `'load'` - consider operation to be finished when the `load` event is fired.
* - `'networkidle'` - **DISCOURAGED** consider operation to be finished when there are no network connections for
* at least `500` ms. Don't use this method for testing, rely on web assertions to assess readiness instead.
* - `'commit'` - consider operation to be finished when network response is received and the document started
* loading.
*/
waitUntil?: 'load' | 'domcontentloaded' | 'networkidle' | 'commit'
}): Promise<null | Response>
/**
* Returns the main resource response. In case of multiple redirects, the navigation will resolve with the first
* non-redirect response.
*
* The method will throw an error if:
* - there's an SSL error (e.g. in case of self-signed certificates).
* - target URL is invalid.
* - the [`timeout`](https://playwright.dev/docs/api/class-page#page-goto-option-timeout) is exceeded during
* navigation.
* - the remote server does not respond or is unreachable.
* - the main resource failed to load.
*
* The method will not throw an error when any valid HTTP status code is returned by the remote server, including 404
* "Not Found" and 500 "Internal Server Error". The status code for such responses can be retrieved by calling
* [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`.
*
* **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`](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.
* @param options
*/
goto(
url: string,
options?: {
/**
* Referer header value. If provided it will take preference over the referer header value set by
* [page.setExtraHTTPHeaders(headers)](https://playwright.dev/docs/api/class-page#page-set-extra-http-headers).
*/
referer?: string
/**
* Allows to cancel the operation using an
* [`AbortSignal`](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal). If the signal is aborted, the
* operation will be aborted and throw an error. Note that providing a signal does not disable the default timeout,
* which can be changed using
* [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); pass
* `timeout: 0` to disable the timeout entirely.
*/
signal?: AbortSignal
/**
* Maximum operation time in milliseconds. Defaults to `0` - no timeout. The default value can be changed via
* `navigationTimeout` option in the config, or by using the
* [browserContext.setDefaultNavigationTimeout(timeout)](https://playwright.dev/docs/api/class-browsercontext#browser-context-set-default-navigation-timeout),
* [browserContext.setDefaultTimeout(timeout)](https://playwright.dev/docs/api/class-browsercontext#browser-context-set-default-timeout),
* [page.setDefaultNavigationTimeout(timeout)](https://playwright.dev/docs/api/class-page#page-set-default-navigation-timeout)
* or [page.setDefaultTimeout(timeout)](https://playwright.dev/docs/api/class-page#page-set-default-timeout) methods.
*/
timeout?: number
/**
* When to consider operation succeeded, defaults to `load`. Events can be either:
* - `'domcontentloaded'` - consider operation to be finished when the `DOMContentLoaded` event is fired.
* - `'load'` - consider operation to be finished when the `load` event is fired.
* - `'networkidle'` - **DISCOURAGED** consider operation to be finished when there are no network connections for
* at least `500` ms. Don't use this method for testing, rely on web assertions to assess readiness instead.
* - `'commit'` - consider operation to be finished when network response is received and the document started
* loading.
*/
waitUntil?: 'load' | 'domcontentloaded' | 'networkidle' | 'commit'
},
): Promise<null | Response>
/**
* Hide all locator highlight overlays previously added by
* [locator.highlight([options])](https://playwright.dev/docs/api/class-locator#locator-highlight) on this page.
*/
hideHighlight(): Promise<void>
/**
* **NOTE** Use locator-based [locator.hover([options])](https://playwright.dev/docs/api/class-locator#locator-hover) instead.
* Read more about [locators](https://playwright.dev/docs/locators).
*
* This method hovers over an element matching
* [`selector`](https://playwright.dev/docs/api/class-page#page-hover-option-selector) by performing the following
* steps:
* 1. Find an element matching [`selector`](https://playwright.dev/docs/api/class-page#page-hover-option-selector).
* If there is none, wait until a matching element is attached to the DOM.
* 1. Wait for [actionability](https://playwright.dev/docs/actionability) checks on the matched element, unless
* [`force`](https://playwright.dev/docs/api/class-page#page-hover-option-force) option is set. If the element
* is detached during the checks, the whole action is retried.
* 1. Scroll the element into view if needed.
* 1. Use [page.mouse](https://playwright.dev/docs/api/class-page#page-mouse) to hover over the center of the
* element, or the specified
* [`position`](https://playwright.dev/docs/api/class-page#page-hover-option-position).
*
* When all steps combined have not finished during the specified
* [`timeout`](https://playwright.dev/docs/api/class-page#page-hover-option-timeout), this method throws a
* [TimeoutError](https://playwright.dev/docs/api/class-timeouterror). Passing zero timeout disables this.
* @param selector A selector to search for an element. If there are multiple elements satisfying the selector, the first will be
* used.
* @param options
*/
hover(
selector: string,
options?: {
/**
* Whether to bypass the [actionability](https://playwright.dev/docs/actionability) checks. Defaults to `false`.
*/
force?: boolean
/**
* Modifier keys to press. Ensures that only these modifiers are pressed during the operation, and then restores
* current modifiers back. If not specified, currently pressed modifiers are used. "ControlOrMeta" resolves to
* "Control" on Windows and Linux and to "Meta" on macOS.
*/
modifiers?: Array<'Alt' | 'Control' | 'ControlOrMeta' | 'Meta' | 'Shift'>
/**
* This option has no effect.
* @deprecated This option has no effect.
*/
noWaitAfter?: boolean
/**
* A point to use relative to the top-left corner of element padding box. If not specified, uses some visible point of
* the element.
*/
position?: {
x: number
y: number
}
/**
* Controls whether Playwright scrolls the element into view before performing the action. Defaults to `"auto"`, which
* scrolls the element into view when necessary, including scrolling nested scrollable containers. When set to
* `"none"`, Playwright does not scroll the element and the action fails if the element is not already in the
* viewport. This is useful to assert that an element is reachable by the user without additional scrolling.
*/
scroll?: 'auto' | 'none'
/**
* Allows to cancel the operation using an
* [`AbortSignal`](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal). If the signal is aborted, the
* operation will be aborted and throw an error. Note that providing a signal does not disable the default timeout,
* which can be changed using
* [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); pass
* `timeout: 0` to disable the timeout entirely.
*/
signal?: AbortSignal
/**
* 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.
*/
strict?: boolean
/**
* Maximum time in milliseconds. Defaults to `0` - no timeout. The default value can be changed via `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.
*/
timeout?: number
/**
* When set, this method only performs the [actionability](https://playwright.dev/docs/actionability) checks and skips the action. Defaults
* to `false`. Useful to wait until the element is ready for the action without performing it. Note that keyboard
* `modifiers` will be pressed regardless of `trial` to allow testing elements which are only visible when those keys
* are pressed.
*/
trial?: boolean
},
): Promise<void>
/**
* **NOTE** Use locator-based [locator.innerHTML([options])](https://playwright.dev/docs/api/class-locator#locator-inner-html)
* instead. Read more about [locators](https://playwright.dev/docs/locators).
*
* Returns `element.innerHTML`.
* @param selector A selector to search for an element. If there are multiple elements satisfying the selector, the first will be
* used.
* @param options
*/
innerHTML(
selector: string,
options?: {
/**
* Allows to cancel the operation using an
* [`AbortSignal`](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal). If the signal is aborted, the
* operation will be aborted and throw an error. Note that providing a signal does not disable the default timeout,
* which can be changed using
* [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); pass
* `timeout: 0` to disable the timeout entirely.
*/
signal?: AbortSignal
/**
* 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.
*/
strict?: boolean
/**
* Maximum time in milliseconds. Defaults to `0` - no timeout. The default value can be changed via `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.
*/
timeout?: number
},
): Promise<string>
/**
* **NOTE** Use locator-based [locator.innerText([options])](https://playwright.dev/docs/api/class-locator#locator-inner-text)
* instead. Read more about [locators](https://playwright.dev/docs/locators).
*
* Returns `element.innerText`.
* @param selector A selector to search for an element. If there are multiple elements satisfying the selector, the first will be
* used.
* @param options
*/
innerText(
selector: string,
options?: {
/**
* Allows to cancel the operation using an
* [`AbortSignal`](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal). If the signal is aborted, the
* operation will be aborted and throw an error. Note that providing a signal does not disable the default timeout,
* which can be changed using
* [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); pass
* `timeout: 0` to disable the timeout entirely.
*/
signal?: AbortSignal
/**
* 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.
*/
strict?: boolean
/**
* Maximum time in milliseconds. Defaults to `0` - no timeout. The default value can be changed via `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.
*/
timeout?: number
},
): Promise<string>
/**
* **NOTE** Use locator-based
* [locator.inputValue([options])](https://playwright.dev/docs/api/class-locator#locator-input-value) instead. Read
* more about [locators](https://playwright.dev/docs/locators).
*
* Returns `input.value` for the selected `<input>` or `<textarea>` or `<select>` element.
*
* Throws for non-input elements. However, if the element is inside the `<label>` element that has an associated
* [control](https://developer.mozilla.org/en-US/docs/Web/API/HTMLLabelElement/control), returns the value of the
* control.
* @param selector A selector to search for an element. If there are multiple elements satisfying the selector, the first will be
* used.
* @param options
*/
inputValue(
selector: string,
options?: {
/**
* Allows to cancel the operation using an
* [`AbortSignal`](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal). If the signal is aborted, the
* operation will be aborted and throw an error. Note that providing a signal does not disable the default timeout,
* which can be changed using
* [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); pass
* `timeout: 0` to disable the timeout entirely.
*/
signal?: AbortSignal
/**
* 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.
*/
strict?: boolean
/**
* Maximum time in milliseconds. Defaults to `0` - no timeout. The default value can be changed via `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.
*/
timeout?: number
},
): Promise<string>
/**
* **NOTE** Use locator-based [locator.isChecked([options])](https://playwright.dev/docs/api/class-locator#locator-is-checked)
* instead. Read more about [locators](https://playwright.dev/docs/locators).
*
* Returns whether the element is checked. Throws if the element is not a checkbox or radio input.
* @param selector A selector to search for an element. If there are multiple elements satisfying the selector, the first will be
* used.
* @param options
*/
isChecked(
selector: string,
options?: {
/**
* Allows to cancel the operation using an
* [`AbortSignal`](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal). If the signal is aborted, the
* operation will be aborted and throw an error. Note that providing a signal does not disable the default timeout,
* which can be changed using
* [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); pass
* `timeout: 0` to disable the timeout entirely.
*/
signal?: AbortSignal
/**
* 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.
*/
strict?: boolean
/**
* Maximum time in milliseconds. Defaults to `0` - no timeout. The default value can be changed via `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.
*/
timeout?: number
},
): Promise<boolean>
/**
* Indicates that the page has been closed.
*/
isClosed(): boolean
/**
* **NOTE** Use locator-based
* [locator.isDisabled([options])](https://playwright.dev/docs/api/class-locator#locator-is-disabled) instead. Read
* more about [locators](https://playwright.dev/docs/locators).
*
* Returns whether the element is disabled, the opposite of [enabled](https://playwright.dev/docs/actionability#enabled).
* @param selector A selector to search for an element. If there are multiple elements satisfying the selector, the first will be
* used.
* @param options
*/
isDisabled(
selector: string,
options?: {
/**
* Allows to cancel the operation using an
* [`AbortSignal`](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal). If the signal is aborted, the
* operation will be aborted and throw an error. Note that providing a signal does not disable the default timeout,
* which can be changed using
* [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); pass
* `timeout: 0` to disable the timeout entirely.
*/
signal?: AbortSignal
/**
* 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.
*/
strict?: boolean
/**
* Maximum time in milliseconds. Defaults to `0` - no timeout. The default value can be changed via `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.
*/
timeout?: number
},
): Promise<boolean>
/**
* **NOTE** Use locator-based
* [locator.isEditable([options])](https://playwright.dev/docs/api/class-locator#locator-is-editable) instead. Read
* more about [locators](https://playwright.dev/docs/locators).
*
* Returns whether the element is [editable](https://playwright.dev/docs/actionability#editable).
* @param selector A selector to search for an element. If there are multiple elements satisfying the selector, the first will be
* used.
* @param options
*/
isEditable(
selector: string,
options?: {
/**
* Allows to cancel the operation using an
* [`AbortSignal`](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal). If the signal is aborted, the
* operation will be aborted and throw an error. Note that providing a signal does not disable the default timeout,
* which can be changed using
* [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); pass
* `timeout: 0` to disable the timeout entirely.
*/
signal?: AbortSignal
/**
* 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.
*/
strict?: boolean
/**
* Maximum time in milliseconds. Defaults to `0` - no timeout. The default value can be changed via `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.
*/
timeout?: number
},
): Promise<boolean>
/**
* **NOTE** Use locator-based [locator.isEnabled([options])](https://playwright.dev/docs/api/class-locator#locator-is-enabled)
* instead. Read more about [locators](https://playwright.dev/docs/locators).
*
* Returns whether the element is [enabled](https://playwright.dev/docs/actionability#enabled).
* @param selector A selector to search for an element. If there are multiple elements satisfying the selector, the first will be
* used.
* @param options
*/
isEnabled(
selector: string,
options?: {
/**
* Allows to cancel the operation using an
* [`AbortSignal`](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal). If the signal is aborted, the
* operation will be aborted and throw an error. Note that providing a signal does not disable the default timeout,
* which can be changed using
* [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); pass
* `timeout: 0` to disable the timeout entirely.
*/
signal?: AbortSignal
/**
* 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.
*/
strict?: boolean
/**
* Maximum time in milliseconds. Defaults to `0` - no timeout. The default value can be changed via `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.
*/
timeout?: number
},
): Promise<boolean>
/**
* **NOTE** Use locator-based [locator.isHidden([options])](https://playwright.dev/docs/api/class-locator#locator-is-hidden)
* instead. Read more about [locators](https://playwright.dev/docs/locators).
*
* Returns whether the element is hidden, the opposite of [visible](https://playwright.dev/docs/actionability#visible).
* [`selector`](https://playwright.dev/docs/api/class-page#page-is-hidden-option-selector) that does not match any
* elements is considered hidden.
* @param selector A selector to search for an element. If there are multiple elements satisfying the selector, the first will be
* used.
* @param options
*/
isHidden(
selector: string,
options?: {
/**
* 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.
*/
strict?: boolean
/**
* @deprecated This option is ignored.
* [page.isHidden(selector[, options])](https://playwright.dev/docs/api/class-page#page-is-hidden) does not wait for
* the element to become hidden and returns immediately.
*/
timeout?: number
},
): Promise<boolean>
/**
* **NOTE** Use locator-based [locator.isVisible([options])](https://playwright.dev/docs/api/class-locator#locator-is-visible)
* instead. Read more about [locators](https://playwright.dev/docs/locators).
*
* Returns whether the element is [visible](https://playwright.dev/docs/actionability#visible).
* [`selector`](https://playwright.dev/docs/api/class-page#page-is-visible-option-selector) that does not match any
* elements is considered not visible.
* @param selector A selector to search for an element. If there are multiple elements satisfying the selector, the first will be
* used.
* @param options
*/
isVisible(
selector: string,
options?: {
/**
* 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.
*/
strict?: boolean
/**
* @deprecated This option is ignored.
* [page.isVisible(selector[, options])](https://playwright.dev/docs/api/class-page#page-is-visible) does not wait for
* the element to become visible and returns immediately.
*/
timeout?: number
},
): Promise<boolean>
/**
* The method returns an element locator that can be used to perform actions on this page / frame. Locator is resolved
* to the element immediately before performing an action, so a series of actions on the same locator can in fact be
* performed on different DOM elements. That would happen if the DOM structure between those actions has changed.
*
* [Learn more about locators](https://playwright.dev/docs/locators).
* @param selector A selector to use when resolving DOM element.
* @param options
*/
locator(
selector: string,
options?: {
/**
* Narrows down the results of the method to those which contain elements matching this relative locator. For example,
* `article` that has `text=Playwright` matches `<article><div>Playwright</div></article>`.
*
* Inner locator **must be relative** to the outer locator and is queried starting with the outer locator match, not
* the document root. For example, you can find `content` that has `div` in
* `<article><content><div>Playwright</div></content></article>`. However, looking for `content` that has `article
* div` will fail, because the inner locator must be relative and should not use any elements outside the `content`.
*
* Note that outer and inner locators must belong to the same frame. Inner locator must not contain
* [FrameLocator](https://playwright.dev/docs/api/class-framelocator)s.
*/
has?: Locator
/**
* Matches elements that do not contain an element that matches an inner locator. Inner locator is queried against the
* outer one. For example, `article` that does not have `div` matches `<article><span>Playwright</span></article>`.
*
* Note that outer and inner locators must belong to the same frame. Inner locator must not contain
* [FrameLocator](https://playwright.dev/docs/api/class-framelocator)s.
*/
hasNot?: Locator
/**
* Matches elements that do not contain specified text somewhere inside, possibly in a child or a descendant element.
* When passed a [string], matching is case-insensitive and searches for a substring.
*/
hasNotText?: string | RegExp
/**
* Matches elements containing specified text somewhere inside, possibly in a child or a descendant element. When
* passed a [string], matching is case-insensitive and searches for a substring. For example, `"Playwright"` matches
* `<article><div>Playwright</div></article>`.
*/
hasText?: string | RegExp
},
): Locator
/**
* The page's main frame. Page is guaranteed to have a main frame which persists during navigations.
*/
mainFrame(): Frame
/**
* Returns the opener for popup pages and `null` for others. If the opener has been closed already the returns `null`.
*/
opener(): Promise<null | Page>
/**
* Returns up to (currently) 200 last page errors from this page. See
* [page.on('pageerror')](https://playwright.dev/docs/api/class-page#page-event-page-error) for more details.
* @param options
*/
pageErrors(options?: {
/**
* Controls which errors are returned:
*/
filter?: 'all' | 'since-navigation'
}): Promise<Array<Error>>
/**
* Pauses script execution. Playwright will stop executing the script and wait for the user to either press the
* 'Resume' button in the page overlay or to call `playwright.resume()` in the DevTools console.
*
* 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`](https://playwright.dev/docs/api/class-browsertype#browser-type-launch-option-headless) option.
*
*/
pause(): Promise<void>
/**
* Returns the PDF buffer.
*
* `page.pdf()` generates a pdf of the page with `print` css media. To generate a pdf with `screen` media, call
* [page.emulateMedia([options])](https://playwright.dev/docs/api/class-page#page-emulate-media) before calling
* `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.
*
* **Usage**
*
* ```js
* // Generates a PDF with 'screen' media type.
* await page.emulateMedia({ media: 'screen' });
* await page.pdf({ path: 'page.pdf' });
* ```
*
* The [`width`](https://playwright.dev/docs/api/class-page#page-pdf-option-width),
* [`height`](https://playwright.dev/docs/api/class-page#page-pdf-option-height), and
* [`margin`](https://playwright.dev/docs/api/class-page#page-pdf-option-margin) options accept values labeled with
* units. Unlabeled values are treated as pixels.
*
* A few examples:
* - `page.pdf({width: 100})` - prints with width set to 100 pixels
* - `page.pdf({width: '100px'})` - prints with width set to 100 pixels
* - `page.pdf({width: '10cm'})` - prints with width set to 10 centimeters.
*
* All possible units are:
* - `px` - pixel
* - `in` - inch
* - `cm` - centimeter
* - `mm` - millimeter
*
* The [`format`](https://playwright.dev/docs/api/class-page#page-pdf-option-format) options are:
* - `Letter`: 8.5in x 11in
* - `Legal`: 8.5in x 14in
* - `Tabloid`: 11in x 17in
* - `Ledger`: 17in x 11in
* - `A0`: 33.1in x 46.8in
* - `A1`: 23.4in x 33.1in
* - `A2`: 16.54in x 23.4in
* - `A3`: 11.7in x 16.54in
* - `A4`: 8.27in x 11.7in
* - `A5`: 5.83in x 8.27in
* - `A6`: 4.13in x 5.83in
*
* **NOTE** [`headerTemplate`](https://playwright.dev/docs/api/class-page#page-pdf-option-header-template) and
* [`footerTemplate`](https://playwright.dev/docs/api/class-page#page-pdf-option-footer-template) 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?: {
/**
* Display header and footer. Defaults to `false`.
*/
displayHeaderFooter?: boolean
/**
* HTML template for the print footer. Should use the same format as the
* [`headerTemplate`](https://playwright.dev/docs/api/class-page#page-pdf-option-header-template).
*/
footerTemplate?: string
/**
* Paper format. If set, takes priority over
* [`width`](https://playwright.dev/docs/api/class-page#page-pdf-option-width) or
* [`height`](https://playwright.dev/docs/api/class-page#page-pdf-option-height) options. Defaults to 'Letter'.
*/
format?: string
/**
* HTML template for the print header. Should be valid HTML markup with following classes used to inject printing
* values into them:
* - `'date'` formatted print date
* - `'title'` document title
* - `'url'` document location
* - `'pageNumber'` current page number
* - `'totalPages'` total pages in the document
*/
headerTemplate?: string
/**
* Paper height, accepts values labeled with units.
*/
height?: string | number
/**
* Paper orientation. Defaults to `false`.
*/
landscape?: boolean
/**
* Paper margins, defaults to none.
*/
margin?: {
/**
* Top margin, accepts values labeled with units. Defaults to `0`.
*/
top?: string | number
/**
* Right margin, accepts values labeled with units. Defaults to `0`.
*/
right?: string | number
/**
* Bottom margin, accepts values labeled with units. Defaults to `0`.
*/
bottom?: string | number
/**
* Left margin, accepts values labeled with units. Defaults to `0`.
*/
left?: string | number
}
/**
* Whether or not to embed the document outline into the PDF. Defaults to `false`.
*/
outline?: boolean
/**
* Paper ranges to print, e.g., '1-5, 8, 11-13'. Defaults to the empty string, which means print all pages.
*/
pageRanges?: string
/**
* The file path to save the PDF to. If [`path`](https://playwright.dev/docs/api/class-page#page-pdf-option-path) is a
* relative path, then it is resolved relative to the current working directory. If no path is provided, the PDF won't
* be saved to the disk.
*/
path?: string
/**
* Give any CSS `@page` size declared in the page priority over what is declared in
* [`width`](https://playwright.dev/docs/api/class-page#page-pdf-option-width) and
* [`height`](https://playwright.dev/docs/api/class-page#page-pdf-option-height) or
* [`format`](https://playwright.dev/docs/api/class-page#page-pdf-option-format) options. Defaults to `false`, which
* will scale the content to fit the paper size.
*/
preferCSSPageSize?: boolean
/**
* Print background graphics. Defaults to `false`.
*/
printBackground?: boolean
/**
* Scale of the webpage rendering. Defaults to `1`. Scale amount must be between 0.1 and 2.
*/
scale?: number
/**
* Whether or not to generate tagged (accessible) PDF. Defaults to `false`.
*/
tagged?: boolean
/**
* Paper width, accepts values labeled with units.
*/
width?: string | number
}): Promise<Buffer>
/**
* Enters pick locator mode where hovering over page elements highlights them and shows the corresponding locator.
* Once the user clicks an element, the mode is deactivated and the
* [Locator](https://playwright.dev/docs/api/class-locator) for the picked element is returned.
*
* **Usage**
*
* ```js
* const locator = await page.pickLocator();
* console.log(locator);
* ```
*
*/
pickLocator(): Promise<Locator>
/**
* **NOTE** Use locator-based [locator.press(key[, options])](https://playwright.dev/docs/api/class-locator#locator-press)
* instead. Read more about [locators](https://playwright.dev/docs/locators).
*
* Focuses the element, and then uses
* [keyboard.down(key)](https://playwright.dev/docs/api/class-keyboard#keyboard-down) and
* [keyboard.up(key)](https://playwright.dev/docs/api/class-keyboard#keyboard-up).
*
* [`key`](https://playwright.dev/docs/api/class-page#page-press-option-key) can specify the intended
* [keyboardEvent.key](https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/key) value or a single character
* to generate the text for. A superset of the
* [`key`](https://playwright.dev/docs/api/class-page#page-press-option-key) values can be found
* [here](https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/key/Key_Values). Examples of the keys are:
*
* `F1` - `F12`, `Digit0`- `Digit9`, `KeyA`- `KeyZ`, `Backquote`, `Minus`, `Equal`, `Backslash`, `Backspace`, `Tab`,
* `Delete`, `Escape`, `ArrowDown`, `End`, `Enter`, `Home`, `Insert`, `PageDown`, `PageUp`, `ArrowRight`, `ArrowUp`,
* etc.
*
* Following modification shortcuts are also supported: `Shift`, `Control`, `Alt`, `Meta`, `ShiftLeft`,
* `ControlOrMeta`. `ControlOrMeta` resolves to `Control` on Windows and Linux and to `Meta` on macOS.
*
* Holding down `Shift` will type the text that corresponds to the
* [`key`](https://playwright.dev/docs/api/class-page#page-press-option-key) in the upper case.
*
* If [`key`](https://playwright.dev/docs/api/class-page#page-press-option-key) is a single character, it is
* case-sensitive, so the values `a` and `A` will generate different respective texts.
*
* Shortcuts such as `key: "Control+o"`, `key: "Control++` or `key: "Control+Shift+T"` are supported as well. When
* specified with the modifier, modifier is pressed and being held while the subsequent key is being pressed.
*
* **Usage**
*
* ```js
* const page = await browser.newPage();
* await page.goto('https://keycode.info');
* await page.press('body', 'A');
* await page.screenshot({ path: 'A.png' });
* await page.press('body', 'ArrowLeft');
* await page.screenshot({ path: 'ArrowLeft.png' });
* await page.press('body', 'Shift+O');
* await page.screenshot({ path: 'O.png' });
* await browser.close();
* ```
*
* @param selector A selector to search for an element. If there are multiple elements satisfying the selector, the first will be
* used.
* @param key Name of the key to press or a character to generate, such as `ArrowLeft` or `a`.
* @param options
*/
press(
selector: string,
key: string,
options?: {
/**
* Time to wait between `keydown` and `keyup` in milliseconds. Defaults to 0.
*/
delay?: number
/**
* Actions that initiate navigations are waiting for these navigations to happen and for pages to start loading. You
* can opt out of waiting via setting this flag. You would only need this option in the exceptional cases such as
* navigating to inaccessible pages. Defaults to `false`.
* @deprecated This option will default to `true` in the future.
*/
noWaitAfter?: boolean
/**
* Allows to cancel the operation using an
* [`AbortSignal`](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal). If the signal is aborted, the
* operation will be aborted and throw an error. Note that providing a signal does not disable the default timeout,
* which can be changed using
* [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); pass
* `timeout: 0` to disable the timeout entirely.
*/
signal?: AbortSignal
/**
* 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.
*/
strict?: boolean
/**
* Maximum time in milliseconds. Defaults to `0` - no timeout. The default value can be changed via `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.
*/
timeout?: number
},
): Promise<void>
/**
* This method reloads the current page, in the same way as if the user had triggered a browser refresh. Returns the
* main resource response. In case of multiple redirects, the navigation will resolve with the response of the last
* redirect.
* @param options
*/
reload(options?: {
/**
* Allows to cancel the operation using an
* [`AbortSignal`](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal). If the signal is aborted, the
* operation will be aborted and throw an error. Note that providing a signal does not disable the default timeout,
* which can be changed using
* [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); pass
* `timeout: 0` to disable the timeout entirely.
*/
signal?: AbortSignal
/**
* Maximum operation time in milliseconds. Defaults to `0` - no timeout. The default value can be changed via
* `navigationTimeout` option in the config, or by using the
* [browserContext.setDefaultNavigationTimeout(timeout)](https://playwright.dev/docs/api/class-browsercontext#browser-context-set-default-navigation-timeout),
* [browserContext.setDefaultTimeout(timeout)](https://playwright.dev/docs/api/class-browsercontext#browser-context-set-default-timeout),
* [page.setDefaultNavigationTimeout(timeout)](https://playwright.dev/docs/api/class-page#page-set-default-navigation-timeout)
* or [page.setDefaultTimeout(timeout)](https://playwright.dev/docs/api/class-page#page-set-default-timeout) methods.
*/
timeout?: number
/**
* When to consider operation succeeded, defaults to `load`. Events can be either:
* - `'domcontentloaded'` - consider operation to be finished when the `DOMContentLoaded` event is fired.
* - `'load'` - consider operation to be finished when the `load` event is fired.
* - `'networkidle'` - **DISCOURAGED** consider operation to be finished when there are no network connections for
* at least `500` ms. Don't use this method for testing, rely on web assertions to assess readiness instead.
* - `'commit'` - consider operation to be finished when network response is received and the document started
* loading.
*/
waitUntil?: 'load' | 'domcontentloaded' | 'networkidle' | 'commit'
}): Promise<null | Response>
/**
* Removes all locator handlers added by
* [page.addLocatorHandler(locator, handler[, options])](https://playwright.dev/docs/api/class-page#page-add-locator-handler)
* for a specific locator.
* @param locator Locator passed to
* [page.addLocatorHandler(locator, handler[, options])](https://playwright.dev/docs/api/class-page#page-add-locator-handler).
*/
removeLocatorHandler(locator: Locator): Promise<void>
/**
* Request the page to perform garbage collection. Note that there is no guarantee that all unreachable objects will
* be collected.
*
* This is useful to help detect memory leaks. For example, if your page has a large object `'suspect'` that might be
* leaked, you can check that it does not leak by using a
* [`WeakRef`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/WeakRef).
*
* ```js
* // 1. In your page, save a WeakRef for the "suspect".
* await page.evaluate(() => globalThis.suspectWeakRef = new WeakRef(suspect));
* // 2. Request garbage collection.
* await page.requestGC();
* // 3. Check that weak ref does not deref to the original object.
* expect(await page.evaluate(() => !globalThis.suspectWeakRef.deref())).toBe(true);
* ```
*
*/
requestGC(): Promise<void>
/**
* Returns up to (currently) 100 last network request from this page. See
* [page.on('request')](https://playwright.dev/docs/api/class-page#page-event-request) for more details.
*
* Returned requests should be accessed immediately, otherwise they might be collected to prevent unbounded memory
* growth as new requests come in. Once collected, retrieving most information about the request is impossible.
*
* Note that requests reported through the
* [page.on('request')](https://playwright.dev/docs/api/class-page#page-event-request) request are not collected, so
* there is a trade off between efficient memory usage with
* [page.requests()](https://playwright.dev/docs/api/class-page#page-requests) and the amount of available information
* reported through [page.on('request')](https://playwright.dev/docs/api/class-page#page-event-request).
*/
requests(): Promise<Array<Request>>
/**
* Routing provides the capability to modify network requests that are made by a page.
*
* Once routing is enabled, every request matching the url pattern will stall unless it's continued, fulfilled or
* aborted.
*
* **NOTE** The handler will only be called for the first url if the response is a redirect.
*
* **NOTE** [page.route(url, handler[, options])](https://playwright.dev/docs/api/class-page#page-route) will not
* intercept requests intercepted by Service Worker. See [this](https://github.com/microsoft/playwright/issues/1090)
* issue. We recommend disabling Service Workers when using request interception by setting
* [`serviceWorkers`](https://playwright.dev/docs/api/class-browser#browser-new-context-option-service-workers) to
* `'block'`.
*
* **NOTE** [page.route(url, handler[, options])](https://playwright.dev/docs/api/class-page#page-route) will not
* intercept the first request of a popup page. Use
* [browserContext.route(url, handler[, options])](https://playwright.dev/docs/api/class-browsercontext#browser-context-route)
* instead.
*
* **Usage**
*
* An example of a naive handler that aborts all image requests:
*
* ```js
* const page = await browser.newPage();
* await page.route('**\/*.{png,jpg,jpeg}', route => route.abort());
* await page.goto('https://example.com');
* await browser.close();
* ```
*
* or the same snippet using a regex pattern instead:
*
* ```js
* const page = await browser.newPage();
* await page.route(/(\.png$)|(\.jpg$)/, route => route.abort());
* await page.goto('https://example.com');
* await browser.close();
* ```
*
* It is possible to examine the request to decide the route action. For example, mocking all requests that contain
* some post data, and leaving all other requests as is:
*
* ```js
* await page.route('/api/**', async route => {
* if (route.request().postData().includes('my-string'))
* await route.fulfill({ body: 'mocked-data' });
* else
* await route.continue();
* });
* ```
*
* If a request matches multiple registered routes, the most recently registered route takes precedence.
*
* Page routes take precedence over browser context routes (set up with
* [browserContext.route(url, handler[, options])](https://playwright.dev/docs/api/class-browsercontext#browser-context-route))
* when request matches both handlers.
*
* To remove a route with its handler you can use
* [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, URL pattern, or predicate that receives a [URL] to match during routing. If
* [`baseURL`](https://playwright.dev/docs/api/class-browser#browser-new-context-option-base-url) is set in the
* context options and the provided URL is a string that does not start with `*`, it is resolved using the
* [`new URL()`](https://developer.mozilla.org/en-US/docs/Web/API/URL/URL) constructor.
* @param handler handler function to route the request.
* @param options
*/
route(
url: string | RegExp | URLPattern | ((url: URL) => boolean),
handler: (route: Route, request: Request) => Promise<any> | any,
options?: {
/**
* How often a route should be used. By default it will be used every time.
*/
times?: number
},
): Promise<Disposable>
/**
* If specified the network requests that are made in the page will be served from the HAR file. Read more about
* [Replaying from HAR](https://playwright.dev/docs/mock#replaying-from-har).
*
* Playwright will not serve requests intercepted by Service Worker from the HAR file. See
* [this](https://github.com/microsoft/playwright/issues/1090) issue. We recommend disabling Service Workers when
* using request interception by setting
* [`serviceWorkers`](https://playwright.dev/docs/api/class-browser#browser-new-context-option-service-workers) to
* `'block'`.
* @param har Path to a [HAR](http://www.softwareishard.com/blog/har-12-spec) file with prerecorded network data. If `path` is a
* relative path, then it is resolved relative to the current working directory.
* @param options
*/
routeFromHAR(
har: string,
options?: {
/**
* - If set to 'abort' any request not found in the HAR file will be aborted.
* - If set to 'fallback' missing requests will be sent to the network.
*
* Defaults to abort.
*/
notFound?: 'abort' | 'fallback'
/**
* If specified, updates the given HAR with the actual network information instead of serving from file. The file is
* written to disk when
* [browserContext.close([options])](https://playwright.dev/docs/api/class-browsercontext#browser-context-close) is
* called.
*/
update?: boolean
/**
* Optional setting to control resource content management. If `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.
*/
updateContent?: 'embed' | 'attach'
/**
* 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
* `minimal`.
*/
updateMode?: 'full' | 'minimal'
/**
* A glob pattern, regular expression or predicate to match the request URL. Only requests with URL matching the
* pattern will be served from the HAR file. If not specified, all requests are served from the HAR file.
*/
url?: string | RegExp
},
): Promise<void>
/**
* This method allows to modify websocket connections that are made by the page.
*
* Note that only `WebSocket`s created after this method was called will be routed. It is recommended to call this
* method before navigating the page.
*
* **Usage**
*
* Below is an example of a simple mock that responds to a single message. See
* [WebSocketRoute](https://playwright.dev/docs/api/class-websocketroute) for more details and examples.
*
* ```js
* await page.routeWebSocket('/ws', ws => {
* ws.onMessage(message => {
* if (message === 'request')
* ws.send('response');
* });
* });
* ```
*
* @param url Only WebSockets with the url matching this pattern will be routed. A string pattern can be relative to the
* [`baseURL`](https://playwright.dev/docs/api/class-browser#browser-new-context-option-base-url) context option.
* @param handler Handler function to route the WebSocket.
*/
routeWebSocket(
url: string | RegExp | URLPattern | ((url: URL) => boolean),
handler: (websocketroute: WebSocketRoute) => Promise<any> | any,
): Promise<void>
/**
* Returns the buffer with the captured screenshot.
* @param options
*/
screenshot(options?: PageScreenshotOptions): Promise<Buffer>
/**
* **NOTE** Use locator-based
* [locator.selectOption(values[, options])](https://playwright.dev/docs/api/class-locator#locator-select-option)
* instead. Read more about [locators](https://playwright.dev/docs/locators).
*
* This method waits for an element matching
* [`selector`](https://playwright.dev/docs/api/class-page#page-select-option-option-selector), waits for
* [actionability](https://playwright.dev/docs/actionability) checks, waits until all specified options are present in the `<select>`
* element and selects these options.
*
* If the target element is not a `<select>` element, this method throws an error. However, if the element is inside
* the `<label>` element that has an associated
* [control](https://developer.mozilla.org/en-US/docs/Web/API/HTMLLabelElement/control), the control will be used
* instead.
*
* Returns the array of option values that have been successfully selected.
*
* Triggers a `change` and `input` event once all the provided options have been selected.
*
* **Usage**
*
* ```js
* // Single selection matching the value or label
* page.selectOption('select#colors', 'blue');
*
* // single selection matching the label
* page.selectOption('select#colors', { label: 'Blue' });
*
* // multiple selection
* page.selectOption('select#colors', ['red', 'green', 'blue']);
*
* ```
*
* @param selector A selector to search for an element. If there are multiple elements satisfying the selector, the first will be
* used.
* @param values Options to select. If the `<select>` has the `multiple` attribute, all matching options are selected, otherwise
* only the first option matching one of the passed options is selected. String values are matching both values and
* labels. Option is considered matching if all specified properties match.
* @param options
*/
selectOption(
selector: string,
values:
| null
| string
| ElementHandle
| ReadonlyArray<string>
| {
/**
* Matches by `option.value`. Optional.
*/
value?: string
/**
* Matches by `option.label`. Optional.
*/
label?: string
/**
* Matches by the index. Optional.
*/
index?: number
}
| ReadonlyArray<ElementHandle>
| ReadonlyArray<{
/**
* Matches by `option.value`. Optional.
*/
value?: string
/**
* Matches by `option.label`. Optional.
*/
label?: string
/**
* Matches by the index. Optional.
*/
index?: number
}>,
options?: {
/**
* Whether to bypass the [actionability](https://playwright.dev/docs/actionability) checks. Defaults to `false`.
*/
force?: boolean
/**
* This option has no effect.
* @deprecated This option has no effect.
*/
noWaitAfter?: boolean
/**
* Allows to cancel the operation using an
* [`AbortSignal`](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal). If the signal is aborted, the
* operation will be aborted and throw an error. Note that providing a signal does not disable the default timeout,
* which can be changed using
* [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); pass
* `timeout: 0` to disable the timeout entirely.
*/
signal?: AbortSignal
/**
* 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.
*/
strict?: boolean
/**
* Maximum time in milliseconds. Defaults to `0` - no timeout. The default value can be changed via `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.
*/
timeout?: number
},
): Promise<Array<string>>
/**
* **NOTE** Use locator-based
* [locator.setChecked(checked[, options])](https://playwright.dev/docs/api/class-locator#locator-set-checked)
* instead. Read more about [locators](https://playwright.dev/docs/locators).
*
* This method checks or unchecks an element matching
* [`selector`](https://playwright.dev/docs/api/class-page#page-set-checked-option-selector) by performing the
* following steps:
* 1. Find an element matching
* [`selector`](https://playwright.dev/docs/api/class-page#page-set-checked-option-selector). If there is none,
* wait until a matching element is attached to the DOM.
* 1. Ensure that matched element is a checkbox or a radio input. If not, this method throws.
* 1. If the element already has the right checked state, this method returns immediately.
* 1. Wait for [actionability](https://playwright.dev/docs/actionability) checks on the matched element, unless
* [`force`](https://playwright.dev/docs/api/class-page#page-set-checked-option-force) option is set. If the
* element is detached during the checks, the whole action is retried.
* 1. Scroll the element into view if needed.
* 1. Use [page.mouse](https://playwright.dev/docs/api/class-page#page-mouse) to click in the center of the
* element.
* 1. Ensure that the element is now checked or unchecked. If not, this method throws.
*
* When all steps combined have not finished during the specified
* [`timeout`](https://playwright.dev/docs/api/class-page#page-set-checked-option-timeout), this method throws a
* [TimeoutError](https://playwright.dev/docs/api/class-timeouterror). Passing zero timeout disables this.
* @param selector A selector to search for an element. If there are multiple elements satisfying the selector, the first will be
* used.
* @param checked Whether to check or uncheck the checkbox.
* @param options
*/
setChecked(
selector: string,
checked: boolean,
options?: {
/**
* Whether to bypass the [actionability](https://playwright.dev/docs/actionability) checks. Defaults to `false`.
*/
force?: boolean
/**
* This option has no effect.
* @deprecated This option has no effect.
*/
noWaitAfter?: boolean
/**
* A point to use relative to the top-left corner of element padding box. If not specified, uses some visible point of
* the element.
*/
position?: {
x: number
y: number
}
/**
* Controls whether Playwright scrolls the element into view before performing the action. Defaults to `"auto"`, which
* scrolls the element into view when necessary, including scrolling nested scrollable containers. When set to
* `"none"`, Playwright does not scroll the element and the action fails if the element is not already in the
* viewport. This is useful to assert that an element is reachable by the user without additional scrolling.
*/
scroll?: 'auto' | 'none'
/**
* Allows to cancel the operation using an
* [`AbortSignal`](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal). If the signal is aborted, the
* operation will be aborted and throw an error. Note that providing a signal does not disable the default timeout,
* which can be changed using
* [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); pass
* `timeout: 0` to disable the timeout entirely.
*/
signal?: AbortSignal
/**
* 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.
*/
strict?: boolean
/**
* Maximum time in milliseconds. Defaults to `0` - no timeout. The default value can be changed via `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.
*/
timeout?: number
/**
* When set, this method only performs the [actionability](https://playwright.dev/docs/actionability) checks and skips the action. Defaults
* to `false`. Useful to wait until the element is ready for the action without performing it.
*/
trial?: boolean
},
): Promise<void>
/**
* This method internally calls [document.write()](https://developer.mozilla.org/en-US/docs/Web/API/Document/write),
* inheriting all its specific characteristics and behaviors.
* @param html HTML markup to assign to the page.
* @param options
*/
setContent(
html: string,
options?: {
/**
* Allows to cancel the operation using an
* [`AbortSignal`](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal). If the signal is aborted, the
* operation will be aborted and throw an error. Note that providing a signal does not disable the default timeout,
* which can be changed using
* [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); pass
* `timeout: 0` to disable the timeout entirely.
*/
signal?: AbortSignal
/**
* Maximum operation time in milliseconds. Defaults to `0` - no timeout. The default value can be changed via
* `navigationTimeout` option in the config, or by using the
* [browserContext.setDefaultNavigationTimeout(timeout)](https://playwright.dev/docs/api/class-browsercontext#browser-context-set-default-navigation-timeout),
* [browserContext.setDefaultTimeout(timeout)](https://playwright.dev/docs/api/class-browsercontext#browser-context-set-default-timeout),
* [page.setDefaultNavigationTimeout(timeout)](https://playwright.dev/docs/api/class-page#page-set-default-navigation-timeout)
* or [page.setDefaultTimeout(timeout)](https://playwright.dev/docs/api/class-page#page-set-default-timeout) methods.
*/
timeout?: number
/**
* When to consider operation succeeded, defaults to `load`. Events can be either:
* - `'domcontentloaded'` - consider operation to be finished when the `DOMContentLoaded` event is fired.
* - `'load'` - consider operation to be finished when the `load` event is fired.
* - `'networkidle'` - **DISCOURAGED** consider operation to be finished when there are no network connections for
* at least `500` ms. Don't use this method for testing, rely on web assertions to assess readiness instead.
* - `'commit'` - consider operation to be finished when network response is received and the document started
* loading.
*/
waitUntil?: 'load' | 'domcontentloaded' | 'networkidle' | 'commit'
},
): Promise<void>
/**
* This setting will change the default maximum navigation time for the following methods and related shortcuts:
* - [page.goBack([options])](https://playwright.dev/docs/api/class-page#page-go-back)
* - [page.goForward([options])](https://playwright.dev/docs/api/class-page#page-go-forward)
* - [page.goto(url[, options])](https://playwright.dev/docs/api/class-page#page-goto)
* - [page.reload([options])](https://playwright.dev/docs/api/class-page#page-reload)
* - [page.setContent(html[, options])](https://playwright.dev/docs/api/class-page#page-set-content)
* - [page.waitForNavigation([options])](https://playwright.dev/docs/api/class-page#page-wait-for-navigation)
* - [page.waitForURL(url[, options])](https://playwright.dev/docs/api/class-page#page-wait-for-url)
*
* **NOTE**
* [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
/**
* This setting will change the default maximum time for all the methods accepting
* [`timeout`](https://playwright.dev/docs/api/class-page#page-set-default-timeout-option-timeout) option.
*
* **NOTE**
* [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. Pass `0` to disable timeout.
*/
setDefaultTimeout(timeout: number): void
/**
* The extra HTTP headers will be sent with every request the page initiates.
*
* **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<void>
/**
* **NOTE** Use locator-based
* [locator.setInputFiles(files[, options])](https://playwright.dev/docs/api/class-locator#locator-set-input-files)
* instead. Read more about [locators](https://playwright.dev/docs/locators).
*
* Sets the value of the file input to these file paths or files. If some of the `filePaths` are relative paths, then
* they are resolved relative to the current working directory. For empty array, clears the selected files. For inputs
* with a `[webkitdirectory]` attribute, only a single directory path is supported.
*
* This method expects [`selector`](https://playwright.dev/docs/api/class-page#page-set-input-files-option-selector)
* to point to an [input element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input). However, if the
* element is inside the `<label>` element that has an associated
* [control](https://developer.mozilla.org/en-US/docs/Web/API/HTMLLabelElement/control), targets the control instead.
* @param selector A selector to search for an element. If there are multiple elements satisfying the selector, the first will be
* used.
* @param files
* @param options
*/
setInputFiles(
selector: string,
files:
| string
| ReadonlyArray<string>
| {
/**
* File name
*/
name: string
/**
* File type
*/
mimeType: string
/**
* File content
*/
buffer: Buffer
}
| ReadonlyArray<{
/**
* File name
*/
name: string
/**
* File type
*/
mimeType: string
/**
* File content
*/
buffer: Buffer
}>,
options?: {
/**
* This option has no effect.
* @deprecated This option has no effect.
*/
noWaitAfter?: boolean
/**
* Allows to cancel the operation using an
* [`AbortSignal`](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal). If the signal is aborted, the
* operation will be aborted and throw an error. Note that providing a signal does not disable the default timeout,
* which can be changed using
* [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); pass
* `timeout: 0` to disable the timeout entirely.
*/
signal?: AbortSignal
/**
* 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.
*/
strict?: boolean
/**
* Maximum time in milliseconds. Defaults to `0` - no timeout. The default value can be changed via `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.
*/
timeout?: number
},
): Promise<void>
/**
* In the case of multiple pages in a single browser, each page can have its own viewport size. However,
* [browser.newContext([options])](https://playwright.dev/docs/api/class-browser#browser-new-context) allows to set
* viewport size (and more) for all pages in the context at once.
*
* [page.setViewportSize(viewportSize)](https://playwright.dev/docs/api/class-page#page-set-viewport-size) will resize
* the page. A lot of websites don't expect phones to change size, so you should set the viewport size before
* navigating to the page.
* [page.setViewportSize(viewportSize)](https://playwright.dev/docs/api/class-page#page-set-viewport-size) will also
* reset `screen` size, use
* [browser.newContext([options])](https://playwright.dev/docs/api/class-browser#browser-new-context) with `screen`
* and `viewport` parameters if you need better control of these properties.
*
* **Usage**
*
* ```js
* const page = await browser.newPage();
* await page.setViewportSize({
* width: 640,
* height: 480,
* });
* await page.goto('https://example.com');
* ```
*
* @param viewportSize
*/
setViewportSize(viewportSize: {
/**
* page width in pixels.
*/
width: number
/**
* page height in pixels.
*/
height: number
}): Promise<void>
/**
* **NOTE** Use locator-based [locator.tap([options])](https://playwright.dev/docs/api/class-locator#locator-tap) instead. Read
* more about [locators](https://playwright.dev/docs/locators).
*
* This method taps an element matching
* [`selector`](https://playwright.dev/docs/api/class-page#page-tap-option-selector) by performing the following
* steps:
* 1. Find an element matching [`selector`](https://playwright.dev/docs/api/class-page#page-tap-option-selector).
* If there is none, wait until a matching element is attached to the DOM.
* 1. Wait for [actionability](https://playwright.dev/docs/actionability) checks on the matched element, unless
* [`force`](https://playwright.dev/docs/api/class-page#page-tap-option-force) option is set. If the element is
* detached during the checks, the whole action is retried.
* 1. Scroll the element into view if needed.
* 1. Use [page.touchscreen](https://playwright.dev/docs/api/class-page#page-touchscreen) to tap the center of the
* element, or the specified [`position`](https://playwright.dev/docs/api/class-page#page-tap-option-position).
*
* When all steps combined have not finished during the specified
* [`timeout`](https://playwright.dev/docs/api/class-page#page-tap-option-timeout), this method throws a
* [TimeoutError](https://playwright.dev/docs/api/class-timeouterror). Passing zero timeout disables this.
*
* **NOTE** [page.tap(selector[, options])](https://playwright.dev/docs/api/class-page#page-tap) will throw if the
* [`hasTouch`](https://playwright.dev/docs/api/class-browser#browser-new-context-option-has-touch) 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
*/
tap(
selector: string,
options?: {
/**
* Whether to bypass the [actionability](https://playwright.dev/docs/actionability) checks. Defaults to `false`.
*/
force?: boolean
/**
* Modifier keys to press. Ensures that only these modifiers are pressed during the operation, and then restores
* current modifiers back. If not specified, currently pressed modifiers are used. "ControlOrMeta" resolves to
* "Control" on Windows and Linux and to "Meta" on macOS.
*/
modifiers?: Array<'Alt' | 'Control' | 'ControlOrMeta' | 'Meta' | 'Shift'>
/**
* This option has no effect.
* @deprecated This option has no effect.
*/
noWaitAfter?: boolean
/**
* A point to use relative to the top-left corner of element padding box. If not specified, uses some visible point of
* the element.
*/
position?: {
x: number
y: number
}
/**
* Controls whether Playwright scrolls the element into view before performing the action. Defaults to `"auto"`, which
* scrolls the element into view when necessary, including scrolling nested scrollable containers. When set to
* `"none"`, Playwright does not scroll the element and the action fails if the element is not already in the
* viewport. This is useful to assert that an element is reachable by the user without additional scrolling.
*/
scroll?: 'auto' | 'none'
/**
* Allows to cancel the operation using an
* [`AbortSignal`](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal). If the signal is aborted, the
* operation will be aborted and throw an error. Note that providing a signal does not disable the default timeout,
* which can be changed using
* [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); pass
* `timeout: 0` to disable the timeout entirely.
*/
signal?: AbortSignal
/**
* 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.
*/
strict?: boolean
/**
* Maximum time in milliseconds. Defaults to `0` - no timeout. The default value can be changed via `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.
*/
timeout?: number
/**
* When set, this method only performs the [actionability](https://playwright.dev/docs/actionability) checks and skips the action. Defaults
* to `false`. Useful to wait until the element is ready for the action without performing it. Note that keyboard
* `modifiers` will be pressed regardless of `trial` to allow testing elements which are only visible when those keys
* are pressed.
*/
trial?: boolean
},
): Promise<void>
/**
* **NOTE** Use locator-based
* [locator.textContent([options])](https://playwright.dev/docs/api/class-locator#locator-text-content) instead. Read
* more about [locators](https://playwright.dev/docs/locators).
*
* Returns `element.textContent`.
* @param selector A selector to search for an element. If there are multiple elements satisfying the selector, the first will be
* used.
* @param options
*/
textContent(
selector: string,
options?: {
/**
* Allows to cancel the operation using an
* [`AbortSignal`](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal). If the signal is aborted, the
* operation will be aborted and throw an error. Note that providing a signal does not disable the default timeout,
* which can be changed using
* [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); pass
* `timeout: 0` to disable the timeout entirely.
*/
signal?: AbortSignal
/**
* 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.
*/
strict?: boolean
/**
* Maximum time in milliseconds. Defaults to `0` - no timeout. The default value can be changed via `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.
*/
timeout?: number
},
): Promise<null | string>
/**
* Returns the page's title.
*/
title(): Promise<string>
/**
* Sends a `keydown`, `keypress`/`input`, and `keyup` event for each character in the text. `page.type` can be used to
* send fine-grained keyboard events. To fill values in form fields, use
* [page.fill(selector, value[, options])](https://playwright.dev/docs/api/class-page#page-fill).
*
* To press a special key, like `Control` or `ArrowDown`, use
* [keyboard.press(key[, options])](https://playwright.dev/docs/api/class-keyboard#keyboard-press).
*
* **Usage**
* @deprecated In most cases, you should use
* [locator.fill(value[, options])](https://playwright.dev/docs/api/class-locator#locator-fill) instead. You only need
* to press keys one by one if there is special keyboard handling on the page - in this case use
* [locator.pressSequentially(text[, options])](https://playwright.dev/docs/api/class-locator#locator-press-sequentially).
* @param selector A selector to search for an element. If there are multiple elements satisfying the selector, the first will be
* used.
* @param text A text to type into a focused element.
* @param options
*/
type(
selector: string,
text: string,
options?: {
/**
* Time to wait between key presses in milliseconds. Defaults to 0.
*/
delay?: number
/**
* This option has no effect.
* @deprecated This option has no effect.
*/
noWaitAfter?: boolean
/**
* Allows to cancel the operation using an
* [`AbortSignal`](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal). If the signal is aborted, the
* operation will be aborted and throw an error. Note that providing a signal does not disable the default timeout,
* which can be changed using
* [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); pass
* `timeout: 0` to disable the timeout entirely.
*/
signal?: AbortSignal
/**
* 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.
*/
strict?: boolean
/**
* Maximum time in milliseconds. Defaults to `0` - no timeout. The default value can be changed via `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.
*/
timeout?: number
},
): Promise<void>
/**
* **NOTE** Use locator-based [locator.uncheck([options])](https://playwright.dev/docs/api/class-locator#locator-uncheck)
* instead. Read more about [locators](https://playwright.dev/docs/locators).
*
* This method unchecks an element matching
* [`selector`](https://playwright.dev/docs/api/class-page#page-uncheck-option-selector) by performing the following
* steps:
* 1. Find an element matching
* [`selector`](https://playwright.dev/docs/api/class-page#page-uncheck-option-selector). If there is none, wait
* until a matching element is attached to the DOM.
* 1. Ensure that matched element is a checkbox or a radio input. If not, this method throws. If the element is
* already unchecked, this method returns immediately.
* 1. Wait for [actionability](https://playwright.dev/docs/actionability) checks on the matched element, unless
* [`force`](https://playwright.dev/docs/api/class-page#page-uncheck-option-force) option is set. If the element
* is detached during the checks, the whole action is retried.
* 1. Scroll the element into view if needed.
* 1. Use [page.mouse](https://playwright.dev/docs/api/class-page#page-mouse) to click in the center of the
* element.
* 1. Ensure that the element is now unchecked. If not, this method throws.
*
* When all steps combined have not finished during the specified
* [`timeout`](https://playwright.dev/docs/api/class-page#page-uncheck-option-timeout), this method throws a
* [TimeoutError](https://playwright.dev/docs/api/class-timeouterror). Passing zero timeout disables this.
* @param selector A selector to search for an element. If there are multiple elements satisfying the selector, the first will be
* used.
* @param options
*/
uncheck(
selector: string,
options?: {
/**
* Whether to bypass the [actionability](https://playwright.dev/docs/actionability) checks. Defaults to `false`.
*/
force?: boolean
/**
* This option has no effect.
* @deprecated This option has no effect.
*/
noWaitAfter?: boolean
/**
* A point to use relative to the top-left corner of element padding box. If not specified, uses some visible point of
* the element.
*/
position?: {
x: number
y: number
}
/**
* Controls whether Playwright scrolls the element into view before performing the action. Defaults to `"auto"`, which
* scrolls the element into view when necessary, including scrolling nested scrollable containers. When set to
* `"none"`, Playwright does not scroll the element and the action fails if the element is not already in the
* viewport. This is useful to assert that an element is reachable by the user without additional scrolling.
*/
scroll?: 'auto' | 'none'
/**
* Allows to cancel the operation using an
* [`AbortSignal`](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal). If the signal is aborted, the
* operation will be aborted and throw an error. Note that providing a signal does not disable the default timeout,
* which can be changed using
* [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); pass
* `timeout: 0` to disable the timeout entirely.
*/
signal?: AbortSignal
/**
* 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.
*/
strict?: boolean
/**
* Maximum time in milliseconds. Defaults to `0` - no timeout. The default value can be changed via `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.
*/
timeout?: number
/**
* When set, this method only performs the [actionability](https://playwright.dev/docs/actionability) checks and skips the action. Defaults
* to `false`. Useful to wait until the element is ready for the action without performing it.
*/
trial?: boolean
},
): Promise<void>
/**
* Removes a route created with
* [page.route(url, handler[, options])](https://playwright.dev/docs/api/class-page#page-route). When
* [`handler`](https://playwright.dev/docs/api/class-page#page-unroute-option-handler) is not specified, removes all
* routes for the [`url`](https://playwright.dev/docs/api/class-page#page-unroute-option-url).
* @param url A glob pattern, regex pattern, URL pattern, or predicate receiving [URL] to match while routing.
* @param handler Optional handler function to route the request.
*/
unroute(
url: string | RegExp | URLPattern | ((url: URL) => boolean),
handler?: (route: Route, request: Request) => Promise<any> | any,
): Promise<void>
/**
* Removes all routes created with
* [page.route(url, handler[, options])](https://playwright.dev/docs/api/class-page#page-route) and
* [page.routeFromHAR(har[, options])](https://playwright.dev/docs/api/class-page#page-route-from-har).
* @param options
*/
unrouteAll(options?: {
/**
* Specifies whether to wait for already running handlers and what to do if they throw errors:
* - `'default'` - do not wait for current handler calls (if any) to finish, if unrouted handler throws, it may
* result in unhandled error
* - `'wait'` - wait for current handler calls (if any) to finish
* - `'ignoreErrors'` - do not wait for current handler calls (if any) to finish, all errors thrown by the handlers
* after unrouting are silently caught
*/
behavior?: 'wait' | 'ignoreErrors' | 'default'
}): Promise<void>
url(): string
/**
* Video object associated with this page. Can be used to access the video file when using the `recordVideo` context
* option.
*/
video(): null | Video
viewportSize(): null | {
/**
* page width in pixels.
*/
width: number
/**
* page height in pixels.
*/
height: number
}
/**
* Emitted when the page closes.
*/
waitForEvent(
event: 'close',
optionsOrPredicate?:
| {
predicate?: (page: Page) => boolean | Promise<boolean>
timeout?: number
signal?: AbortSignal
}
| ((page: Page) => boolean | Promise<boolean>),
): Promise<Page>
/**
* Emitted when JavaScript within the page calls one of console API methods, e.g. `console.log` or `console.dir`.
*
* The arguments passed into `console.log` are available on the
* [ConsoleMessage](https://playwright.dev/docs/api/class-consolemessage) event handler argument.
*
* **Usage**
*
* ```js
* page.on('console', async msg => {
* const values = [];
* for (const arg of msg.args())
* values.push(await arg.jsonValue());
* console.log(...values);
* });
* await page.evaluate(() => console.log('hello', 5, { foo: 'bar' }));
* ```
*
*/
waitForEvent(
event: 'console',
optionsOrPredicate?:
| {
predicate?: (consoleMessage: ConsoleMessage) => boolean | Promise<boolean>
timeout?: number
signal?: AbortSignal
}
| ((consoleMessage: ConsoleMessage) => boolean | Promise<boolean>),
): Promise<ConsoleMessage>
/**
* Emitted when the page crashes. Browser pages might crash if they try to allocate too much memory. When the page
* crashes, ongoing and subsequent operations will throw.
*
* The most common way to deal with crashes is to catch an exception:
*
* ```js
* try {
* // Crash might happen during a click.
* await page.click('button');
* // Or while waiting for an event.
* await page.waitForEvent('popup');
* } catch (e) {
* // When the page crashes, exception message contains 'crash'.
* }
* ```
*
*/
waitForEvent(
event: 'crash',
optionsOrPredicate?:
| {
predicate?: (page: Page) => boolean | Promise<boolean>
timeout?: number
signal?: AbortSignal
}
| ((page: Page) => boolean | Promise<boolean>),
): Promise<Page>
/**
* Emitted when a JavaScript dialog appears, such as `alert`, `prompt`, `confirm` or `beforeunload`. Listener **must**
* either [dialog.accept([promptText])](https://playwright.dev/docs/api/class-dialog#dialog-accept) or
* [dialog.dismiss()](https://playwright.dev/docs/api/class-dialog#dialog-dismiss) the dialog - otherwise the page
* will [freeze](https://developer.mozilla.org/en-US/docs/Web/JavaScript/EventLoop#never_blocking) waiting for the
* dialog, and actions like click will never finish.
*
* **Usage**
*
* ```js
* page.on('dialog', dialog => dialog.accept());
* ```
*
* **NOTE** When no [page.on('dialog')](https://playwright.dev/docs/api/class-page#page-event-dialog) or
* [browserContext.on('dialog')](https://playwright.dev/docs/api/class-browsercontext#browser-context-event-dialog)
* listeners are present, all dialogs are automatically dismissed.
*
*/
waitForEvent(
event: 'dialog',
optionsOrPredicate?:
| {
predicate?: (dialog: Dialog) => boolean | Promise<boolean>
timeout?: number
signal?: AbortSignal
}
| ((dialog: Dialog) => boolean | Promise<boolean>),
): Promise<Dialog>
/**
* Emitted when a JavaScript dialog has been closed, either by
* [dialog.accept([promptText])](https://playwright.dev/docs/api/class-dialog#dialog-accept), by
* [dialog.dismiss()](https://playwright.dev/docs/api/class-dialog#dialog-dismiss), or manually by the user in the
* headed browser.
*/
waitForEvent(
event: 'dialogclosed',
optionsOrPredicate?:
| {
predicate?: (dialog: Dialog) => boolean | Promise<boolean>
timeout?: number
signal?: AbortSignal
}
| ((dialog: Dialog) => boolean | Promise<boolean>),
): Promise<Dialog>
/**
* Emitted when the JavaScript
* [`DOMContentLoaded`](https://developer.mozilla.org/en-US/docs/Web/Events/DOMContentLoaded) event is dispatched.
*/
waitForEvent(
event: 'domcontentloaded',
optionsOrPredicate?:
| {
predicate?: (page: Page) => boolean | Promise<boolean>
timeout?: number
signal?: AbortSignal
}
| ((page: Page) => boolean | Promise<boolean>),
): Promise<Page>
/**
* Emitted when attachment download started. User can access basic file operations on downloaded content via the
* passed [Download](https://playwright.dev/docs/api/class-download) instance.
*/
waitForEvent(
event: 'download',
optionsOrPredicate?:
| {
predicate?: (download: Download) => boolean | Promise<boolean>
timeout?: number
signal?: AbortSignal
}
| ((download: Download) => boolean | Promise<boolean>),
): Promise<Download>
/**
* Emitted when a file chooser is supposed to appear, such as after clicking the `<input type=file>`. Playwright can
* respond to it via setting the input files using
* [fileChooser.setFiles(files[, options])](https://playwright.dev/docs/api/class-filechooser#file-chooser-set-files)
* that can be uploaded after that.
*
* ```js
* page.on('filechooser', async fileChooser => {
* await fileChooser.setFiles(path.join(__dirname, '/tmp/myfile.pdf'));
* });
* ```
*
*/
waitForEvent(
event: 'filechooser',
optionsOrPredicate?:
| {
predicate?: (fileChooser: FileChooser) => boolean | Promise<boolean>
timeout?: number
signal?: AbortSignal
}
| ((fileChooser: FileChooser) => boolean | Promise<boolean>),
): Promise<FileChooser>
/**
* Emitted when a frame is attached.
*/
waitForEvent(
event: 'frameattached',
optionsOrPredicate?:
| {
predicate?: (frame: Frame) => boolean | Promise<boolean>
timeout?: number
signal?: AbortSignal
}
| ((frame: Frame) => boolean | Promise<boolean>),
): Promise<Frame>
/**
* Emitted when a frame is detached.
*/
waitForEvent(
event: 'framedetached',
optionsOrPredicate?:
| {
predicate?: (frame: Frame) => boolean | Promise<boolean>
timeout?: number
signal?: AbortSignal
}
| ((frame: Frame) => boolean | Promise<boolean>),
): Promise<Frame>
/**
* Emitted when a frame is navigated to a new url.
*/
waitForEvent(
event: 'framenavigated',
optionsOrPredicate?:
| {
predicate?: (frame: Frame) => boolean | Promise<boolean>
timeout?: number
signal?: AbortSignal
}
| ((frame: Frame) => boolean | Promise<boolean>),
): Promise<Frame>
/**
* Emitted when the JavaScript [`load`](https://developer.mozilla.org/en-US/docs/Web/Events/load) event is dispatched.
*/
waitForEvent(
event: 'load',
optionsOrPredicate?:
| {
predicate?: (page: Page) => boolean | Promise<boolean>
timeout?: number
signal?: AbortSignal
}
| ((page: Page) => boolean | Promise<boolean>),
): Promise<Page>
/**
* Emitted when an uncaught exception happens within the page.
*
* ```js
* // Log all uncaught errors to the terminal
* page.on('pageerror', exception => {
* console.log(`Uncaught exception: "${exception}"`);
* });
*
* // Navigate to a page with an exception.
* await page.goto('data:text/html,<script>throw new Error("Test")</script>');
* ```
*
*/
waitForEvent(
event: 'pageerror',
optionsOrPredicate?:
| {
predicate?: (error: Error) => boolean | Promise<boolean>
timeout?: number
signal?: AbortSignal
}
| ((error: Error) => boolean | Promise<boolean>),
): Promise<Error>
/**
* Emitted when the page opens a new tab or window. This event is emitted in addition to the
* [browserContext.on('page')](https://playwright.dev/docs/api/class-browsercontext#browser-context-event-page), but
* only for popups relevant to this page.
*
* The earliest moment that page is available is when it has navigated to the initial url. For example, when opening a
* popup with `window.open('http://example.com')`, this event will fire when the network request to
* "http://example.com" is done and its response has started loading in the popup. If you would like to route/listen
* to this network request, use
* [browserContext.route(url, handler[, options])](https://playwright.dev/docs/api/class-browsercontext#browser-context-route)
* and
* [browserContext.on('request')](https://playwright.dev/docs/api/class-browsercontext#browser-context-event-request)
* respectively instead of similar methods on the [Page](https://playwright.dev/docs/api/class-page).
*
* ```js
* // Start waiting for popup before clicking. Note no await.
* const popupPromise = page.waitForEvent('popup');
* await page.getByText('open the popup').click();
* const popup = await popupPromise;
* console.log(await popup.evaluate('location.href'));
* ```
*
* **NOTE** Use
* [page.waitForLoadState([state, options])](https://playwright.dev/docs/api/class-page#page-wait-for-load-state) to
* wait until the page gets to a particular state (you should not need it in most cases).
*
*/
waitForEvent(
event: 'popup',
optionsOrPredicate?:
| {
predicate?: (page: Page) => boolean | Promise<boolean>
timeout?: number
signal?: AbortSignal
}
| ((page: Page) => boolean | Promise<boolean>),
): Promise<Page>
/**
* Emitted when a page issues a request. The [request] object is read-only. In order to intercept and mutate requests,
* see [page.route(url, handler[, options])](https://playwright.dev/docs/api/class-page#page-route) or
* [browserContext.route(url, handler[, options])](https://playwright.dev/docs/api/class-browsercontext#browser-context-route).
*/
waitForEvent(
event: 'request',
optionsOrPredicate?:
| {
predicate?: (request: Request) => boolean | Promise<boolean>
timeout?: number
signal?: AbortSignal
}
| ((request: Request) => boolean | Promise<boolean>),
): Promise<Request>
/**
* Emitted when a request fails, for example by timing out.
*
* ```js
* page.on('requestfailed', request => {
* console.log(request.url() + ' ' + request.failure().errorText);
* });
* ```
*
* **NOTE** HTTP Error responses, such as 404 or 503, are still successful responses from HTTP standpoint, so request
* will complete with
* [page.on('requestfinished')](https://playwright.dev/docs/api/class-page#page-event-request-finished) event and not
* with [page.on('requestfailed')](https://playwright.dev/docs/api/class-page#page-event-request-failed). A request
* will only be considered failed when the client cannot get an HTTP response from the server, e.g. due to network
* error net::ERR_FAILED.
*
*/
waitForEvent(
event: 'requestfailed',
optionsOrPredicate?:
| {
predicate?: (request: Request) => boolean | Promise<boolean>
timeout?: number
signal?: AbortSignal
}
| ((request: Request) => boolean | Promise<boolean>),
): Promise<Request>
/**
* Emitted when a request finishes successfully after downloading the response body. For a successful response, the
* sequence of events is `request`, `response` and `requestfinished`.
*/
waitForEvent(
event: 'requestfinished',
optionsOrPredicate?:
| {
predicate?: (request: Request) => boolean | Promise<boolean>
timeout?: number
signal?: AbortSignal
}
| ((request: Request) => boolean | Promise<boolean>),
): Promise<Request>
/**
* Emitted when [response] status and headers are received for a request. For a successful response, the sequence of
* events is `request`, `response` and `requestfinished`.
*/
waitForEvent(
event: 'response',
optionsOrPredicate?:
| {
predicate?: (response: Response) => boolean | Promise<boolean>
timeout?: number
signal?: AbortSignal
}
| ((response: Response) => boolean | Promise<boolean>),
): Promise<Response>
/**
* Emitted when [WebSocket](https://playwright.dev/docs/api/class-websocket) request is sent.
*/
waitForEvent(
event: 'websocket',
optionsOrPredicate?:
| {
predicate?: (webSocket: WebSocket) => boolean | Promise<boolean>
timeout?: number
signal?: AbortSignal
}
| ((webSocket: WebSocket) => boolean | Promise<boolean>),
): Promise<WebSocket>
/**
* Emitted when a dedicated [WebWorker](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API) is spawned
* by the page.
*/
waitForEvent(
event: 'worker',
optionsOrPredicate?:
| {
predicate?: (worker: Worker) => boolean | Promise<boolean>
timeout?: number
signal?: AbortSignal
}
| ((worker: Worker) => boolean | Promise<boolean>),
): Promise<Worker>
/**
* Returns when the required load state has been reached.
*
* This resolves when the page reaches a required load state, `load` by default. The navigation must have been
* committed when this method is called. If current document has already reached the required state, resolves
* immediately.
*
* **NOTE** Most of the time, this method is not needed because Playwright
* [auto-waits before every action](https://playwright.dev/docs/actionability).
*
* **Usage**
*
* ```js
* await page.getByRole('button').click(); // Click triggers navigation.
* await page.waitForLoadState(); // The promise resolves after 'load' event.
* ```
*
* ```js
* const popupPromise = page.waitForEvent('popup');
* await page.getByRole('button').click(); // Click triggers a popup.
* const popup = await popupPromise;
* await popup.waitForLoadState('domcontentloaded'); // Wait for the 'DOMContentLoaded' event.
* console.log(await popup.title()); // Popup is ready to use.
* ```
*
* @param state Optional load state to wait for, defaults to `load`. If the state has been already reached while loading current
* document, the method resolves immediately. Can be one of:
* - `'load'` - wait for the `load` event to be fired.
* - `'domcontentloaded'` - wait for the `DOMContentLoaded` event to be fired.
* - `'networkidle'` - **DISCOURAGED** wait until there are no network connections for at least `500` ms. Don't use
* this method for testing, rely on web assertions to assess readiness instead.
* @param options
*/
waitForLoadState(
state?: 'load' | 'domcontentloaded' | 'networkidle',
options?: {
/**
* Allows to cancel the waiting using an
* [`AbortSignal`](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal). If the signal is aborted, the
* waiting will be aborted and the operation will throw an error. Note that providing a signal does not disable the
* default timeout, which can be changed using
* [browserContext.setDefaultTimeout(timeout)](https://playwright.dev/docs/api/class-browsercontext#browser-context-set-default-timeout);
* pass `timeout: 0` to disable the timeout entirely.
*/
signal?: AbortSignal
/**
* Maximum operation time in milliseconds. Defaults to `0` - no timeout. The default value can be changed via
* `navigationTimeout` option in the config, or by using the
* [browserContext.setDefaultNavigationTimeout(timeout)](https://playwright.dev/docs/api/class-browsercontext#browser-context-set-default-navigation-timeout),
* [browserContext.setDefaultTimeout(timeout)](https://playwright.dev/docs/api/class-browsercontext#browser-context-set-default-timeout),
* [page.setDefaultNavigationTimeout(timeout)](https://playwright.dev/docs/api/class-page#page-set-default-navigation-timeout)
* or [page.setDefaultTimeout(timeout)](https://playwright.dev/docs/api/class-page#page-set-default-timeout) methods.
*/
timeout?: number
},
): Promise<void>
/**
* Waits for the main frame navigation and returns the main resource response. In case of multiple redirects, the
* navigation will resolve with the response of the last redirect. In case of navigation to a different anchor or
* navigation due to History API usage, the navigation will resolve with `null`.
*
* **Usage**
*
* This resolves when the page navigates to a new URL or reloads. It is useful for when you run code which will
* indirectly cause the page to navigate. e.g. The click target has an `onclick` handler that triggers navigation from
* a `setTimeout`. Consider this example:
*
* ```js
* // Start waiting for navigation before clicking. Note no await.
* const navigationPromise = page.waitForNavigation();
* await page.getByText('Navigate after timeout').click();
* await navigationPromise;
* ```
*
* **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.
*
* @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
*/
waitForNavigation(options?: {
/**
* Allows to cancel the waiting using an
* [`AbortSignal`](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal). If the signal is aborted, the
* waiting will be aborted and the operation will throw an error. Note that providing a signal does not disable the
* default timeout, which can be changed using
* [browserContext.setDefaultTimeout(timeout)](https://playwright.dev/docs/api/class-browsercontext#browser-context-set-default-timeout);
* pass `timeout: 0` to disable the timeout entirely.
*/
signal?: AbortSignal
/**
* Maximum operation time in milliseconds. Defaults to `0` - no timeout. The default value can be changed via
* `navigationTimeout` option in the config, or by using the
* [browserContext.setDefaultNavigationTimeout(timeout)](https://playwright.dev/docs/api/class-browsercontext#browser-context-set-default-navigation-timeout),
* [browserContext.setDefaultTimeout(timeout)](https://playwright.dev/docs/api/class-browsercontext#browser-context-set-default-timeout),
* [page.setDefaultNavigationTimeout(timeout)](https://playwright.dev/docs/api/class-page#page-set-default-navigation-timeout)
* or [page.setDefaultTimeout(timeout)](https://playwright.dev/docs/api/class-page#page-set-default-timeout) methods.
*/
timeout?: number
/**
* A glob pattern, regex pattern, URL pattern, or predicate receiving [URL] to match while waiting for the navigation.
* Note that if the parameter is a string without wildcard characters, the method will wait for navigation to URL that
* is exactly equal to the string.
*/
url?: string | RegExp | URLPattern | ((url: URL) => boolean)
/**
* When to consider operation succeeded, defaults to `load`. Events can be either:
* - `'domcontentloaded'` - consider operation to be finished when the `DOMContentLoaded` event is fired.
* - `'load'` - consider operation to be finished when the `load` event is fired.
* - `'networkidle'` - **DISCOURAGED** consider operation to be finished when there are no network connections for
* at least `500` ms. Don't use this method for testing, rely on web assertions to assess readiness instead.
* - `'commit'` - consider operation to be finished when network response is received and the document started
* loading.
*/
waitUntil?: 'load' | 'domcontentloaded' | 'networkidle' | 'commit'
}): Promise<null | Response>
/**
* Waits for the matching request and returns it. See [waiting for event](https://playwright.dev/docs/events#waiting-for-event) for more
* details about events.
*
* **Usage**
*
* ```js
* // Start waiting for request before clicking. Note no await.
* const requestPromise = page.waitForRequest('https://example.com/resource');
* await page.getByText('trigger request').click();
* const request = await requestPromise;
*
* // Alternative way with a predicate. Note no await.
* const requestPromise = page.waitForRequest(request =>
* request.url() === 'https://example.com' && request.method() === 'GET',
* );
* await page.getByText('trigger request').click();
* const request = await requestPromise;
* ```
*
* @param urlOrPredicate Request URL string, regex or predicate receiving [Request](https://playwright.dev/docs/api/class-request) object.
* @param options
*/
waitForRequest(
urlOrPredicate: string | RegExp | ((request: Request) => boolean | Promise<boolean>),
options?: {
/**
* Allows to cancel the waiting using an
* [`AbortSignal`](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal). If the signal is aborted, the
* waiting will be aborted and the operation will throw an error. Note that providing a signal does not disable the
* default timeout, which can be changed using
* [browserContext.setDefaultTimeout(timeout)](https://playwright.dev/docs/api/class-browsercontext#browser-context-set-default-timeout);
* pass `timeout: 0` to disable the timeout entirely.
*/
signal?: AbortSignal
/**
* Maximum wait time in milliseconds, defaults to 30 seconds, pass `0` to disable the timeout. The default value can
* be changed by using the
* [page.setDefaultTimeout(timeout)](https://playwright.dev/docs/api/class-page#page-set-default-timeout) method.
*/
timeout?: number
},
): Promise<Request>
/**
* Returns the matched response. See [waiting for event](https://playwright.dev/docs/events#waiting-for-event) for more details about
* events.
*
* **Usage**
*
* ```js
* // Start waiting for response before clicking. Note no await.
* const responsePromise = page.waitForResponse('https://example.com/resource');
* await page.getByText('trigger response').click();
* const response = await responsePromise;
*
* // Alternative way with a predicate. Note no await.
* const responsePromise = page.waitForResponse(response =>
* response.url() === 'https://example.com' && response.status() === 200
* && response.request().method() === 'GET'
* );
* await page.getByText('trigger response').click();
* const response = await responsePromise;
* ```
*
* @param urlOrPredicate Request URL string, regex or predicate receiving [Response](https://playwright.dev/docs/api/class-response) object.
* When a [`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.
* @param options
*/
waitForResponse(
urlOrPredicate: string | RegExp | ((response: Response) => boolean | Promise<boolean>),
options?: {
/**
* Allows to cancel the waiting using an
* [`AbortSignal`](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal). If the signal is aborted, the
* waiting will be aborted and the operation will throw an error. Note that providing a signal does not disable the
* default timeout, which can be changed using
* [browserContext.setDefaultTimeout(timeout)](https://playwright.dev/docs/api/class-browsercontext#browser-context-set-default-timeout);
* pass `timeout: 0` to disable the timeout entirely.
*/
signal?: AbortSignal
/**
* Maximum wait time in milliseconds, defaults to 30 seconds, pass `0` to disable the timeout. The default value can
* be changed 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.
*/
timeout?: number
},
): Promise<Response>
/**
* **NOTE** Never wait for timeout in production. Tests that wait for time are inherently flaky. Use
* [Locator](https://playwright.dev/docs/api/class-locator) actions and web assertions that wait automatically.
*
* Waits for the given [`timeout`](https://playwright.dev/docs/api/class-page#page-wait-for-timeout-option-timeout) in
* milliseconds.
*
* Note that `page.waitForTimeout()` should only be used for debugging. Tests using the timer in production are going
* to be flaky. Use signals such as network events, selectors becoming visible and others instead.
*
* **Usage**
*
* ```js
* // wait for 1 second
* await page.waitForTimeout(1000);
* ```
*
* @param timeout A timeout to wait for
*/
waitForTimeout(timeout: number): Promise<void>
/**
* Waits for the main frame to navigate to the given URL.
*
* **Usage**
*
* ```js
* await page.click('a.delayed-navigation'); // Clicking the link will indirectly cause a navigation
* await page.waitForURL('**\/target.html');
* ```
*
* @param url A glob pattern, regex pattern, URL pattern, or predicate receiving [URL] to match while waiting for the navigation.
* Note that if the parameter is a string without wildcard characters, the method will wait for navigation to URL that
* is exactly equal to the string.
* @param options
*/
waitForURL(
url: string | RegExp | URLPattern | ((url: URL) => boolean),
options?: {
/**
* Allows to cancel the waiting using an
* [`AbortSignal`](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal). If the signal is aborted, the
* waiting will be aborted and the operation will throw an error. Note that providing a signal does not disable the
* default timeout, which can be changed using
* [browserContext.setDefaultTimeout(timeout)](https://playwright.dev/docs/api/class-browsercontext#browser-context-set-default-timeout);
* pass `timeout: 0` to disable the timeout entirely.
*/
signal?: AbortSignal
/**
* Maximum operation time in milliseconds. Defaults to `0` - no timeout. The default value can be changed via
* `navigationTimeout` option in the config, or by using the
* [browserContext.setDefaultNavigationTimeout(timeout)](https://playwright.dev/docs/api/class-browsercontext#browser-context-set-default-navigation-timeout),
* [browserContext.setDefaultTimeout(timeout)](https://playwright.dev/docs/api/class-browsercontext#browser-context-set-default-timeout),
* [page.setDefaultNavigationTimeout(timeout)](https://playwright.dev/docs/api/class-page#page-set-default-navigation-timeout)
* or [page.setDefaultTimeout(timeout)](https://playwright.dev/docs/api/class-page#page-set-default-timeout) methods.
*/
timeout?: number
/**
* When to consider operation succeeded, defaults to `load`. Events can be either:
* - `'domcontentloaded'` - consider operation to be finished when the `DOMContentLoaded` event is fired.
* - `'load'` - consider operation to be finished when the `load` event is fired.
* - `'networkidle'` - **DISCOURAGED** consider operation to be finished when there are no network connections for
* at least `500` ms. Don't use this method for testing, rely on web assertions to assess readiness instead.
* - `'commit'` - consider operation to be finished when network response is received and the document started
* loading.
*/
waitUntil?: 'load' | 'domcontentloaded' | 'networkidle' | 'commit'
},
): Promise<void>
/**
* This method returns all of the dedicated
* [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<Worker>
/**
* Playwright has ability to mock clock and passage of time.
*/
clock: Clock
/**
* **NOTE** Only available for Chromium atm.
*
* Browser-specific Coverage implementation. See [Coverage](https://playwright.dev/docs/api/class-coverage) for more
* details.
*/
coverage: Coverage
keyboard: Keyboard
/**
* Provides access to the page's `localStorage` for the current origin. See
* [WebStorage](https://playwright.dev/docs/api/class-webstorage).
*
* ```js
* await page.localStorage.setItem('token', 'abc');
* const token = await page.localStorage.getItem('token');
* ```
*
*/
localStorage: WebStorage
mouse: Mouse
/**
* API testing helper associated with this page. This method returns the same instance as
* [browserContext.request](https://playwright.dev/docs/api/class-browsercontext#browser-context-request) on the
* page's context. See
* [browserContext.request](https://playwright.dev/docs/api/class-browsercontext#browser-context-request) for more
* details.
*/
request: APIRequestContext
/**
* [Screencast](https://playwright.dev/docs/api/class-screencast) object associated with this page.
*
* **Usage**
*
* ```js
* page.screencast.on('screencastFrame', data => {
* console.log('received frame, jpeg size:', data.length);
* });
* await page.screencast.start();
* // ... perform actions ...
* await page.screencast.stop();
* ```
*
*/
screencast: Screencast
/**
* Provides access to the page's `sessionStorage` for the current origin. See
* [WebStorage](https://playwright.dev/docs/api/class-webstorage).
*
* ```js
* await page.sessionStorage.setItem('flag', '1');
* const flag = await page.sessionStorage.getItem('flag');
* ```
*
*/
sessionStorage: WebStorage
touchscreen: Touchscreen
[Symbol.asyncDispose](): Promise<void>
}
PlaywrightTestArgs
Playwright Test is based on the concept of the test fixtures. Test fixtures are used to establish environment for each test, giving the test everything it needs and nothing else.
Playwright Test looks at each test declaration, analyses the set of fixtures the test needs and prepares those
fixtures specifically for the test. Values prepared by the fixtures are merged into a single object that is
available to the test, hooks, annotations and other fixtures as a first parameter.
import { test, expect } from '@playwright/test'
test('basic test', async ({ page }) => {
// ...
})
Given the test above, Playwright Test will set up the page fixture before running the test, and tear it down
after the test has finished. page fixture provides a Page object
that is available to the test.
Playwright Test comes with builtin fixtures listed below, and you can add your own fixtures as well. Playwright Test also [provides options]TestOptions to configure fixtures.browser, fixtures.context and fixtures.page.
interface PlaywrightTestArgs {
/**
* Isolated [BrowserContext](https://playwright.dev/docs/api/class-browsercontext) instance, created for each test.
* Since contexts are isolated between each other, every test gets a fresh environment, even when multiple tests run
* in a single [Browser](https://playwright.dev/docs/api/class-browser) for maximum efficiency.
*
* Learn how to [configure context](https://playwright.dev/docs/test-configuration) and see
* [available options][TestOptions](https://playwright.dev/docs/api/class-testoptions).
*
* Default [fixtures.page](https://playwright.dev/docs/api/class-fixtures#fixtures-page) belongs to this context.
*
* **Usage**
*
* ```js
* test('example test', async ({ page, context }) => {
* await context.route('*external.com/*', route => route.abort());
* // ...
* });
* ```
*
*/
context: BrowserContext
/**
* Isolated [Page](https://playwright.dev/docs/api/class-page) instance, created for each test. Pages are isolated
* between tests due to [fixtures.context](https://playwright.dev/docs/api/class-fixtures#fixtures-context) isolation.
*
* This is the most common fixture used in a test.
*
* **Usage**
*
* ```js
* import { test, expect } from '@playwright/test';
*
* test('basic test', async ({ page }) => {
* await page.goto('/signin');
* await page.getByLabel('User Name').fill('user');
* await page.getByLabel('Password').fill('password');
* await page.getByText('Sign in').click();
* // ...
* });
* ```
*
*/
page: Page
/**
* Isolated [APIRequestContext](https://playwright.dev/docs/api/class-apirequestcontext) instance for each test.
*
* **Usage**
*
* ```js
* import { test, expect } from '@playwright/test';
*
* test('basic test', async ({ request }) => {
* await request.post('/signin', {
* data: {
* username: 'user',
* password: 'password'
* }
* });
* // ...
* });
* ```
*
*/
request: APIRequestContext
/**
* Mounts a component story and returns a [Locator](https://playwright.dev/docs/api/class-locator) pointing to the
* root element the story was rendered into. Scope your queries from the returned locator:
* `component.getByRole('button')`, not `page.getByRole('button')`.
*
* A **story** is a small wrapper component that embeds the component under test in one specific scenario: hard-coded
* props, mock data, providers, recorded callbacks. Stories are rendered by a **gallery** page that you implement and
* serve at [testOptions.baseURL](https://playwright.dev/docs/api/class-testoptions#test-options-base-url). The
* gallery exposes `window.mount(params)` and `window.unmount()` functions that render a story into its root element.
* Each call to [fixtures.mount(storyId[, props])](https://playwright.dev/docs/api/class-fixtures#fixtures-mount)
* navigates to [testOptions.baseURL](https://playwright.dev/docs/api/class-testoptions#test-options-base-url) and
* calls `window.mount()` with the story id and props, so tests are fully isolated from each other.
*
* **Usage**
*
* ```js
* test('click should expand', async ({ mount }) => {
* const component = await mount('components/Expandable/Stateful');
* await component.getByRole('button').click();
* await expect(component.getByTestId('expanded')).toHaveValue('true');
* });
* ```
*
* Pass the story type as a template argument to type-check the props:
*
* ```js
* import type { WithTitle } from './Button.story';
*
* test('renders the title', async ({ mount }) => {
* const component = await mount<typeof WithTitle>('Button/WithTitle', { title: 'Hello' });
* await expect(component).toContainText('Hello');
* });
* ```
*
* The returned locator is augmented with two methods:
* - `update(props)` - re-renders the same story with new props without remounting, preserving component state;
* - `unmount()` - unmounts the story.
* @param storyId Identifier of the story to mount, as resolved by the gallery page. Conventionally, the story file path plus the
* exported story name, for example `'components/Button/Primary'`.
* @param props Optional plain, serializable props passed to the story.
*/
mount: <Story = never, Id extends StoryId = StoryId>(
storyId: Id,
props?: MountProps<Story, Id>,
) => Promise<
Locator & { update(props?: MountProps<Story, Id>): Promise<void>; unmount(): Promise<void> }
>
}
PlaywrightTestOptions
Playwright Test provides many options to configure test environment, Browser, BrowserContext and more.
These options are usually provided in the configuration file through testConfig.use and testProject.use.
// playwright.config.ts
import { defineConfig } from '@playwright/test'
export default defineConfig({
use: {
headless: false,
viewport: { width: 1280, height: 720 },
ignoreHTTPSErrors: true,
video: 'on-first-retry',
},
})
Alternatively, with test.use(options) you can override some options for a file.
// example.spec.ts
import { test, expect } from '@playwright/test'
// Run tests in this file with portrait-like viewport.
test.use({ viewport: { width: 600, height: 900 } })
test('my portrait test', async ({ page }) => {
// ...
})
interface PlaywrightTestOptions {
/**
* Whether to automatically download all the attachments. Defaults to `true` where all the downloads are accepted.
*
* **Usage**
*
* ```js
* // playwright.config.ts
* import { defineConfig } from '@playwright/test';
*
* export default defineConfig({
* use: {
* acceptDownloads: false,
* },
* });
* ```
*
*/
acceptDownloads: boolean
/**
* Toggles bypassing page's Content-Security-Policy. Defaults to `false`.
*
* **Usage**
*
* ```js
* // playwright.config.ts
* import { defineConfig } from '@playwright/test';
*
* export default defineConfig({
* use: {
* bypassCSP: true,
* }
* });
* ```
*
*/
bypassCSP: boolean
/**
* Emulates [prefers-colors-scheme](https://developer.mozilla.org/en-US/docs/Web/CSS/@media/prefers-color-scheme)
* 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'`.
*
* **Usage**
*
* ```js
* // playwright.config.ts
* import { defineConfig } from '@playwright/test';
*
* export default defineConfig({
* use: {
* colorScheme: 'dark',
* },
* });
* ```
*
*/
colorScheme: ColorScheme
/**
* 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'`.
*
* **Usage**
*
* ```js
* // playwright.config.ts
* import { defineConfig } from '@playwright/test';
*
* export default defineConfig({
* use: {
* contrast: 'more',
* },
* });
* ```
*
*/
contrast: Contrast
/**
* TLS Client Authentication allows the server to request a client certificate and verify it.
*
* **Details**
*
* An array of client certificates to be used. Each certificate object must have either both `certPath` and `keyPath`,
* a single `pfxPath`, or their corresponding direct value equivalents (`cert` and `key`, or `pfx`). Optionally,
* `passphrase` property should be provided if the certificate is encrypted. The `origin` property should be provided
* with an exact match to the request origin that the certificate is valid for.
*
* Client certificate authentication is only active when at least one client certificate is provided. If you want to
* reject all client certificates sent by the server, you need to provide a client certificate with an `origin` that
* does not match any of the domains you plan to visit.
*
* **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`.
*
* **Usage**
*
* ```js
* // playwright.config.ts
* import { defineConfig } from '@playwright/test';
*
* export default defineConfig({
* use: {
* clientCertificates: [{
* origin: 'https://example.com',
* certPath: './cert.pem',
* keyPath: './key.pem',
* passphrase: 'mysecretpassword',
* }],
* },
* });
* ```
*
*/
clientCertificates: ClientCertificate[] | undefined
/**
* 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).
*
* **Usage**
*
* ```js
* // playwright.config.ts
* import { defineConfig } from '@playwright/test';
*
* export default defineConfig({
* use: {
* viewport: { width: 2560, height: 1440 },
* deviceScaleFactor: 2,
* },
* });
* ```
*
*/
deviceScaleFactor: number | undefined
/**
* An object containing additional HTTP headers to be sent with every request. Defaults to none.
*
* **Usage**
*
* ```js
* // playwright.config.ts
* import { defineConfig } from '@playwright/test';
*
* export default defineConfig({
* use: {
* extraHTTPHeaders: {
* 'X-My-Header': 'value',
* },
* },
* });
* ```
*
*/
extraHTTPHeaders: ExtraHTTPHeaders | undefined
/**
* 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'`.
*
* **Usage**
*
* ```js
* // playwright.config.ts
* import { defineConfig } from '@playwright/test';
*
* export default defineConfig({
* use: {
* forcedColors: 'active',
* },
* });
* ```
*
*/
forcedColors: ForcedColors
/**
* **Usage**
*
* ```js
* // playwright.config.ts
* import { defineConfig } from '@playwright/test';
*
* export default defineConfig({
* use: {
* geolocation: { longitude: 12.492507, latitude: 41.889938 },
* },
* });
* ```
*
* Learn more about [geolocation](https://playwright.dev/docs/emulation#color-scheme-and-media).
*/
geolocation: Geolocation | undefined
/**
* Specifies if viewport supports touch events. Defaults to false. Learn more about
* [mobile emulation](https://playwright.dev/docs/emulation#devices).
*
* **Usage**
*
* ```js
* // playwright.config.ts
* import { defineConfig } from '@playwright/test';
*
* export default defineConfig({
* use: {
* hasTouch: true
* },
* });
* ```
*
*/
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.
*
* Pass an array to use different credentials for different origins. The first entry that matches the request origin
* is used, and entries with no origin match any request.
*
* **Usage**
*
* ```js
* // playwright.config.ts
* import { defineConfig } from '@playwright/test';
*
* export default defineConfig({
* use: {
* httpCredentials: {
* username: 'user',
* password: 'pass',
* },
* },
* });
* ```
*
*/
httpCredentials: HTTPCredentials | HTTPCredentials[] | undefined
/**
* Whether to ignore HTTPS errors when sending network requests. Defaults to `false`.
*
* **Usage**
*
* ```js
* // playwright.config.ts
* import { defineConfig } from '@playwright/test';
*
* export default defineConfig({
* use: {
* ignoreHTTPSErrors: true,
* },
* });
* ```
*
*/
ignoreHTTPSErrors: boolean
/**
* 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).
*
* **Usage**
*
* ```js
* // playwright.config.ts
* import { defineConfig } from '@playwright/test';
*
* export default defineConfig({
* use: {
* isMobile: false,
* },
* });
* ```
*
*/
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).
*
* **Usage**
*
* ```js
* // playwright.config.ts
* import { defineConfig } from '@playwright/test';
*
* export default defineConfig({
* use: {
* javaScriptEnabled: false,
* },
* });
* ```
*
*/
javaScriptEnabled: boolean
/**
* 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 `en-US`. Learn more
* about emulation in our [emulation guide](https://playwright.dev/docs/emulation#locale--timezone).
*
* **Usage**
*
* ```js
* // playwright.config.ts
* import { defineConfig } from '@playwright/test';
*
* export default defineConfig({
* use: {
* locale: 'it-IT',
* },
* });
* ```
*
*/
locale: string | undefined
/**
* Whether to emulate network being offline. Defaults to `false`. Learn more about
* [network emulation](https://playwright.dev/docs/emulation#offline).
*
* **Usage**
*
* ```js
* // playwright.config.ts
* import { defineConfig } from '@playwright/test';
*
* export default defineConfig({
* use: {
* offline: true
* },
* });
* ```
*
*/
offline: boolean
/**
* 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.
*
* **Usage**
*
* ```js
* // playwright.config.ts
* import { defineConfig } from '@playwright/test';
*
* export default defineConfig({
* use: {
* permissions: ['notifications'],
* },
* });
* ```
*
*/
permissions: string[] | undefined
/**
* Network proxy settings.
*
* **Usage**
*
* ```js
* // playwright.config.ts
* import { defineConfig } from '@playwright/test';
*
* export default defineConfig({
* use: {
* proxy: {
* server: 'http://myproxy.com:3128',
* bypass: 'localhost',
* },
* },
* });
* ```
*
*/
proxy: Proxy | undefined
/**
* 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'`.
*
* **Usage**
*
* ```js
* // playwright.config.ts
* import { defineConfig } from '@playwright/test';
*
* export default defineConfig({
* use: {
* reducedMotion: 'reduce',
* },
* });
* ```
*
*/
reducedMotion: ReducedMotion
/**
* Learn more about [storage state and auth](https://playwright.dev/docs/auth).
*
* 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).
*
* **Usage**
*
* ```js
* // playwright.config.ts
* import { defineConfig } from '@playwright/test';
*
* export default defineConfig({
* use: {
* storageState: 'storage-state.json',
* },
* });
* ```
*
* **Details**
*
* When storage state is set up in the config, it is possible to reset storage state for a file:
*
* ```js
* // not-signed-in.spec.ts
* import { test } from '@playwright/test';
*
* // Reset storage state for this file to avoid being authenticated
* test.use({ storageState: { cookies: [], origins: [] } });
*
* test('not signed in test', async ({ page }) => {
* // ...
* });
* ```
*
*/
storageState: StorageState | undefined
/**
* 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.
*
* **Usage**
*
* ```js
* // playwright.config.ts
* import { defineConfig } from '@playwright/test';
*
* export default defineConfig({
* use: {
* timezoneId: 'Europe/Rome',
* },
* });
* ```
*
*/
timezoneId: string | undefined
/**
* Specific user agent to use in this context.
*
* **Usage**
*
* ```js
* // playwright.config.ts
* import { defineConfig } from '@playwright/test';
*
* export default defineConfig({
* use: {
* userAgent: 'some custom ua',
* },
* });
* ```
*
*/
userAgent: string | undefined
/**
* 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.
*
* **Usage**
*
* ```js
* // playwright.config.ts
* import { defineConfig } from '@playwright/test';
*
* export default defineConfig({
* use: {
* viewport: { width: 100, height: 100 },
* },
* });
* ```
*
*/
viewport: ViewportSize | null
/**
* When using [page.goto(url[, options])](https://playwright.dev/docs/api/class-page#page-goto),
* [page.route(url, handler[, options])](https://playwright.dev/docs/api/class-page#page-route),
* [page.waitForURL(url[, options])](https://playwright.dev/docs/api/class-page#page-wait-for-url),
* [page.waitForRequest(urlOrPredicate[, options])](https://playwright.dev/docs/api/class-page#page-wait-for-request),
* or
* [page.waitForResponse(urlOrPredicate[, options])](https://playwright.dev/docs/api/class-page#page-wait-for-response)
* it takes the base URL in consideration by using the
* [`URL()`](https://developer.mozilla.org/en-US/docs/Web/API/URL/URL) constructor for building the corresponding URL.
* Unset by default. Examples:
* - baseURL: `http://localhost:3000` and navigating to `/bar.html` results in `http://localhost:3000/bar.html`
* - baseURL: `http://localhost:3000/foo/` and navigating to `./bar.html` results in
* `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`
*
* **Usage**
*
* ```js
* import { defineConfig, devices } from '@playwright/test';
*
* export default defineConfig({
* use: {
* /* Base URL to use in actions like `await page.goto('/')`. *\/
* baseURL: 'http://localhost:3000',
* },
* });
* ```
*
*/
baseURL: string | undefined
/**
* Options used to create the context, as passed to
* [browser.newContext([options])](https://playwright.dev/docs/api/class-browser#browser-new-context). Specific
* options like [testOptions.viewport](https://playwright.dev/docs/api/class-testoptions#test-options-viewport) take
* priority over this.
*
* **Usage**
*
* ```js
* // playwright.config.ts
* import { defineConfig } from '@playwright/test';
*
* export default defineConfig({
* use: {
* contextOptions: {
* reducedMotion: 'reduce',
* },
* },
* });
* ```
*
*/
contextOptions: BrowserContextOptions
/**
* Default timeout for each Playwright action in milliseconds, defaults to 0 (no timeout).
*
* This is a default timeout for all Playwright actions, same as configured via
* [page.setDefaultTimeout(timeout)](https://playwright.dev/docs/api/class-page#page-set-default-timeout).
*
* **Usage**
*
* ```js
* import { defineConfig, devices } from '@playwright/test';
*
* export default defineConfig({
* use: {
* /* Maximum time each action such as `click()` can take. Defaults to 0 (no limit). *\/
* actionTimeout: 0,
* },
* });
* ```
*
* Learn more about [various timeouts](https://playwright.dev/docs/test-timeouts).
*/
actionTimeout: number
/**
* Timeout for each navigation action in milliseconds. Defaults to 0 (no timeout).
*
* This is a default navigation timeout, same as configured via
* [page.setDefaultNavigationTimeout(timeout)](https://playwright.dev/docs/api/class-page#page-set-default-navigation-timeout).
*
* **Usage**
*
* ```js
* // playwright.config.ts
* import { defineConfig } from '@playwright/test';
*
* export default defineConfig({
* use: {
* navigationTimeout: 3000,
* },
* });
* ```
*
* Learn more about [various timeouts](https://playwright.dev/docs/test-timeouts).
*/
navigationTimeout: number
/**
* Whether to allow sites to register Service workers. Defaults to `'allow'`.
* - `'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.
*
* **Usage**
*
* ```js
* // playwright.config.ts
* import { defineConfig } from '@playwright/test';
*
* export default defineConfig({
* use: {
* serviceWorkers: 'allow'
* },
* });
* ```
*
*/
serviceWorkers: ServiceWorkerPolicy
/**
* Custom attribute to be used in
* [page.getByTestId(testId)](https://playwright.dev/docs/api/class-page#page-get-by-test-id). `data-testid` is used
* by default. To match elements with any of several attributes, pass them as a comma-separated list.
*
* **Usage**
*
* ```js
* // playwright.config.ts
* import { defineConfig } from '@playwright/test';
*
* export default defineConfig({
* use: {
* testIdAttribute: 'pw-test-id',
* },
* });
* ```
*
* Multiple attributes:
*
* ```js
* // playwright.config.ts
* import { defineConfig } from '@playwright/test';
*
* export default defineConfig({
* use: {
* testIdAttribute: 'data-pw,data-ti',
* },
* });
* ```
*
*/
testIdAttribute: string
}
PlaywrightWorkerArgs
Playwright Test is based on the concept of the test fixtures. Test fixtures are used to establish environment for each test, giving the test everything it needs and nothing else.
Playwright Test looks at each test declaration, analyses the set of fixtures the test needs and prepares those
fixtures specifically for the test. Values prepared by the fixtures are merged into a single object that is
available to the test, hooks, annotations and other fixtures as a first parameter.
import { test, expect } from '@playwright/test'
test('basic test', async ({ page }) => {
// ...
})
Given the test above, Playwright Test will set up the page fixture before running the test, and tear it down
after the test has finished. page fixture provides a Page object
that is available to the test.
Playwright Test comes with builtin fixtures listed below, and you can add your own fixtures as well. Playwright Test also [provides options]TestOptions to configure fixtures.browser, fixtures.context and fixtures.page.
interface PlaywrightWorkerArgs {
playwright: typeof import('playwright-core')
/**
* [Browser](https://playwright.dev/docs/api/class-browser) instance is shared between all tests in the
* [same worker](https://playwright.dev/docs/test-parallel) - this makes testing efficient. However, each test runs in an isolated
* [BrowserContext](https://playwright.dev/docs/api/class-browsercontext) and gets a fresh environment.
*
* Learn how to [configure browser](https://playwright.dev/docs/test-configuration) and see
* [available options][TestOptions](https://playwright.dev/docs/api/class-testoptions).
*
* **Usage**
*
* ```js
* test.beforeAll(async ({ browser }) => {
* const page = await browser.newPage();
* // ...
* });
* ```
*
*/
browser: Browser
}
PlaywrightWorkerOptions
Playwright Test provides many options to configure test environment, Browser, BrowserContext and more.
These options are usually provided in the configuration file through testConfig.use and testProject.use.
// playwright.config.ts
import { defineConfig } from '@playwright/test'
export default defineConfig({
use: {
headless: false,
viewport: { width: 1280, height: 720 },
ignoreHTTPSErrors: true,
video: 'on-first-retry',
},
})
Alternatively, with test.use(options) you can override some options for a file.
// example.spec.ts
import { test, expect } from '@playwright/test'
// Run tests in this file with portrait-like viewport.
test.use({ viewport: { width: 600, height: 900 } })
test('my portrait test', async ({ page }) => {
// ...
})
interface PlaywrightWorkerOptions {
/**
* Name of the browser that runs tests. Defaults to `'chromium'`. Most of the time you should set `browserName` in
* your [TestConfig](https://playwright.dev/docs/api/class-testconfig):
*
* **Usage**
*
* ```js
* // playwright.config.ts
* import { defineConfig, devices } from '@playwright/test';
*
* export default defineConfig({
* use: {
* browserName: 'firefox',
* },
* });
* ```
*
*/
browserName: BrowserName
defaultBrowserType: BrowserName
/**
* 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`.
*
* **Usage**
*
* ```js
* // playwright.config.ts
* import { defineConfig } from '@playwright/test';
*
* export default defineConfig({
* use: {
* headless: false
* },
* });
* ```
*
*/
headless: boolean
/**
* Browser distribution channel.
*
* Use "chromium" to [opt in to new headless mode](https://playwright.dev/docs/browsers#chromium-new-headless-mode).
*
* 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).
*
* **Usage**
*
* ```js
* // playwright.config.ts
* import { defineConfig } from '@playwright/test';
*
* export default defineConfig({
* projects: [
* {
* name: 'Microsoft Edge',
* use: {
* ...devices['Desktop Edge'],
* channel: 'msedge'
* },
* },
* ]
* });
* ```
*
*/
channel: BrowserChannel | undefined
/**
* Options used to launch the browser, as passed to
* [browserType.launch([options])](https://playwright.dev/docs/api/class-browsertype#browser-type-launch). Specific
* options [testOptions.headless](https://playwright.dev/docs/api/class-testoptions#test-options-headless) and
* [testOptions.channel](https://playwright.dev/docs/api/class-testoptions#test-options-channel) take priority over
* this.
*
* **NOTE** Use custom browser args at your own risk, as some of them may break Playwright functionality.
*
* **Usage**
*
* ```js
* // playwright.config.ts
* import { defineConfig } from '@playwright/test';
*
* export default defineConfig({
* projects: [
* {
* name: 'chromium',
* use: {
* ...devices['Desktop Chrome'],
* launchOptions: {
* args: ['--start-maximized']
* }
* }
* }
* ]
* });
* ```
*
*/
launchOptions: Omit<LaunchOptions, 'tracesDir'>
/**
* **Usage**
*
* ```js
* // playwright.config.ts
* import { defineConfig } from '@playwright/test';
*
* export default defineConfig({
* use: {
* connectOptions: {
* wsEndpoint: 'ws://localhost:5678',
* },
* },
* });
* ```
*
* When connect options are specified, default
* [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) use the remote browser instead of
* 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.
*/
connectOptions: ConnectOptions | undefined
/**
* **NOTE** This option trades test isolation for speed and is intended for component tests that drive a story gallery. Leave
* it unset for end-to-end tests - a fresh browser context per test is one of the core guarantees of Playwright Test.
*
* **Experimental.** When set to `true`, all tests in a worker process run in a single browser context that is reused
* between tests, instead of getting a brand new context per test. Defaults to `false`.
*
* Between tests, Playwright resets the state that component tests typically touch: it clears cookies, cache, local
* storage and IndexedDB of visited origins, unregisters service workers, closes extra pages, removes routes, bindings
* and init scripts, and re-applies the configured storage state, viewport and emulation options.
*
* This reset is best-effort, not a guarantee of isolation. State that is **not** reset includes:
* - Permissions granted with
* [browserContext.grantPermissions(permissions[, options])](https://playwright.dev/docs/api/class-browsercontext#browser-context-grant-permissions)
* during a test.
* - Runtime changes made through
* [browserContext.setGeolocation(geolocation)](https://playwright.dev/docs/api/class-browsercontext#browser-context-set-geolocation),
* [browserContext.setOffline(offline)](https://playwright.dev/docs/api/class-browsercontext#browser-context-set-offline)
* and
* [browserContext.setExtraHTTPHeaders(headers)](https://playwright.dev/docs/api/class-browsercontext#browser-context-set-extra-http-headers).
* - Browsing history, `window.name` and any browser-process-wide state.
*
* Additional restrictions:
* - The option is ignored when
* [testOptions.video](https://playwright.dev/docs/api/class-testoptions#test-options-video) recording is enabled.
* - Only a few context options may differ between consecutive tests: `colorScheme`, `forcedColors`,
* `reducedMotion`, `contrast`, `screen`, `userAgent`, `viewport` and `testIdAttribute`. Changing any other option
* in [test.use(options)](https://playwright.dev/docs/api/class-test#test-use), for example `locale` or
* `storageState`, silently forces a fresh context and negates the speedup.
* - Do not combine with
* [testOptions.connectOptions](https://playwright.dev/docs/api/class-testoptions#test-options-connect-options)
* pointing multiple workers at a shared browser - workers would compete for the single reusable context.
* - `recordHar` in
* [testOptions.contextOptions](https://playwright.dev/docs/api/class-testoptions#test-options-context-options) is
* not supported and produces no HAR file.
*
* **Usage**
*
* ```js
* // playwright.config.ts
* import { defineConfig } from '@playwright/test';
*
* export default defineConfig({
* projects: [
* {
* name: 'components',
* testDir: './tests/components',
* use: { reuseContext: true },
* },
* ],
* });
* ```
*
*/
reuseContext: boolean
/**
* Whether to automatically capture a screenshot after each test. Defaults to `'off'`.
* - `'off'`: Do not capture screenshots.
* - `'on'`: Capture screenshot after each test.
* - `'only-on-failure'`: Capture screenshot after each test failure.
* - `'on-first-failure'`: Capture screenshot after each test's first failure.
*
* **Usage**
*
* ```js
* // playwright.config.ts
* import { defineConfig } from '@playwright/test';
*
* export default defineConfig({
* use: {
* screenshot: 'only-on-failure',
* },
* });
* ```
*
* Learn more about [automatic screenshots](https://playwright.dev/docs/test-use-options#recording-options).
*/
screenshot:
| ScreenshotMode
| ({ mode: ScreenshotMode } & Pick<PageScreenshotOptions, 'fullPage' | 'omitBackground'>)
/**
* Whether to record trace for each test. Defaults to `'off'`. The initial run of a test is the "first run";
* subsequent runs caused by [retries](https://playwright.dev/docs/test-retries) are "retries".
* - `'off'`: Do not record trace.
* - `'on'`: Record and keep a trace for every run.
* - `'on-first-retry'`: Record and keep a trace only for the first retry of a test.
* - `'on-all-retries'`: Record and keep a trace for every retry.
* - `'retain-on-failure'`: Record a trace for every run, but keep it only for runs that failed. A failed run's
* trace is kept even when a later retry passes.
* - `'retain-on-first-failure'`: Record a trace only for the first run of a test (not for retries), and keep it
* only if that run failed.
* - `'retain-on-failure-and-retries'`: Record a trace for every run, and keep it for any run that failed or that is
* a retry.
*
* See [trace modes](https://playwright.dev/docs/test-use-options#trace-modes) for a side-by-side comparison of what each mode records and
* keeps.
*
* For more control, pass an object that specifies `mode` and trace features to enable.
*
* **Usage**
*
* ```js
* // playwright.config.ts
* import { defineConfig } from '@playwright/test';
*
* export default defineConfig({
* use: {
* trace: 'on-first-retry'
* },
* });
* ```
*
* Learn more about [recording trace](https://playwright.dev/docs/test-use-options#recording-options).
*/
trace:
| TraceMode
| /** deprecated */ 'retry-with-trace'
| {
mode: TraceMode
snapshots?: boolean | { dom?: boolean; aria?: boolean; screen?: boolean }
screenshots?: boolean
sources?: boolean
attachments?: boolean
}
/**
* Whether to record video for each test. Defaults to `'off'`. The initial run of a test is the "first run";
* subsequent runs caused by [retries](https://playwright.dev/docs/test-retries) are "retries".
* - `'off'`: Do not record video.
* - `'on'`: Record and keep a video for every run.
* - `'on-first-retry'`: Record and keep a video only for the first retry of a test.
* - `'on-all-retries'`: Record and keep a video for every retry.
* - `'retain-on-failure'`: Record a video for every run, but keep it only for runs that failed. A failed run's
* video is kept even when a later retry passes.
* - `'retain-on-first-failure'`: Record a video only for the first run of a test (not for retries), and keep it
* only if that run failed.
* - `'retain-on-failure-and-retries'`: Record a video for every run, and keep it for any run that failed or that is
* a retry.
*
* See [video modes](https://playwright.dev/docs/test-use-options#video-modes) for a side-by-side comparison of what each mode records and
* keeps.
*
* To control video size, pass an object with `mode` and `size` properties. If video size is not specified, it will be
* equal to [testOptions.viewport](https://playwright.dev/docs/api/class-testoptions#test-options-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.
*
* To annotate actions in the video, pass `show` with `action` and/or `test` sub-options. The `action` option controls
* visual highlights on interacted elements with an optional `delay` in milliseconds (defaults to `500`). The `test`
* option controls which test information is displayed as a status overlay.
*
* **Usage**
*
* ```js
* // playwright.config.ts
* import { defineConfig } from '@playwright/test';
*
* export default defineConfig({
* use: {
* video: 'on-first-retry',
* },
* });
* ```
*
* Learn more about [recording video](https://playwright.dev/docs/test-use-options#recording-options).
*/
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
cursor?: 'none' | 'pointer'
}
test?: {
level?: 'file' | 'title' | 'step'
position?: 'top-left' | 'top' | 'top-right' | 'bottom-left' | 'bottom' | 'bottom-right'
fontSize?: number
}
}
}
}
Request
Whenever the page sends a request for a network resource the following sequence of events are emitted by Page:
- page.on('request') emitted when the request is issued by the page.
- page.on('response') emitted when/if the response status and headers are received for the request.
- page.on('requestfinished') emitted when the response body is downloaded and the request is complete.
If request fails at some point, then instead of 'requestfinished' event (and possibly instead of 'response'
event), the page.on('requestfailed') event
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.
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.
interface Request {
/**
* An object with all the request HTTP headers associated with this request. The header names are lower-cased.
*/
allHeaders(): Promise<{ [key: string]: string }>
/**
* Returns the [Response](https://playwright.dev/docs/api/class-response) object if the response has already been
* received, `null` otherwise.
*
* Unlike [request.response()](https://playwright.dev/docs/api/class-request#request-response), this method does not
* wait for the response to arrive. It returns immediately with the response object if the response has been received,
* or `null` if the response has not been received yet.
*/
existingResponse(): null | Response
/**
* The method returns `null` unless this request has failed, as reported by `requestfailed` event.
*
* **Usage**
*
* Example of logging of all the failed requests:
*
* ```js
* page.on('requestfailed', request => {
* console.log(request.url() + ' ' + request.failure().errorText);
* });
* ```
*
*/
failure(): null | {
/**
* Human-readable error message, e.g. `'net::ERR_FAILED'`.
*/
errorText: string
}
/**
* Returns the [Frame](https://playwright.dev/docs/api/class-frame) that initiated this request.
*
* **Usage**
*
* ```js
* const frameUrl = request.frame().url();
* ```
*
* **Details**
*
* Note that in some cases the frame is not available, and this method will throw.
* - When request originates in the Service Worker. You can use `request.serviceWorker()` to check that.
* - When navigation request is issued before the corresponding frame is created. You can use
* [request.isNavigationRequest()](https://playwright.dev/docs/api/class-request#request-is-navigation-request) to
* check that.
*
* Here is an example that handles all the cases:
*
* ```js
* if (request.serviceWorker())
* console.log(`request ${request.url()} from a service worker`);
* else if (request.isNavigationRequest())
* console.log(`request ${request.url()} is a navigation request`);
* else
* console.log(`request ${request.url()} from a frame ${request.frame().url()}`);
* ```
*
*/
frame(): Frame
/**
* An object with the request HTTP headers. The header names are lower-cased. Note that this method does not return
* security-related headers, including cookie-related ones. You can use
* [request.allHeaders()](https://playwright.dev/docs/api/class-request#request-all-headers) for complete list of
* headers that include `cookie` information.
*/
headers(): { [key: string]: string }
/**
* An array with all the request HTTP headers associated with this request. Unlike
* [request.allHeaders()](https://playwright.dev/docs/api/class-request#request-all-headers), header names are NOT
* lower-cased. Headers with multiple entries, such as `Set-Cookie`, appear in the array multiple times.
*/
headersArray(): Promise<
Array<{
/**
* Name of the header.
*/
name: string
/**
* Value of the header.
*/
value: string
}>
>
/**
* Returns the value of the header matching the name. The name is case-insensitive.
* @param name Name of the header.
*/
headerValue(name: string): Promise<null | string>
/**
* Whether this request is driving frame's navigation.
*
* Some navigation requests are issued before the corresponding frame is created, and therefore do not have
* [request.frame()](https://playwright.dev/docs/api/class-request#request-frame) available.
*/
isNavigationRequest(): boolean
/**
* Request's method (GET, POST, etc.)
*/
method(): string
/**
* Request's post body, if any.
*/
postData(): null | string
/**
* Request's post body in a binary form, if any.
*/
postDataBuffer(): null | Buffer
/**
* Returns parsed request's body for `form-urlencoded` and JSON as a fallback if any.
*
* When the response is `application/x-www-form-urlencoded` then a key/value object of the values will be returned.
* Otherwise it will be parsed as JSON.
*/
postDataJSON(): null | Serializable
/**
* Request that was redirected by the server to this one, if any.
*
* When the server responds with a redirect, Playwright creates a new
* [Request](https://playwright.dev/docs/api/class-request) object. The two requests are connected by
* `redirectedFrom()` and `redirectedTo()` methods. When multiple server redirects has happened, it is possible to
* construct the whole redirect chain by repeatedly calling `redirectedFrom()`.
*
* **Usage**
*
* For example, if the website `http://example.com` redirects to `https://example.com`:
*
* ```js
* const response = await page.goto('http://example.com');
* console.log(response.request().redirectedFrom().url()); // 'http://example.com'
* ```
*
* If the website `https://google.com` has no redirects:
*
* ```js
* const response = await page.goto('https://google.com');
* console.log(response.request().redirectedFrom()); // null
* ```
*
*/
redirectedFrom(): null | Request
/**
* New request issued by the browser if the server responded with redirect.
*
* **Usage**
*
* This method is the opposite of
* [request.redirectedFrom()](https://playwright.dev/docs/api/class-request#request-redirected-from):
*
* ```js
* console.log(request.redirectedFrom().redirectedTo() === request); // true
* ```
*
*/
redirectedTo(): null | Request
/**
* Contains the request's resource type as it was perceived by the rendering engine. ResourceType will be one of the
* following: `document`, `stylesheet`, `image`, `media`, `font`, `script`, `texttrack`, `xhr`, `fetch`,
* `eventsource`, `websocket`, `manifest`, `other`.
*/
resourceType(): string
/**
* Returns the matching [Response](https://playwright.dev/docs/api/class-response) object, or `null` if the response
* was not received due to error.
*/
response(): Promise<null | Response>
/**
* The Service [Worker](https://playwright.dev/docs/api/class-worker) that is performing the request.
*
* **Details**
*
* This method is Chromium only. It's safe to call when using other browsers, but it will always be `null`.
*
* Requests originated in a Service Worker do not have a
* [request.frame()](https://playwright.dev/docs/api/class-request#request-frame) available.
*/
serviceWorker(): null | Worker
/**
* Returns resource size information for given request.
*/
sizes(): Promise<{
/**
* Size of the request body (POST data payload) in bytes. Set to 0 if there was no body.
*/
requestBodySize: number
/**
* Total number of bytes from the start of the HTTP request message until (and including) the double CRLF before the
* body.
*/
requestHeadersSize: number
/**
* Size of the received response body (encoded) in bytes.
*/
responseBodySize: number
/**
* Total number of bytes from the start of the HTTP response message until (and including) the double CRLF before the
* body.
*/
responseHeadersSize: number
}>
/**
* Returns resource timing information for given request. Most of the timing values become available upon the
* response, `responseEnd` becomes available when request finishes. Find more information at
* [Resource Timing API](https://developer.mozilla.org/en-US/docs/Web/API/PerformanceResourceTiming).
*
* **Usage**
*
* ```js
* const requestFinishedPromise = page.waitForEvent('requestfinished');
* await page.goto('http://example.com');
* const request = await requestFinishedPromise;
* console.log(request.timing());
* ```
*
*/
timing(): {
/**
* Request start time in milliseconds elapsed since January 1, 1970 00:00:00 UTC
*/
startTime: number
/**
* Time immediately before the client starts the domain name lookup for the resource. The value is given in
* milliseconds relative to `startTime`, -1 if not available.
*/
domainLookupStart: number
/**
* Time immediately after the client ends the domain name lookup for the resource. The value is given in milliseconds
* relative to `startTime`, -1 if not available.
*/
domainLookupEnd: number
/**
* Time immediately before the client starts establishing the connection to the server to retrieve the resource. The
* value is given in milliseconds relative to `startTime`, -1 if not available.
*/
connectStart: number
/**
* Time immediately before the client starts the handshake process to secure the current connection. The value is
* given in milliseconds relative to `startTime`, -1 if not available.
*/
secureConnectionStart: number
/**
* Time immediately after the client establishes the connection to the server to retrieve the resource. The value is
* given in milliseconds relative to `startTime`, -1 if not available.
*/
connectEnd: number
/**
* Time immediately before the client starts requesting the resource from the server, cache, or local resource. The
* value is given in milliseconds relative to `startTime`, -1 if not available.
*/
requestStart: number
/**
* Time immediately after the client receives the first byte of the response from the server, cache, or local
* resource. The value is given in milliseconds relative to `startTime`, -1 if not available.
*/
responseStart: number
/**
* Time immediately after the client receives the last byte of the resource or immediately before the transport
* connection is closed, whichever comes first. The value is given in milliseconds relative to `startTime`, -1 if not
* available.
*/
responseEnd: number
}
/**
* URL of the request.
*/
url(): string
}
Response
Response class represents responses which are received by page.
interface Response {
/**
* An object with all the response HTTP headers associated with this response.
*/
allHeaders(): Promise<{ [key: string]: string }>
/**
* Returns the buffer with response body.
*/
body(): Promise<Buffer>
/**
* Waits for this response to finish, returns always `null`.
*/
finished(): Promise<null | Error>
/**
* Returns the [Frame](https://playwright.dev/docs/api/class-frame) that initiated this response.
*/
frame(): Frame
/**
* Indicates whether this Response was fulfilled by a Service Worker's Fetch Handler (i.e. via
* [FetchEvent.respondWith](https://developer.mozilla.org/en-US/docs/Web/API/FetchEvent/respondWith)).
*/
fromServiceWorker(): boolean
/**
* An object with the response HTTP headers. The header names are lower-cased. Note that this method does not return
* security-related headers, including cookie-related ones. You can use
* [response.allHeaders()](https://playwright.dev/docs/api/class-response#response-all-headers) for complete list of
* headers that include `cookie` information.
*/
headers(): { [key: string]: string }
/**
* An array with all the request HTTP headers associated with this response. Unlike
* [response.allHeaders()](https://playwright.dev/docs/api/class-response#response-all-headers), header names are NOT
* lower-cased. Headers with multiple entries, such as `Set-Cookie`, appear in the array multiple times.
*/
headersArray(): Promise<
Array<{
/**
* Name of the header.
*/
name: string
/**
* Value of the header.
*/
value: string
}>
>
/**
* Returns the value of the header matching the name. The name is case-insensitive. If multiple headers have the same
* name (except `set-cookie`), they are returned as a list separated by `, `. For `set-cookie`, the `\n` separator is
* used. If no headers are found, `null` is returned.
* @param name Name of the header.
*/
headerValue(name: string): Promise<null | string>
/**
* Returns all values of the headers matching the name, for example `set-cookie`. The name is case-insensitive.
* @param name Name of the header.
*/
headerValues(name: string): Promise<Array<string>>
/**
* Returns the http version used by the response.
*/
httpVersion(): Promise<string>
/**
* Returns the JSON representation of response body.
*
* This method will throw if the response body is not parsable via `JSON.parse`.
*/
json(): Promise<Serializable>
/**
* Contains a boolean stating whether the response was successful (status in the range 200-299) or not.
*/
ok(): boolean
/**
* Returns the matching [Request](https://playwright.dev/docs/api/class-request) object.
*/
request(): Request
/**
* Returns SSL and other security information.
*/
securityDetails(): Promise<null | {
/**
* Common Name component of the Issuer field. from the certificate. This should only be used for informational
* purposes. Optional.
*/
issuer?: string
/**
* The specific TLS protocol used. (e.g. `TLS 1.3`). Optional.
*/
protocol?: string
/**
* Common Name component of the Subject field from the certificate. This should only be used for informational
* purposes. Optional.
*/
subjectName?: string
/**
* Unix timestamp (in seconds) specifying when this cert becomes valid. Optional.
*/
validFrom?: number
/**
* Unix timestamp (in seconds) specifying when this cert becomes invalid. Optional.
*/
validTo?: number
}>
/**
* Returns the IP address and port of the server.
*/
serverAddr(): Promise<null | {
/**
* IPv4 or IPV6 address of the server.
*/
ipAddress: string
port: number
}>
/**
* Contains the status code of the response (e.g., 200 for a success).
*/
status(): number
/**
* Contains the status text of the response (e.g. usually an "OK" for a success).
*/
statusText(): string
/**
* Returns the text representation of response body.
*/
text(): Promise<string>
/**
* Contains the URL of the response.
*/
url(): string
}
Route
Whenever a network route is set up with
page.route(url, handler[, options]) or
browserContext.route(url, handler[, options]),
the Route object allows to handle the route.
Learn more about networking.
interface Route {
/**
* Aborts the route's request.
* @param errorCode Optional error code. Defaults to `failed`, could be one of the following:
* - `'aborted'` - An operation was aborted (due to user action)
* - `'accessdenied'` - Permission to access a resource, other than the network, was denied
* - `'addressunreachable'` - The IP address is unreachable. This usually means that there is no route to the
* specified host or network.
* - `'blockedbyclient'` - The client chose to block the request.
* - `'blockedbyresponse'` - The request failed because the response was delivered along with requirements which are
* not met ('X-Frame-Options' and 'Content-Security-Policy' ancestor checks, for instance).
* - `'connectionaborted'` - A connection timed out as a result of not receiving an ACK for data sent.
* - `'connectionclosed'` - A connection was closed (corresponding to a TCP FIN).
* - `'connectionfailed'` - A connection attempt failed.
* - `'connectionrefused'` - A connection attempt was refused.
* - `'connectionreset'` - A connection was reset (corresponding to a TCP RST).
* - `'internetdisconnected'` - The Internet connection has been lost.
* - `'namenotresolved'` - The host name could not be resolved.
* - `'timedout'` - An operation timed out.
* - `'failed'` - A generic failure occurred.
*/
abort(errorCode?: string): Promise<void>
/**
* Sends route's request to the network with optional overrides.
*
* **Usage**
*
* ```js
* await page.route('**\/*', async (route, request) => {
* // Override headers
* const headers = {
* ...request.headers(),
* foo: 'foo-value', // set "foo" header
* bar: undefined, // remove "bar" header
* };
* await route.continue({ headers });
* });
* ```
*
* **Details**
*
* The [`headers`](https://playwright.dev/docs/api/class-route#route-continue-option-headers) option applies to both
* the routed request and any redirects it initiates. However,
* [`url`](https://playwright.dev/docs/api/class-route#route-continue-option-url),
* [`method`](https://playwright.dev/docs/api/class-route#route-continue-option-method), and
* [`postData`](https://playwright.dev/docs/api/class-route#route-continue-option-post-data) only apply to the
* original request and are not carried over to redirected requests.
*
* [route.continue([options])](https://playwright.dev/docs/api/class-route#route-continue) will immediately send the
* request to the network, other matching handlers won't be invoked. Use
* [route.fallback([options])](https://playwright.dev/docs/api/class-route#route-fallback) If you want next matching
* handler in the chain to be invoked.
*
* **NOTE** Some request headers are **forbidden** and cannot be overridden (for example, `Cookie`, `Host`,
* `Content-Length` and others, see
* [this MDN page](https://developer.mozilla.org/en-US/docs/Glossary/Forbidden_request_header) for full list). If an
* override is provided for a forbidden header, it will be ignored and the original request header will be used.
*
* To set custom cookies, use
* [browserContext.addCookies(cookies)](https://playwright.dev/docs/api/class-browsercontext#browser-context-add-cookies).
*
* @param options
*/
continue(options?: {
/**
* If set changes the request HTTP headers. Header values will be converted to a string.
*/
headers?: { [key: string]: string }
/**
* If set changes the request method (e.g. GET or POST).
*/
method?: string
/**
* If set changes the post data of request.
*/
postData?: string | Buffer | Serializable
/**
* If set changes the request URL. New URL must have same protocol as original one.
*/
url?: string
}): Promise<void>
/**
* Continues route's request with optional overrides. The method is similar to
* [route.continue([options])](https://playwright.dev/docs/api/class-route#route-continue) with the difference that
* other matching handlers will be invoked before sending the request.
*
* **Usage**
*
* When several routes match the given pattern, they run in the order opposite to their registration. That way the
* last registered route can always override all the previous ones. In the example below, request will be handled by
* the bottom-most handler first, then it'll fall back to the previous one and in the end will be aborted by the first
* registered route.
*
* ```js
* await page.route('**\/*', async route => {
* // Runs last.
* await route.abort();
* });
* await page.route('**\/*', async route => {
* // Runs second.
* await route.fallback();
* });
* await page.route('**\/*', async route => {
* // Runs first.
* await route.fallback();
* });
* ```
*
* Registering multiple routes is useful when you want separate handlers to handle different kinds of requests, for
* example API calls vs page resources or GET requests vs POST requests as in the example below.
*
* ```js
* // Handle GET requests.
* await page.route('**\/*', async route => {
* if (route.request().method() !== 'GET') {
* await route.fallback();
* return;
* }
* // Handling GET only.
* // ...
* });
*
* // Handle POST requests.
* await page.route('**\/*', async route => {
* if (route.request().method() !== 'POST') {
* await route.fallback();
* return;
* }
* // Handling POST only.
* // ...
* });
* ```
*
* One can also modify request while falling back to the subsequent handler, that way intermediate route handler can
* modify url, method, headers and postData of the request.
*
* ```js
* await page.route('**\/*', async (route, request) => {
* // Override headers
* const headers = {
* ...request.headers(),
* foo: 'foo-value', // set "foo" header
* bar: undefined, // remove "bar" header
* };
* await route.fallback({ headers });
* });
* ```
*
* Use [route.continue([options])](https://playwright.dev/docs/api/class-route#route-continue) to immediately send the
* request to the network, other matching handlers won't be invoked in that case.
* @param options
*/
fallback(options?: {
/**
* If set changes the request HTTP headers. Header values will be converted to a string.
*/
headers?: { [key: string]: string }
/**
* If set changes the request method (e.g. GET or POST).
*/
method?: string
/**
* If set changes the post data of request.
*/
postData?: string | Buffer | Serializable
/**
* If set changes the request URL. New URL must have same protocol as original one. Changing the URL won't affect the
* route matching, all the routes are matched using the original request URL.
*/
url?: string
}): Promise<void>
/**
* Performs the request and fetches result without fulfilling it, so that the response could be modified and then
* fulfilled.
*
* **Usage**
*
* ```js
* await page.route('https://dog.ceo/api/breeds/list/all', async route => {
* const response = await route.fetch();
* const json = await response.json();
* json.message['big_red_dog'] = [];
* await route.fulfill({ response, json });
* });
* ```
*
* **Details**
*
* Note that [`headers`](https://playwright.dev/docs/api/class-route#route-fetch-option-headers) option will apply to
* the fetched request as well as any redirects initiated by it. If you want to only apply
* [`headers`](https://playwright.dev/docs/api/class-route#route-fetch-option-headers) to the original request, but
* not to redirects, look into [route.continue([options])](https://playwright.dev/docs/api/class-route#route-continue)
* instead.
* @param options
*/
fetch<T = any>(options?: {
/**
* If set changes the request HTTP headers. Header values will be converted to a string.
*/
headers?: { [key: string]: string }
/**
* Maximum number of request redirects that will be followed automatically. An error will be thrown if the number is
* exceeded. Defaults to `20`. Pass `0` to not follow redirects.
*/
maxRedirects?: number
/**
* Maximum number of times network errors should be retried. Currently only `ECONNRESET` error is retried. Does not
* retry based on HTTP response codes. An error will be thrown if the limit is exceeded. Defaults to `0` - no retries.
*/
maxRetries?: number
/**
* If set changes the request method (e.g. GET or POST).
*/
method?: string
/**
* Allows to set post data of the request. If the data parameter is an object, it will be serialized to json string
* and `content-type` header will be set to `application/json` if not explicitly set. Otherwise the `content-type`
* header will be set to `application/octet-stream` if not explicitly set.
*/
postData?: string | Buffer | Serializable
/**
* Allows to cancel the operation using an
* [`AbortSignal`](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal). If the signal is aborted, the
* operation will be aborted and throw an error. Note that providing a signal does not disable the default timeout,
* which can be changed using
* [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); pass
* `timeout: 0` to disable the timeout entirely.
*/
signal?: AbortSignal
/**
* Request timeout in milliseconds. Defaults to `30000` (30 seconds). Pass `0` to disable timeout.
*/
timeout?: number
/**
* If set changes the request URL. New URL must have same protocol as original one.
*/
url?: string
}): Promise<APIResponse<T>>
/**
* Fulfills route's request with given response.
*
* **Usage**
*
* An example of fulfilling all requests with 404 responses:
*
* ```js
* await page.route('**\/*', async route => {
* await route.fulfill({
* status: 404,
* contentType: 'text/plain',
* body: 'Not Found!'
* });
* });
* ```
*
* An example of serving static file:
*
* ```js
* await page.route('**\/xhr_endpoint', route => route.fulfill({ path: 'mock_data.json' }));
* ```
*
* @param options
*/
fulfill(options?: {
/**
* Response body.
*/
body?: string | Buffer
/**
* If set, equals to setting `Content-Type` response header.
*/
contentType?: string
/**
* Response headers. Header values will be converted to a string.
*/
headers?: { [key: string]: string }
/**
* JSON response. This method will set the content type to `application/json` if not set.
*/
json?: Serializable
/**
* File path to respond with. The content type will be inferred from file extension. If `path` is a relative path,
* then it is resolved relative to the current working directory.
*/
path?: string
/**
* [APIResponse](https://playwright.dev/docs/api/class-apiresponse) to fulfill route's request with. Individual fields
* of the response (such as headers) can be overridden using fulfill options.
*/
response?: APIResponse
/**
* Response status code, defaults to `200`.
*/
status?: number
}): Promise<void>
/**
* A request to be routed.
*/
request(): Request
}
RuntimeCall
The page-side dispatcher's request shape.
interface RuntimeCall {
fn: string
args: unknown[]
}
TestInfo
TestInfo contains information about currently running test. It is available to test functions,
test.beforeEach([title, hookFunction]),
test.afterEach([title, hookFunction]),
test.beforeAll([title, hookFunction]) and
test.afterAll([title, hookFunction]) hooks, and
test-scoped fixtures. TestInfo provides utilities to control test execution: attach files, update test timeout,
determine which test is currently running and whether it was retried, etc.
import { test, expect } from '@playwright/test'
test('basic test', async ({ page }, testInfo) => {
expect(testInfo.title).toBe('basic test')
await page.screenshot(testInfo.outputPath('screenshot.png'))
})
interface TestInfo {
/**
* Returns a path to a snapshot file with the given `name`. Pass
* [`kind`](https://playwright.dev/docs/api/class-testinfo#test-info-snapshot-path-option-kind) to obtain a specific
* path:
* - `kind: 'screenshot'` for
* [expect(page).toHaveScreenshot(name[, options])](https://playwright.dev/docs/api/class-pageassertions#page-assertions-to-have-screenshot-1);
* - `kind: 'aria'` for
* [expect(locator).toMatchAriaSnapshot(expected[, options])](https://playwright.dev/docs/api/class-locatorassertions#locator-assertions-to-match-aria-snapshot);
* - `kind: 'snapshot'` for
* [expect(value).toMatchSnapshot(name[, options])](https://playwright.dev/docs/api/class-snapshotassertions#snapshot-assertions-to-match-snapshot-1).
*
* **Usage**
*
* ```js
* await expect(page).toHaveScreenshot('header.png');
* // Screenshot assertion above expects screenshot at this path:
* const screenshotPath = test.info().snapshotPath('header.png', { kind: 'screenshot' });
*
* await expect(page.getByRole('main')).toMatchAriaSnapshot({ name: 'main.aria.yml' });
* // Aria snapshot assertion above expects snapshot at this path:
* const ariaSnapshotPath = test.info().snapshotPath('main.aria.yml', { kind: 'aria' });
*
* expect('some text').toMatchSnapshot('snapshot.txt');
* // Snapshot assertion above expects snapshot at this path:
* const snapshotPath = test.info().snapshotPath('snapshot.txt');
*
* expect('some text').toMatchSnapshot(['dir', 'subdir', 'snapshot.txt']);
* // Snapshot assertion above expects snapshot at this path:
* const nestedPath = test.info().snapshotPath('dir', 'subdir', 'snapshot.txt');
* ```
*
* @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.
*
* When passing [`kind`](https://playwright.dev/docs/api/class-testinfo#test-info-snapshot-path-option-kind), multiple
* name segments are not supported.
* @param options
*/
snapshotPath(...name: ReadonlyArray<string>): string
/**
* Returns a path to a snapshot file with the given `name`. Pass
* [`kind`](https://playwright.dev/docs/api/class-testinfo#test-info-snapshot-path-option-kind) to obtain a specific
* path:
* - `kind: 'screenshot'` for
* [expect(page).toHaveScreenshot(name[, options])](https://playwright.dev/docs/api/class-pageassertions#page-assertions-to-have-screenshot-1);
* - `kind: 'aria'` for
* [expect(locator).toMatchAriaSnapshot(expected[, options])](https://playwright.dev/docs/api/class-locatorassertions#locator-assertions-to-match-aria-snapshot);
* - `kind: 'snapshot'` for
* [expect(value).toMatchSnapshot(name[, options])](https://playwright.dev/docs/api/class-snapshotassertions#snapshot-assertions-to-match-snapshot-1).
*
* **Usage**
*
* ```js
* await expect(page).toHaveScreenshot('header.png');
* // Screenshot assertion above expects screenshot at this path:
* const screenshotPath = test.info().snapshotPath('header.png', { kind: 'screenshot' });
*
* await expect(page.getByRole('main')).toMatchAriaSnapshot({ name: 'main.aria.yml' });
* // Aria snapshot assertion above expects snapshot at this path:
* const ariaSnapshotPath = test.info().snapshotPath('main.aria.yml', { kind: 'aria' });
*
* expect('some text').toMatchSnapshot('snapshot.txt');
* // Snapshot assertion above expects snapshot at this path:
* const snapshotPath = test.info().snapshotPath('snapshot.txt');
*
* expect('some text').toMatchSnapshot(['dir', 'subdir', 'snapshot.txt']);
* // Snapshot assertion above expects snapshot at this path:
* const nestedPath = test.info().snapshotPath('dir', 'subdir', 'snapshot.txt');
* ```
*
* @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.
*
* When passing [`kind`](https://playwright.dev/docs/api/class-testinfo#test-info-snapshot-path-option-kind), multiple
* name segments are not supported.
* @param options
*/
snapshotPath(name: string, options: { kind: 'snapshot' | 'screenshot' | 'aria' }): string
/**
* Attach a value or a file from disk to the current test. Some reporters show test attachments. Either
* [`path`](https://playwright.dev/docs/api/class-testinfo#test-info-attach-option-path) or
* [`body`](https://playwright.dev/docs/api/class-testinfo#test-info-attach-option-body) must be specified, but not
* both.
*
* For example, you can attach a screenshot to the test:
*
* ```js
* import { test, expect } from '@playwright/test';
*
* test('basic test', async ({ page }, testInfo) => {
* await page.goto('https://playwright.dev');
* const screenshot = await page.screenshot();
* await testInfo.attach('screenshot', { body: screenshot, contentType: 'image/png' });
* });
* ```
*
* Or you can attach files returned by your APIs:
*
* ```js
* import { test, expect } from '@playwright/test';
* import { download } from './my-custom-helpers';
*
* test('basic test', async ({}, testInfo) => {
* const tmpPath = await download('a');
* await testInfo.attach('downloaded', { path: tmpPath });
* });
* ```
*
* **NOTE** [testInfo.attach(name[, options])](https://playwright.dev/docs/api/class-testinfo#test-info-attach)
* 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.
*
* @param name Attachment name. The name will also be sanitized and used as the prefix of file name when saving to disk.
* @param options
*/
attach(
name: string,
options?: {
/**
* Attachment body. Mutually exclusive with
* [`path`](https://playwright.dev/docs/api/class-testinfo#test-info-attach-option-path).
*/
body?: string | Buffer
/**
* Content type of this attachment to properly present in the report, for example `'application/json'` or
* `'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.
*/
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).
*/
path?: string
},
): Promise<void>
/**
* Marks the currently running test as "should fail". Playwright Test runs this test and ensures that it is actually
* 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).
*/
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).
* @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.
*/
fail(condition: boolean, description?: string): void
/**
* 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).
*/
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).
* @param condition Test is marked as "fixme" when the condition is `true`.
* @param description Optional description that will be reflected in a test report.
*/
fixme(condition: boolean, description?: string): void
/**
* Returns a path inside the [testInfo.outputDir](https://playwright.dev/docs/api/class-testinfo#test-info-output-dir)
* where the test can safely put a temporary file. Guarantees that tests running in parallel will not interfere with
* each other.
*
* ```js
* import { test, expect } from '@playwright/test';
* import fs from 'fs';
*
* test('example test', async ({}, testInfo) => {
* const file = testInfo.outputPath('dir', 'temporary-file.txt');
* await fs.promises.writeFile(file, 'Put some data to the dir/temporary-file.txt', 'utf8');
* });
* ```
*
* > Note that `pathSegments` accepts path segments to the test output directory such as
* `testInfo.outputPath('relative', 'path', 'to', 'output')`.
* > 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.
* @param pathSegments Path segments to append at the end of the resulting path.
*/
outputPath(...pathSegments: ReadonlyArray<string>): string
/**
* Changes the timeout for the currently running test. Zero means no timeout. Learn more about
* [various timeouts](https://playwright.dev/docs/test-timeouts).
*
* Timeout is usually specified in the [configuration file](https://playwright.dev/docs/test-configuration), but it could be useful to
* change the timeout in certain scenarios:
*
* ```js
* import { test, expect } from '@playwright/test';
*
* test.beforeEach(async ({ page }, testInfo) => {
* // Extend timeout for all tests running this hook by 30 seconds.
* testInfo.setTimeout(testInfo.timeout + 30000);
* });
* ```
*
* @param timeout Timeout in milliseconds.
*/
setTimeout(timeout: number): void
/**
* 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).
*/
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).
* @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.
*/
skip(condition: boolean, description?: string): void
/**
* 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).
*/
slow(): void
/**
* 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).
* @param condition Test is marked as "slow" when the condition is `true`.
* @param description Optional description that will be reflected in a test report.
*/
slow(condition: boolean, description?: string): void
/**
* The list of annotations applicable to the current test. Includes annotations from the test, annotations from all
* [test.describe([title, details, callback])](https://playwright.dev/docs/api/class-test#test-describe) groups the
* test belongs to and file-level annotations for the test file.
*
* Learn more about [test annotations](https://playwright.dev/docs/test-annotations).
*/
annotations: Array<{
/**
* Annotation type, for example `'skip'` or `'fail'`.
*/
type: string
/**
* Optional description.
*/
description?: string
/**
* Optional location in the source where the annotation is added.
*/
location?: Location
}>
/**
* The list of files or buffers attached to the current test. Some reporters show test attachments.
*
* 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.
*/
attachments: Array<{
/**
* Attachment name.
*/
name: string
/**
* Content type of this attachment to properly present in the report, for example `'application/json'` or
* `'image/png'`.
*/
contentType: string
/**
* Optional path on the filesystem to the attached file.
*/
path?: string
/**
* Optional attachment body used instead of a file.
*/
body?: Buffer
}>
/**
* Column number where the currently running test is declared.
*/
column: number
/**
* Processed configuration from the [configuration file](https://playwright.dev/docs/test-configuration).
*/
config: FullConfig
/**
* 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.
*/
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).
*/
error?: TestInfoError
/**
* Errors thrown during test execution, if any.
*/
errors: Array<TestInfoError>
/**
* Expected status for the currently running test. This is usually `'passed'`, except for a few cases:
* - `'skipped'` for skipped tests, e.g. with
* [test.skip([title, details, body, condition, callback, description])](https://playwright.dev/docs/api/class-test#test-skip);
* - `'failed'` for tests marked as failed with
* [test.fail([title, details, body, condition, callback, description])](https://playwright.dev/docs/api/class-test#test-fail).
*
* Expected status is usually compared with the actual
* [testInfo.status](https://playwright.dev/docs/api/class-testinfo#test-info-status):
*
* ```js
* import { test, expect } from '@playwright/test';
*
* test.afterEach(async ({}, testInfo) => {
* if (testInfo.status !== testInfo.expectedStatus)
* console.log(`${testInfo.title} did not run as expected!`);
* });
* ```
*
*/
expectedStatus: 'passed' | 'failed' | 'timedOut' | 'skipped' | 'interrupted'
/**
* Absolute path to a file where the currently running test is declared.
*/
file: string
/**
* Test function as passed to `test(title, testFunction)`.
*/
fn: Function
/**
* Line number where the currently running test is declared.
*/
line: number
/**
* Absolute path to the output directory for this specific test run. Each test run gets its own directory so they
* cannot conflict.
*/
outputDir: string
/**
* The index of the worker between `0` and `workers - 1`. It is guaranteed that workers running at the same time have
* a different `parallelIndex`. When a worker is restarted, for example after a failure, the new worker process has
* the same `parallelIndex`.
*
* Also available as `process.env.TEST_PARALLEL_INDEX`. Learn more about
* [parallelism and sharding](https://playwright.dev/docs/test-parallel) with Playwright Test.
*/
parallelIndex: number
/**
* Processed project configuration from the [configuration file](https://playwright.dev/docs/test-configuration).
*/
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).
*/
repeatEachIndex: number
/**
* Specifies the retry number when the test is retried after a failure. The first test run has
* [testInfo.retry](https://playwright.dev/docs/api/class-testinfo#test-info-retry) equal to zero, the first retry has
* it equal to one, and so on. Learn more about [retries](https://playwright.dev/docs/test-retries#retries).
*
* ```js
* import { test, expect } from '@playwright/test';
*
* test.beforeEach(async ({}, testInfo) => {
* // You can access testInfo.retry in any hook or fixture.
* if (testInfo.retry > 0)
* console.log(`Retrying!`);
* });
*
* test('my test', async ({ page }, testInfo) => {
* // Here we clear some server-side state when retrying.
* if (testInfo.retry)
* await cleanSomeCachesOnTheServer();
* // ...
* });
* ```
*
*/
retry: number
/**
* Absolute path to the snapshot output directory for this specific test. Each test suite gets its own directory so
* they cannot conflict.
*
* This property does not account for the
* [testProject.snapshotPathTemplate](https://playwright.dev/docs/api/class-testproject#test-project-snapshot-path-template)
* configuration.
*/
snapshotDir: string
/**
* **NOTE** Use of [testInfo.snapshotSuffix](https://playwright.dev/docs/api/class-testinfo#test-info-snapshot-suffix)
* is discouraged. Please use
* [testConfig.snapshotPathTemplate](https://playwright.dev/docs/api/class-testconfig#test-config-snapshot-path-template)
* to configure snapshot paths.
*
* Suffix used to differentiate snapshots between multiple test configurations. For example, if snapshots depend on
* 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).
*/
snapshotSuffix: string
/**
* Actual status for the currently running test. Available after the test has finished in
* [test.afterEach([title, hookFunction])](https://playwright.dev/docs/api/class-test#test-after-each) hook and
* fixtures.
*
* Status is usually compared with the
* [testInfo.expectedStatus](https://playwright.dev/docs/api/class-testinfo#test-info-expected-status):
*
* ```js
* import { test, expect } from '@playwright/test';
*
* test.afterEach(async ({}, testInfo) => {
* if (testInfo.status !== testInfo.expectedStatus)
* console.log(`${testInfo.title} did not run as expected!`);
* });
* ```
*
*/
status?: 'passed' | 'failed' | 'timedOut' | 'skipped' | 'interrupted'
/**
* Tags that apply to the test. Learn more about [tags](https://playwright.dev/docs/test-annotations#tag-tests).
*
* **NOTE** Any changes made to this list while the test is running will not be visible to test reporters.
*
*/
tags: Array<string>
/**
* Test id matching the test case id in the reporter API.
*/
testId: string
/**
* Timeout in milliseconds for the currently running test. Zero means no timeout. Learn more about
* [various timeouts](https://playwright.dev/docs/test-timeouts).
*
* Timeout is usually specified in the [configuration file](https://playwright.dev/docs/test-configuration)
*
* ```js
* import { test, expect } from '@playwright/test';
*
* test.beforeEach(async ({ page }, testInfo) => {
* // Extend timeout for all tests running this hook by 30 seconds.
* testInfo.setTimeout(testInfo.timeout + 30000);
* });
* ```
*
*/
timeout: number
/**
* The title of the currently running test as passed to `test(title, testFunction)`.
*/
title: string
/**
* The full title path starting with the test file name.
*/
titlePath: Array<string>
/**
* The unique index of the worker process that is running the test. When a worker is restarted, for example after a
* failure, the new worker process gets a new unique `workerIndex`.
*
* Also available as `process.env.TEST_WORKER_INDEX`. Learn more about [parallelism and sharding](https://playwright.dev/docs/test-parallel)
* with Playwright Test.
*/
workerIndex: number
}
TestType
Playwright Test provides a test function to declare tests and expect function to write assertions.
import { test, expect } from '@playwright/test'
test('basic test', async ({ page }) => {
await page.goto('https://playwright.dev/')
const name = await page.innerText('.navbar__title')
expect(name).toBe('Playwright')
})
interface TestType<TestArgs extends {}, WorkerArgs extends {}> {
/**
* Declares a test.
* - `test(title, body)`
* - `test(title, details, body)`
*
* **Usage**
*
* ```js
* import { test, expect } from '@playwright/test';
*
* test('basic test', async ({ page }) => {
* await page.goto('https://playwright.dev/');
* // ...
* });
* ```
*
* **Tags**
*
* You can tag tests by providing additional test details. Alternatively, you can include tags in the test title. Note
* that each tag must start with `@` symbol.
*
* ```js
* import { test, expect } from '@playwright/test';
*
* test('basic test', {
* tag: '@smoke',
* }, async ({ page }) => {
* await page.goto('https://playwright.dev/');
* // ...
* });
*
* test('another test @smoke', async ({ page }) => {
* await page.goto('https://playwright.dev/');
* // ...
* });
* ```
*
* Test tags are displayed in the test report, and are available to a custom reporter via `TestCase.tags` property.
*
* You can also filter tests by their tags during test execution:
* - in the [command line](https://playwright.dev/docs/test-cli#all-options);
* - in the config with [testConfig.grep](https://playwright.dev/docs/api/class-testconfig#test-config-grep) and
* [testProject.grep](https://playwright.dev/docs/api/class-testproject#test-project-grep);
*
* Learn more about [tagging](https://playwright.dev/docs/test-annotations#tag-tests).
*
* **Annotations**
*
* You can annotate tests by providing additional test details.
*
* ```js
* import { test, expect } from '@playwright/test';
*
* test('basic test', {
* annotation: {
* type: 'issue',
* description: 'https://github.com/microsoft/playwright/issues/23180',
* },
* }, async ({ page }) => {
* await page.goto('https://playwright.dev/');
* // ...
* });
* ```
*
* Test annotations are displayed in the test report, and are available to a custom reporter via
* `TestCase.annotations` property.
*
* You can also add annotations during runtime by manipulating
* [testInfo.annotations](https://playwright.dev/docs/api/class-testinfo#test-info-annotations).
*
* Learn more about [test annotations](https://playwright.dev/docs/test-annotations).
*
* **Locks**
*
* You can declare named locks to prevent specific tests from running at the same time, while all other tests continue
* to run in parallel. Tests that share a lock name never run concurrently, even when they are declared in different
* files or belong to different [projects](https://playwright.dev/docs/test-projects). This is useful when a few tests access a shared
* resource that does not support concurrent access.
*
* ```js
* import { test, expect } from '@playwright/test';
*
* test('update user settings', {
* lock: 'user-settings',
* }, async ({ page }) => {
* // This test never runs concurrently with other tests
* // that declare the 'user-settings' lock.
* });
* ```
*
* Learn more about [test locks](https://playwright.dev/docs/test-parallel#test-locks).
* @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
* [TestInfo](https://playwright.dev/docs/api/class-testinfo).
*/
(title: string, body: TestBody<TestArgs & WorkerArgs>): void
/**
* Declares a test.
* - `test(title, body)`
* - `test(title, details, body)`
*
* **Usage**
*
* ```js
* import { test, expect } from '@playwright/test';
*
* test('basic test', async ({ page }) => {
* await page.goto('https://playwright.dev/');
* // ...
* });
* ```
*
* **Tags**
*
* You can tag tests by providing additional test details. Alternatively, you can include tags in the test title. Note
* that each tag must start with `@` symbol.
*
* ```js
* import { test, expect } from '@playwright/test';
*
* test('basic test', {
* tag: '@smoke',
* }, async ({ page }) => {
* await page.goto('https://playwright.dev/');
* // ...
* });
*
* test('another test @smoke', async ({ page }) => {
* await page.goto('https://playwright.dev/');
* // ...
* });
* ```
*
* Test tags are displayed in the test report, and are available to a custom reporter via `TestCase.tags` property.
*
* You can also filter tests by their tags during test execution:
* - in the [command line](https://playwright.dev/docs/test-cli#all-options);
* - in the config with [testConfig.grep](https://playwright.dev/docs/api/class-testconfig#test-config-grep) and
* [testProject.grep](https://playwright.dev/docs/api/class-testproject#test-project-grep);
*
* Learn more about [tagging](https://playwright.dev/docs/test-annotations#tag-tests).
*
* **Annotations**
*
* You can annotate tests by providing additional test details.
*
* ```js
* import { test, expect } from '@playwright/test';
*
* test('basic test', {
* annotation: {
* type: 'issue',
* description: 'https://github.com/microsoft/playwright/issues/23180',
* },
* }, async ({ page }) => {
* await page.goto('https://playwright.dev/');
* // ...
* });
* ```
*
* Test annotations are displayed in the test report, and are available to a custom reporter via
* `TestCase.annotations` property.
*
* You can also add annotations during runtime by manipulating
* [testInfo.annotations](https://playwright.dev/docs/api/class-testinfo#test-info-annotations).
*
* Learn more about [test annotations](https://playwright.dev/docs/test-annotations).
*
* **Locks**
*
* You can declare named locks to prevent specific tests from running at the same time, while all other tests continue
* to run in parallel. Tests that share a lock name never run concurrently, even when they are declared in different
* files or belong to different [projects](https://playwright.dev/docs/test-projects). This is useful when a few tests access a shared
* resource that does not support concurrent access.
*
* ```js
* import { test, expect } from '@playwright/test';
*
* test('update user settings', {
* lock: 'user-settings',
* }, async ({ page }) => {
* // This test never runs concurrently with other tests
* // that declare the 'user-settings' lock.
* });
* ```
*
* Learn more about [test locks](https://playwright.dev/docs/test-parallel#test-locks).
* @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
* [TestInfo](https://playwright.dev/docs/api/class-testinfo).
*/
(title: string, details: TestDetails, body: TestBody<TestArgs & WorkerArgs>): void
/**
* Declares a focused test. If there are some focused tests or suites, all of them will be run but nothing else.
* - `test.only(title, body)`
* - `test.only(title, details, body)`
*
* **Usage**
*
* ```js
* test.only('focus this test', async ({ page }) => {
* // Run only focused tests in the entire project.
* });
* ```
*
* @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.
* @param body Test body that takes one or two arguments: an object with fixtures and optional
* [TestInfo](https://playwright.dev/docs/api/class-testinfo).
*/
only(title: string, body: TestBody<TestArgs & WorkerArgs>): void
/**
* Declares a focused test. If there are some focused tests or suites, all of them will be run but nothing else.
* - `test.only(title, body)`
* - `test.only(title, details, body)`
*
* **Usage**
*
* ```js
* test.only('focus this test', async ({ page }) => {
* // Run only focused tests in the entire project.
* });
* ```
*
* @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.
* @param body Test body that takes one or two arguments: an object with fixtures and optional
* [TestInfo](https://playwright.dev/docs/api/class-testinfo).
*/
only(title: string, details: TestDetails, body: TestBody<TestArgs & WorkerArgs>): void
/**
* Declares a group of tests.
* - `test.describe(title, callback)`
* - `test.describe(callback)`
* - `test.describe(title, details, callback)`
*
* **Usage**
*
* You can declare a group of tests with a title. The title will be visible in the test report as a part of each
* test's title.
*
* ```js
* test.describe('two tests', () => {
* test('one', async ({ page }) => {
* // ...
* });
*
* test('two', async ({ page }) => {
* // ...
* });
* });
* ```
*
* **Anonymous group**
*
* You can also declare a test group without a title. This is convenient to give a group of tests a common option with
* [test.use(options)](https://playwright.dev/docs/api/class-test#test-use).
*
* ```js
* test.describe(() => {
* test.use({ colorScheme: 'dark' });
*
* test('one', async ({ page }) => {
* // ...
* });
*
* test('two', async ({ page }) => {
* // ...
* });
* });
* ```
*
* **Tags**
*
* You can tag all tests in a group by providing additional details. Note that each tag must start with `@` symbol.
*
* ```js
* import { test, expect } from '@playwright/test';
*
* test.describe('two tagged tests', {
* tag: '@smoke',
* }, () => {
* test('one', async ({ page }) => {
* // ...
* });
*
* test('two', async ({ page }) => {
* // ...
* });
* });
* ```
*
* Learn more about [tagging](https://playwright.dev/docs/test-annotations#tag-tests).
*
* **Annotations**
*
* You can annotate all tests in a group by providing additional details.
*
* ```js
* import { test, expect } from '@playwright/test';
*
* test.describe('two annotated tests', {
* annotation: {
* type: 'issue',
* description: 'https://github.com/microsoft/playwright/issues/23180',
* },
* }, () => {
* test('one', async ({ page }) => {
* // ...
* });
*
* test('two', async ({ page }) => {
* // ...
* });
* });
* ```
*
* Learn more about [test annotations](https://playwright.dev/docs/test-annotations).
*
* **Locks**
*
* You can declare named locks for all tests in a group by providing additional details. Tests that share a lock name
* never run concurrently. Learn more about [test locks](https://playwright.dev/docs/test-parallel#test-locks).
*
* ```js
* import { test, expect } from '@playwright/test';
*
* test.describe('two tests with a lock', {
* lock: 'user-settings',
* }, () => {
* test('one', async ({ page }) => {
* // ...
* });
*
* test('two', async ({ page }) => {
* // ...
* });
* });
* ```
*
* @param title Group title.
* @param details Additional details for all tests in the group.
* @param callback A callback that is run immediately when calling
* [test.describe([title, details, callback])](https://playwright.dev/docs/api/class-test#test-describe). Any tests
* declared in this callback will belong to the group.
*/
describe: {
/**
* Declares a group of tests.
* - `test.describe(title, callback)`
* - `test.describe(callback)`
* - `test.describe(title, details, callback)`
*
* **Usage**
*
* You can declare a group of tests with a title. The title will be visible in the test report as a part of each
* test's title.
*
* ```js
* test.describe('two tests', () => {
* test('one', async ({ page }) => {
* // ...
* });
*
* test('two', async ({ page }) => {
* // ...
* });
* });
* ```
*
* **Anonymous group**
*
* You can also declare a test group without a title. This is convenient to give a group of tests a common option with
* [test.use(options)](https://playwright.dev/docs/api/class-test#test-use).
*
* ```js
* test.describe(() => {
* test.use({ colorScheme: 'dark' });
*
* test('one', async ({ page }) => {
* // ...
* });
*
* test('two', async ({ page }) => {
* // ...
* });
* });
* ```
*
* **Tags**
*
* You can tag all tests in a group by providing additional details. Note that each tag must start with `@` symbol.
*
* ```js
* import { test, expect } from '@playwright/test';
*
* test.describe('two tagged tests', {
* tag: '@smoke',
* }, () => {
* test('one', async ({ page }) => {
* // ...
* });
*
* test('two', async ({ page }) => {
* // ...
* });
* });
* ```
*
* Learn more about [tagging](https://playwright.dev/docs/test-annotations#tag-tests).
*
* **Annotations**
*
* You can annotate all tests in a group by providing additional details.
*
* ```js
* import { test, expect } from '@playwright/test';
*
* test.describe('two annotated tests', {
* annotation: {
* type: 'issue',
* description: 'https://github.com/microsoft/playwright/issues/23180',
* },
* }, () => {
* test('one', async ({ page }) => {
* // ...
* });
*
* test('two', async ({ page }) => {
* // ...
* });
* });
* ```
*
* Learn more about [test annotations](https://playwright.dev/docs/test-annotations).
*
* **Locks**
*
* You can declare named locks for all tests in a group by providing additional details. Tests that share a lock name
* never run concurrently. Learn more about [test locks](https://playwright.dev/docs/test-parallel#test-locks).
*
* ```js
* import { test, expect } from '@playwright/test';
*
* test.describe('two tests with a lock', {
* lock: 'user-settings',
* }, () => {
* test('one', async ({ page }) => {
* // ...
* });
*
* test('two', async ({ page }) => {
* // ...
* });
* });
* ```
*
* @param title Group title.
* @param details Additional details for all tests in the group.
* @param callback A callback that is run immediately when calling
* [test.describe([title, details, callback])](https://playwright.dev/docs/api/class-test#test-describe). Any tests
* declared in this callback will belong to the group.
*/
(title: string, callback: () => void): void
/**
* Declares a group of tests.
* - `test.describe(title, callback)`
* - `test.describe(callback)`
* - `test.describe(title, details, callback)`
*
* **Usage**
*
* You can declare a group of tests with a title. The title will be visible in the test report as a part of each
* test's title.
*
* ```js
* test.describe('two tests', () => {
* test('one', async ({ page }) => {
* // ...
* });
*
* test('two', async ({ page }) => {
* // ...
* });
* });
* ```
*
* **Anonymous group**
*
* You can also declare a test group without a title. This is convenient to give a group of tests a common option with
* [test.use(options)](https://playwright.dev/docs/api/class-test#test-use).
*
* ```js
* test.describe(() => {
* test.use({ colorScheme: 'dark' });
*
* test('one', async ({ page }) => {
* // ...
* });
*
* test('two', async ({ page }) => {
* // ...
* });
* });
* ```
*
* **Tags**
*
* You can tag all tests in a group by providing additional details. Note that each tag must start with `@` symbol.
*
* ```js
* import { test, expect } from '@playwright/test';
*
* test.describe('two tagged tests', {
* tag: '@smoke',
* }, () => {
* test('one', async ({ page }) => {
* // ...
* });
*
* test('two', async ({ page }) => {
* // ...
* });
* });
* ```
*
* Learn more about [tagging](https://playwright.dev/docs/test-annotations#tag-tests).
*
* **Annotations**
*
* You can annotate all tests in a group by providing additional details.
*
* ```js
* import { test, expect } from '@playwright/test';
*
* test.describe('two annotated tests', {
* annotation: {
* type: 'issue',
* description: 'https://github.com/microsoft/playwright/issues/23180',
* },
* }, () => {
* test('one', async ({ page }) => {
* // ...
* });
*
* test('two', async ({ page }) => {
* // ...
* });
* });
* ```
*
* Learn more about [test annotations](https://playwright.dev/docs/test-annotations).
*
* **Locks**
*
* You can declare named locks for all tests in a group by providing additional details. Tests that share a lock name
* never run concurrently. Learn more about [test locks](https://playwright.dev/docs/test-parallel#test-locks).
*
* ```js
* import { test, expect } from '@playwright/test';
*
* test.describe('two tests with a lock', {
* lock: 'user-settings',
* }, () => {
* test('one', async ({ page }) => {
* // ...
* });
*
* test('two', async ({ page }) => {
* // ...
* });
* });
* ```
*
* @param title Group title.
* @param details Additional details for all tests in the group.
* @param callback A callback that is run immediately when calling
* [test.describe([title, details, callback])](https://playwright.dev/docs/api/class-test#test-describe). Any tests
* declared in this callback will belong to the group.
*/
(callback: () => void): void
/**
* Declares a group of tests.
* - `test.describe(title, callback)`
* - `test.describe(callback)`
* - `test.describe(title, details, callback)`
*
* **Usage**
*
* You can declare a group of tests with a title. The title will be visible in the test report as a part of each
* test's title.
*
* ```js
* test.describe('two tests', () => {
* test('one', async ({ page }) => {
* // ...
* });
*
* test('two', async ({ page }) => {
* // ...
* });
* });
* ```
*
* **Anonymous group**
*
* You can also declare a test group without a title. This is convenient to give a group of tests a common option with
* [test.use(options)](https://playwright.dev/docs/api/class-test#test-use).
*
* ```js
* test.describe(() => {
* test.use({ colorScheme: 'dark' });
*
* test('one', async ({ page }) => {
* // ...
* });
*
* test('two', async ({ page }) => {
* // ...
* });
* });
* ```
*
* **Tags**
*
* You can tag all tests in a group by providing additional details. Note that each tag must start with `@` symbol.
*
* ```js
* import { test, expect } from '@playwright/test';
*
* test.describe('two tagged tests', {
* tag: '@smoke',
* }, () => {
* test('one', async ({ page }) => {
* // ...
* });
*
* test('two', async ({ page }) => {
* // ...
* });
* });
* ```
*
* Learn more about [tagging](https://playwright.dev/docs/test-annotations#tag-tests).
*
* **Annotations**
*
* You can annotate all tests in a group by providing additional details.
*
* ```js
* import { test, expect } from '@playwright/test';
*
* test.describe('two annotated tests', {
* annotation: {
* type: 'issue',
* description: 'https://github.com/microsoft/playwright/issues/23180',
* },
* }, () => {
* test('one', async ({ page }) => {
* // ...
* });
*
* test('two', async ({ page }) => {
* // ...
* });
* });
* ```
*
* Learn more about [test annotations](https://playwright.dev/docs/test-annotations).
*
* **Locks**
*
* You can declare named locks for all tests in a group by providing additional details. Tests that share a lock name
* never run concurrently. Learn more about [test locks](https://playwright.dev/docs/test-parallel#test-locks).
*
* ```js
* import { test, expect } from '@playwright/test';
*
* test.describe('two tests with a lock', {
* lock: 'user-settings',
* }, () => {
* test('one', async ({ page }) => {
* // ...
* });
*
* test('two', async ({ page }) => {
* // ...
* });
* });
* ```
*
* @param title Group title.
* @param details Additional details for all tests in the group.
* @param callback A callback that is run immediately when calling
* [test.describe([title, details, callback])](https://playwright.dev/docs/api/class-test#test-describe). Any tests
* declared in this callback will belong to the group.
*/
(title: string, details: TestDetails, callback: () => void): void
/**
* Declares a focused group of tests. If there are some focused tests or suites, all of them will be run but nothing
* else.
* - `test.describe.only(title, callback)`
* - `test.describe.only(callback)`
* - `test.describe.only(title, details, callback)`
*
* **Usage**
*
* ```js
* test.describe.only('focused group', () => {
* test('in the focused group', async ({ page }) => {
* // This test will run
* });
* });
* test('not in the focused group', async ({ page }) => {
* // This test will not run
* });
* ```
*
* You can also omit the title.
*
* ```js
* test.describe.only(() => {
* // ...
* });
* ```
*
* @param title Group title.
* @param details See [test.describe([title, details, callback])](https://playwright.dev/docs/api/class-test#test-describe) for
* details description.
* @param callback A callback that is run immediately when calling
* [test.describe.only([title, details, callback])](https://playwright.dev/docs/api/class-test#test-describe-only).
* Any tests added in this callback will belong to the group.
*/
only(title: string, callback: () => void): void
/**
* Declares a focused group of tests. If there are some focused tests or suites, all of them will be run but nothing
* else.
* - `test.describe.only(title, callback)`
* - `test.describe.only(callback)`
* - `test.describe.only(title, details, callback)`
*
* **Usage**
*
* ```js
* test.describe.only('focused group', () => {
* test('in the focused group', async ({ page }) => {
* // This test will run
* });
* });
* test('not in the focused group', async ({ page }) => {
* // This test will not run
* });
* ```
*
* You can also omit the title.
*
* ```js
* test.describe.only(() => {
* // ...
* });
* ```
*
* @param title Group title.
* @param details See [test.describe([title, details, callback])](https://playwright.dev/docs/api/class-test#test-describe) for
* details description.
* @param callback A callback that is run immediately when calling
* [test.describe.only([title, details, callback])](https://playwright.dev/docs/api/class-test#test-describe-only).
* Any tests added in this callback will belong to the group.
*/
only(callback: () => void): void
/**
* Declares a focused group of tests. If there are some focused tests or suites, all of them will be run but nothing
* else.
* - `test.describe.only(title, callback)`
* - `test.describe.only(callback)`
* - `test.describe.only(title, details, callback)`
*
* **Usage**
*
* ```js
* test.describe.only('focused group', () => {
* test('in the focused group', async ({ page }) => {
* // This test will run
* });
* });
* test('not in the focused group', async ({ page }) => {
* // This test will not run
* });
* ```
*
* You can also omit the title.
*
* ```js
* test.describe.only(() => {
* // ...
* });
* ```
*
* @param title Group title.
* @param details See [test.describe([title, details, callback])](https://playwright.dev/docs/api/class-test#test-describe) for
* details description.
* @param callback A callback that is run immediately when calling
* [test.describe.only([title, details, callback])](https://playwright.dev/docs/api/class-test#test-describe-only).
* Any tests added in this callback will belong to the group.
*/
only(title: string, details: TestDetails, callback: () => void): void
/**
* Declares a skipped test group, similarly to
* [test.describe([title, details, callback])](https://playwright.dev/docs/api/class-test#test-describe). Tests in the
* skipped group are never run.
* - `test.describe.skip(title, callback)`
* - `test.describe.skip(title)`
* - `test.describe.skip(title, details, callback)`
*
* **Usage**
*
* ```js
* test.describe.skip('skipped group', () => {
* test('example', async ({ page }) => {
* // This test will not run
* });
* });
* ```
*
* You can also omit the title.
*
* ```js
* test.describe.skip(() => {
* // ...
* });
* ```
*
* @param title Group title.
* @param details See [test.describe([title, details, callback])](https://playwright.dev/docs/api/class-test#test-describe) for
* details description.
* @param callback A callback that is run immediately when calling
* [test.describe.skip(title[, details, callback])](https://playwright.dev/docs/api/class-test#test-describe-skip).
* Any tests added in this callback will belong to the group, and will not be run.
*/
skip(title: string, callback: () => void): void
/**
* Declares a skipped test group, similarly to
* [test.describe([title, details, callback])](https://playwright.dev/docs/api/class-test#test-describe). Tests in the
* skipped group are never run.
* - `test.describe.skip(title, callback)`
* - `test.describe.skip(title)`
* - `test.describe.skip(title, details, callback)`
*
* **Usage**
*
* ```js
* test.describe.skip('skipped group', () => {
* test('example', async ({ page }) => {
* // This test will not run
* });
* });
* ```
*
* You can also omit the title.
*
* ```js
* test.describe.skip(() => {
* // ...
* });
* ```
*
* @param title Group title.
* @param details See [test.describe([title, details, callback])](https://playwright.dev/docs/api/class-test#test-describe) for
* details description.
* @param callback A callback that is run immediately when calling
* [test.describe.skip(title[, details, callback])](https://playwright.dev/docs/api/class-test#test-describe-skip).
* Any tests added in this callback will belong to the group, and will not be run.
*/
skip(callback: () => void): void
/**
* Declares a skipped test group, similarly to
* [test.describe([title, details, callback])](https://playwright.dev/docs/api/class-test#test-describe). Tests in the
* skipped group are never run.
* - `test.describe.skip(title, callback)`
* - `test.describe.skip(title)`
* - `test.describe.skip(title, details, callback)`
*
* **Usage**
*
* ```js
* test.describe.skip('skipped group', () => {
* test('example', async ({ page }) => {
* // This test will not run
* });
* });
* ```
*
* You can also omit the title.
*
* ```js
* test.describe.skip(() => {
* // ...
* });
* ```
*
* @param title Group title.
* @param details See [test.describe([title, details, callback])](https://playwright.dev/docs/api/class-test#test-describe) for
* details description.
* @param callback A callback that is run immediately when calling
* [test.describe.skip(title[, details, callback])](https://playwright.dev/docs/api/class-test#test-describe-skip).
* Any tests added in this callback will belong to the group, and will not be run.
*/
skip(title: string, details: TestDetails, callback: () => void): void
/**
* Declares a test group similarly to
* [test.describe([title, details, callback])](https://playwright.dev/docs/api/class-test#test-describe). Tests in
* this group are marked as "fixme" and will not be executed.
* - `test.describe.fixme(title, callback)`
* - `test.describe.fixme(callback)`
* - `test.describe.fixme(title, details, callback)`
*
* **Usage**
*
* ```js
* test.describe.fixme('broken tests that should be fixed', () => {
* test('example', async ({ page }) => {
* // This test will not run
* });
* });
* ```
*
* You can also omit the title.
*
* ```js
* test.describe.fixme(() => {
* // ...
* });
* ```
*
* @param title Group title.
* @param details See [test.describe([title, details, callback])](https://playwright.dev/docs/api/class-test#test-describe) for
* details description.
* @param callback A callback that is run immediately when calling
* [test.describe.fixme([title, details, callback])](https://playwright.dev/docs/api/class-test#test-describe-fixme).
* Any tests added in this callback will belong to the group, and will not be run.
*/
fixme(title: string, callback: () => void): void
/**
* Declares a test group similarly to
* [test.describe([title, details, callback])](https://playwright.dev/docs/api/class-test#test-describe). Tests in
* this group are marked as "fixme" and will not be executed.
* - `test.describe.fixme(title, callback)`
* - `test.describe.fixme(callback)`
* - `test.describe.fixme(title, details, callback)`
*
* **Usage**
*
* ```js
* test.describe.fixme('broken tests that should be fixed', () => {
* test('example', async ({ page }) => {
* // This test will not run
* });
* });
* ```
*
* You can also omit the title.
*
* ```js
* test.describe.fixme(() => {
* // ...
* });
* ```
*
* @param title Group title.
* @param details See [test.describe([title, details, callback])](https://playwright.dev/docs/api/class-test#test-describe) for
* details description.
* @param callback A callback that is run immediately when calling
* [test.describe.fixme([title, details, callback])](https://playwright.dev/docs/api/class-test#test-describe-fixme).
* Any tests added in this callback will belong to the group, and will not be run.
*/
fixme(callback: () => void): void
/**
* Declares a test group similarly to
* [test.describe([title, details, callback])](https://playwright.dev/docs/api/class-test#test-describe). Tests in
* this group are marked as "fixme" and will not be executed.
* - `test.describe.fixme(title, callback)`
* - `test.describe.fixme(callback)`
* - `test.describe.fixme(title, details, callback)`
*
* **Usage**
*
* ```js
* test.describe.fixme('broken tests that should be fixed', () => {
* test('example', async ({ page }) => {
* // This test will not run
* });
* });
* ```
*
* You can also omit the title.
*
* ```js
* test.describe.fixme(() => {
* // ...
* });
* ```
*
* @param title Group title.
* @param details See [test.describe([title, details, callback])](https://playwright.dev/docs/api/class-test#test-describe) for
* details description.
* @param callback A callback that is run immediately when calling
* [test.describe.fixme([title, details, callback])](https://playwright.dev/docs/api/class-test#test-describe-fixme).
* Any tests added in this callback will belong to the group, and will not be run.
*/
fixme(title: string, details: TestDetails, callback: () => void): void
/**
* **NOTE** See [test.describe.configure([options])](https://playwright.dev/docs/api/class-test#test-describe-configure) for
* the preferred way of configuring the execution mode.
*
* Declares a group of tests that should always be run serially. If one of the tests fails, all subsequent tests are
* skipped. All tests in a group are retried together.
*
* **NOTE** Using serial is not recommended. It is usually better to make your tests isolated, so they can be run
* independently.
*
* - `test.describe.serial(title, callback)`
* - `test.describe.serial(title)`
* - `test.describe.serial(title, details, callback)`
*
* **Usage**
*
* ```js
* test.describe.serial('group', () => {
* test('runs first', async ({ page }) => {});
* test('runs second', async ({ page }) => {});
* });
* ```
*
* You can also omit the title.
*
* ```js
* test.describe.serial(() => {
* // ...
* });
* ```
*
* @param title Group title.
* @param details See [test.describe([title, details, callback])](https://playwright.dev/docs/api/class-test#test-describe) for
* details description.
* @param callback A callback that is run immediately when calling
* [test.describe.serial([title, details, callback])](https://playwright.dev/docs/api/class-test#test-describe-serial).
* Any tests added in this callback will belong to the group.
*/
serial: {
/**
* **NOTE** See [test.describe.configure([options])](https://playwright.dev/docs/api/class-test#test-describe-configure) for
* the preferred way of configuring the execution mode.
*
* Declares a group of tests that should always be run serially. If one of the tests fails, all subsequent tests are
* skipped. All tests in a group are retried together.
*
* **NOTE** Using serial is not recommended. It is usually better to make your tests isolated, so they can be run
* independently.
*
* - `test.describe.serial(title, callback)`
* - `test.describe.serial(title)`
* - `test.describe.serial(title, details, callback)`
*
* **Usage**
*
* ```js
* test.describe.serial('group', () => {
* test('runs first', async ({ page }) => {});
* test('runs second', async ({ page }) => {});
* });
* ```
*
* You can also omit the title.
*
* ```js
* test.describe.serial(() => {
* // ...
* });
* ```
*
* @param title Group title.
* @param details See [test.describe([title, details, callback])](https://playwright.dev/docs/api/class-test#test-describe) for
* details description.
* @param callback A callback that is run immediately when calling
* [test.describe.serial([title, details, callback])](https://playwright.dev/docs/api/class-test#test-describe-serial).
* Any tests added in this callback will belong to the group.
*/
(title: string, callback: () => void): void
/**
* **NOTE** See [test.describe.configure([options])](https://playwright.dev/docs/api/class-test#test-describe-configure) for
* the preferred way of configuring the execution mode.
*
* Declares a group of tests that should always be run serially. If one of the tests fails, all subsequent tests are
* skipped. All tests in a group are retried together.
*
* **NOTE** Using serial is not recommended. It is usually better to make your tests isolated, so they can be run
* independently.
*
* - `test.describe.serial(title, callback)`
* - `test.describe.serial(title)`
* - `test.describe.serial(title, details, callback)`
*
* **Usage**
*
* ```js
* test.describe.serial('group', () => {
* test('runs first', async ({ page }) => {});
* test('runs second', async ({ page }) => {});
* });
* ```
*
* You can also omit the title.
*
* ```js
* test.describe.serial(() => {
* // ...
* });
* ```
*
* @param title Group title.
* @param details See [test.describe([title, details, callback])](https://playwright.dev/docs/api/class-test#test-describe) for
* details description.
* @param callback A callback that is run immediately when calling
* [test.describe.serial([title, details, callback])](https://playwright.dev/docs/api/class-test#test-describe-serial).
* Any tests added in this callback will belong to the group.
*/
(callback: () => void): void
/**
* **NOTE** See [test.describe.configure([options])](https://playwright.dev/docs/api/class-test#test-describe-configure) for
* the preferred way of configuring the execution mode.
*
* Declares a group of tests that should always be run serially. If one of the tests fails, all subsequent tests are
* skipped. All tests in a group are retried together.
*
* **NOTE** Using serial is not recommended. It is usually better to make your tests isolated, so they can be run
* independently.
*
* - `test.describe.serial(title, callback)`
* - `test.describe.serial(title)`
* - `test.describe.serial(title, details, callback)`
*
* **Usage**
*
* ```js
* test.describe.serial('group', () => {
* test('runs first', async ({ page }) => {});
* test('runs second', async ({ page }) => {});
* });
* ```
*
* You can also omit the title.
*
* ```js
* test.describe.serial(() => {
* // ...
* });
* ```
*
* @param title Group title.
* @param details See [test.describe([title, details, callback])](https://playwright.dev/docs/api/class-test#test-describe) for
* details description.
* @param callback A callback that is run immediately when calling
* [test.describe.serial([title, details, callback])](https://playwright.dev/docs/api/class-test#test-describe-serial).
* Any tests added in this callback will belong to the group.
*/
(title: string, details: TestDetails, callback: () => void): void
/**
* **NOTE** See [test.describe.configure([options])](https://playwright.dev/docs/api/class-test#test-describe-configure) for
* the preferred way of configuring the execution mode.
*
* Declares a focused group of tests that should always be run serially. If one of the tests fails, all subsequent
* tests are skipped. All tests in a group are retried together. If there are some focused tests or suites, all of
* them will be run but nothing else.
*
* **NOTE** Using serial is not recommended. It is usually better to make your tests isolated, so they can be run
* independently.
*
* - `test.describe.serial.only(title, callback)`
* - `test.describe.serial.only(title)`
* - `test.describe.serial.only(title, details, callback)`
*
* **Usage**
*
* ```js
* test.describe.serial.only('group', () => {
* test('runs first', async ({ page }) => {
* });
* test('runs second', async ({ page }) => {
* });
* });
* ```
*
* You can also omit the title.
*
* ```js
* test.describe.serial.only(() => {
* // ...
* });
* ```
*
* @param title Group title.
* @param details See [test.describe([title, details, callback])](https://playwright.dev/docs/api/class-test#test-describe) for
* details description.
* @param callback A callback that is run immediately when calling
* [test.describe.serial.only(title[, details, callback])](https://playwright.dev/docs/api/class-test#test-describe-serial-only).
* Any tests added in this callback will belong to the group.
*/
only(title: string, callback: () => void): void
/**
* **NOTE** See [test.describe.configure([options])](https://playwright.dev/docs/api/class-test#test-describe-configure) for
* the preferred way of configuring the execution mode.
*
* Declares a focused group of tests that should always be run serially. If one of the tests fails, all subsequent
* tests are skipped. All tests in a group are retried together. If there are some focused tests or suites, all of
* them will be run but nothing else.
*
* **NOTE** Using serial is not recommended. It is usually better to make your tests isolated, so they can be run
* independently.
*
* - `test.describe.serial.only(title, callback)`
* - `test.describe.serial.only(title)`
* - `test.describe.serial.only(title, details, callback)`
*
* **Usage**
*
* ```js
* test.describe.serial.only('group', () => {
* test('runs first', async ({ page }) => {
* });
* test('runs second', async ({ page }) => {
* });
* });
* ```
*
* You can also omit the title.
*
* ```js
* test.describe.serial.only(() => {
* // ...
* });
* ```
*
* @param title Group title.
* @param details See [test.describe([title, details, callback])](https://playwright.dev/docs/api/class-test#test-describe) for
* details description.
* @param callback A callback that is run immediately when calling
* [test.describe.serial.only(title[, details, callback])](https://playwright.dev/docs/api/class-test#test-describe-serial-only).
* Any tests added in this callback will belong to the group.
*/
only(callback: () => void): void
/**
* **NOTE** See [test.describe.configure([options])](https://playwright.dev/docs/api/class-test#test-describe-configure) for
* the preferred way of configuring the execution mode.
*
* Declares a focused group of tests that should always be run serially. If one of the tests fails, all subsequent
* tests are skipped. All tests in a group are retried together. If there are some focused tests or suites, all of
* them will be run but nothing else.
*
* **NOTE** Using serial is not recommended. It is usually better to make your tests isolated, so they can be run
* independently.
*
* - `test.describe.serial.only(title, callback)`
* - `test.describe.serial.only(title)`
* - `test.describe.serial.only(title, details, callback)`
*
* **Usage**
*
* ```js
* test.describe.serial.only('group', () => {
* test('runs first', async ({ page }) => {
* });
* test('runs second', async ({ page }) => {
* });
* });
* ```
*
* You can also omit the title.
*
* ```js
* test.describe.serial.only(() => {
* // ...
* });
* ```
*
* @param title Group title.
* @param details See [test.describe([title, details, callback])](https://playwright.dev/docs/api/class-test#test-describe) for
* details description.
* @param callback A callback that is run immediately when calling
* [test.describe.serial.only(title[, details, callback])](https://playwright.dev/docs/api/class-test#test-describe-serial-only).
* Any tests added in this callback will belong to the group.
*/
only(title: string, details: TestDetails, callback: () => void): void
}
/**
* **NOTE** See [test.describe.configure([options])](https://playwright.dev/docs/api/class-test#test-describe-configure) for
* the preferred way of configuring the execution mode.
*
* Declares a group of tests that could be run in parallel. By default, tests in a single test file run one after
* another, but using
* [test.describe.parallel([title, details, callback])](https://playwright.dev/docs/api/class-test#test-describe-parallel)
* allows them to run in parallel.
* - `test.describe.parallel(title, callback)`
* - `test.describe.parallel(callback)`
* - `test.describe.parallel(title, details, callback)`
*
* **Usage**
*
* ```js
* test.describe.parallel('group', () => {
* test('runs in parallel 1', async ({ page }) => {});
* test('runs in parallel 2', async ({ page }) => {});
* });
* ```
*
* Note that parallel tests are executed in separate processes and cannot share any state or global variables. Each of
* the parallel tests executes all relevant hooks.
*
* You can also omit the title.
*
* ```js
* test.describe.parallel(() => {
* // ...
* });
* ```
*
* @param title Group title.
* @param details See [test.describe([title, details, callback])](https://playwright.dev/docs/api/class-test#test-describe) for
* details description.
* @param callback A callback that is run immediately when calling
* [test.describe.parallel([title, details, callback])](https://playwright.dev/docs/api/class-test#test-describe-parallel).
* Any tests added in this callback will belong to the group.
*/
parallel: {
/**
* **NOTE** See [test.describe.configure([options])](https://playwright.dev/docs/api/class-test#test-describe-configure) for
* the preferred way of configuring the execution mode.
*
* Declares a group of tests that could be run in parallel. By default, tests in a single test file run one after
* another, but using
* [test.describe.parallel([title, details, callback])](https://playwright.dev/docs/api/class-test#test-describe-parallel)
* allows them to run in parallel.
* - `test.describe.parallel(title, callback)`
* - `test.describe.parallel(callback)`
* - `test.describe.parallel(title, details, callback)`
*
* **Usage**
*
* ```js
* test.describe.parallel('group', () => {
* test('runs in parallel 1', async ({ page }) => {});
* test('runs in parallel 2', async ({ page }) => {});
* });
* ```
*
* Note that parallel tests are executed in separate processes and cannot share any state or global variables. Each of
* the parallel tests executes all relevant hooks.
*
* You can also omit the title.
*
* ```js
* test.describe.parallel(() => {
* // ...
* });
* ```
*
* @param title Group title.
* @param details See [test.describe([title, details, callback])](https://playwright.dev/docs/api/class-test#test-describe) for
* details description.
* @param callback A callback that is run immediately when calling
* [test.describe.parallel([title, details, callback])](https://playwright.dev/docs/api/class-test#test-describe-parallel).
* Any tests added in this callback will belong to the group.
*/
(title: string, callback: () => void): void
/**
* **NOTE** See [test.describe.configure([options])](https://playwright.dev/docs/api/class-test#test-describe-configure) for
* the preferred way of configuring the execution mode.
*
* Declares a group of tests that could be run in parallel. By default, tests in a single test file run one after
* another, but using
* [test.describe.parallel([title, details, callback])](https://playwright.dev/docs/api/class-test#test-describe-parallel)
* allows them to run in parallel.
* - `test.describe.parallel(title, callback)`
* - `test.describe.parallel(callback)`
* - `test.describe.parallel(title, details, callback)`
*
* **Usage**
*
* ```js
* test.describe.parallel('group', () => {
* test('runs in parallel 1', async ({ page }) => {});
* test('runs in parallel 2', async ({ page }) => {});
* });
* ```
*
* Note that parallel tests are executed in separate processes and cannot share any state or global variables. Each of
* the parallel tests executes all relevant hooks.
*
* You can also omit the title.
*
* ```js
* test.describe.parallel(() => {
* // ...
* });
* ```
*
* @param title Group title.
* @param details See [test.describe([title, details, callback])](https://playwright.dev/docs/api/class-test#test-describe) for
* details description.
* @param callback A callback that is run immediately when calling
* [test.describe.parallel([title, details, callback])](https://playwright.dev/docs/api/class-test#test-describe-parallel).
* Any tests added in this callback will belong to the group.
*/
(callback: () => void): void
/**
* **NOTE** See [test.describe.configure([options])](https://playwright.dev/docs/api/class-test#test-describe-configure) for
* the preferred way of configuring the execution mode.
*
* Declares a group of tests that could be run in parallel. By default, tests in a single test file run one after
* another, but using
* [test.describe.parallel([title, details, callback])](https://playwright.dev/docs/api/class-test#test-describe-parallel)
* allows them to run in parallel.
* - `test.describe.parallel(title, callback)`
* - `test.describe.parallel(callback)`
* - `test.describe.parallel(title, details, callback)`
*
* **Usage**
*
* ```js
* test.describe.parallel('group', () => {
* test('runs in parallel 1', async ({ page }) => {});
* test('runs in parallel 2', async ({ page }) => {});
* });
* ```
*
* Note that parallel tests are executed in separate processes and cannot share any state or global variables. Each of
* the parallel tests executes all relevant hooks.
*
* You can also omit the title.
*
* ```js
* test.describe.parallel(() => {
* // ...
* });
* ```
*
* @param title Group title.
* @param details See [test.describe([title, details, callback])](https://playwright.dev/docs/api/class-test#test-describe) for
* details description.
* @param callback A callback that is run immediately when calling
* [test.describe.parallel([title, details, callback])](https://playwright.dev/docs/api/class-test#test-describe-parallel).
* Any tests added in this callback will belong to the group.
*/
(title: string, details: TestDetails, callback: () => void): void
/**
* **NOTE** See [test.describe.configure([options])](https://playwright.dev/docs/api/class-test#test-describe-configure) for
* the preferred way of configuring the execution mode.
*
* Declares a focused group of tests that could be run in parallel. This is similar to
* [test.describe.parallel([title, details, callback])](https://playwright.dev/docs/api/class-test#test-describe-parallel),
* but focuses the group. If there are some focused tests or suites, all of them will be run but nothing else.
* - `test.describe.parallel.only(title, callback)`
* - `test.describe.parallel.only(callback)`
* - `test.describe.parallel.only(title, details, callback)`
*
* **Usage**
*
* ```js
* test.describe.parallel.only('group', () => {
* test('runs in parallel 1', async ({ page }) => {});
* test('runs in parallel 2', async ({ page }) => {});
* });
* ```
*
* You can also omit the title.
*
* ```js
* test.describe.parallel.only(() => {
* // ...
* });
* ```
*
* @param title Group title.
* @param details See [test.describe([title, details, callback])](https://playwright.dev/docs/api/class-test#test-describe) for
* details description.
* @param callback A callback that is run immediately when calling
* [test.describe.parallel.only([title, details, callback])](https://playwright.dev/docs/api/class-test#test-describe-parallel-only).
* Any tests added in this callback will belong to the group.
*/
only(title: string, callback: () => void): void
/**
* **NOTE** See [test.describe.configure([options])](https://playwright.dev/docs/api/class-test#test-describe-configure) for
* the preferred way of configuring the execution mode.
*
* Declares a focused group of tests that could be run in parallel. This is similar to
* [test.describe.parallel([title, details, callback])](https://playwright.dev/docs/api/class-test#test-describe-parallel),
* but focuses the group. If there are some focused tests or suites, all of them will be run but nothing else.
* - `test.describe.parallel.only(title, callback)`
* - `test.describe.parallel.only(callback)`
* - `test.describe.parallel.only(title, details, callback)`
*
* **Usage**
*
* ```js
* test.describe.parallel.only('group', () => {
* test('runs in parallel 1', async ({ page }) => {});
* test('runs in parallel 2', async ({ page }) => {});
* });
* ```
*
* You can also omit the title.
*
* ```js
* test.describe.parallel.only(() => {
* // ...
* });
* ```
*
* @param title Group title.
* @param details See [test.describe([title, details, callback])](https://playwright.dev/docs/api/class-test#test-describe) for
* details description.
* @param callback A callback that is run immediately when calling
* [test.describe.parallel.only([title, details, callback])](https://playwright.dev/docs/api/class-test#test-describe-parallel-only).
* Any tests added in this callback will belong to the group.
*/
only(callback: () => void): void
/**
* **NOTE** See [test.describe.configure([options])](https://playwright.dev/docs/api/class-test#test-describe-configure) for
* the preferred way of configuring the execution mode.
*
* Declares a focused group of tests that could be run in parallel. This is similar to
* [test.describe.parallel([title, details, callback])](https://playwright.dev/docs/api/class-test#test-describe-parallel),
* but focuses the group. If there are some focused tests or suites, all of them will be run but nothing else.
* - `test.describe.parallel.only(title, callback)`
* - `test.describe.parallel.only(callback)`
* - `test.describe.parallel.only(title, details, callback)`
*
* **Usage**
*
* ```js
* test.describe.parallel.only('group', () => {
* test('runs in parallel 1', async ({ page }) => {});
* test('runs in parallel 2', async ({ page }) => {});
* });
* ```
*
* You can also omit the title.
*
* ```js
* test.describe.parallel.only(() => {
* // ...
* });
* ```
*
* @param title Group title.
* @param details See [test.describe([title, details, callback])](https://playwright.dev/docs/api/class-test#test-describe) for
* details description.
* @param callback A callback that is run immediately when calling
* [test.describe.parallel.only([title, details, callback])](https://playwright.dev/docs/api/class-test#test-describe-parallel-only).
* Any tests added in this callback will belong to the group.
*/
only(title: string, details: TestDetails, callback: () => void): void
}
/**
* Configures the enclosing scope. Can be executed either on the top level or inside a describe. Configuration applies
* to the entire scope, regardless of whether it run before or after the test declaration.
*
* Learn more about the execution modes [here](https://playwright.dev/docs/test-parallel).
*
* **Usage**
* - Running tests in parallel.
*
* ```js
* // Run all the tests in the file concurrently using parallel workers.
* test.describe.configure({ mode: 'parallel' });
* test('runs in parallel 1', async ({ page }) => {});
* test('runs in parallel 2', async ({ page }) => {});
* ```
*
* - Running tests in order, retrying each failed test independently.
*
* This is the default mode. It can be useful to set it explicitly to override project configuration that uses
* `fullyParallel`.
*
* ```js
* // Tests in this file run in order. Retries, if any, run independently.
* test.describe.configure({ mode: 'default' });
* test('runs first', async ({ page }) => {});
* test('runs second', async ({ page }) => {});
* ```
*
* - Running tests serially, retrying from the start. If one of the serial tests fails, all subsequent tests are
* skipped.
*
* **NOTE** Running serially is not recommended. It is usually better to make your tests isolated, so they can be
* run independently.
*
* ```js
* // Annotate tests as inter-dependent.
* test.describe.configure({ mode: 'serial' });
* test('runs first', async ({ page }) => {});
* test('runs second', async ({ page }) => {});
* ```
*
* - Configuring retries and timeout for each test.
*
* ```js
* // Each test in the file will be retried twice and have a timeout of 20 seconds.
* test.describe.configure({ retries: 2, timeout: 20_000 });
* test('runs first', async ({ page }) => {});
* test('runs second', async ({ page }) => {});
* ```
*
* - Run multiple describes in parallel, but tests inside each describe in order.
*
* ```js
* test.describe.configure({ mode: 'parallel' });
*
* test.describe('A, runs in parallel with B', () => {
* test.describe.configure({ mode: 'default' });
* test('in order A1', async ({ page }) => {});
* test('in order A2', async ({ page }) => {});
* });
*
* test.describe('B, runs in parallel with A', () => {
* test.describe.configure({ mode: 'default' });
* test('in order B1', async ({ page }) => {});
* test('in order B2', async ({ page }) => {});
* });
* ```
*
* @param options
*/
configure: (options: {
mode?: 'default' | 'parallel' | 'serial'
retries?: number
timeout?: number
}) => void
}
/**
* Skip a test. Playwright will not run the test past the `test.skip()` call.
*
* Skipped tests are not supposed to be ever run. If you intend to fix the test, use
* [test.fixme([title, details, body, condition, callback, description])](https://playwright.dev/docs/api/class-test#test-fixme)
* instead.
*
* To declare a skipped test:
* - `test.skip(title, body)`
* - `test.skip(title, details, body)`
*
* To skip a test at runtime:
* - `test.skip(condition, description)`
* - `test.skip(callback, description)`
* - `test.skip()`
*
* **Usage**
*
* You can declare a skipped test, and Playwright will not run it.
*
* ```js
* import { test, expect } from '@playwright/test';
*
* test.skip('never run', async ({ page }) => {
* // ...
* });
* ```
*
* If your test should be skipped in some configurations, but not all, you can skip the test inside the test body
* based on some condition. We recommend passing a `description` argument in this case. Playwright will run the test,
* but abort it immediately after the `test.skip` call.
*
* ```js
* import { test, expect } from '@playwright/test';
*
* test('Safari-only test', async ({ page, browserName }) => {
* test.skip(browserName !== 'webkit', 'This feature is Safari-only');
* // ...
* });
* ```
*
* You can skip all tests in a file or
* [test.describe([title, details, callback])](https://playwright.dev/docs/api/class-test#test-describe) group based
* on some condition with a single `test.skip(callback, description)` call.
*
* ```js
* import { test, expect } from '@playwright/test';
*
* test.skip(({ browserName }) => browserName !== 'webkit', 'Safari-only');
*
* test('Safari-only test 1', async ({ page }) => {
* // ...
* });
* test('Safari-only test 2', async ({ page }) => {
* // ...
* });
* ```
*
* You can also call `test.skip()` without arguments inside the test body to always skip the test. However, we
* recommend using `test.skip(title, body)` instead.
*
* ```js
* import { test, expect } from '@playwright/test';
*
* test('less readable', async ({ page }) => {
* test.skip();
* // ...
* });
* ```
*
* @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.
* @param body Test body that takes one or two arguments: an object with fixtures and optional
* [TestInfo](https://playwright.dev/docs/api/class-testinfo).
* @param condition Test is marked as "skipped" when the condition is `true`.
* @param callback A function that returns whether to mark as "skipped", based on test fixtures. Test or tests are marked as "skipped"
* when the return value is `true`.
* @param description Optional description that will be reflected in a test report.
*/
skip(title: string, body: TestBody<TestArgs & WorkerArgs>): void
/**
* Skip a test. Playwright will not run the test past the `test.skip()` call.
*
* Skipped tests are not supposed to be ever run. If you intend to fix the test, use
* [test.fixme([title, details, body, condition, callback, description])](https://playwright.dev/docs/api/class-test#test-fixme)
* instead.
*
* To declare a skipped test:
* - `test.skip(title, body)`
* - `test.skip(title, details, body)`
*
* To skip a test at runtime:
* - `test.skip(condition, description)`
* - `test.skip(callback, description)`
* - `test.skip()`
*
* **Usage**
*
* You can declare a skipped test, and Playwright will not run it.
*
* ```js
* import { test, expect } from '@playwright/test';
*
* test.skip('never run', async ({ page }) => {
* // ...
* });
* ```
*
* If your test should be skipped in some configurations, but not all, you can skip the test inside the test body
* based on some condition. We recommend passing a `description` argument in this case. Playwright will run the test,
* but abort it immediately after the `test.skip` call.
*
* ```js
* import { test, expect } from '@playwright/test';
*
* test('Safari-only test', async ({ page, browserName }) => {
* test.skip(browserName !== 'webkit', 'This feature is Safari-only');
* // ...
* });
* ```
*
* You can skip all tests in a file or
* [test.describe([title, details, callback])](https://playwright.dev/docs/api/class-test#test-describe) group based
* on some condition with a single `test.skip(callback, description)` call.
*
* ```js
* import { test, expect } from '@playwright/test';
*
* test.skip(({ browserName }) => browserName !== 'webkit', 'Safari-only');
*
* test('Safari-only test 1', async ({ page }) => {
* // ...
* });
* test('Safari-only test 2', async ({ page }) => {
* // ...
* });
* ```
*
* You can also call `test.skip()` without arguments inside the test body to always skip the test. However, we
* recommend using `test.skip(title, body)` instead.
*
* ```js
* import { test, expect } from '@playwright/test';
*
* test('less readable', async ({ page }) => {
* test.skip();
* // ...
* });
* ```
*
* @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.
* @param body Test body that takes one or two arguments: an object with fixtures and optional
* [TestInfo](https://playwright.dev/docs/api/class-testinfo).
* @param condition Test is marked as "skipped" when the condition is `true`.
* @param callback A function that returns whether to mark as "skipped", based on test fixtures. Test or tests are marked as "skipped"
* when the return value is `true`.
* @param description Optional description that will be reflected in a test report.
*/
skip(title: string, details: TestDetails, body: TestBody<TestArgs & WorkerArgs>): void
/**
* Skip a test. Playwright will not run the test past the `test.skip()` call.
*
* Skipped tests are not supposed to be ever run. If you intend to fix the test, use
* [test.fixme([title, details, body, condition, callback, description])](https://playwright.dev/docs/api/class-test#test-fixme)
* instead.
*
* To declare a skipped test:
* - `test.skip(title, body)`
* - `test.skip(title, details, body)`
*
* To skip a test at runtime:
* - `test.skip(condition, description)`
* - `test.skip(callback, description)`
* - `test.skip()`
*
* **Usage**
*
* You can declare a skipped test, and Playwright will not run it.
*
* ```js
* import { test, expect } from '@playwright/test';
*
* test.skip('never run', async ({ page }) => {
* // ...
* });
* ```
*
* If your test should be skipped in some configurations, but not all, you can skip the test inside the test body
* based on some condition. We recommend passing a `description` argument in this case. Playwright will run the test,
* but abort it immediately after the `test.skip` call.
*
* ```js
* import { test, expect } from '@playwright/test';
*
* test('Safari-only test', async ({ page, browserName }) => {
* test.skip(browserName !== 'webkit', 'This feature is Safari-only');
* // ...
* });
* ```
*
* You can skip all tests in a file or
* [test.describe([title, details, callback])](https://playwright.dev/docs/api/class-test#test-describe) group based
* on some condition with a single `test.skip(callback, description)` call.
*
* ```js
* import { test, expect } from '@playwright/test';
*
* test.skip(({ browserName }) => browserName !== 'webkit', 'Safari-only');
*
* test('Safari-only test 1', async ({ page }) => {
* // ...
* });
* test('Safari-only test 2', async ({ page }) => {
* // ...
* });
* ```
*
* You can also call `test.skip()` without arguments inside the test body to always skip the test. However, we
* recommend using `test.skip(title, body)` instead.
*
* ```js
* import { test, expect } from '@playwright/test';
*
* test('less readable', async ({ page }) => {
* test.skip();
* // ...
* });
* ```
*
* @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.
* @param body Test body that takes one or two arguments: an object with fixtures and optional
* [TestInfo](https://playwright.dev/docs/api/class-testinfo).
* @param condition Test is marked as "skipped" when the condition is `true`.
* @param callback A function that returns whether to mark as "skipped", based on test fixtures. Test or tests are marked as "skipped"
* when the return value is `true`.
* @param description Optional description that will be reflected in a test report.
*/
skip(): void
/**
* Skip a test. Playwright will not run the test past the `test.skip()` call.
*
* Skipped tests are not supposed to be ever run. If you intend to fix the test, use
* [test.fixme([title, details, body, condition, callback, description])](https://playwright.dev/docs/api/class-test#test-fixme)
* instead.
*
* To declare a skipped test:
* - `test.skip(title, body)`
* - `test.skip(title, details, body)`
*
* To skip a test at runtime:
* - `test.skip(condition, description)`
* - `test.skip(callback, description)`
* - `test.skip()`
*
* **Usage**
*
* You can declare a skipped test, and Playwright will not run it.
*
* ```js
* import { test, expect } from '@playwright/test';
*
* test.skip('never run', async ({ page }) => {
* // ...
* });
* ```
*
* If your test should be skipped in some configurations, but not all, you can skip the test inside the test body
* based on some condition. We recommend passing a `description` argument in this case. Playwright will run the test,
* but abort it immediately after the `test.skip` call.
*
* ```js
* import { test, expect } from '@playwright/test';
*
* test('Safari-only test', async ({ page, browserName }) => {
* test.skip(browserName !== 'webkit', 'This feature is Safari-only');
* // ...
* });
* ```
*
* You can skip all tests in a file or
* [test.describe([title, details, callback])](https://playwright.dev/docs/api/class-test#test-describe) group based
* on some condition with a single `test.skip(callback, description)` call.
*
* ```js
* import { test, expect } from '@playwright/test';
*
* test.skip(({ browserName }) => browserName !== 'webkit', 'Safari-only');
*
* test('Safari-only test 1', async ({ page }) => {
* // ...
* });
* test('Safari-only test 2', async ({ page }) => {
* // ...
* });
* ```
*
* You can also call `test.skip()` without arguments inside the test body to always skip the test. However, we
* recommend using `test.skip(title, body)` instead.
*
* ```js
* import { test, expect } from '@playwright/test';
*
* test('less readable', async ({ page }) => {
* test.skip();
* // ...
* });
* ```
*
* @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.
* @param body Test body that takes one or two arguments: an object with fixtures and optional
* [TestInfo](https://playwright.dev/docs/api/class-testinfo).
* @param condition Test is marked as "skipped" when the condition is `true`.
* @param callback A function that returns whether to mark as "skipped", based on test fixtures. Test or tests are marked as "skipped"
* when the return value is `true`.
* @param description Optional description that will be reflected in a test report.
*/
skip(condition: boolean, description?: string): void
/**
* Skip a test. Playwright will not run the test past the `test.skip()` call.
*
* Skipped tests are not supposed to be ever run. If you intend to fix the test, use
* [test.fixme([title, details, body, condition, callback, description])](https://playwright.dev/docs/api/class-test#test-fixme)
* instead.
*
* To declare a skipped test:
* - `test.skip(title, body)`
* - `test.skip(title, details, body)`
*
* To skip a test at runtime:
* - `test.skip(condition, description)`
* - `test.skip(callback, description)`
* - `test.skip()`
*
* **Usage**
*
* You can declare a skipped test, and Playwright will not run it.
*
* ```js
* import { test, expect } from '@playwright/test';
*
* test.skip('never run', async ({ page }) => {
* // ...
* });
* ```
*
* If your test should be skipped in some configurations, but not all, you can skip the test inside the test body
* based on some condition. We recommend passing a `description` argument in this case. Playwright will run the test,
* but abort it immediately after the `test.skip` call.
*
* ```js
* import { test, expect } from '@playwright/test';
*
* test('Safari-only test', async ({ page, browserName }) => {
* test.skip(browserName !== 'webkit', 'This feature is Safari-only');
* // ...
* });
* ```
*
* You can skip all tests in a file or
* [test.describe([title, details, callback])](https://playwright.dev/docs/api/class-test#test-describe) group based
* on some condition with a single `test.skip(callback, description)` call.
*
* ```js
* import { test, expect } from '@playwright/test';
*
* test.skip(({ browserName }) => browserName !== 'webkit', 'Safari-only');
*
* test('Safari-only test 1', async ({ page }) => {
* // ...
* });
* test('Safari-only test 2', async ({ page }) => {
* // ...
* });
* ```
*
* You can also call `test.skip()` without arguments inside the test body to always skip the test. However, we
* recommend using `test.skip(title, body)` instead.
*
* ```js
* import { test, expect } from '@playwright/test';
*
* test('less readable', async ({ page }) => {
* test.skip();
* // ...
* });
* ```
*
* @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.
* @param body Test body that takes one or two arguments: an object with fixtures and optional
* [TestInfo](https://playwright.dev/docs/api/class-testinfo).
* @param condition Test is marked as "skipped" when the condition is `true`.
* @param callback A function that returns whether to mark as "skipped", based on test fixtures. Test or tests are marked as "skipped"
* when the return value is `true`.
* @param description Optional description that will be reflected in a test report.
*/
skip(callback: ConditionBody<TestArgs & WorkerArgs>, description?: string): void
/**
* Mark a test as "fixme", with the intention to fix it. Playwright will not run the test past the `test.fixme()`
* call.
*
* To declare a "fixme" test:
* - `test.fixme(title, body)`
* - `test.fixme(title, details, body)`
*
* To annotate test as "fixme" at runtime:
* - `test.fixme(condition, description)`
* - `test.fixme(callback, description)`
* - `test.fixme()`
*
* **Usage**
*
* You can declare a test as to be fixed, and Playwright will not run it.
*
* ```js
* import { test, expect } from '@playwright/test';
*
* test.fixme('to be fixed', async ({ page }) => {
* // ...
* });
* ```
*
* If your test should be fixed in some configurations, but not all, you can mark the test as "fixme" inside the test
* body based on some condition. We recommend passing a `description` argument in this case. Playwright will run the
* test, but abort it immediately after the `test.fixme` call.
*
* ```js
* import { test, expect } from '@playwright/test';
*
* test('to be fixed in Safari', async ({ page, browserName }) => {
* test.fixme(browserName === 'webkit', 'This feature breaks in Safari for some reason');
* // ...
* });
* ```
*
* You can mark all tests in a file or
* [test.describe([title, details, callback])](https://playwright.dev/docs/api/class-test#test-describe) group as
* "fixme" based on some condition with a single `test.fixme(callback, description)` call.
*
* ```js
* import { test, expect } from '@playwright/test';
*
* test.fixme(({ browserName }) => browserName === 'webkit', 'Should figure out the issue');
*
* test('to be fixed in Safari 1', async ({ page }) => {
* // ...
* });
* test('to be fixed in Safari 2', async ({ page }) => {
* // ...
* });
* ```
*
* You can also call `test.fixme()` without arguments inside the test body to always mark the test as failed. We
* recommend using `test.fixme(title, body)` instead.
*
* ```js
* import { test, expect } from '@playwright/test';
*
* test('less readable', async ({ page }) => {
* test.fixme();
* // ...
* });
* ```
*
* @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.
* @param body Test body that takes one or two arguments: an object with fixtures and optional
* [TestInfo](https://playwright.dev/docs/api/class-testinfo).
* @param condition Test is marked as "fixme" when the condition is `true`.
* @param callback A function that returns whether to mark as "fixme", based on test fixtures. Test or tests are marked as "fixme"
* when the return value is `true`.
* @param description Optional description that will be reflected in a test report.
*/
fixme(title: string, body: TestBody<TestArgs & WorkerArgs>): void
/**
* Mark a test as "fixme", with the intention to fix it. Playwright will not run the test past the `test.fixme()`
* call.
*
* To declare a "fixme" test:
* - `test.fixme(title, body)`
* - `test.fixme(title, details, body)`
*
* To annotate test as "fixme" at runtime:
* - `test.fixme(condition, description)`
* - `test.fixme(callback, description)`
* - `test.fixme()`
*
* **Usage**
*
* You can declare a test as to be fixed, and Playwright will not run it.
*
* ```js
* import { test, expect } from '@playwright/test';
*
* test.fixme('to be fixed', async ({ page }) => {
* // ...
* });
* ```
*
* If your test should be fixed in some configurations, but not all, you can mark the test as "fixme" inside the test
* body based on some condition. We recommend passing a `description` argument in this case. Playwright will run the
* test, but abort it immediately after the `test.fixme` call.
*
* ```js
* import { test, expect } from '@playwright/test';
*
* test('to be fixed in Safari', async ({ page, browserName }) => {
* test.fixme(browserName === 'webkit', 'This feature breaks in Safari for some reason');
* // ...
* });
* ```
*
* You can mark all tests in a file or
* [test.describe([title, details, callback])](https://playwright.dev/docs/api/class-test#test-describe) group as
* "fixme" based on some condition with a single `test.fixme(callback, description)` call.
*
* ```js
* import { test, expect } from '@playwright/test';
*
* test.fixme(({ browserName }) => browserName === 'webkit', 'Should figure out the issue');
*
* test('to be fixed in Safari 1', async ({ page }) => {
* // ...
* });
* test('to be fixed in Safari 2', async ({ page }) => {
* // ...
* });
* ```
*
* You can also call `test.fixme()` without arguments inside the test body to always mark the test as failed. We
* recommend using `test.fixme(title, body)` instead.
*
* ```js
* import { test, expect } from '@playwright/test';
*
* test('less readable', async ({ page }) => {
* test.fixme();
* // ...
* });
* ```
*
* @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.
* @param body Test body that takes one or two arguments: an object with fixtures and optional
* [TestInfo](https://playwright.dev/docs/api/class-testinfo).
* @param condition Test is marked as "fixme" when the condition is `true`.
* @param callback A function that returns whether to mark as "fixme", based on test fixtures. Test or tests are marked as "fixme"
* when the return value is `true`.
* @param description Optional description that will be reflected in a test report.
*/
fixme(title: string, details: TestDetails, body: TestBody<TestArgs & WorkerArgs>): void
/**
* Mark a test as "fixme", with the intention to fix it. Playwright will not run the test past the `test.fixme()`
* call.
*
* To declare a "fixme" test:
* - `test.fixme(title, body)`
* - `test.fixme(title, details, body)`
*
* To annotate test as "fixme" at runtime:
* - `test.fixme(condition, description)`
* - `test.fixme(callback, description)`
* - `test.fixme()`
*
* **Usage**
*
* You can declare a test as to be fixed, and Playwright will not run it.
*
* ```js
* import { test, expect } from '@playwright/test';
*
* test.fixme('to be fixed', async ({ page }) => {
* // ...
* });
* ```
*
* If your test should be fixed in some configurations, but not all, you can mark the test as "fixme" inside the test
* body based on some condition. We recommend passing a `description` argument in this case. Playwright will run the
* test, but abort it immediately after the `test.fixme` call.
*
* ```js
* import { test, expect } from '@playwright/test';
*
* test('to be fixed in Safari', async ({ page, browserName }) => {
* test.fixme(browserName === 'webkit', 'This feature breaks in Safari for some reason');
* // ...
* });
* ```
*
* You can mark all tests in a file or
* [test.describe([title, details, callback])](https://playwright.dev/docs/api/class-test#test-describe) group as
* "fixme" based on some condition with a single `test.fixme(callback, description)` call.
*
* ```js
* import { test, expect } from '@playwright/test';
*
* test.fixme(({ browserName }) => browserName === 'webkit', 'Should figure out the issue');
*
* test('to be fixed in Safari 1', async ({ page }) => {
* // ...
* });
* test('to be fixed in Safari 2', async ({ page }) => {
* // ...
* });
* ```
*
* You can also call `test.fixme()` without arguments inside the test body to always mark the test as failed. We
* recommend using `test.fixme(title, body)` instead.
*
* ```js
* import { test, expect } from '@playwright/test';
*
* test('less readable', async ({ page }) => {
* test.fixme();
* // ...
* });
* ```
*
* @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.
* @param body Test body that takes one or two arguments: an object with fixtures and optional
* [TestInfo](https://playwright.dev/docs/api/class-testinfo).
* @param condition Test is marked as "fixme" when the condition is `true`.
* @param callback A function that returns whether to mark as "fixme", based on test fixtures. Test or tests are marked as "fixme"
* when the return value is `true`.
* @param description Optional description that will be reflected in a test report.
*/
fixme(): void
/**
* Mark a test as "fixme", with the intention to fix it. Playwright will not run the test past the `test.fixme()`
* call.
*
* To declare a "fixme" test:
* - `test.fixme(title, body)`
* - `test.fixme(title, details, body)`
*
* To annotate test as "fixme" at runtime:
* - `test.fixme(condition, description)`
* - `test.fixme(callback, description)`
* - `test.fixme()`
*
* **Usage**
*
* You can declare a test as to be fixed, and Playwright will not run it.
*
* ```js
* import { test, expect } from '@playwright/test';
*
* test.fixme('to be fixed', async ({ page }) => {
* // ...
* });
* ```
*
* If your test should be fixed in some configurations, but not all, you can mark the test as "fixme" inside the test
* body based on some condition. We recommend passing a `description` argument in this case. Playwright will run the
* test, but abort it immediately after the `test.fixme` call.
*
* ```js
* import { test, expect } from '@playwright/test';
*
* test('to be fixed in Safari', async ({ page, browserName }) => {
* test.fixme(browserName === 'webkit', 'This feature breaks in Safari for some reason');
* // ...
* });
* ```
*
* You can mark all tests in a file or
* [test.describe([title, details, callback])](https://playwright.dev/docs/api/class-test#test-describe) group as
* "fixme" based on some condition with a single `test.fixme(callback, description)` call.
*
* ```js
* import { test, expect } from '@playwright/test';
*
* test.fixme(({ browserName }) => browserName === 'webkit', 'Should figure out the issue');
*
* test('to be fixed in Safari 1', async ({ page }) => {
* // ...
* });
* test('to be fixed in Safari 2', async ({ page }) => {
* // ...
* });
* ```
*
* You can also call `test.fixme()` without arguments inside the test body to always mark the test as failed. We
* recommend using `test.fixme(title, body)` instead.
*
* ```js
* import { test, expect } from '@playwright/test';
*
* test('less readable', async ({ page }) => {
* test.fixme();
* // ...
* });
* ```
*
* @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.
* @param body Test body that takes one or two arguments: an object with fixtures and optional
* [TestInfo](https://playwright.dev/docs/api/class-testinfo).
* @param condition Test is marked as "fixme" when the condition is `true`.
* @param callback A function that returns whether to mark as "fixme", based on test fixtures. Test or tests are marked as "fixme"
* when the return value is `true`.
* @param description Optional description that will be reflected in a test report.
*/
fixme(condition: boolean, description?: string): void
/**
* Mark a test as "fixme", with the intention to fix it. Playwright will not run the test past the `test.fixme()`
* call.
*
* To declare a "fixme" test:
* - `test.fixme(title, body)`
* - `test.fixme(title, details, body)`
*
* To annotate test as "fixme" at runtime:
* - `test.fixme(condition, description)`
* - `test.fixme(callback, description)`
* - `test.fixme()`
*
* **Usage**
*
* You can declare a test as to be fixed, and Playwright will not run it.
*
* ```js
* import { test, expect } from '@playwright/test';
*
* test.fixme('to be fixed', async ({ page }) => {
* // ...
* });
* ```
*
* If your test should be fixed in some configurations, but not all, you can mark the test as "fixme" inside the test
* body based on some condition. We recommend passing a `description` argument in this case. Playwright will run the
* test, but abort it immediately after the `test.fixme` call.
*
* ```js
* import { test, expect } from '@playwright/test';
*
* test('to be fixed in Safari', async ({ page, browserName }) => {
* test.fixme(browserName === 'webkit', 'This feature breaks in Safari for some reason');
* // ...
* });
* ```
*
* You can mark all tests in a file or
* [test.describe([title, details, callback])](https://playwright.dev/docs/api/class-test#test-describe) group as
* "fixme" based on some condition with a single `test.fixme(callback, description)` call.
*
* ```js
* import { test, expect } from '@playwright/test';
*
* test.fixme(({ browserName }) => browserName === 'webkit', 'Should figure out the issue');
*
* test('to be fixed in Safari 1', async ({ page }) => {
* // ...
* });
* test('to be fixed in Safari 2', async ({ page }) => {
* // ...
* });
* ```
*
* You can also call `test.fixme()` without arguments inside the test body to always mark the test as failed. We
* recommend using `test.fixme(title, body)` instead.
*
* ```js
* import { test, expect } from '@playwright/test';
*
* test('less readable', async ({ page }) => {
* test.fixme();
* // ...
* });
* ```
*
* @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.
* @param body Test body that takes one or two arguments: an object with fixtures and optional
* [TestInfo](https://playwright.dev/docs/api/class-testinfo).
* @param condition Test is marked as "fixme" when the condition is `true`.
* @param callback A function that returns whether to mark as "fixme", based on test fixtures. Test or tests are marked as "fixme"
* when the return value is `true`.
* @param description Optional description that will be reflected in a test report.
*/
fixme(callback: ConditionBody<TestArgs & WorkerArgs>, description?: string): void
/**
* Marks a test as "should fail". Playwright runs this test and ensures that it is actually failing. This is useful
* for documentation purposes to acknowledge that some functionality is broken until it is fixed.
*
* To declare a "failing" test:
* - `test.fail(title, body)`
* - `test.fail(title, details, body)`
*
* To annotate test as "failing" at runtime:
* - `test.fail(condition, description)`
* - `test.fail(callback, description)`
* - `test.fail()`
*
* **Usage**
*
* You can declare a test as failing, so that Playwright ensures it actually fails.
*
* ```js
* import { test, expect } from '@playwright/test';
*
* test.fail('not yet ready', async ({ page }) => {
* // ...
* });
* ```
*
* If your test fails in some configurations, but not all, you can mark the test as failing inside the test body based
* on some condition. We recommend passing a `description` argument in this case.
*
* ```js
* import { test, expect } from '@playwright/test';
*
* test('fail in WebKit', async ({ page, browserName }) => {
* test.fail(browserName === 'webkit', 'This feature is not implemented for Mac yet');
* // ...
* });
* ```
*
* You can mark all tests in a file or
* [test.describe([title, details, callback])](https://playwright.dev/docs/api/class-test#test-describe) group as
* "should fail" based on some condition with a single `test.fail(callback, description)` call.
*
* ```js
* import { test, expect } from '@playwright/test';
*
* test.fail(({ browserName }) => browserName === 'webkit', 'not implemented yet');
*
* test('fail in WebKit 1', async ({ page }) => {
* // ...
* });
* test('fail in WebKit 2', async ({ page }) => {
* // ...
* });
* ```
*
* You can also call `test.fail()` without arguments inside the test body to always mark the test as failed. We
* recommend declaring a failing test with `test.fail(title, body)` instead.
*
* ```js
* import { test, expect } from '@playwright/test';
*
* test('less readable', async ({ page }) => {
* test.fail();
* // ...
* });
* ```
*
* @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.
* @param body Test body that takes one or two arguments: an object with fixtures and optional
* [TestInfo](https://playwright.dev/docs/api/class-testinfo).
* @param condition Test is marked as "should fail" when the condition is `true`.
* @param callback A function that returns whether to mark as "should fail", based on test fixtures. Test or tests are marked as
* "should fail" when the return value is `true`.
* @param description Optional description that will be reflected in a test report.
*/
fail: {
/**
* Marks a test as "should fail". Playwright runs this test and ensures that it is actually failing. This is useful
* for documentation purposes to acknowledge that some functionality is broken until it is fixed.
*
* To declare a "failing" test:
* - `test.fail(title, body)`
* - `test.fail(title, details, body)`
*
* To annotate test as "failing" at runtime:
* - `test.fail(condition, description)`
* - `test.fail(callback, description)`
* - `test.fail()`
*
* **Usage**
*
* You can declare a test as failing, so that Playwright ensures it actually fails.
*
* ```js
* import { test, expect } from '@playwright/test';
*
* test.fail('not yet ready', async ({ page }) => {
* // ...
* });
* ```
*
* If your test fails in some configurations, but not all, you can mark the test as failing inside the test body based
* on some condition. We recommend passing a `description` argument in this case.
*
* ```js
* import { test, expect } from '@playwright/test';
*
* test('fail in WebKit', async ({ page, browserName }) => {
* test.fail(browserName === 'webkit', 'This feature is not implemented for Mac yet');
* // ...
* });
* ```
*
* You can mark all tests in a file or
* [test.describe([title, details, callback])](https://playwright.dev/docs/api/class-test#test-describe) group as
* "should fail" based on some condition with a single `test.fail(callback, description)` call.
*
* ```js
* import { test, expect } from '@playwright/test';
*
* test.fail(({ browserName }) => browserName === 'webkit', 'not implemented yet');
*
* test('fail in WebKit 1', async ({ page }) => {
* // ...
* });
* test('fail in WebKit 2', async ({ page }) => {
* // ...
* });
* ```
*
* You can also call `test.fail()` without arguments inside the test body to always mark the test as failed. We
* recommend declaring a failing test with `test.fail(title, body)` instead.
*
* ```js
* import { test, expect } from '@playwright/test';
*
* test('less readable', async ({ page }) => {
* test.fail();
* // ...
* });
* ```
*
* @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.
* @param body Test body that takes one or two arguments: an object with fixtures and optional
* [TestInfo](https://playwright.dev/docs/api/class-testinfo).
* @param condition Test is marked as "should fail" when the condition is `true`.
* @param callback A function that returns whether to mark as "should fail", based on test fixtures. Test or tests are marked as
* "should fail" when the return value is `true`.
* @param description Optional description that will be reflected in a test report.
*/
(title: string, body: TestBody<TestArgs & WorkerArgs>): void
/**
* Marks a test as "should fail". Playwright runs this test and ensures that it is actually failing. This is useful
* for documentation purposes to acknowledge that some functionality is broken until it is fixed.
*
* To declare a "failing" test:
* - `test.fail(title, body)`
* - `test.fail(title, details, body)`
*
* To annotate test as "failing" at runtime:
* - `test.fail(condition, description)`
* - `test.fail(callback, description)`
* - `test.fail()`
*
* **Usage**
*
* You can declare a test as failing, so that Playwright ensures it actually fails.
*
* ```js
* import { test, expect } from '@playwright/test';
*
* test.fail('not yet ready', async ({ page }) => {
* // ...
* });
* ```
*
* If your test fails in some configurations, but not all, you can mark the test as failing inside the test body based
* on some condition. We recommend passing a `description` argument in this case.
*
* ```js
* import { test, expect } from '@playwright/test';
*
* test('fail in WebKit', async ({ page, browserName }) => {
* test.fail(browserName === 'webkit', 'This feature is not implemented for Mac yet');
* // ...
* });
* ```
*
* You can mark all tests in a file or
* [test.describe([title, details, callback])](https://playwright.dev/docs/api/class-test#test-describe) group as
* "should fail" based on some condition with a single `test.fail(callback, description)` call.
*
* ```js
* import { test, expect } from '@playwright/test';
*
* test.fail(({ browserName }) => browserName === 'webkit', 'not implemented yet');
*
* test('fail in WebKit 1', async ({ page }) => {
* // ...
* });
* test('fail in WebKit 2', async ({ page }) => {
* // ...
* });
* ```
*
* You can also call `test.fail()` without arguments inside the test body to always mark the test as failed. We
* recommend declaring a failing test with `test.fail(title, body)` instead.
*
* ```js
* import { test, expect } from '@playwright/test';
*
* test('less readable', async ({ page }) => {
* test.fail();
* // ...
* });
* ```
*
* @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.
* @param body Test body that takes one or two arguments: an object with fixtures and optional
* [TestInfo](https://playwright.dev/docs/api/class-testinfo).
* @param condition Test is marked as "should fail" when the condition is `true`.
* @param callback A function that returns whether to mark as "should fail", based on test fixtures. Test or tests are marked as
* "should fail" when the return value is `true`.
* @param description Optional description that will be reflected in a test report.
*/
(title: string, details: TestDetails, body: TestBody<TestArgs & WorkerArgs>): void
/**
* Marks a test as "should fail". Playwright runs this test and ensures that it is actually failing. This is useful
* for documentation purposes to acknowledge that some functionality is broken until it is fixed.
*
* To declare a "failing" test:
* - `test.fail(title, body)`
* - `test.fail(title, details, body)`
*
* To annotate test as "failing" at runtime:
* - `test.fail(condition, description)`
* - `test.fail(callback, description)`
* - `test.fail()`
*
* **Usage**
*
* You can declare a test as failing, so that Playwright ensures it actually fails.
*
* ```js
* import { test, expect } from '@playwright/test';
*
* test.fail('not yet ready', async ({ page }) => {
* // ...
* });
* ```
*
* If your test fails in some configurations, but not all, you can mark the test as failing inside the test body based
* on some condition. We recommend passing a `description` argument in this case.
*
* ```js
* import { test, expect } from '@playwright/test';
*
* test('fail in WebKit', async ({ page, browserName }) => {
* test.fail(browserName === 'webkit', 'This feature is not implemented for Mac yet');
* // ...
* });
* ```
*
* You can mark all tests in a file or
* [test.describe([title, details, callback])](https://playwright.dev/docs/api/class-test#test-describe) group as
* "should fail" based on some condition with a single `test.fail(callback, description)` call.
*
* ```js
* import { test, expect } from '@playwright/test';
*
* test.fail(({ browserName }) => browserName === 'webkit', 'not implemented yet');
*
* test('fail in WebKit 1', async ({ page }) => {
* // ...
* });
* test('fail in WebKit 2', async ({ page }) => {
* // ...
* });
* ```
*
* You can also call `test.fail()` without arguments inside the test body to always mark the test as failed. We
* recommend declaring a failing test with `test.fail(title, body)` instead.
*
* ```js
* import { test, expect } from '@playwright/test';
*
* test('less readable', async ({ page }) => {
* test.fail();
* // ...
* });
* ```
*
* @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.
* @param body Test body that takes one or two arguments: an object with fixtures and optional
* [TestInfo](https://playwright.dev/docs/api/class-testinfo).
* @param condition Test is marked as "should fail" when the condition is `true`.
* @param callback A function that returns whether to mark as "should fail", based on test fixtures. Test or tests are marked as
* "should fail" when the return value is `true`.
* @param description Optional description that will be reflected in a test report.
*/
(condition: boolean, description?: string): void
/**
* Marks a test as "should fail". Playwright runs this test and ensures that it is actually failing. This is useful
* for documentation purposes to acknowledge that some functionality is broken until it is fixed.
*
* To declare a "failing" test:
* - `test.fail(title, body)`
* - `test.fail(title, details, body)`
*
* To annotate test as "failing" at runtime:
* - `test.fail(condition, description)`
* - `test.fail(callback, description)`
* - `test.fail()`
*
* **Usage**
*
* You can declare a test as failing, so that Playwright ensures it actually fails.
*
* ```js
* import { test, expect } from '@playwright/test';
*
* test.fail('not yet ready', async ({ page }) => {
* // ...
* });
* ```
*
* If your test fails in some configurations, but not all, you can mark the test as failing inside the test body based
* on some condition. We recommend passing a `description` argument in this case.
*
* ```js
* import { test, expect } from '@playwright/test';
*
* test('fail in WebKit', async ({ page, browserName }) => {
* test.fail(browserName === 'webkit', 'This feature is not implemented for Mac yet');
* // ...
* });
* ```
*
* You can mark all tests in a file or
* [test.describe([title, details, callback])](https://playwright.dev/docs/api/class-test#test-describe) group as
* "should fail" based on some condition with a single `test.fail(callback, description)` call.
*
* ```js
* import { test, expect } from '@playwright/test';
*
* test.fail(({ browserName }) => browserName === 'webkit', 'not implemented yet');
*
* test('fail in WebKit 1', async ({ page }) => {
* // ...
* });
* test('fail in WebKit 2', async ({ page }) => {
* // ...
* });
* ```
*
* You can also call `test.fail()` without arguments inside the test body to always mark the test as failed. We
* recommend declaring a failing test with `test.fail(title, body)` instead.
*
* ```js
* import { test, expect } from '@playwright/test';
*
* test('less readable', async ({ page }) => {
* test.fail();
* // ...
* });
* ```
*
* @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.
* @param body Test body that takes one or two arguments: an object with fixtures and optional
* [TestInfo](https://playwright.dev/docs/api/class-testinfo).
* @param condition Test is marked as "should fail" when the condition is `true`.
* @param callback A function that returns whether to mark as "should fail", based on test fixtures. Test or tests are marked as
* "should fail" when the return value is `true`.
* @param description Optional description that will be reflected in a test report.
*/
(callback: ConditionBody<TestArgs & WorkerArgs>, description?: string): void
/**
* Marks a test as "should fail". Playwright runs this test and ensures that it is actually failing. This is useful
* for documentation purposes to acknowledge that some functionality is broken until it is fixed.
*
* To declare a "failing" test:
* - `test.fail(title, body)`
* - `test.fail(title, details, body)`
*
* To annotate test as "failing" at runtime:
* - `test.fail(condition, description)`
* - `test.fail(callback, description)`
* - `test.fail()`
*
* **Usage**
*
* You can declare a test as failing, so that Playwright ensures it actually fails.
*
* ```js
* import { test, expect } from '@playwright/test';
*
* test.fail('not yet ready', async ({ page }) => {
* // ...
* });
* ```
*
* If your test fails in some configurations, but not all, you can mark the test as failing inside the test body based
* on some condition. We recommend passing a `description` argument in this case.
*
* ```js
* import { test, expect } from '@playwright/test';
*
* test('fail in WebKit', async ({ page, browserName }) => {
* test.fail(browserName === 'webkit', 'This feature is not implemented for Mac yet');
* // ...
* });
* ```
*
* You can mark all tests in a file or
* [test.describe([title, details, callback])](https://playwright.dev/docs/api/class-test#test-describe) group as
* "should fail" based on some condition with a single `test.fail(callback, description)` call.
*
* ```js
* import { test, expect } from '@playwright/test';
*
* test.fail(({ browserName }) => browserName === 'webkit', 'not implemented yet');
*
* test('fail in WebKit 1', async ({ page }) => {
* // ...
* });
* test('fail in WebKit 2', async ({ page }) => {
* // ...
* });
* ```
*
* You can also call `test.fail()` without arguments inside the test body to always mark the test as failed. We
* recommend declaring a failing test with `test.fail(title, body)` instead.
*
* ```js
* import { test, expect } from '@playwright/test';
*
* test('less readable', async ({ page }) => {
* test.fail();
* // ...
* });
* ```
*
* @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.
* @param body Test body that takes one or two arguments: an object with fixtures and optional
* [TestInfo](https://playwright.dev/docs/api/class-testinfo).
* @param condition Test is marked as "should fail" when the condition is `true`.
* @param callback A function that returns whether to mark as "should fail", based on test fixtures. Test or tests are marked as
* "should fail" when the return value is `true`.
* @param description Optional description that will be reflected in a test report.
*/
(): void
/**
* You can use `test.fail.only` to focus on a specific test that is expected to fail. This is particularly useful when
* debugging a failing test or working on a specific issue.
*
* To declare a focused "failing" test:
* - `test.fail.only(title, body)`
* - `test.fail.only(title, details, body)`
*
* **Usage**
*
* You can declare a focused failing test, so that Playwright runs only this test and ensures it actually fails.
*
* ```js
* import { test, expect } from '@playwright/test';
*
* test.fail.only('focused failing test', async ({ page }) => {
* // This test is expected to fail
* });
* test('not in the focused group', async ({ page }) => {
* // This test will not run
* });
* ```
*
* @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.
* @param body Test body that takes one or two arguments: an object with fixtures and optional
* [TestInfo](https://playwright.dev/docs/api/class-testinfo).
*/
only(title: string, body: TestBody<TestArgs & WorkerArgs>): void
/**
* You can use `test.fail.only` to focus on a specific test that is expected to fail. This is particularly useful when
* debugging a failing test or working on a specific issue.
*
* To declare a focused "failing" test:
* - `test.fail.only(title, body)`
* - `test.fail.only(title, details, body)`
*
* **Usage**
*
* You can declare a focused failing test, so that Playwright runs only this test and ensures it actually fails.
*
* ```js
* import { test, expect } from '@playwright/test';
*
* test.fail.only('focused failing test', async ({ page }) => {
* // This test is expected to fail
* });
* test('not in the focused group', async ({ page }) => {
* // This test will not run
* });
* ```
*
* @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.
* @param body Test body that takes one or two arguments: an object with fixtures and optional
* [TestInfo](https://playwright.dev/docs/api/class-testinfo).
*/
only(title: string, details: TestDetails, body: TestBody<TestArgs & WorkerArgs>): void
}
/**
* Aborts the currently running test by throwing an error. The test is immediately marked as failed and execution
* stops. This is useful from inside a fixture or a route handler when you have detected an unrecoverable misuse and
* want to fail the test right away.
*
* **Usage**
*
* ```js
* import { test, expect } from '@playwright/test';
*
* test('does not publish to shared page', async ({ page }) => {
* await page.route('**\/publish', route => {
* test.abort('Tests must not publish to the shared page. Use the `clone` option.');
* return route.abort();
* });
* // ...
* });
* ```
*
* @param message Optional message describing the reason for the abort. It will be included in the failure error.
*/
abort(message?: string): never
/**
* Marks a test as "slow". Slow test will be given triple the default timeout.
*
* Note that [test.slow([condition, callback, description])](https://playwright.dev/docs/api/class-test#test-slow)
* cannot be used in a `beforeAll` or `afterAll` hook. Use
* [test.setTimeout(timeout)](https://playwright.dev/docs/api/class-test#test-set-timeout) instead.
* - `test.slow()`
* - `test.slow(condition, description)`
* - `test.slow(callback, description)`
*
* **Usage**
*
* You can mark a test as slow by calling `test.slow()` inside the test body.
*
* ```js
* import { test, expect } from '@playwright/test';
*
* test('slow test', async ({ page }) => {
* test.slow();
* // ...
* });
* ```
*
* If your test is slow in some configurations, but not all, you can mark it as slow based on a condition. We
* recommend passing a `description` argument in this case.
*
* ```js
* import { test, expect } from '@playwright/test';
*
* test('slow in Safari', async ({ page, browserName }) => {
* test.slow(browserName === 'webkit', 'This feature is slow in Safari');
* // ...
* });
* ```
*
* You can mark all tests in a file or
* [test.describe([title, details, callback])](https://playwright.dev/docs/api/class-test#test-describe) group as
* "slow" based on some condition by passing a callback.
*
* ```js
* import { test, expect } from '@playwright/test';
*
* test.slow(({ browserName }) => browserName === 'webkit', 'all tests are slow in Safari');
*
* test('slow in Safari 1', async ({ page }) => {
* // ...
* });
* test('fail in Safari 2', async ({ page }) => {
* // ...
* });
* ```
*
* @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`.
* @param description Optional description that will be reflected in a test report.
*/
slow(): void
/**
* Marks a test as "slow". Slow test will be given triple the default timeout.
*
* Note that [test.slow([condition, callback, description])](https://playwright.dev/docs/api/class-test#test-slow)
* cannot be used in a `beforeAll` or `afterAll` hook. Use
* [test.setTimeout(timeout)](https://playwright.dev/docs/api/class-test#test-set-timeout) instead.
* - `test.slow()`
* - `test.slow(condition, description)`
* - `test.slow(callback, description)`
*
* **Usage**
*
* You can mark a test as slow by calling `test.slow()` inside the test body.
*
* ```js
* import { test, expect } from '@playwright/test';
*
* test('slow test', async ({ page }) => {
* test.slow();
* // ...
* });
* ```
*
* If your test is slow in some configurations, but not all, you can mark it as slow based on a condition. We
* recommend passing a `description` argument in this case.
*
* ```js
* import { test, expect } from '@playwright/test';
*
* test('slow in Safari', async ({ page, browserName }) => {
* test.slow(browserName === 'webkit', 'This feature is slow in Safari');
* // ...
* });
* ```
*
* You can mark all tests in a file or
* [test.describe([title, details, callback])](https://playwright.dev/docs/api/class-test#test-describe) group as
* "slow" based on some condition by passing a callback.
*
* ```js
* import { test, expect } from '@playwright/test';
*
* test.slow(({ browserName }) => browserName === 'webkit', 'all tests are slow in Safari');
*
* test('slow in Safari 1', async ({ page }) => {
* // ...
* });
* test('fail in Safari 2', async ({ page }) => {
* // ...
* });
* ```
*
* @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`.
* @param description Optional description that will be reflected in a test report.
*/
slow(condition: boolean, description?: string): void
/**
* Marks a test as "slow". Slow test will be given triple the default timeout.
*
* Note that [test.slow([condition, callback, description])](https://playwright.dev/docs/api/class-test#test-slow)
* cannot be used in a `beforeAll` or `afterAll` hook. Use
* [test.setTimeout(timeout)](https://playwright.dev/docs/api/class-test#test-set-timeout) instead.
* - `test.slow()`
* - `test.slow(condition, description)`
* - `test.slow(callback, description)`
*
* **Usage**
*
* You can mark a test as slow by calling `test.slow()` inside the test body.
*
* ```js
* import { test, expect } from '@playwright/test';
*
* test('slow test', async ({ page }) => {
* test.slow();
* // ...
* });
* ```
*
* If your test is slow in some configurations, but not all, you can mark it as slow based on a condition. We
* recommend passing a `description` argument in this case.
*
* ```js
* import { test, expect } from '@playwright/test';
*
* test('slow in Safari', async ({ page, browserName }) => {
* test.slow(browserName === 'webkit', 'This feature is slow in Safari');
* // ...
* });
* ```
*
* You can mark all tests in a file or
* [test.describe([title, details, callback])](https://playwright.dev/docs/api/class-test#test-describe) group as
* "slow" based on some condition by passing a callback.
*
* ```js
* import { test, expect } from '@playwright/test';
*
* test.slow(({ browserName }) => browserName === 'webkit', 'all tests are slow in Safari');
*
* test('slow in Safari 1', async ({ page }) => {
* // ...
* });
* test('fail in Safari 2', async ({ page }) => {
* // ...
* });
* ```
*
* @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`.
* @param description Optional description that will be reflected in a test report.
*/
slow(callback: ConditionBody<TestArgs & WorkerArgs>, description?: string): void
/**
* Changes the timeout for the test. Zero means no timeout. Learn more about [various timeouts](https://playwright.dev/docs/test-timeouts).
*
* Timeout for the currently running test is available through
* [testInfo.timeout](https://playwright.dev/docs/api/class-testinfo#test-info-timeout).
*
* **Usage**
* - Changing test timeout.
*
* ```js
* test('very slow test', async ({ page }) => {
* test.setTimeout(120000);
* // ...
* });
* ```
*
* - Changing timeout from a slow `beforeEach` hook. Note that this affects the test timeout that is shared with
* `beforeEach` hooks.
*
* ```js
* test.beforeEach(async ({ page }, testInfo) => {
* // Extend timeout for all tests running this hook by 30 seconds.
* test.setTimeout(testInfo.timeout + 30000);
* });
* ```
*
* - Changing timeout for a `beforeAll` or `afterAll` hook. Note this affects the hook's timeout, not the test
* timeout.
*
* ```js
* test.beforeAll(async () => {
* // Set timeout for this hook.
* test.setTimeout(60000);
* });
* ```
*
* - Changing timeout for all tests in a
* [test.describe([title, details, callback])](https://playwright.dev/docs/api/class-test#test-describe) group.
*
* ```js
* test.describe('group', () => {
* // Applies to all tests in this group.
* test.describe.configure({ timeout: 60000 });
*
* test('test one', async () => { /* ... *\/ });
* test('test two', async () => { /* ... *\/ });
* test('test three', async () => { /* ... *\/ });
* });
* ```
*
* @param timeout Timeout in milliseconds.
*/
setTimeout(timeout: number): void
/**
* Declares a `beforeEach` hook that is executed before each test.
*
* When called in the scope of a test file, runs before each test in the file. When called inside a
* [test.describe([title, details, callback])](https://playwright.dev/docs/api/class-test#test-describe) group, runs
* before each test in the group.
*
* You can access all the same [Fixtures](https://playwright.dev/docs/api/class-fixtures) as the test body itself, and
* also the [TestInfo](https://playwright.dev/docs/api/class-testinfo) object that gives a lot of useful information.
* For example, you can navigate the page before starting the test.
*
* You can use [test.afterEach([title, hookFunction])](https://playwright.dev/docs/api/class-test#test-after-each) to
* teardown any resources set up in `beforeEach`.
* - `test.beforeEach(hookFunction)`
* - `test.beforeEach(title, hookFunction)`
*
* **Details**
*
* When multiple `beforeEach` hooks are added, they will run in the order of their registration.
*
* Playwright will continue running all applicable hooks even if some of them have failed.
*
* **Usage**
*
* ```js
* // example.spec.ts
* import { test, expect } from '@playwright/test';
*
* test.beforeEach(async ({ page }) => {
* console.log(`Running ${test.info().title}`);
* await page.goto('https://my.start.url/');
* });
*
* test('my test', async ({ page }) => {
* expect(page.url()).toBe('https://my.start.url/');
* });
* ```
*
* Alternatively, you can declare a hook **with a title**.
*
* ```js
* // example.spec.ts
* test.beforeEach('Open start URL', async ({ page }) => {
* console.log(`Running ${test.info().title}`);
* await page.goto('https://my.start.url/');
* });
* ```
*
* @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).
*/
beforeEach(inner: (args: TestArgs & WorkerArgs, testInfo: TestInfo) => Promise<any> | any): void
/**
* Declares a `beforeEach` hook that is executed before each test.
*
* When called in the scope of a test file, runs before each test in the file. When called inside a
* [test.describe([title, details, callback])](https://playwright.dev/docs/api/class-test#test-describe) group, runs
* before each test in the group.
*
* You can access all the same [Fixtures](https://playwright.dev/docs/api/class-fixtures) as the test body itself, and
* also the [TestInfo](https://playwright.dev/docs/api/class-testinfo) object that gives a lot of useful information.
* For example, you can navigate the page before starting the test.
*
* You can use [test.afterEach([title, hookFunction])](https://playwright.dev/docs/api/class-test#test-after-each) to
* teardown any resources set up in `beforeEach`.
* - `test.beforeEach(hookFunction)`
* - `test.beforeEach(title, hookFunction)`
*
* **Details**
*
* When multiple `beforeEach` hooks are added, they will run in the order of their registration.
*
* Playwright will continue running all applicable hooks even if some of them have failed.
*
* **Usage**
*
* ```js
* // example.spec.ts
* import { test, expect } from '@playwright/test';
*
* test.beforeEach(async ({ page }) => {
* console.log(`Running ${test.info().title}`);
* await page.goto('https://my.start.url/');
* });
*
* test('my test', async ({ page }) => {
* expect(page.url()).toBe('https://my.start.url/');
* });
* ```
*
* Alternatively, you can declare a hook **with a title**.
*
* ```js
* // example.spec.ts
* test.beforeEach('Open start URL', async ({ page }) => {
* console.log(`Running ${test.info().title}`);
* await page.goto('https://my.start.url/');
* });
* ```
*
* @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).
*/
beforeEach(
title: string,
inner: (args: TestArgs & WorkerArgs, testInfo: TestInfo) => Promise<any> | any,
): void
/**
* Declares an `afterEach` hook that is executed after each test.
*
* When called in the scope of a test file, runs after each test in the file. When called inside a
* [test.describe([title, details, callback])](https://playwright.dev/docs/api/class-test#test-describe) group, runs
* after each test in the group.
*
* You can access all the same [Fixtures](https://playwright.dev/docs/api/class-fixtures) as the test body itself, and
* also the [TestInfo](https://playwright.dev/docs/api/class-testinfo) object that gives a lot of useful information.
* For example, you can check whether the test succeeded or failed.
* - `test.afterEach(hookFunction)`
* - `test.afterEach(title, hookFunction)`
*
* **Details**
*
* When multiple `afterEach` hooks are added, they will run in the order of their registration.
*
* Playwright will continue running all applicable hooks even if some of them have failed.
*
* **Usage**
*
* ```js
* // example.spec.ts
* import { test, expect } from '@playwright/test';
*
* test.afterEach(async ({ page }) => {
* console.log(`Finished ${test.info().title} with status ${test.info().status}`);
*
* if (test.info().status !== test.info().expectedStatus)
* console.log(`Did not run as expected, ended up at ${page.url()}`);
* });
*
* test('my test', async ({ page }) => {
* // ...
* });
* ```
*
* Alternatively, you can declare a hook **with a title**.
*
* ```js
* // example.spec.ts
* test.afterEach('Status check', async ({ page }) => {
* if (test.info().status !== test.info().expectedStatus)
* console.log(`Did not run as expected, ended up at ${page.url()}`);
* });
* ```
*
* @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).
*/
afterEach(inner: (args: TestArgs & WorkerArgs, testInfo: TestInfo) => Promise<any> | any): void
/**
* Declares an `afterEach` hook that is executed after each test.
*
* When called in the scope of a test file, runs after each test in the file. When called inside a
* [test.describe([title, details, callback])](https://playwright.dev/docs/api/class-test#test-describe) group, runs
* after each test in the group.
*
* You can access all the same [Fixtures](https://playwright.dev/docs/api/class-fixtures) as the test body itself, and
* also the [TestInfo](https://playwright.dev/docs/api/class-testinfo) object that gives a lot of useful information.
* For example, you can check whether the test succeeded or failed.
* - `test.afterEach(hookFunction)`
* - `test.afterEach(title, hookFunction)`
*
* **Details**
*
* When multiple `afterEach` hooks are added, they will run in the order of their registration.
*
* Playwright will continue running all applicable hooks even if some of them have failed.
*
* **Usage**
*
* ```js
* // example.spec.ts
* import { test, expect } from '@playwright/test';
*
* test.afterEach(async ({ page }) => {
* console.log(`Finished ${test.info().title} with status ${test.info().status}`);
*
* if (test.info().status !== test.info().expectedStatus)
* console.log(`Did not run as expected, ended up at ${page.url()}`);
* });
*
* test('my test', async ({ page }) => {
* // ...
* });
* ```
*
* Alternatively, you can declare a hook **with a title**.
*
* ```js
* // example.spec.ts
* test.afterEach('Status check', async ({ page }) => {
* if (test.info().status !== test.info().expectedStatus)
* console.log(`Did not run as expected, ended up at ${page.url()}`);
* });
* ```
*
* @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).
*/
afterEach(
title: string,
inner: (args: TestArgs & WorkerArgs, testInfo: TestInfo) => Promise<any> | any,
): void
/**
* Declares a `beforeAll` hook that is executed once per worker process before all tests.
*
* When called in the scope of a test file, runs before all tests in the file. When called inside a
* [test.describe([title, details, callback])](https://playwright.dev/docs/api/class-test#test-describe) group, runs
* before all tests in the group.
*
* You can use [test.afterAll([title, hookFunction])](https://playwright.dev/docs/api/class-test#test-after-all) to
* teardown any resources set up in `beforeAll`.
* - `test.beforeAll(hookFunction)`
* - `test.beforeAll(title, hookFunction)`
*
* **Details**
*
* When multiple `beforeAll` hooks are added, they will run in the order of their registration.
*
* Note that worker process is restarted on test failures, and `beforeAll` hook runs again in the new worker. Learn
* more about [workers and failures](https://playwright.dev/docs/test-retries).
*
* Playwright will continue running all applicable hooks even if some of them have failed.
*
* **Usage**
*
* ```js
* // example.spec.ts
* import { test, expect } from '@playwright/test';
*
* test.beforeAll(async () => {
* console.log('Before tests');
* });
*
* test.afterAll(async () => {
* console.log('After tests');
* });
*
* test('my test', async ({ page }) => {
* // ...
* });
* ```
*
* Alternatively, you can declare a hook **with a title**.
*
* ```js
* // example.spec.ts
* test.beforeAll('Setup', async () => {
* console.log('Before tests');
* });
* ```
*
* @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).
*/
beforeAll(inner: (args: TestArgs & WorkerArgs, testInfo: TestInfo) => Promise<any> | any): void
/**
* Declares a `beforeAll` hook that is executed once per worker process before all tests.
*
* When called in the scope of a test file, runs before all tests in the file. When called inside a
* [test.describe([title, details, callback])](https://playwright.dev/docs/api/class-test#test-describe) group, runs
* before all tests in the group.
*
* You can use [test.afterAll([title, hookFunction])](https://playwright.dev/docs/api/class-test#test-after-all) to
* teardown any resources set up in `beforeAll`.
* - `test.beforeAll(hookFunction)`
* - `test.beforeAll(title, hookFunction)`
*
* **Details**
*
* When multiple `beforeAll` hooks are added, they will run in the order of their registration.
*
* Note that worker process is restarted on test failures, and `beforeAll` hook runs again in the new worker. Learn
* more about [workers and failures](https://playwright.dev/docs/test-retries).
*
* Playwright will continue running all applicable hooks even if some of them have failed.
*
* **Usage**
*
* ```js
* // example.spec.ts
* import { test, expect } from '@playwright/test';
*
* test.beforeAll(async () => {
* console.log('Before tests');
* });
*
* test.afterAll(async () => {
* console.log('After tests');
* });
*
* test('my test', async ({ page }) => {
* // ...
* });
* ```
*
* Alternatively, you can declare a hook **with a title**.
*
* ```js
* // example.spec.ts
* test.beforeAll('Setup', async () => {
* console.log('Before tests');
* });
* ```
*
* @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).
*/
beforeAll(
title: string,
inner: (args: TestArgs & WorkerArgs, testInfo: TestInfo) => Promise<any> | any,
): void
/**
* Declares an `afterAll` hook that is executed once per worker after all tests.
*
* When called in the scope of a test file, runs after all tests in the file. When called inside a
* [test.describe([title, details, callback])](https://playwright.dev/docs/api/class-test#test-describe) group, runs
* after all tests in the group.
*
* **Details**
*
* When multiple `afterAll` hooks are added, they will run in the order of their registration.
*
* Note that worker process is restarted on test failures, and `afterAll` hook runs again in the new worker. Learn
* more about [workers and failures](https://playwright.dev/docs/test-retries).
*
* Playwright will continue running all applicable hooks even if some of them have failed.
* - `test.afterAll(hookFunction)`
* - `test.afterAll(title, hookFunction)`
*
* **Usage**
*
* ```js
* test.afterAll(async () => {
* console.log('Done with tests');
* // ...
* });
* ```
*
* Alternatively, you can declare a hook **with a title**.
*
* ```js
* test.afterAll('Teardown', async () => {
* console.log('Done with tests');
* // ...
* });
* ```
*
* @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).
*/
afterAll(inner: (args: TestArgs & WorkerArgs, testInfo: TestInfo) => Promise<any> | any): void
/**
* Declares an `afterAll` hook that is executed once per worker after all tests.
*
* When called in the scope of a test file, runs after all tests in the file. When called inside a
* [test.describe([title, details, callback])](https://playwright.dev/docs/api/class-test#test-describe) group, runs
* after all tests in the group.
*
* **Details**
*
* When multiple `afterAll` hooks are added, they will run in the order of their registration.
*
* Note that worker process is restarted on test failures, and `afterAll` hook runs again in the new worker. Learn
* more about [workers and failures](https://playwright.dev/docs/test-retries).
*
* Playwright will continue running all applicable hooks even if some of them have failed.
* - `test.afterAll(hookFunction)`
* - `test.afterAll(title, hookFunction)`
*
* **Usage**
*
* ```js
* test.afterAll(async () => {
* console.log('Done with tests');
* // ...
* });
* ```
*
* Alternatively, you can declare a hook **with a title**.
*
* ```js
* test.afterAll('Teardown', async () => {
* console.log('Done with tests');
* // ...
* });
* ```
*
* @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).
*/
afterAll(
title: string,
inner: (args: TestArgs & WorkerArgs, testInfo: TestInfo) => Promise<any> | any,
): void
/**
* Specifies options or fixtures to use in a single test file or a
* [test.describe([title, details, callback])](https://playwright.dev/docs/api/class-test#test-describe) group. Most
* useful to set an option, for example set `locale` to configure `context` fixture.
*
* **Usage**
*
* ```js
* import { test, expect } from '@playwright/test';
*
* test.use({ locale: 'en-US' });
*
* test('test with locale', async ({ page }) => {
* // Default context and page have locale as specified
* });
* ```
*
* **Details**
*
* `test.use` can be called either in the global scope or inside `test.describe`. It is an error to call it within
* `beforeEach` or `beforeAll`.
*
* It is also possible to override a fixture by providing a function.
*
* ```js
* import { test, expect } from '@playwright/test';
*
* test.use({
* locale: async ({}, use) => {
* // Read locale from some configuration file.
* const locale = await fs.promises.readFile('test-locale', 'utf-8');
* await use(locale);
* },
* });
*
* test('test with locale', async ({ page }) => {
* // Default context and page have locale as specified
* });
* ```
*
* @param options An object with local options.
*/
use(fixtures: Fixtures<{}, {}, TestArgs, WorkerArgs>): void
/**
* Declares a test step that is shown in the report.
*
* **Usage**
*
* ```js
* import { test, expect } from '@playwright/test';
*
* test('test', async ({ page }) => {
* await test.step('Log in', async () => {
* // ...
* });
*
* await test.step('Outer step', async () => {
* // ...
* // You can nest steps inside each other.
* await test.step('Inner step', async () => {
* // ...
* });
* });
* });
* ```
*
* **Details**
*
* The method returns the value returned by the step callback.
*
* ```js
* import { test, expect } from '@playwright/test';
*
* test('test', async ({ page }) => {
* const user = await test.step('Log in', async () => {
* // ...
* return 'john';
* });
* expect(user).toBe('john');
* });
* ```
*
* **Decorator**
*
* You can use TypeScript method decorators to turn a method into a step. Each call to the decorated method will show
* up as a step in the report.
*
* ```js
* function step(target: Function, context: ClassMethodDecoratorContext) {
* return function replacementMethod(...args: any) {
* const name = this.constructor.name + '.' + (context.name as string);
* return test.step(name, async () => {
* return await target.call(this, ...args);
* }, { box: true });
* };
* }
*
* class LoginPage {
* constructor(readonly page: Page) {}
*
* @step
* async login() {
* const account = { username: 'Alice', password: 's3cr3t' };
* await this.page.getByLabel('Username or email address').fill(account.username);
* await this.page.getByLabel('Password').fill(account.password);
* await this.page.getByRole('button', { name: 'Sign in' }).click();
* await expect(this.page.getByRole('button', { name: 'View profile and more' })).toBeVisible();
* }
* }
*
* test('example', async ({ page }) => {
* const loginPage = new LoginPage(page);
* await loginPage.login();
* });
* ```
*
* **Boxing**
*
* When something inside a step fails, you would usually see the error pointing to the exact action that failed. For
* example, consider the following login step:
*
* ```js
* async function login(page) {
* await test.step('login', async () => {
* const account = { username: 'Alice', password: 's3cr3t' };
* await page.getByLabel('Username or email address').fill(account.username);
* await page.getByLabel('Password').fill(account.password);
* await page.getByRole('button', { name: 'Sign in' }).click();
* await expect(page.getByRole('button', { name: 'View profile and more' })).toBeVisible();
* });
* }
*
* test('example', async ({ page }) => {
* await page.goto('https://github.com/login');
* await login(page);
* });
* ```
*
* ```txt
* Error: Timed out 5000ms waiting for expect(locator).toBeVisible()
* ... error details omitted ...
*
* 8 | await page.getByRole('button', { name: 'Sign in' }).click();
* > 9 | await expect(page.getByRole('button', { name: 'View profile and more' })).toBeVisible();
* | ^
* 10 | });
* ```
*
* As we see above, the test may fail with an error pointing inside the step. If you would like the error to highlight
* the "login" step instead of its internals, use the `box` option. An error inside a boxed step points to the step
* call site.
*
* ```js
* async function login(page) {
* await test.step('login', async () => {
* // ...
* }, { box: true }); // Note the "box" option here.
* }
* ```
*
* ```txt
* Error: Timed out 5000ms waiting for expect(locator).toBeVisible()
* ... error details omitted ...
*
* 14 | await page.goto('https://github.com/login');
* > 15 | await login(page);
* | ^
* 16 | });
* ```
*
* You can also create a TypeScript decorator for a boxed step, similar to a regular step decorator above:
*
* ```js
* function boxedStep(target: Function, context: ClassMethodDecoratorContext) {
* return function replacementMethod(...args: any) {
* const name = this.constructor.name + '.' + (context.name as string);
* return test.step(name, async () => {
* return await target.call(this, ...args);
* }, { box: true }); // Note the "box" option here.
* };
* }
*
* class LoginPage {
* constructor(readonly page: Page) {}
*
* @boxedStep
* async login() {
* // ....
* }
* }
*
* test('example', async ({ page }) => {
* const loginPage = new LoginPage(page);
* await loginPage.login(); // <-- Error will be reported on this line.
* });
* ```
*
* @param title Step name.
* @param body Step body.
* @param options
*/
step: {
/**
* Declares a test step that is shown in the report.
*
* **Usage**
*
* ```js
* import { test, expect } from '@playwright/test';
*
* test('test', async ({ page }) => {
* await test.step('Log in', async () => {
* // ...
* });
*
* await test.step('Outer step', async () => {
* // ...
* // You can nest steps inside each other.
* await test.step('Inner step', async () => {
* // ...
* });
* });
* });
* ```
*
* **Details**
*
* The method returns the value returned by the step callback.
*
* ```js
* import { test, expect } from '@playwright/test';
*
* test('test', async ({ page }) => {
* const user = await test.step('Log in', async () => {
* // ...
* return 'john';
* });
* expect(user).toBe('john');
* });
* ```
*
* **Decorator**
*
* You can use TypeScript method decorators to turn a method into a step. Each call to the decorated method will show
* up as a step in the report.
*
* ```js
* function step(target: Function, context: ClassMethodDecoratorContext) {
* return function replacementMethod(...args: any) {
* const name = this.constructor.name + '.' + (context.name as string);
* return test.step(name, async () => {
* return await target.call(this, ...args);
* }, { box: true });
* };
* }
*
* class LoginPage {
* constructor(readonly page: Page) {}
*
* @step
* async login() {
* const account = { username: 'Alice', password: 's3cr3t' };
* await this.page.getByLabel('Username or email address').fill(account.username);
* await this.page.getByLabel('Password').fill(account.password);
* await this.page.getByRole('button', { name: 'Sign in' }).click();
* await expect(this.page.getByRole('button', { name: 'View profile and more' })).toBeVisible();
* }
* }
*
* test('example', async ({ page }) => {
* const loginPage = new LoginPage(page);
* await loginPage.login();
* });
* ```
*
* **Boxing**
*
* When something inside a step fails, you would usually see the error pointing to the exact action that failed. For
* example, consider the following login step:
*
* ```js
* async function login(page) {
* await test.step('login', async () => {
* const account = { username: 'Alice', password: 's3cr3t' };
* await page.getByLabel('Username or email address').fill(account.username);
* await page.getByLabel('Password').fill(account.password);
* await page.getByRole('button', { name: 'Sign in' }).click();
* await expect(page.getByRole('button', { name: 'View profile and more' })).toBeVisible();
* });
* }
*
* test('example', async ({ page }) => {
* await page.goto('https://github.com/login');
* await login(page);
* });
* ```
*
* ```txt
* Error: Timed out 5000ms waiting for expect(locator).toBeVisible()
* ... error details omitted ...
*
* 8 | await page.getByRole('button', { name: 'Sign in' }).click();
* > 9 | await expect(page.getByRole('button', { name: 'View profile and more' })).toBeVisible();
* | ^
* 10 | });
* ```
*
* As we see above, the test may fail with an error pointing inside the step. If you would like the error to highlight
* the "login" step instead of its internals, use the `box` option. An error inside a boxed step points to the step
* call site.
*
* ```js
* async function login(page) {
* await test.step('login', async () => {
* // ...
* }, { box: true }); // Note the "box" option here.
* }
* ```
*
* ```txt
* Error: Timed out 5000ms waiting for expect(locator).toBeVisible()
* ... error details omitted ...
*
* 14 | await page.goto('https://github.com/login');
* > 15 | await login(page);
* | ^
* 16 | });
* ```
*
* You can also create a TypeScript decorator for a boxed step, similar to a regular step decorator above:
*
* ```js
* function boxedStep(target: Function, context: ClassMethodDecoratorContext) {
* return function replacementMethod(...args: any) {
* const name = this.constructor.name + '.' + (context.name as string);
* return test.step(name, async () => {
* return await target.call(this, ...args);
* }, { box: true }); // Note the "box" option here.
* };
* }
*
* class LoginPage {
* constructor(readonly page: Page) {}
*
* @boxedStep
* async login() {
* // ....
* }
* }
*
* test('example', async ({ page }) => {
* const loginPage = new LoginPage(page);
* await loginPage.login(); // <-- Error will be reported on this line.
* });
* ```
*
* @param title Step name.
* @param body Step body.
* @param options
*/
<T>(
title: string,
body: (step: TestStepInfo) => T | Promise<T>,
options?: {
box?: boolean
location?: Location
timeout?: number
params?: { [key: string]: any }
subtitle?: string
},
): Promise<T>
/**
* Mark a test step as "skip" to temporarily disable its execution, useful for steps that are currently failing and
* planned for a near-term fix. Playwright will not run the step. See also
* [testStepInfo.skip(condition[, description])](https://playwright.dev/docs/api/class-teststepinfo#test-step-info-skip-2).
*
* We recommend [testStepInfo.skip()](https://playwright.dev/docs/api/class-teststepinfo#test-step-info-skip-1)
* instead.
*
* **Usage**
*
* You can declare a skipped step, and Playwright will not run it.
*
* ```js
* import { test, expect } from '@playwright/test';
*
* test('my test', async ({ page }) => {
* // ...
* await test.step.skip('not yet ready', async () => {
* // ...
* });
* });
* ```
*
* @param title Step name.
* @param body Step body.
* @param options
*/
skip(
title: string,
body: (step: TestStepInfo) => any | Promise<any>,
options?: {
box?: boolean
location?: Location
timeout?: number
params?: { [key: string]: any }
subtitle?: string
},
): Promise<void>
}
/**
* `expect` function can be used to create test assertions. Read more about [test assertions](https://playwright.dev/docs/test-assertions).
*
* **Usage**
*
* ```js
* test('example', async ({ page }) => {
* await test.expect(page).toHaveTitle('Title');
* });
* ```
*
*/
expect: Expect<{}>
/**
* Extends the `test` object by defining fixtures and/or options that can be used in the tests.
*
* **Usage**
*
* First define a fixture and/or an option.
*
* ```js
* import { test as base } from '@playwright/test';
* import { TodoPage } from './todo-page';
*
* export type Options = { defaultItem: string };
*
* // Extend basic test by providing a "defaultItem" option and a "todoPage" fixture.
* export const test = base.extend<Options & { todoPage: TodoPage }>({
* // Define an option and provide a default value.
* // We can later override it in the config.
* defaultItem: ['Do stuff', { option: true }],
*
* // Define a fixture. Note that it can use built-in fixture "page"
* // and a new option "defaultItem".
* todoPage: async ({ page, defaultItem }, use) => {
* const todoPage = new TodoPage(page);
* await todoPage.goto();
* await todoPage.addToDo(defaultItem);
* await use(todoPage);
* await todoPage.removeAll();
* },
* });
* ```
*
* Then use the fixture in the test.
*
* ```js
* // example.spec.ts
* import { test } from './my-test';
*
* test('test 1', async ({ todoPage }) => {
* await todoPage.addToDo('my todo');
* // ...
* });
* ```
*
* Configure the option in config file.
*
* ```js
* // playwright.config.ts
* import { defineConfig } from '@playwright/test';
* import type { Options } from './my-test';
*
* export default defineConfig<Options>({
* projects: [
* {
* name: 'shopping',
* use: { defaultItem: 'Buy milk' },
* },
* {
* name: 'wellbeing',
* use: { defaultItem: 'Exercise!' },
* },
* ]
* });
* ```
*
* Learn more about [fixtures](https://playwright.dev/docs/test-fixtures) and [parametrizing tests](https://playwright.dev/docs/test-parameterize).
* @param fixtures An object containing fixtures and/or options. Learn more about [fixtures format](https://playwright.dev/docs/test-fixtures).
*/
extend<T extends {}, W extends {} = {}>(
fixtures: Fixtures<T, W, TestArgs, WorkerArgs>,
): TestType<TestArgs & T, WorkerArgs & W>
/**
* Returns information about the currently running test. This method can only be called during the test execution,
* otherwise it throws.
*
* **Usage**
*
* ```js
* test('example test', async ({ page }) => {
* // ...
* await test.info().attach('screenshot', {
* body: await page.screenshot(),
* contentType: 'image/png',
* });
* });
* ```
*
*/
info(): TestInfo
}
TextMatch
Serialised text matcher (a RegExp cannot cross the wire).
interface TextMatch {
s?: string
exact?: boolean
ignoreCase?: boolean
re?: { source: string; flags: string }
}
Touchscreen
The Touchscreen class operates in main-frame CSS pixels relative to the top-left corner of the viewport. Methods on
the touchscreen can only be used in browser contexts that have been initialized with hasTouch set to true.
This class is limited to emulating tap gestures. For examples of other gestures simulated by manually dispatching touch events, see the emulating legacy touch events page.
interface Touchscreen {
/**
* Dispatches a `touchstart` and `touchend` event with a single touch at the position
* ([`x`](https://playwright.dev/docs/api/class-touchscreen#touchscreen-tap-option-x),[`y`](https://playwright.dev/docs/api/class-touchscreen#touchscreen-tap-option-y)).
*
* **NOTE** [touchscreen.tap(x, y)](https://playwright.dev/docs/api/class-touchscreen#touchscreen-tap) will throw if
* the [`hasTouch`](https://playwright.dev/docs/api/class-browser#browser-new-context-option-has-touch) 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.
*/
tap(x: number, y: number): Promise<void>
}
Types
Expect
type Expect<ExtendedMatchers = {}> = {
<T = unknown>(
actual: T,
messageOrOptions?: string | { message?: string },
): MakeMatchers<void, T, ExtendedMatchers>
soft: Expect<ExtendedMatchers>
poll: <T = unknown>(
actual: () => T | Promise<T>,
messageOrOptions?: string | { message?: string; timeout?: number; intervals?: number[] },
) => PollMatchers<Promise<void>, T, ExtendedMatchers>
extend<
MoreMatchers extends Record<
string,
(
this: ExpectMatcherState,
receiver: any,
...args: any[]
) => MatcherReturnType | Promise<MatcherReturnType>
>,
>(
matchers: MoreMatchers,
): Expect<ExtendedMatchers & MoreMatchers>
configure: (configuration: {
message?: string
timeout?: number
soft?: boolean
}) => Expect<ExtendedMatchers>
getState(): unknown
not: Omit<AsymmetricMatchers, 'any' | 'anything'>
} & AsymmetricMatchers
Fixtures
type Fixtures<T extends {} = {}, W extends {} = {}, PT extends {} = {}, PW extends {} = {}> = {
[K in keyof PW]?:
| WorkerFixtureValue<PW[K], W & PW>
| [
WorkerFixtureValue<PW[K], W & PW>,
{ scope: 'worker'; timeout?: number | undefined; title?: string; box?: boolean | 'self' },
]
} & {
[K in keyof PT]?:
| TestFixtureValue<PT[K], T & W & PT & PW>
| [
TestFixtureValue<PT[K], T & W & PT & PW>,
{ scope: 'test'; timeout?: number | undefined; title?: string; box?: boolean | 'self' },
]
} & {
[K in Exclude<keyof W, keyof PW | keyof PT>]?: [
WorkerFixtureValue<W[K], W & PW>,
{
scope: 'worker'
auto?: boolean
option?: boolean
timeout?: number | undefined
title?: string
box?: boolean | 'self'
},
]
} & {
[K in Exclude<keyof T, keyof PW | keyof PT>]?:
| TestFixtureValue<T[K], T & W & PT & PW>
| [
TestFixtureValue<T[K], T & W & PT & PW>,
{
scope?: 'test'
auto?: boolean
option?: boolean
timeout?: number | undefined
title?: string
box?: boolean | 'self'
},
]
}
LocatorStep
One step of a locator chain.
type LocatorStep =
| { k: 'css'; sel: string }
/** A Playwright selector string, parsed in the page (`>>`, `text=`, `xpath=`, `nth=`, `:has-text()`...). */
| { k: 'raw'; sel: string }
| { k: 'text'; m: TextMatch }
| { k: 'xpath'; expr: string }
| {
k: 'role'
role: string
name?: TextMatch
level?: number
checked?: boolean
pressed?: boolean
expanded?: boolean
selected?: boolean
disabled?: boolean
includeHidden?: boolean
}
| { k: 'label'; m: TextMatch }
| { k: 'placeholder'; m: TextMatch }
| { k: 'testid'; attr: string; m: TextMatch }
| { k: 'title'; m: TextMatch }
| { k: 'alt'; m: TextMatch }
| { k: 'nth'; i: number }
| { k: 'visible' }
| {
k: 'filter'
hasText?: TextMatch
hasNotText?: TextMatch
has?: LocatorStep[]
hasNot?: LocatorStep[]
}
PlaywrightTestConfig
type PlaywrightTestConfig<TestArgs = {}, WorkerArgs = {}> = Config<
PlaywrightTestOptions & CustomProperties<TestArgs>,
PlaywrightWorkerOptions & CustomProperties<WorkerArgs>
>
PlaywrightTestProject
type PlaywrightTestProject<TestArgs = {}, WorkerArgs = {}> = Project<
PlaywrightTestOptions & CustomProperties<TestArgs>,
PlaywrightWorkerOptions & CustomProperties<WorkerArgs>
>
TestFixture
type TestFixture<R, Args extends {}> = (
args: Args,
use: (r: R) => Promise<void>,
testInfo: TestInfo,
) => any
WorkerFixture
type WorkerFixture<R, Args extends {}> = (
args: Args,
use: (r: R) => Promise<void>,
workerInfo: WorkerInfo,
) => any
Classes
E2ELocatorImpl
A Playwright-shaped Locator: a lazy chain of steps resolved inside the page on every action.
E2EPageImpl
A Playwright-shaped Page over an E2ETransport; createEvaluatePage wraps it in a Proxy.
Functions
createEvaluatePage(transport, options?)
Build a Playwright-shaped Page over a transport. Bonds call this from
connect(); the returned object carries the documented subset and throws an
E2EUnsupportedError naming the alternative for the rest.
function createEvaluatePage(transport: E2ETransport, options?: E2EPageOptions): Promise<Page>
defineConfig(config)
Defines Playwright config
function defineConfig(config: PlaywrightTestConfig<{}, {}>): PlaywrightTestConfig<{}, {}>
installE2ERuntime()
Install the runtime. Runs INSIDE the page — see the module doc; the body must stay self-contained.
The runtime never waits: every call is ONE attempt, and a call that would
have to wait (an element not there yet, not visible yet, covered) answers
{ retry: true, error } so the DRIVER polls with its own clock. A page in a
background tab has its timers throttled to once a second (a minute, after a
while) — a setTimeout in here would stretch every auto-wait by that much,
while the WebSocket messages that carry the calls are delivered on time.
function installE2ERuntime(): { version: number }
isE2ELocator(value)
Whether a value is a locator built by createEvaluatePage.
function isE2ELocator(value: unknown): boolean
isE2EPage(value)
Whether a value is a page built by createEvaluatePage.
function isE2EPage(value: unknown): boolean
textMatch(value, opts?)
function textMatch(
value: string | RegExp,
opts?: { exact?: boolean; ignoreCase?: boolean },
): TextMatch
textMatchFull(value, opts?)
Full-text match (expect's toHaveText): a string must equal the whole text; a RegExp tests it.
function textMatchFull(value: string | RegExp, opts?: { ignoreCase?: boolean }): TextMatch
withConsoleGuard(base)
Extend a Playwright test with the auto-attached console-error guard.
To intentionally let a known error through (rare — almost always a smell
that should be fixed in the app), use
test.info().annotations.push({ type: 'allow-console-error', description: 'why' })
inside the test body BEFORE the error fires. The description is matched
against the error text as a regular expression; if it is not a valid regex
it is matched as a plain substring instead. An annotation with no
description allows every error — always provide one.
function withConsoleGuard(
base: BaseTest,
): TestType<
PlaywrightTestArgs & PlaywrightTestOptions & ConsoleGuardFixtures,
PlaywrightWorkerArgs & PlaywrightWorkerOptions
>
Constants
ALWAYS_IGNORE
Substrings that are always ignored — browser noise that doesn't reflect app bugs.
const ALWAYS_IGNORE: readonly RegExp[]
chromium
This object can be used to launch or connect to Chromium, returning instances of Browser.
const chromium: BrowserType<{}>
devices
const devices: Devices
E2E_LOCATOR
Brand on locators created here (the expect wrapper routes on it).
const E2E_LOCATOR: typeof E2E_LOCATOR
E2E_PAGE
Brand on pages created here.
const E2E_PAGE: typeof E2E_PAGE
E2E_RUNTIME_VERSION
Bumped when the in-page runtime's protocol changes; a page holding an older one is re-installed.
const E2E_RUNTIME_VERSION: 2
e2eProviderName
The provider name this process resolved at import time (see resolveE2EProviderName).
const e2eProviderName: E2EProviderName
expect
Playwright's expect, plus polling matchers for pages and locators built
over the preview. expect(value), expect.soft, expect.poll,
expect.configure and the asymmetric matchers behave exactly as in
Playwright.
const expect: Expect<{}>
firefox
This object can be used to launch or connect to Firefox, returning instances of Browser.
const firefox: BrowserType<{}>
request
Exposes API that can be used for the Web API testing.
const request: APIRequest
test
Drop-in for import { test } from '@playwright/test'.
With the playwright provider this IS Playwright's test — real browsers,
traces, videos, every fixture untouched. With any other provider (the live
preview inside a molecule sandbox) the page fixture comes from the bonded
provider's connect(), honouring the project's baseURL, viewport,
actionTimeout and navigationTimeout options, and no browser is launched.
Either way the console-error guard is attached to every test.
const test: TestType<
PlaywrightTestArgs & PlaywrightTestOptions & ConsoleGuardFixtures,
PlaywrightWorkerArgs & PlaywrightWorkerOptions
>
webkit
This object can be used to launch or connect to WebKit, returning instances of Browser.
const webkit: BrowserType<{}>
Injection Notes
Requirements
Peer dependencies:
@molecule/app-bond^1.0.1@molecule/app-e2e^1.0.0@playwright/test^1.50.0
Runtime Dependencies
-
@molecule/app-bond -
@molecule/app-e2e -
@playwright/test -
What works over the preview (the
@molecule/app-e2e-previewbond):page.goto/reload/goBack/goForward/url/title/content,page.evaluate/$eval/$$eval,page.locatorand everygetBy*(role with name/level/checked/pressed/expanded/selected, text, label, placeholder, title, alt text, test id),first/last/nth/filter/count/all,click/dblclick/hover/tap/fill/clear/type/press/check/uncheck/setChecked/ selectOption/focus/blur/dispatchEvent/scrollIntoViewIfNeeded,textContent/innerText/innerHTML/inputValue/getAttribute/isVisible/isHidden/ isEnabled/isDisabled/isEditable/isChecked/boundingBox/evaluate/evaluateAll/ waitFor,page.setViewportSize/viewportSize,page.mouse.*,page.keyboard.*,page.request.get/post/put/patch/delete/fetch(runsfetchinside the page, cookies included),waitForSelector/waitForURL/ waitForFunction/waitForLoadState/waitForTimeout,page.on('console' | 'pageerror' | 'dialog' | 'close'), andexpect(locator)withtoBeVisible/toBeHidden/toBeAttached/toHaveCount/toHaveText/toContainText/ toHaveAttribute/toHaveClass/toContainClass/toHaveCSS/toHaveValue/toHaveId/ toBeChecked/toBeEnabled/toBeDisabled/toBeEditable/toBeEmpty/toBeFocused/ toBeInViewport/toHaveAccessibleName/toHaveRole(+.not,expect.soft,expect.configure),expect(page).toHaveTitle/toHaveURL. -
The escape hatch is
page.evaluate(). Anything the list above does not cover — a computed style, a scroll position,matchMedia, afetch— is oneevaluateaway; the function runs inside the real page and returns JSON. -
Not available over the preview, and the method THROWS naming the alternative: screenshots and
toHaveScreenshot(assert layout withboundingBox()and computed styles instead),page.route/waitForResponse/ waitForRequest(read the response withpage.requestorfetchinevaluate), element handles ($,$$,elementHandle— use locators),setInputFiles,dragTo, iframes inside the preview,emulateMedia,addInitScript/exposeFunction,context.cookies/storageState(readdocument.cookie/localStorageinevaluate). The playwright bond supports all of them. -
Viewport.
page.setViewportSizeasks the IDE to resize the preview frame and throws if the host did not (a preview opened in a plain tab keeps the tab's width). Test phone layouts at 390×844 this way. The size is RE-ASSERTED after everygoto/reload/goBack/goForward, because the viewport belongs to the host's frame and not to the document: without that, a navigation could land at the host's own width while the page kept reporting the phone size, and every measurement after it was a desktop number wearing a phone label. The re-assert WARNS instead of throwing (a navigation must not fail over a frame size), so readpage.viewportSize()when a measurement has to be provably at the width you asked for. -
Events.
page.on('response')/'request'never fire over the preview (a one-time warning says so);'console'and'pageerror'do, so the console-error guard works there too. -
Over the preview, the person's browser is the renderer. If no tab shows the preview,
connect()fails within seconds — once per run, not once per test — with a message naming the cause and the alternative (MOL_E2E_PROVIDER=playwright, a real browser that needs no tab; every sandbox ships one). Keep the IDE tab open (the IDE holds a screen wake lock while a build runs) or open the preview URL in any other tab — any connected viewer will do. -
createEvaluatePage()is how a bond that can only run code inside a page (anE2ETransport) gets the whole Playwright-shaped page; the preview bond uses it, and so can any future one. -
@playwright/testis a peer dependency: it supplies the runner (npx playwright test),expectfor plain values, and thePagetypes. It never downloads browsers on install; only the playwright bond needsnpx playwright install.