diff --git a/dotnet/versioned_docs/version-stable/api/class-apiresponse.mdx b/dotnet/versioned_docs/version-stable/api/class-apiresponse.mdx index 9a4ed66b68..fcfd8db6e5 100644 --- a/dotnet/versioned_docs/version-stable/api/class-apiresponse.mdx +++ b/dotnet/versioned_docs/version-stable/api/class-apiresponse.mdx @@ -229,6 +229,50 @@ await ApiResponse.TextAsync(); --- +### Timing {/* #api-response-timing */} + +Added in: v1.62apiResponse.Timing + +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](../mock.mdx#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). + +**Usage** + +```csharp +ApiResponse.Timing +``` + +**Returns** +- Timing# + - `startTime` [float] + + Request start time in milliseconds elapsed since January 1, 1970 00:00:00 UTC + - `domainLookupStart` [float] + + 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. + - `domainLookupEnd` [float] + + 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. + - `connectStart` [float] + + 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. + - `secureConnectionStart` [float] + + 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. + - `connectEnd` [float] + + 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. + - `requestStart` [float] + + 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. + - `responseStart` [float] + + 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. + - `responseEnd` [float] + + 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. + +--- + ### Url {/* #api-response-url */} Added in: v1.16apiResponse.Url diff --git a/dotnet/versioned_docs/version-stable/api/class-browsercontext.mdx b/dotnet/versioned_docs/version-stable/api/class-browsercontext.mdx index 2499945640..71d36105ea 100644 --- a/dotnet/versioned_docs/version-stable/api/class-browsercontext.mdx +++ b/dotnet/versioned_docs/version-stable/api/class-browsercontext.mdx @@ -903,7 +903,7 @@ await BrowserContext.SetOfflineAsync(offline); Added in: v1.59browserContext.SetStorageStateAsync -Clears the existing cookies, local storage and IndexedDB entries for all origins and sets the new storage state. +Clears the existing cookies, local storage, IndexedDB 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.InstallAsync()](/api/class-credentials.mdx#credentials-install)), preventing all real authenticators from working in this context. **Usage** @@ -926,7 +926,7 @@ await context.SetStorageStateAsync("state.json"); Added before v1.9browserContext.StorageStateAsync -Returns storage state for this browser context, contains current cookies, local storage snapshot and IndexedDB snapshot. +Returns storage state for this browser context, contains current cookies, local storage snapshot, IndexedDB snapshot and virtual WebAuthn credentials. **Usage** @@ -936,6 +936,9 @@ await BrowserContext.StorageStateAsync(options); **Arguments** - `options` `BrowserContextStorageStateOptions?` *(optional)* + - `Credentials` [bool]? *(optional)* Added in: v1.61# + + Set to `true` to include the context's virtual WebAuthn [BrowserContext.Credentials](/api/class-browsercontext.mdx#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](/api/class-browser.mdx#browser-new-context-option-storage-state) option or [BrowserContext.SetStorageStateAsync()](/api/class-browsercontext.mdx#browser-context-set-storage-state). Note that restoring the storage state that contains credentials will automatically install the virtual WebAuthn authenticator (see [Credentials.InstallAsync()](/api/class-credentials.mdx#credentials-install)), and prevent all real authenticators from working in this context. - `IndexedDB` [bool]? *(optional)* Added in: v1.51# 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. diff --git a/dotnet/versioned_docs/version-stable/api/class-browsertype.mdx b/dotnet/versioned_docs/version-stable/api/class-browsertype.mdx index ba4bbf9cbf..1042c70f38 100644 --- a/dotnet/versioned_docs/version-stable/api/class-browsertype.mdx +++ b/dotnet/versioned_docs/version-stable/api/class-browsertype.mdx @@ -100,6 +100,10 @@ Connecting over the Chrome DevTools Protocol is only supported for Chromium-base This connection is significantly lower fidelity than the Playwright protocol connection via [BrowserType.ConnectAsync()](/api/class-browsertype.mdx#browser-type-connect). If you are experiencing issues or attempting to use advanced functionality, you probably want to use [BrowserType.ConnectAsync()](/api/class-browsertype.mdx#browser-type-connect). ::: +:::warning +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** ```csharp diff --git a/dotnet/versioned_docs/version-stable/api/class-credentials.mdx b/dotnet/versioned_docs/version-stable/api/class-credentials.mdx index a80ab3288b..651ece10e1 100644 --- a/dotnet/versioned_docs/version-stable/api/class-credentials.mdx +++ b/dotnet/versioned_docs/version-stable/api/class-credentials.mdx @@ -9,7 +9,7 @@ import HTMLCard from '@site/src/components/HTMLCard'; `Credentials` is a virtual WebAuthn authenticator scoped to a [BrowserContext]. It lets tests register passkeys and answer `navigator.credentials.create()` / `navigator.credentials.get()` ceremonies in the page, without a real authenticator or hardware security key. -There are two common ways to use it: +There are three common ways to use it: **Usage: seed a known credential** @@ -31,7 +31,7 @@ await page.GotoAsync("https://example.com/login"); // The page's navigator.credentials.get() is answered with the seeded passkey. ``` -**Usage: capture a passkey, then reuse it** +**Usage: capture a credential, then reuse it** ```csharp // setup test: let the app register a passkey, then save it. @@ -66,6 +66,10 @@ await page.GotoAsync("https://example.com/login"); // navigator.credentials.get() resolves the captured passkey — already signed in. ``` +**Usage: save credentials in the storage state, restore later** + +See [authentication guide](../auth.mdx) for examples of using saving and resotring the storage state. + **Defaults** diff --git a/dotnet/versioned_docs/version-stable/api/class-elementhandle.mdx b/dotnet/versioned_docs/version-stable/api/class-elementhandle.mdx index fffa2f817f..debe9183bb 100644 --- a/dotnet/versioned_docs/version-stable/api/class-elementhandle.mdx +++ b/dotnet/versioned_docs/version-stable/api/class-elementhandle.mdx @@ -204,6 +204,9 @@ await ElementHandle.CheckAsync(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. + - `Scroll` `enum ScrollMode { Auto, None }?` *(optional)* Added in: v1.62# + + 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. - `Timeout` [float]? *(optional)*# Maximum time in milliseconds. Defaults to `30000` (30 seconds). Pass `0` to disable timeout. The default value can be changed by using the [BrowserContext.SetDefaultTimeout()](/api/class-browsercontext.mdx#browser-context-set-default-timeout) or [Page.SetDefaultTimeout()](/api/class-page.mdx#page-set-default-timeout) methods. @@ -276,6 +279,9 @@ await ElementHandle.ClickAsync(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. + - `Scroll` `enum ScrollMode { Auto, None }?` *(optional)* Added in: v1.62# + + 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. - `Steps` [int]? *(optional)* Added in: v1.57# 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. @@ -352,6 +358,9 @@ await ElementHandle.DblClickAsync(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. + - `Scroll` `enum ScrollMode { Auto, None }?` *(optional)* Added in: v1.62# + + 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. - `Steps` [int]? *(optional)* Added in: v1.57# 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. @@ -662,6 +671,9 @@ await ElementHandle.HoverAsync(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. + - `Scroll` `enum ScrollMode { Auto, None }?` *(optional)* Added in: v1.62# + + 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. - `Timeout` [float]? *(optional)*# Maximum time in milliseconds. Defaults to `30000` (30 seconds). Pass `0` to disable timeout. The default value can be changed by using the [BrowserContext.SetDefaultTimeout()](/api/class-browsercontext.mdx#browser-context-set-default-timeout) or [Page.SetDefaultTimeout()](/api/class-page.mdx#page-set-default-timeout) methods. @@ -747,7 +759,10 @@ await ElementHandle.InputValueAsync(options); - `options` `ElementHandleInputValueOptions?` *(optional)* - `Timeout` [float]? *(optional)*# - Maximum time in milliseconds. Defaults to `30000` (30 seconds). Pass `0` to disable timeout. The default value can be changed by using the [BrowserContext.SetDefaultTimeout()](/api/class-browsercontext.mdx#browser-context-set-default-timeout) or [Page.SetDefaultTimeout()](/api/class-page.mdx#page-set-default-timeout) methods. + :::warning[Deprecated] + This option is ignored. The value is returned immediately. + ::: + **Returns** - [string]# @@ -1061,7 +1076,7 @@ await ElementHandle.ScreenshotAsync(options); The file path to save the image to. The screenshot type will be inferred from file extension. If [Path](/api/class-elementhandle.mdx#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. - `Quality` [int]? *(optional)*# - The quality of the image, between 0-100. Not applicable to `png` images. + 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. - `Scale` `enum ScreenshotScale { Css, Device }?` *(optional)*# 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. @@ -1073,7 +1088,7 @@ await ElementHandle.ScreenshotAsync(options); - `Timeout` [float]? *(optional)*# Maximum time in milliseconds. Defaults to `30000` (30 seconds). Pass `0` to disable timeout. The default value can be changed by using the [BrowserContext.SetDefaultTimeout()](/api/class-browsercontext.mdx#browser-context-set-default-timeout) or [Page.SetDefaultTimeout()](/api/class-page.mdx#page-set-default-timeout) methods. - - `Type` `enum ScreenshotType { Png, Jpeg }?` *(optional)*# + - `Type` `enum ScreenshotType { Png, Jpeg, Webp }?` *(optional)*# Specify screenshot type, defaults to `png`. @@ -1271,6 +1286,9 @@ await ElementHandle.SetCheckedAsync(checked, 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. + - `Scroll` `enum ScrollMode { Auto, None }?` *(optional)* Added in: v1.62# + + 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. - `Timeout` [float]? *(optional)*# Maximum time in milliseconds. Defaults to `30000` (30 seconds). Pass `0` to disable timeout. The default value can be changed by using the [BrowserContext.SetDefaultTimeout()](/api/class-browsercontext.mdx#browser-context-set-default-timeout) or [Page.SetDefaultTimeout()](/api/class-page.mdx#page-set-default-timeout) methods. @@ -1388,6 +1406,9 @@ await ElementHandle.TapAsync(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. + - `Scroll` `enum ScrollMode { Auto, None }?` *(optional)* Added in: v1.62# + + 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. - `Timeout` [float]? *(optional)*# Maximum time in milliseconds. Defaults to `30000` (30 seconds). Pass `0` to disable timeout. The default value can be changed by using the [BrowserContext.SetDefaultTimeout()](/api/class-browsercontext.mdx#browser-context-set-default-timeout) or [Page.SetDefaultTimeout()](/api/class-page.mdx#page-set-default-timeout) methods. @@ -1515,6 +1536,9 @@ await ElementHandle.UncheckAsync(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. + - `Scroll` `enum ScrollMode { Auto, None }?` *(optional)* Added in: v1.62# + + 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. - `Timeout` [float]? *(optional)*# Maximum time in milliseconds. Defaults to `30000` (30 seconds). Pass `0` to disable timeout. The default value can be changed by using the [BrowserContext.SetDefaultTimeout()](/api/class-browsercontext.mdx#browser-context-set-default-timeout) or [Page.SetDefaultTimeout()](/api/class-page.mdx#page-set-default-timeout) methods. diff --git a/dotnet/versioned_docs/version-stable/api/class-frame.mdx b/dotnet/versioned_docs/version-stable/api/class-frame.mdx index 15c70e31f1..98d4983459 100644 --- a/dotnet/versioned_docs/version-stable/api/class-frame.mdx +++ b/dotnet/versioned_docs/version-stable/api/class-frame.mdx @@ -173,6 +173,9 @@ await Frame.DragAndDropAsync(source, target, options); This option has no effect. + - `Scroll` `enum ScrollMode { Auto, None }?` *(optional)* Added in: v1.62# + + 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. - `SourcePosition` SourcePosition? *(optional)* Added in: v1.14# - `X` [float] @@ -1125,6 +1128,9 @@ await Frame.CheckAsync(selector, 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. + - `Scroll` `enum ScrollMode { Auto, None }?` *(optional)* Added in: v1.62# + + 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. - `Strict` [bool]? *(optional)* Added in: v1.14# 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. @@ -1202,6 +1208,9 @@ await Frame.ClickAsync(selector, 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. + - `Scroll` `enum ScrollMode { Auto, None }?` *(optional)* Added in: v1.62# + + 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. - `Strict` [bool]? *(optional)* Added in: v1.14# 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. @@ -1280,6 +1289,9 @@ await Frame.DblClickAsync(selector, 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. + - `Scroll` `enum ScrollMode { Auto, None }?` *(optional)* Added in: v1.62# + + 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. - `Strict` [bool]? *(optional)* Added in: v1.14# 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. @@ -1624,6 +1636,9 @@ await Frame.HoverAsync(selector, 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. + - `Scroll` `enum ScrollMode { Auto, None }?` *(optional)* Added in: v1.62# + + 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. - `Strict` [bool]? *(optional)* Added in: v1.14# 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. @@ -2303,6 +2318,9 @@ await Frame.SetCheckedAsync(selector, checked, 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. + - `Scroll` `enum ScrollMode { Auto, None }?` *(optional)* Added in: v1.62# + + 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. - `Strict` [bool]? *(optional)*# 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. @@ -2431,6 +2449,9 @@ await Frame.TapAsync(selector, 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. + - `Scroll` `enum ScrollMode { Auto, None }?` *(optional)* Added in: v1.62# + + 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. - `Strict` [bool]? *(optional)* Added in: v1.14# 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. @@ -2581,6 +2602,9 @@ await Frame.UncheckAsync(selector, 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. + - `Scroll` `enum ScrollMode { Auto, None }?` *(optional)* Added in: v1.62# + + 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. - `Strict` [bool]? *(optional)* Added in: v1.14# 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. diff --git a/dotnet/versioned_docs/version-stable/api/class-locator.mdx b/dotnet/versioned_docs/version-stable/api/class-locator.mdx index ea563477ff..09347b2184 100644 --- a/dotnet/versioned_docs/version-stable/api/class-locator.mdx +++ b/dotnet/versioned_docs/version-stable/api/class-locator.mdx @@ -272,6 +272,9 @@ await page.GetByRole(AriaRole.Checkbox).CheckAsync(); A point to use relative to the top-left corner of element padding box. If not specified, uses some visible point of the element. + - `Scroll` `enum ScrollMode { Auto, None }?` *(optional)* Added in: v1.62# + + 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. - `Timeout` [float]? *(optional)*# Maximum time in milliseconds. Defaults to `30000` (30 seconds). Pass `0` to disable timeout. The default value can be changed by using the [BrowserContext.SetDefaultTimeout()](/api/class-browsercontext.mdx#browser-context-set-default-timeout) or [Page.SetDefaultTimeout()](/api/class-page.mdx#page-set-default-timeout) methods. @@ -394,6 +397,9 @@ await page.Locator("canvas").ClickAsync(new() { A point to use relative to the top-left corner of element padding box. If not specified, uses some visible point of the element. + - `Scroll` `enum ScrollMode { Auto, None }?` *(optional)* Added in: v1.62# + + 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. - `Steps` [int]? *(optional)* Added in: v1.57# 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. @@ -509,6 +515,9 @@ await Locator.DblClickAsync(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. + - `Scroll` `enum ScrollMode { Auto, None }?` *(optional)* Added in: v1.62# + + 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. - `Steps` [int]? *(optional)* Added in: v1.57# 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. @@ -678,6 +687,9 @@ await source.DragToAsync(target, new() This option has no effect. + - `Scroll` `enum ScrollMode { Auto, None }?` *(optional)* Added in: v1.62# + + 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. - `SourcePosition` SourcePosition? *(optional)*# - `X` [float] @@ -1478,6 +1490,9 @@ await page.GetByRole(AriaRole.Link).HoverAsync(); A point to use relative to the top-left corner of element padding box. If not specified, uses some visible point of the element. + - `Scroll` `enum ScrollMode { Auto, None }?` *(optional)* Added in: v1.62# + + 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. - `Timeout` [float]? *(optional)*# Maximum time in milliseconds. Defaults to `30000` (30 seconds). Pass `0` to disable timeout. The default value can be changed by using the [BrowserContext.SetDefaultTimeout()](/api/class-browsercontext.mdx#browser-context-set-default-timeout) or [Page.SetDefaultTimeout()](/api/class-page.mdx#page-set-default-timeout) methods. @@ -2061,7 +2076,7 @@ await page.GetByRole(AriaRole.Link).ScreenshotAsync(new() { The file path to save the image to. The screenshot type will be inferred from file extension. If [Path](/api/class-locator.mdx#locator-screenshot-option-path) is a relative path, then it is resolved relative to the current working directory. If no path is provided, the image won't be saved to the disk. - `Quality` [int]? *(optional)*# - The quality of the image, between 0-100. Not applicable to `png` images. + 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. - `Scale` `enum ScreenshotScale { Css, Device }?` *(optional)*# 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. @@ -2073,7 +2088,7 @@ await page.GetByRole(AriaRole.Link).ScreenshotAsync(new() { - `Timeout` [float]? *(optional)*# Maximum time in milliseconds. Defaults to `30000` (30 seconds). Pass `0` to disable timeout. The default value can be changed by using the [BrowserContext.SetDefaultTimeout()](/api/class-browsercontext.mdx#browser-context-set-default-timeout) or [Page.SetDefaultTimeout()](/api/class-page.mdx#page-set-default-timeout) methods. - - `Type` `enum ScreenshotType { Png, Jpeg }?` *(optional)*# + - `Type` `enum ScreenshotType { Png, Jpeg, Webp }?` *(optional)*# Specify screenshot type, defaults to `png`. @@ -2248,6 +2263,9 @@ await page.GetByRole(AriaRole.Checkbox).SetCheckedAsync(true); A point to use relative to the top-left corner of element padding box. If not specified, uses some visible point of the element. + - `Scroll` `enum ScrollMode { Auto, None }?` *(optional)* Added in: v1.62# + + 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. - `Timeout` [float]? *(optional)*# Maximum time in milliseconds. Defaults to `30000` (30 seconds). Pass `0` to disable timeout. The default value can be changed by using the [BrowserContext.SetDefaultTimeout()](/api/class-browsercontext.mdx#browser-context-set-default-timeout) or [Page.SetDefaultTimeout()](/api/class-page.mdx#page-set-default-timeout) methods. @@ -2373,6 +2391,9 @@ await Locator.TapAsync(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. + - `Scroll` `enum ScrollMode { Auto, None }?` *(optional)* Added in: v1.62# + + 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. - `Timeout` [float]? *(optional)*# Maximum time in milliseconds. Defaults to `30000` (30 seconds). Pass `0` to disable timeout. The default value can be changed by using the [BrowserContext.SetDefaultTimeout()](/api/class-browsercontext.mdx#browser-context-set-default-timeout) or [Page.SetDefaultTimeout()](/api/class-page.mdx#page-set-default-timeout) methods. @@ -2462,6 +2483,9 @@ await page.GetByRole(AriaRole.Checkbox).UncheckAsync(); A point to use relative to the top-left corner of element padding box. If not specified, uses some visible point of the element. + - `Scroll` `enum ScrollMode { Auto, None }?` *(optional)* Added in: v1.62# + + 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. - `Timeout` [float]? *(optional)*# Maximum time in milliseconds. Defaults to `30000` (30 seconds). Pass `0` to disable timeout. The default value can be changed by using the [BrowserContext.SetDefaultTimeout()](/api/class-browsercontext.mdx#browser-context-set-default-timeout) or [Page.SetDefaultTimeout()](/api/class-page.mdx#page-set-default-timeout) methods. @@ -2520,6 +2544,41 @@ orderSent.WaitForAsync(); --- +### WaitForFunctionAsync {/* #locator-wait-for-function */} + +Added in: v1.62locator.WaitForFunctionAsync + +Returns when [expression](/api/class-locator.mdx#locator-wait-for-function-option-expression) returns a truthy value, called with the matching element as a first argument, and [arg](/api/class-locator.mdx#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 [expression](/api/class-locator.mdx#locator-wait-for-function-option-expression) returns a [Promise], this method will wait for the promise to resolve before checking its value. + +If [expression](/api/class-locator.mdx#locator-wait-for-function-option-expression) throws or rejects, this method throws. + +**Usage** + +Wait for an attribute to appear: + +Passing argument to [expression](/api/class-locator.mdx#locator-wait-for-function-option-expression): + +**Arguments** +- `expression` [string]# + + JavaScript expression to be evaluated in the browser context. If the expression evaluates to a function, the function is automatically invoked. +- `arg` [EvaluationArgument]? *(optional)*# + + Optional argument to pass to [expression](/api/class-locator.mdx#locator-wait-for-function-option-expression). +- `options` `LocatorWaitForFunctionOptions?` *(optional)* + - `Timeout` [float]? *(optional)*# + + Maximum time to wait for in milliseconds. Defaults to `30000` (30 seconds). Pass `0` to disable timeout. The default value can be changed by using the [BrowserContext.SetDefaultTimeout()](/api/class-browsercontext.mdx#browser-context-set-default-timeout) or [Page.SetDefaultTimeout()](/api/class-page.mdx#page-set-default-timeout) methods. + +**Returns** +- [void]# + +--- + ## Deprecated ### ElementHandleAsync {/* #locator-element-handle */} diff --git a/dotnet/versioned_docs/version-stable/api/class-page.mdx b/dotnet/versioned_docs/version-stable/api/class-page.mdx index 1a8e3ab0c2..08e3980e78 100644 --- a/dotnet/versioned_docs/version-stable/api/class-page.mdx +++ b/dotnet/versioned_docs/version-stable/api/class-page.mdx @@ -471,6 +471,9 @@ await Page.DragAndDropAsync("#source", "#target", new() This option has no effect. + - `Scroll` `enum ScrollMode { Auto, None }?` *(optional)* Added in: v1.62# + + 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. - `SourcePosition` SourcePosition? *(optional)* Added in: v1.14# - `X` [float] @@ -1211,6 +1214,11 @@ Returns the main resource response. In case of multiple redirects, the navigatio Navigate to the previous page in history. +:::warning + +**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. +::: + **Usage** ```csharp @@ -1243,6 +1251,11 @@ Returns the main resource response. In case of multiple redirects, the navigatio Navigate to the next page in history. +:::warning + +**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. +::: + **Usage** ```csharp @@ -2460,7 +2473,7 @@ await Page.ScreenshotAsync(options); The file path to save the image to. The screenshot type will be inferred from file extension. If [Path](/api/class-page.mdx#page-screenshot-option-path) is a relative path, then it is resolved relative to the current working directory. If no path is provided, the image won't be saved to the disk. - `Quality` [int]? *(optional)*# - The quality of the image, between 0-100. Not applicable to `png` images. + 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. - `Scale` `enum ScreenshotScale { Css, Device }?` *(optional)*# 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. @@ -2472,7 +2485,7 @@ await Page.ScreenshotAsync(options); - `Timeout` [float]? *(optional)*# Maximum time in milliseconds. Defaults to `30000` (30 seconds). Pass `0` to disable timeout. The default value can be changed by using the [BrowserContext.SetDefaultTimeout()](/api/class-browsercontext.mdx#browser-context-set-default-timeout) or [Page.SetDefaultTimeout()](/api/class-page.mdx#page-set-default-timeout) methods. - - `Type` `enum ScreenshotType { Png, Jpeg }?` *(optional)*# + - `Type` `enum ScreenshotType { Png, Jpeg, Webp }?` *(optional)*# Specify screenshot type, defaults to `png`. @@ -3471,6 +3484,9 @@ await Page.CheckAsync(selector, 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. + - `Scroll` `enum ScrollMode { Auto, None }?` *(optional)* Added in: v1.62# + + 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. - `Strict` [bool]? *(optional)* Added in: v1.14# 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. @@ -3548,6 +3564,9 @@ await Page.ClickAsync(selector, 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. + - `Scroll` `enum ScrollMode { Auto, None }?` *(optional)* Added in: v1.62# + + 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. - `Strict` [bool]? *(optional)* Added in: v1.14# 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. @@ -3626,6 +3645,9 @@ await Page.DblClickAsync(selector, 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. + - `Scroll` `enum ScrollMode { Auto, None }?` *(optional)* Added in: v1.62# + + 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. - `Strict` [bool]? *(optional)* Added in: v1.14# 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. @@ -3965,6 +3987,9 @@ await Page.HoverAsync(selector, 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. + - `Scroll` `enum ScrollMode { Auto, None }?` *(optional)* Added in: v1.62# + + 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. - `Strict` [bool]? *(optional)* Added in: v1.14# 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. @@ -4675,6 +4700,9 @@ await Page.SetCheckedAsync(selector, checked, 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. + - `Scroll` `enum ScrollMode { Auto, None }?` *(optional)* Added in: v1.62# + + 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. - `Strict` [bool]? *(optional)*# 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. @@ -4803,6 +4831,9 @@ await Page.TapAsync(selector, 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. + - `Scroll` `enum ScrollMode { Auto, None }?` *(optional)* Added in: v1.62# + + 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. - `Strict` [bool]? *(optional)* Added in: v1.14# 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. @@ -4953,6 +4984,9 @@ await Page.UncheckAsync(selector, 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. + - `Scroll` `enum ScrollMode { Auto, None }?` *(optional)* Added in: v1.62# + + 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. - `Strict` [bool]? *(optional)* Added in: v1.14# 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. diff --git a/dotnet/versioned_docs/version-stable/api/class-request.mdx b/dotnet/versioned_docs/version-stable/api/class-request.mdx index 437188a9c6..1a97c0412b 100644 --- a/dotnet/versioned_docs/version-stable/api/class-request.mdx +++ b/dotnet/versioned_docs/version-stable/api/class-request.mdx @@ -394,28 +394,28 @@ Console.WriteLine(request.Timing.ResponseEnd); Request start time in milliseconds elapsed since January 1, 1970 00:00:00 UTC - `domainLookupStart` [float] - Time immediately before the browser starts the domain name lookup for the resource. The value is given in milliseconds relative to `startTime`, -1 if not available. + 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. - `domainLookupEnd` [float] - Time immediately after the browser starts the domain name lookup for the resource. The value is given in milliseconds relative to `startTime`, -1 if not available. + 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. - `connectStart` [float] - Time immediately before the user agent starts establishing the connection to the server to retrieve the resource. The value is given in milliseconds relative to `startTime`, -1 if not available. + 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. - `secureConnectionStart` [float] - Time immediately before the browser starts the handshake process to secure the current connection. The value is given in milliseconds relative to `startTime`, -1 if not available. + 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. - `connectEnd` [float] - Time immediately before the user agent starts establishing the connection to the server to retrieve the resource. The value is given in milliseconds relative to `startTime`, -1 if not available. + 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. - `requestStart` [float] - Time immediately before the browser starts requesting the resource from the server, cache, or local resource. The value is given in milliseconds relative to `startTime`, -1 if not available. + 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. - `responseStart` [float] - Time immediately after the browser 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. + 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. - `responseEnd` [float] - Time immediately after the browser 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. + 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. --- diff --git a/dotnet/versioned_docs/version-stable/auth.mdx b/dotnet/versioned_docs/version-stable/auth.mdx index e3a858646e..01826619fc 100644 --- a/dotnet/versioned_docs/version-stable/auth.mdx +++ b/dotnet/versioned_docs/version-stable/auth.mdx @@ -79,9 +79,9 @@ Redoing login for every test can slow down test execution. To mitigate that, reu Playwright provides a way to reuse the signed-in state in the tests. That way you can log in only once and then skip the log in step for all of the tests. -Web apps use cookie-based or token-based authentication, where authenticated state is stored as [cookies](https://developer.mozilla.org/en-US/docs/Web/HTTP/Cookies), in [local storage](https://developer.mozilla.org/en-US/docs/Web/API/Storage) or in [IndexedDB](https://developer.mozilla.org/en-US/docs/Web/API/IndexedDB_API). Playwright provides [BrowserContext.StorageStateAsync()](/api/class-browsercontext.mdx#browser-context-storage-state) method that can be used to retrieve storage state from authenticated contexts and then create new contexts with prepopulated state. +Web apps use cookie-based or token-based authentication, where authenticated state is stored as [cookies](https://developer.mozilla.org/en-US/docs/Web/HTTP/Cookies), in [local storage](https://developer.mozilla.org/en-US/docs/Web/API/Storage), in [IndexedDB](https://developer.mozilla.org/en-US/docs/Web/API/IndexedDB_API), or as passkeys ([WebAuthn](https://developer.mozilla.org/en-US/docs/Web/API/Web_Authentication_API) credentials). Playwright provides [BrowserContext.StorageStateAsync()](/api/class-browsercontext.mdx#browser-context-storage-state) method that can be used to retrieve storage state from authenticated contexts and then create new contexts with prepopulated state. -Cookies, local storage and IndexedDB state can be used across different browsers. They depend on your application's authentication model which may require some combination of cookies, local storage or IndexedDB. +Cookies, local storage, IndexedDB and virtual WebAuthn credentials (passkeys) can be used across different browsers. They depend on your application's authentication model which may require some combination of cookies, local storage, IndexedDB or passkeys. The following code snippet retrieves state from an authenticated context and creates a new context with that state. @@ -104,7 +104,7 @@ var context = await browser.NewContextAsync(new() ### Session storage -Reusing authenticated state covers [cookies](https://developer.mozilla.org/en-US/docs/Web/HTTP/Cookies), [local storage](https://developer.mozilla.org/en-US/docs/Web/API/Storage) and [IndexedDB](https://developer.mozilla.org/en-US/docs/Web/API/IndexedDB_API) based authentication. Rarely, [session storage](https://developer.mozilla.org/en-US/docs/Web/API/Window/sessionStorage) is used for storing information associated with the signed-in state. Session storage is specific to a particular domain and is not persisted across page loads. Playwright does not provide API to persist session storage, but the following snippet can be used to save/load session storage. +Reusing authenticated state covers [cookies](https://developer.mozilla.org/en-US/docs/Web/HTTP/Cookies), [local storage](https://developer.mozilla.org/en-US/docs/Web/API/Storage), [IndexedDB](https://developer.mozilla.org/en-US/docs/Web/API/IndexedDB_API) and passkey ([WebAuthn](https://developer.mozilla.org/en-US/docs/Web/API/Web_Authentication_API)) based authentication. Rarely, [session storage](https://developer.mozilla.org/en-US/docs/Web/API/Window/sessionStorage) is used for storing information associated with the signed-in state. Session storage is specific to a particular domain and is not persisted across page loads. Playwright does not provide API to persist session storage, but the following snippet can be used to save/load session storage. ```csharp // Get session storage and store as env variable diff --git a/dotnet/versioned_docs/version-stable/ci-intro.mdx b/dotnet/versioned_docs/version-stable/ci-intro.mdx index f81a489f8f..341a04a7cb 100644 --- a/dotnet/versioned_docs/version-stable/ci-intro.mdx +++ b/dotnet/versioned_docs/version-stable/ci-intro.mdx @@ -31,7 +31,7 @@ jobs: timeout-minutes: 60 runs-on: ubuntu-latest steps: - - uses: actions/checkout@v5 + - uses: actions/checkout@v6 - name: Setup dotnet uses: actions/setup-dotnet@v5 with: diff --git a/dotnet/versioned_docs/version-stable/ci.mdx b/dotnet/versioned_docs/version-stable/ci.mdx index 862e37f0df..9ee53130e2 100644 --- a/dotnet/versioned_docs/version-stable/ci.mdx +++ b/dotnet/versioned_docs/version-stable/ci.mdx @@ -47,7 +47,7 @@ jobs: timeout-minutes: 60 runs-on: ubuntu-latest steps: - - uses: actions/checkout@v5 + - uses: actions/checkout@v6 - name: Setup dotnet uses: actions/setup-dotnet@v5 with: @@ -76,10 +76,10 @@ jobs: name: 'Playwright Tests' runs-on: ubuntu-latest container: - image: mcr.microsoft.com/playwright/dotnet:v1.60.0-noble + image: mcr.microsoft.com/playwright/dotnet:v1.61.0-noble options: --user 1001 steps: - - uses: actions/checkout@v5 + - uses: actions/checkout@v6 - name: Setup dotnet uses: actions/setup-dotnet@v5 with: @@ -103,7 +103,7 @@ jobs: runs-on: ubuntu-latest if: github.event.deployment_status.state == 'success' steps: - - uses: actions/checkout@v5 + - uses: actions/checkout@v6 - name: Setup dotnet uses: actions/setup-dotnet@v5 with: @@ -159,7 +159,7 @@ trigger: pool: vmImage: ubuntu-latest -container: mcr.microsoft.com/playwright/dotnet:v1.60.0-noble +container: mcr.microsoft.com/playwright/dotnet:v1.61.0-noble steps: - task: UseDotNet@2 @@ -182,7 +182,7 @@ Running Playwright on CircleCI is very similar to running on GitHub Actions. In executors: pw-noble-development: docker: - - image: mcr.microsoft.com/playwright/dotnet:v1.60.0-noble + - image: mcr.microsoft.com/playwright/dotnet:v1.61.0-noble ``` Note: When using the docker agent definition, you are specifying the resource class of where playwright runs to the 'medium' tier [here](https://circleci.com/docs/configuration-reference?#docker-execution-environment). The default behavior of Playwright is to set the number of workers to the detected core count (2 in the case of the medium tier). Overriding the number of workers to greater than this number will cause unnecessary timeouts and failures. @@ -193,7 +193,7 @@ Jenkins supports Docker agents for pipelines. Use the [Playwright Docker image]( ```groovy pipeline { - agent { docker { image 'mcr.microsoft.com/playwright/dotnet:v1.60.0-noble' } } + agent { docker { image 'mcr.microsoft.com/playwright/dotnet:v1.61.0-noble' } } stages { stage('e2e-tests') { steps { @@ -210,7 +210,7 @@ pipeline { Bitbucket Pipelines can use public [Docker images as build environments](https://confluence.atlassian.com/bitbucket/use-docker-images-as-build-environments-792298897.html). To run Playwright tests on Bitbucket, use our public Docker image ([see Dockerfile](./docker.mdx)). ```yml -image: mcr.microsoft.com/playwright/dotnet:v1.60.0-noble +image: mcr.microsoft.com/playwright/dotnet:v1.61.0-noble ``` ### GitLab CI diff --git a/dotnet/versioned_docs/version-stable/docker.mdx b/dotnet/versioned_docs/version-stable/docker.mdx index 8d6f27c123..c4c21db04f 100644 --- a/dotnet/versioned_docs/version-stable/docker.mdx +++ b/dotnet/versioned_docs/version-stable/docker.mdx @@ -22,7 +22,7 @@ This Docker image is intended to be used for testing and development purposes on ### Pull the image ```bash -docker pull mcr.microsoft.com/playwright/dotnet:v1.60.0-noble +docker pull mcr.microsoft.com/playwright/dotnet:v1.61.0-noble ``` ### Run the image @@ -34,7 +34,7 @@ By default, the Docker image will use the `root` user to run the browsers. This On trusted websites, you can avoid creating a separate user and use root for it since you trust the code which will run on the browsers. ```bash -docker run -it --rm --ipc=host mcr.microsoft.com/playwright/dotnet:v1.60.0-noble /bin/bash +docker run -it --rm --ipc=host mcr.microsoft.com/playwright/dotnet:v1.61.0-noble /bin/bash ``` #### Crawling and scraping @@ -42,7 +42,7 @@ docker run -it --rm --ipc=host mcr.microsoft.com/playwright/dotnet:v1.60.0-noble On untrusted websites, it's recommended to use a separate user for launching the browsers in combination with the seccomp profile. Inside the container or if you are using the Docker image as a base image you have to use `adduser` for it. ```bash -docker run -it --rm --ipc=host --user pwuser --security-opt seccomp=seccomp_profile.json mcr.microsoft.com/playwright/dotnet:v1.60.0-noble /bin/bash +docker run -it --rm --ipc=host --user pwuser --security-opt seccomp=seccomp_profile.json mcr.microsoft.com/playwright/dotnet:v1.61.0-noble /bin/bash ``` [`seccomp_profile.json`](https://github.com/microsoft/playwright/blob/main/utils/docker/seccomp_profile.json) is needed to run Chromium with sandbox. This is a [default Docker seccomp profile](https://github.com/docker/engine/blob/d0d99b04cf6e00ed3fc27e81fc3d94e7eda70af3/profiles/seccomp/default.json) with extra user namespace cloning permissions: @@ -82,7 +82,7 @@ You can run Playwright Server in Docker while keeping your tests running on the Start the Playwright Server in Docker: ```bash -docker run -p 3000:3000 --rm --init -it --workdir /home/pwuser --user pwuser mcr.microsoft.com/playwright:v1.60.0-noble /bin/sh -c "npx -y playwright@1.60.0 run-server --port 3000 --host 0.0.0.0" +docker run -p 3000:3000 --rm --init -it --workdir /home/pwuser --user pwuser mcr.microsoft.com/playwright:v1.61.0-noble /bin/sh -c "npx -y playwright@1.61.0 run-server --port 3000 --host 0.0.0.0" ``` #### Connecting to the Server @@ -99,7 +99,7 @@ await using var browser = await playwright.Chromium.ConnectAsync("ws://127.0.0.1 If you need to access local servers from within the Docker container: ```bash -docker run --add-host=hostmachine:host-gateway -p 3000:3000 --rm --init -it --workdir /home/pwuser --user pwuser mcr.microsoft.com/playwright:v1.60.0-noble /bin/sh -c "npx -y playwright@1.60.0 run-server --port 3000 --host 0.0.0.0" +docker run --add-host=hostmachine:host-gateway -p 3000:3000 --rm --init -it --workdir /home/pwuser --user pwuser mcr.microsoft.com/playwright:v1.61.0-noble /bin/sh -c "npx -y playwright@1.61.0 run-server --port 3000 --host 0.0.0.0" ``` This makes `hostmachine` point to the host's localhost. Your tests should use `hostmachine` instead of `localhost` when accessing local servers. @@ -132,9 +132,10 @@ Once this is enabled you can open the port specified in a new browser tab and yo See [all available image tags]. We currently publish images with the following tags: -- `:v1.60.0` - Playwright v1.60.0 release docker image based on Ubuntu 24.04 LTS (Noble Numbat). -- `:v1.60.0-noble` - Playwright v1.60.0 release docker image based on Ubuntu 24.04 LTS (Noble Numbat). -- `:v1.60.0-jammy` - Playwright v1.60.0 release docker image based on Ubuntu 22.04 LTS (Jammy Jellyfish). +- `:v1.61.0` - Playwright v1.61.0 release docker image based on Ubuntu 24.04 LTS (Noble Numbat). +- `:v1.61.0-noble` - Playwright v1.61.0 release docker image based on Ubuntu 24.04 LTS (Noble Numbat). +- `:v1.61.0-jammy` - Playwright v1.61.0 release docker image based on Ubuntu 22.04 LTS (Jammy Jellyfish). +- `:v1.61.0-resolute` - Playwright v1.61.0 release docker image based on Ubuntu 26.04 LTS (Resolute Raccoon). :::note @@ -144,6 +145,7 @@ It is recommended to always pin your Docker image to a specific version if possi ### Base images We currently publish images based on the following [Ubuntu](https://hub.docker.com/_/ubuntu) versions: +- **Ubuntu 26.04 LTS** (Resolute Raccoon), image tags include `resolute` - **Ubuntu 24.04 LTS** (Noble Numbat), image tags include `noble` - **Ubuntu 22.04 LTS** (Jammy Jellyfish), image tags include `jammy` diff --git a/dotnet/versioned_docs/version-stable/getting-started-cli.mdx b/dotnet/versioned_docs/version-stable/getting-started-cli.mdx index 2ac184da29..69684ba510 100644 --- a/dotnet/versioned_docs/version-stable/getting-started-cli.mdx +++ b/dotnet/versioned_docs/version-stable/getting-started-cli.mdx @@ -17,7 +17,7 @@ Playwright comes with `playwright-cli`, a command-line interface for browser aut ## Prerequisites Before you begin, make sure you have the following installed: -- [Node.js](https://nodejs.org/) 18 or newer +- [Node.js](https://nodejs.org/) 20 or newer - A coding agent: Claude Code, GitHub Copilot, or similar ## Installation @@ -32,6 +32,7 @@ playwright-cli --help Alternatively, install `@playwright/cli` as a local dependency and use `npx`: ```bash +npm install -D @playwright/cli@latest npx playwright-cli --help ``` @@ -131,6 +132,7 @@ playwright-cli snapshot --filename=f # save snapshot to specific file playwright-cli screenshot # screenshot of the current page playwright-cli screenshot [ref] # screenshot of a specific element playwright-cli screenshot --filename=f # save with specific filename +playwright-cli screenshot --hires # capture using device pixels playwright-cli pdf # save page as PDF ``` diff --git a/dotnet/versioned_docs/version-stable/getting-started-mcp.mdx b/dotnet/versioned_docs/version-stable/getting-started-mcp.mdx index 7a3727592f..3acca2e8fb 100644 --- a/dotnet/versioned_docs/version-stable/getting-started-mcp.mdx +++ b/dotnet/versioned_docs/version-stable/getting-started-mcp.mdx @@ -13,7 +13,7 @@ The Playwright MCP server provides browser automation capabilities through the [ ## Prerequisites Before you begin, make sure you have the following installed: -- [Node.js](https://nodejs.org/) 18 or newer +- [Node.js](https://nodejs.org/) 20 or newer - An MCP client: VS Code, Cursor, Windsurf, Claude Code, Claude Desktop, or similar ## Getting Started @@ -194,6 +194,8 @@ When running a headed browser on a system without a display or from IDE worker p npx @playwright/mcp@latest --port 8931 ``` +HTTP sessions use a five-second heartbeat timeout. If your MCP client or proxy does not answer server-initiated pings, set `PLAYWRIGHT_MCP_PING_TIMEOUT_MS` to a longer timeout in milliseconds. Set it to `0` to disable the heartbeat. + Then point your MCP client to the HTTP endpoint: ```json diff --git a/dotnet/versioned_docs/version-stable/navigations.mdx b/dotnet/versioned_docs/version-stable/navigations.mdx index 0d44a3c7aa..829d099812 100644 --- a/dotnet/versioned_docs/version-stable/navigations.mdx +++ b/dotnet/versioned_docs/version-stable/navigations.mdx @@ -60,6 +60,16 @@ await page.GetByText("Click me").ClickAsync(); await page.WaitForURL("**/login"); ``` +## Back/Forward Cache (BFCache) + +Modern browsers utilize a Back/Forward Cache (BFCache) to instantly load a page when a user navigates back or forward. This is achieved by freezing the page's DOM and JavaScript heap in memory, and thawing it upon return. + +By default, Playwright disables the BFCache across all browsers to ensure consistent, clean testing environments. + +Even if you explicitly enable BFCache, **testing BFCache restorations is not supported**. Because a BFCache restore skips the network fetch phase, the browser does not fire standard navigation lifecycle events (such as `commit`, `domcontentloaded`, or `load`). Playwright's internal `Page` state heavily relies on these network-level events to stay synchronized. + +Consequently, triggering a BFCache restore (e.g., via `page.goBack()`) will bypass Playwright's lifecycle tracking, resulting in timeouts and a completely desynchronized `Page` object where subsequent interactions will fail. + ## Navigation events Playwright splits the process of showing a new document in a page into **navigation** and **loading**. diff --git a/java/versioned_docs/version-stable/api/class-apiresponse.mdx b/java/versioned_docs/version-stable/api/class-apiresponse.mdx index a6b413cc1f..fa1987bc93 100644 --- a/java/versioned_docs/version-stable/api/class-apiresponse.mdx +++ b/java/versioned_docs/version-stable/api/class-apiresponse.mdx @@ -210,6 +210,50 @@ APIResponse.text(); --- +### timing {/* #api-response-timing */} + +Added in: v1.62apiResponse.timing + +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](../mock.mdx#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). + +**Usage** + +```java +APIResponse.timing(); +``` + +**Returns** +- Timing# + - `startTime` [double] + + Request start time in milliseconds elapsed since January 1, 1970 00:00:00 UTC + - `domainLookupStart` [double] + + 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. + - `domainLookupEnd` [double] + + 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. + - `connectStart` [double] + + 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. + - `secureConnectionStart` [double] + + 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. + - `connectEnd` [double] + + 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. + - `requestStart` [double] + + 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. + - `responseStart` [double] + + 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. + - `responseEnd` [double] + + 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. + +--- + ### url {/* #api-response-url */} Added in: v1.16apiResponse.url diff --git a/java/versioned_docs/version-stable/api/class-browsercontext.mdx b/java/versioned_docs/version-stable/api/class-browsercontext.mdx index 5ee4b460b5..733835fe36 100644 --- a/java/versioned_docs/version-stable/api/class-browsercontext.mdx +++ b/java/versioned_docs/version-stable/api/class-browsercontext.mdx @@ -800,7 +800,7 @@ BrowserContext.setOffline(offline); Added in: v1.59browserContext.setStorageState -Clears the existing cookies, local storage and IndexedDB entries for all origins and sets the new storage state. +Clears the existing cookies, local storage, IndexedDB 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()](/api/class-credentials.mdx#credentials-install)), preventing all real authenticators from working in this context. **Usage** @@ -823,7 +823,7 @@ context.setStorageState(Paths.get("state.json")); Added before v1.9browserContext.storageState -Returns storage state for this browser context, contains current cookies, local storage snapshot and IndexedDB snapshot. +Returns storage state for this browser context, contains current cookies, local storage snapshot, IndexedDB snapshot and virtual WebAuthn credentials. **Usage** @@ -834,6 +834,9 @@ BrowserContext.storageState(options); **Arguments** - `options` `BrowserContext.StorageStateOptions` *(optional)* + - `setCredentials` [boolean] *(optional)* Added in: v1.61# + + Set to `true` to include the context's virtual WebAuthn [BrowserContext.credentials()](/api/class-browsercontext.mdx#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 [setStorageState](/api/class-browser.mdx#browser-new-context-option-storage-state) option or [BrowserContext.setStorageState()](/api/class-browsercontext.mdx#browser-context-set-storage-state). Note that restoring the storage state that contains credentials will automatically install the virtual WebAuthn authenticator (see [Credentials.install()](/api/class-credentials.mdx#credentials-install)), and prevent all real authenticators from working in this context. - `setIndexedDB` [boolean] *(optional)* Added in: v1.51# 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. diff --git a/java/versioned_docs/version-stable/api/class-browsertype.mdx b/java/versioned_docs/version-stable/api/class-browsertype.mdx index 806c3d9c5b..aa19f174d7 100644 --- a/java/versioned_docs/version-stable/api/class-browsertype.mdx +++ b/java/versioned_docs/version-stable/api/class-browsertype.mdx @@ -99,6 +99,10 @@ Connecting over the Chrome DevTools Protocol is only supported for Chromium-base This connection is significantly lower fidelity than the Playwright protocol connection via [BrowserType.connect()](/api/class-browsertype.mdx#browser-type-connect). If you are experiencing issues or attempting to use advanced functionality, you probably want to use [BrowserType.connect()](/api/class-browsertype.mdx#browser-type-connect). ::: +:::warning +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** ```java diff --git a/java/versioned_docs/version-stable/api/class-credentials.mdx b/java/versioned_docs/version-stable/api/class-credentials.mdx index cf6fd16892..63d0660522 100644 --- a/java/versioned_docs/version-stable/api/class-credentials.mdx +++ b/java/versioned_docs/version-stable/api/class-credentials.mdx @@ -9,7 +9,7 @@ import HTMLCard from '@site/src/components/HTMLCard'; `Credentials` is a virtual WebAuthn authenticator scoped to a [BrowserContext]. It lets tests register passkeys and answer `navigator.credentials.create()` / `navigator.credentials.get()` ceremonies in the page, without a real authenticator or hardware security key. -There are two common ways to use it: +There are three common ways to use it: **Usage: seed a known credential** @@ -29,7 +29,7 @@ page.navigate("https://example.com/login"); // The page's navigator.credentials.get() is answered with the seeded passkey. ``` -**Usage: capture a passkey, then reuse it** +**Usage: capture a credential, then reuse it** ```java // setup test: let the app register a passkey, then save it. @@ -63,6 +63,10 @@ page.navigate("https://example.com/login"); // navigator.credentials.get() resolves the captured passkey — already signed in. ``` +**Usage: save credentials in the storage state, restore later** + +See [authentication guide](../auth.mdx) for examples of using saving and resotring the storage state. + **Defaults** diff --git a/java/versioned_docs/version-stable/api/class-elementhandle.mdx b/java/versioned_docs/version-stable/api/class-elementhandle.mdx index f874bdcab0..58275fa394 100644 --- a/java/versioned_docs/version-stable/api/class-elementhandle.mdx +++ b/java/versioned_docs/version-stable/api/class-elementhandle.mdx @@ -206,6 +206,9 @@ ElementHandle.check(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. + - `setScroll` `enum ScrollMode { AUTO, NONE }` *(optional)* Added in: v1.62# + + 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. - `setTimeout` [double] *(optional)*# Maximum time in milliseconds. Defaults to `30000` (30 seconds). Pass `0` to disable timeout. The default value can be changed by using the [BrowserContext.setDefaultTimeout()](/api/class-browsercontext.mdx#browser-context-set-default-timeout) or [Page.setDefaultTimeout()](/api/class-page.mdx#page-set-default-timeout) methods. @@ -279,6 +282,9 @@ ElementHandle.click(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. + - `setScroll` `enum ScrollMode { AUTO, NONE }` *(optional)* Added in: v1.62# + + 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. - `setSteps` [int] *(optional)* Added in: v1.57# 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. @@ -356,6 +362,9 @@ ElementHandle.dblclick(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. + - `setScroll` `enum ScrollMode { AUTO, NONE }` *(optional)* Added in: v1.62# + + 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. - `setSteps` [int] *(optional)* Added in: v1.57# 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. @@ -668,6 +677,9 @@ ElementHandle.hover(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. + - `setScroll` `enum ScrollMode { AUTO, NONE }` *(optional)* Added in: v1.62# + + 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. - `setTimeout` [double] *(optional)*# Maximum time in milliseconds. Defaults to `30000` (30 seconds). Pass `0` to disable timeout. The default value can be changed by using the [BrowserContext.setDefaultTimeout()](/api/class-browsercontext.mdx#browser-context-set-default-timeout) or [Page.setDefaultTimeout()](/api/class-page.mdx#page-set-default-timeout) methods. @@ -754,7 +766,10 @@ ElementHandle.inputValue(options); - `options` `ElementHandle.InputValueOptions` *(optional)* - `setTimeout` [double] *(optional)*# - Maximum time in milliseconds. Defaults to `30000` (30 seconds). Pass `0` to disable timeout. The default value can be changed by using the [BrowserContext.setDefaultTimeout()](/api/class-browsercontext.mdx#browser-context-set-default-timeout) or [Page.setDefaultTimeout()](/api/class-page.mdx#page-set-default-timeout) methods. + :::warning[Deprecated] + This option is ignored. The value is returned immediately. + ::: + **Returns** - [String]# @@ -1070,7 +1085,7 @@ ElementHandle.screenshot(options); The file path to save the image to. The screenshot type will be inferred from file extension. If [setPath](/api/class-elementhandle.mdx#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. - `setQuality` [int] *(optional)*# - The quality of the image, between 0-100. Not applicable to `png` images. + 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. - `setScale` `enum ScreenshotScale { CSS, DEVICE }` *(optional)*# 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. @@ -1082,7 +1097,7 @@ ElementHandle.screenshot(options); - `setTimeout` [double] *(optional)*# Maximum time in milliseconds. Defaults to `30000` (30 seconds). Pass `0` to disable timeout. The default value can be changed by using the [BrowserContext.setDefaultTimeout()](/api/class-browsercontext.mdx#browser-context-set-default-timeout) or [Page.setDefaultTimeout()](/api/class-page.mdx#page-set-default-timeout) methods. - - `setType` `enum ScreenshotType { PNG, JPEG }` *(optional)*# + - `setType` `enum ScreenshotType { PNG, JPEG, WEBP }` *(optional)*# Specify screenshot type, defaults to `png`. @@ -1278,6 +1293,9 @@ ElementHandle.setChecked(checked, 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. + - `setScroll` `enum ScrollMode { AUTO, NONE }` *(optional)* Added in: v1.62# + + 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. - `setTimeout` [double] *(optional)*# Maximum time in milliseconds. Defaults to `30000` (30 seconds). Pass `0` to disable timeout. The default value can be changed by using the [BrowserContext.setDefaultTimeout()](/api/class-browsercontext.mdx#browser-context-set-default-timeout) or [Page.setDefaultTimeout()](/api/class-page.mdx#page-set-default-timeout) methods. @@ -1397,6 +1415,9 @@ ElementHandle.tap(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. + - `setScroll` `enum ScrollMode { AUTO, NONE }` *(optional)* Added in: v1.62# + + 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. - `setTimeout` [double] *(optional)*# Maximum time in milliseconds. Defaults to `30000` (30 seconds). Pass `0` to disable timeout. The default value can be changed by using the [BrowserContext.setDefaultTimeout()](/api/class-browsercontext.mdx#browser-context-set-default-timeout) or [Page.setDefaultTimeout()](/api/class-page.mdx#page-set-default-timeout) methods. @@ -1525,6 +1546,9 @@ ElementHandle.uncheck(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. + - `setScroll` `enum ScrollMode { AUTO, NONE }` *(optional)* Added in: v1.62# + + 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. - `setTimeout` [double] *(optional)*# Maximum time in milliseconds. Defaults to `30000` (30 seconds). Pass `0` to disable timeout. The default value can be changed by using the [BrowserContext.setDefaultTimeout()](/api/class-browsercontext.mdx#browser-context-set-default-timeout) or [Page.setDefaultTimeout()](/api/class-page.mdx#page-set-default-timeout) methods. diff --git a/java/versioned_docs/version-stable/api/class-frame.mdx b/java/versioned_docs/version-stable/api/class-frame.mdx index 7a755a47fe..0479468040 100644 --- a/java/versioned_docs/version-stable/api/class-frame.mdx +++ b/java/versioned_docs/version-stable/api/class-frame.mdx @@ -173,6 +173,9 @@ Frame.dragAndDrop(source, target, options); This option has no effect. + - `setScroll` `enum ScrollMode { AUTO, NONE }` *(optional)* Added in: v1.62# + + 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. - `setSourcePosition` SourcePosition *(optional)* Added in: v1.14# - `setX` [double] @@ -1130,6 +1133,9 @@ Frame.check(selector, 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. + - `setScroll` `enum ScrollMode { AUTO, NONE }` *(optional)* Added in: v1.62# + + 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. - `setStrict` [boolean] *(optional)* Added in: v1.14# 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. @@ -1208,6 +1214,9 @@ Frame.click(selector, 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. + - `setScroll` `enum ScrollMode { AUTO, NONE }` *(optional)* Added in: v1.62# + + 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. - `setStrict` [boolean] *(optional)* Added in: v1.14# 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. @@ -1287,6 +1296,9 @@ Frame.dblclick(selector, 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. + - `setScroll` `enum ScrollMode { AUTO, NONE }` *(optional)* Added in: v1.62# + + 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. - `setStrict` [boolean] *(optional)* Added in: v1.14# 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. @@ -1637,6 +1649,9 @@ Frame.hover(selector, 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. + - `setScroll` `enum ScrollMode { AUTO, NONE }` *(optional)* Added in: v1.62# + + 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. - `setStrict` [boolean] *(optional)* Added in: v1.14# 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. @@ -2220,6 +2235,9 @@ Frame.setChecked(selector, checked, 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. + - `setScroll` `enum ScrollMode { AUTO, NONE }` *(optional)* Added in: v1.62# + + 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. - `setStrict` [boolean] *(optional)*# 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. @@ -2350,6 +2368,9 @@ Frame.tap(selector, 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. + - `setScroll` `enum ScrollMode { AUTO, NONE }` *(optional)* Added in: v1.62# + + 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. - `setStrict` [boolean] *(optional)* Added in: v1.14# 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. @@ -2502,6 +2523,9 @@ Frame.uncheck(selector, 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. + - `setScroll` `enum ScrollMode { AUTO, NONE }` *(optional)* Added in: v1.62# + + 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. - `setStrict` [boolean] *(optional)* Added in: v1.14# 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. diff --git a/java/versioned_docs/version-stable/api/class-locator.mdx b/java/versioned_docs/version-stable/api/class-locator.mdx index 13a378886d..4a7e76e686 100644 --- a/java/versioned_docs/version-stable/api/class-locator.mdx +++ b/java/versioned_docs/version-stable/api/class-locator.mdx @@ -273,6 +273,9 @@ page.getByRole(AriaRole.CHECKBOX).check(); A point to use relative to the top-left corner of element padding box. If not specified, uses some visible point of the element. + - `setScroll` `enum ScrollMode { AUTO, NONE }` *(optional)* Added in: v1.62# + + 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. - `setTimeout` [double] *(optional)*# Maximum time in milliseconds. Defaults to `30000` (30 seconds). Pass `0` to disable timeout. The default value can be changed by using the [BrowserContext.setDefaultTimeout()](/api/class-browsercontext.mdx#browser-context-set-default-timeout) or [Page.setDefaultTimeout()](/api/class-page.mdx#page-set-default-timeout) methods. @@ -394,6 +397,9 @@ page.locator("canvas").click(new Locator.ClickOptions() A point to use relative to the top-left corner of element padding box. If not specified, uses some visible point of the element. + - `setScroll` `enum ScrollMode { AUTO, NONE }` *(optional)* Added in: v1.62# + + 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. - `setSteps` [int] *(optional)* Added in: v1.57# 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. @@ -510,6 +516,9 @@ Locator.dblclick(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. + - `setScroll` `enum ScrollMode { AUTO, NONE }` *(optional)* Added in: v1.62# + + 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. - `setSteps` [int] *(optional)* Added in: v1.57# 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. @@ -675,6 +684,9 @@ source.dragTo(target, new Locator.DragToOptions() This option has no effect. + - `setScroll` `enum ScrollMode { AUTO, NONE }` *(optional)* Added in: v1.62# + + 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. - `setSourcePosition` SourcePosition *(optional)*# - `setX` [double] @@ -1479,6 +1491,9 @@ page.getByRole(AriaRole.LINK).hover(); A point to use relative to the top-left corner of element padding box. If not specified, uses some visible point of the element. + - `setScroll` `enum ScrollMode { AUTO, NONE }` *(optional)* Added in: v1.62# + + 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. - `setTimeout` [double] *(optional)*# Maximum time in milliseconds. Defaults to `30000` (30 seconds). Pass `0` to disable timeout. The default value can be changed by using the [BrowserContext.setDefaultTimeout()](/api/class-browsercontext.mdx#browser-context-set-default-timeout) or [Page.setDefaultTimeout()](/api/class-page.mdx#page-set-default-timeout) methods. @@ -2064,7 +2079,7 @@ page.getByRole(AriaRole.LINK).screenshot(new Locator.ScreenshotOptions() The file path to save the image to. The screenshot type will be inferred from file extension. If [setPath](/api/class-locator.mdx#locator-screenshot-option-path) is a relative path, then it is resolved relative to the current working directory. If no path is provided, the image won't be saved to the disk. - `setQuality` [int] *(optional)*# - The quality of the image, between 0-100. Not applicable to `png` images. + 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. - `setScale` `enum ScreenshotScale { CSS, DEVICE }` *(optional)*# 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. @@ -2076,7 +2091,7 @@ page.getByRole(AriaRole.LINK).screenshot(new Locator.ScreenshotOptions() - `setTimeout` [double] *(optional)*# Maximum time in milliseconds. Defaults to `30000` (30 seconds). Pass `0` to disable timeout. The default value can be changed by using the [BrowserContext.setDefaultTimeout()](/api/class-browsercontext.mdx#browser-context-set-default-timeout) or [Page.setDefaultTimeout()](/api/class-page.mdx#page-set-default-timeout) methods. - - `setType` `enum ScreenshotType { PNG, JPEG }` *(optional)*# + - `setType` `enum ScreenshotType { PNG, JPEG, WEBP }` *(optional)*# Specify screenshot type, defaults to `png`. @@ -2253,6 +2268,9 @@ page.getByRole(AriaRole.CHECKBOX).setChecked(true); A point to use relative to the top-left corner of element padding box. If not specified, uses some visible point of the element. + - `setScroll` `enum ScrollMode { AUTO, NONE }` *(optional)* Added in: v1.62# + + 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. - `setTimeout` [double] *(optional)*# Maximum time in milliseconds. Defaults to `30000` (30 seconds). Pass `0` to disable timeout. The default value can be changed by using the [BrowserContext.setDefaultTimeout()](/api/class-browsercontext.mdx#browser-context-set-default-timeout) or [Page.setDefaultTimeout()](/api/class-page.mdx#page-set-default-timeout) methods. @@ -2375,6 +2393,9 @@ Locator.tap(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. + - `setScroll` `enum ScrollMode { AUTO, NONE }` *(optional)* Added in: v1.62# + + 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. - `setTimeout` [double] *(optional)*# Maximum time in milliseconds. Defaults to `30000` (30 seconds). Pass `0` to disable timeout. The default value can be changed by using the [BrowserContext.setDefaultTimeout()](/api/class-browsercontext.mdx#browser-context-set-default-timeout) or [Page.setDefaultTimeout()](/api/class-page.mdx#page-set-default-timeout) methods. @@ -2465,6 +2486,9 @@ page.getByRole(AriaRole.CHECKBOX).uncheck(); A point to use relative to the top-left corner of element padding box. If not specified, uses some visible point of the element. + - `setScroll` `enum ScrollMode { AUTO, NONE }` *(optional)* Added in: v1.62# + + 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. - `setTimeout` [double] *(optional)*# Maximum time in milliseconds. Defaults to `30000` (30 seconds). Pass `0` to disable timeout. The default value can be changed by using the [BrowserContext.setDefaultTimeout()](/api/class-browsercontext.mdx#browser-context-set-default-timeout) or [Page.setDefaultTimeout()](/api/class-page.mdx#page-set-default-timeout) methods. @@ -2523,6 +2547,41 @@ orderSent.waitFor(); --- +### waitForFunction {/* #locator-wait-for-function */} + +Added in: v1.62locator.waitForFunction + +Returns when [expression](/api/class-locator.mdx#locator-wait-for-function-option-expression) returns a truthy value, called with the matching element as a first argument, and [arg](/api/class-locator.mdx#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 [expression](/api/class-locator.mdx#locator-wait-for-function-option-expression) returns a [Promise], this method will wait for the promise to resolve before checking its value. + +If [expression](/api/class-locator.mdx#locator-wait-for-function-option-expression) throws or rejects, this method throws. + +**Usage** + +Wait for an attribute to appear: + +Passing argument to [expression](/api/class-locator.mdx#locator-wait-for-function-option-expression): + +**Arguments** +- `expression` [String]# + + JavaScript expression to be evaluated in the browser context. If the expression evaluates to a function, the function is automatically invoked. +- `arg` [EvaluationArgument] *(optional)*# + + Optional argument to pass to [expression](/api/class-locator.mdx#locator-wait-for-function-option-expression). +- `options` `Locator.WaitForFunctionOptions` *(optional)* + - `setTimeout` [double] *(optional)*# + + Maximum time to wait for in milliseconds. Defaults to `30000` (30 seconds). Pass `0` to disable timeout. The default value can be changed by using the [BrowserContext.setDefaultTimeout()](/api/class-browsercontext.mdx#browser-context-set-default-timeout) or [Page.setDefaultTimeout()](/api/class-page.mdx#page-set-default-timeout) methods. + +**Returns** +- [void]# + +--- + ## Deprecated ### elementHandle {/* #locator-element-handle */} diff --git a/java/versioned_docs/version-stable/api/class-page.mdx b/java/versioned_docs/version-stable/api/class-page.mdx index 25a3ec9bf2..d1ad77c016 100644 --- a/java/versioned_docs/version-stable/api/class-page.mdx +++ b/java/versioned_docs/version-stable/api/class-page.mdx @@ -474,6 +474,9 @@ page.dragAndDrop("#source", "#target", new Page.DragAndDropOptions() This option has no effect. + - `setScroll` `enum ScrollMode { AUTO, NONE }` *(optional)* Added in: v1.62# + + 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. - `setSourcePosition` SourcePosition *(optional)* Added in: v1.14# - `setX` [double] @@ -1215,6 +1218,11 @@ Returns the main resource response. In case of multiple redirects, the navigatio Navigate to the previous page in history. +:::warning + +**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. +::: + **Usage** ```java @@ -1248,6 +1256,11 @@ Returns the main resource response. In case of multiple redirects, the navigatio Navigate to the next page in history. +:::warning + +**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. +::: + **Usage** ```java @@ -1987,7 +2000,7 @@ Page.screenshot(options); The file path to save the image to. The screenshot type will be inferred from file extension. If [setPath](/api/class-page.mdx#page-screenshot-option-path) is a relative path, then it is resolved relative to the current working directory. If no path is provided, the image won't be saved to the disk. - `setQuality` [int] *(optional)*# - The quality of the image, between 0-100. Not applicable to `png` images. + 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. - `setScale` `enum ScreenshotScale { CSS, DEVICE }` *(optional)*# 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. @@ -1999,7 +2012,7 @@ Page.screenshot(options); - `setTimeout` [double] *(optional)*# Maximum time in milliseconds. Defaults to `30000` (30 seconds). Pass `0` to disable timeout. The default value can be changed by using the [BrowserContext.setDefaultTimeout()](/api/class-browsercontext.mdx#browser-context-set-default-timeout) or [Page.setDefaultTimeout()](/api/class-page.mdx#page-set-default-timeout) methods. - - `setType` `enum ScreenshotType { PNG, JPEG }` *(optional)*# + - `setType` `enum ScreenshotType { PNG, JPEG, WEBP }` *(optional)*# Specify screenshot type, defaults to `png`. @@ -3339,6 +3352,9 @@ Page.check(selector, 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. + - `setScroll` `enum ScrollMode { AUTO, NONE }` *(optional)* Added in: v1.62# + + 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. - `setStrict` [boolean] *(optional)* Added in: v1.14# 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. @@ -3417,6 +3433,9 @@ Page.click(selector, 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. + - `setScroll` `enum ScrollMode { AUTO, NONE }` *(optional)* Added in: v1.62# + + 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. - `setStrict` [boolean] *(optional)* Added in: v1.14# 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. @@ -3496,6 +3515,9 @@ Page.dblclick(selector, 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. + - `setScroll` `enum ScrollMode { AUTO, NONE }` *(optional)* Added in: v1.62# + + 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. - `setStrict` [boolean] *(optional)* Added in: v1.14# 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. @@ -3842,6 +3864,9 @@ Page.hover(selector, 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. + - `setScroll` `enum ScrollMode { AUTO, NONE }` *(optional)* Added in: v1.62# + + 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. - `setStrict` [boolean] *(optional)* Added in: v1.14# 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. @@ -4456,6 +4481,9 @@ Page.setChecked(selector, checked, 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. + - `setScroll` `enum ScrollMode { AUTO, NONE }` *(optional)* Added in: v1.62# + + 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. - `setStrict` [boolean] *(optional)*# 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. @@ -4586,6 +4614,9 @@ Page.tap(selector, 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. + - `setScroll` `enum ScrollMode { AUTO, NONE }` *(optional)* Added in: v1.62# + + 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. - `setStrict` [boolean] *(optional)* Added in: v1.14# 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. @@ -4738,6 +4769,9 @@ Page.uncheck(selector, 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. + - `setScroll` `enum ScrollMode { AUTO, NONE }` *(optional)* Added in: v1.62# + + 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. - `setStrict` [boolean] *(optional)* Added in: v1.14# 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. diff --git a/java/versioned_docs/version-stable/api/class-request.mdx b/java/versioned_docs/version-stable/api/class-request.mdx index e229fbc34e..80f84ae2f8 100644 --- a/java/versioned_docs/version-stable/api/class-request.mdx +++ b/java/versioned_docs/version-stable/api/class-request.mdx @@ -374,28 +374,28 @@ page.navigate("http://example.com"); Request start time in milliseconds elapsed since January 1, 1970 00:00:00 UTC - `domainLookupStart` [double] - Time immediately before the browser starts the domain name lookup for the resource. The value is given in milliseconds relative to `startTime`, -1 if not available. + 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. - `domainLookupEnd` [double] - Time immediately after the browser starts the domain name lookup for the resource. The value is given in milliseconds relative to `startTime`, -1 if not available. + 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. - `connectStart` [double] - Time immediately before the user agent starts establishing the connection to the server to retrieve the resource. The value is given in milliseconds relative to `startTime`, -1 if not available. + 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. - `secureConnectionStart` [double] - Time immediately before the browser starts the handshake process to secure the current connection. The value is given in milliseconds relative to `startTime`, -1 if not available. + 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. - `connectEnd` [double] - Time immediately before the user agent starts establishing the connection to the server to retrieve the resource. The value is given in milliseconds relative to `startTime`, -1 if not available. + 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. - `requestStart` [double] - Time immediately before the browser starts requesting the resource from the server, cache, or local resource. The value is given in milliseconds relative to `startTime`, -1 if not available. + 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. - `responseStart` [double] - Time immediately after the browser 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. + 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. - `responseEnd` [double] - Time immediately after the browser 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. + 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. --- diff --git a/java/versioned_docs/version-stable/auth.mdx b/java/versioned_docs/version-stable/auth.mdx index ee32fbdbe5..a4d43695ed 100644 --- a/java/versioned_docs/version-stable/auth.mdx +++ b/java/versioned_docs/version-stable/auth.mdx @@ -80,9 +80,9 @@ Redoing login for every test can slow down test execution. To mitigate that, reu Playwright provides a way to reuse the signed-in state in the tests. That way you can log in only once and then skip the log in step for all of the tests. -Web apps use cookie-based or token-based authentication, where authenticated state is stored as [cookies](https://developer.mozilla.org/en-US/docs/Web/HTTP/Cookies), in [local storage](https://developer.mozilla.org/en-US/docs/Web/API/Storage) or in [IndexedDB](https://developer.mozilla.org/en-US/docs/Web/API/IndexedDB_API). Playwright provides [BrowserContext.storageState()](/api/class-browsercontext.mdx#browser-context-storage-state) method that can be used to retrieve storage state from authenticated contexts and then create new contexts with prepopulated state. +Web apps use cookie-based or token-based authentication, where authenticated state is stored as [cookies](https://developer.mozilla.org/en-US/docs/Web/HTTP/Cookies), in [local storage](https://developer.mozilla.org/en-US/docs/Web/API/Storage), in [IndexedDB](https://developer.mozilla.org/en-US/docs/Web/API/IndexedDB_API), or as passkeys ([WebAuthn](https://developer.mozilla.org/en-US/docs/Web/API/Web_Authentication_API) credentials). Playwright provides [BrowserContext.storageState()](/api/class-browsercontext.mdx#browser-context-storage-state) method that can be used to retrieve storage state from authenticated contexts and then create new contexts with prepopulated state. -Cookies, local storage and IndexedDB state can be used across different browsers. They depend on your application's authentication model which may require some combination of cookies, local storage or IndexedDB. +Cookies, local storage, IndexedDB and virtual WebAuthn credentials (passkeys) can be used across different browsers. They depend on your application's authentication model which may require some combination of cookies, local storage, IndexedDB or passkeys. The following code snippet retrieves state from an authenticated context and creates a new context with that state. @@ -99,7 +99,7 @@ BrowserContext context = browser.newContext( ### Session storage -Reusing authenticated state covers [cookies](https://developer.mozilla.org/en-US/docs/Web/HTTP/Cookies), [local storage](https://developer.mozilla.org/en-US/docs/Web/API/Storage) and [IndexedDB](https://developer.mozilla.org/en-US/docs/Web/API/IndexedDB_API) based authentication. Rarely, [session storage](https://developer.mozilla.org/en-US/docs/Web/API/Window/sessionStorage) is used for storing information associated with the signed-in state. Session storage is specific to a particular domain and is not persisted across page loads. Playwright does not provide API to persist session storage, but the following snippet can be used to save/load session storage. +Reusing authenticated state covers [cookies](https://developer.mozilla.org/en-US/docs/Web/HTTP/Cookies), [local storage](https://developer.mozilla.org/en-US/docs/Web/API/Storage), [IndexedDB](https://developer.mozilla.org/en-US/docs/Web/API/IndexedDB_API) and passkey ([WebAuthn](https://developer.mozilla.org/en-US/docs/Web/API/Web_Authentication_API)) based authentication. Rarely, [session storage](https://developer.mozilla.org/en-US/docs/Web/API/Window/sessionStorage) is used for storing information associated with the signed-in state. Session storage is specific to a particular domain and is not persisted across page loads. Playwright does not provide API to persist session storage, but the following snippet can be used to save/load session storage. ```java // Get session storage and store as env variable diff --git a/java/versioned_docs/version-stable/ci-intro.mdx b/java/versioned_docs/version-stable/ci-intro.mdx index 03ce5c94d9..dabb94d078 100644 --- a/java/versioned_docs/version-stable/ci-intro.mdx +++ b/java/versioned_docs/version-stable/ci-intro.mdx @@ -31,7 +31,7 @@ jobs: timeout-minutes: 60 runs-on: ubuntu-latest steps: - - uses: actions/checkout@v5 + - uses: actions/checkout@v6 - uses: actions/setup-java@v5 with: distribution: 'temurin' diff --git a/java/versioned_docs/version-stable/ci.mdx b/java/versioned_docs/version-stable/ci.mdx index 7326ec4996..c5349fb4cd 100644 --- a/java/versioned_docs/version-stable/ci.mdx +++ b/java/versioned_docs/version-stable/ci.mdx @@ -46,7 +46,7 @@ jobs: timeout-minutes: 60 runs-on: ubuntu-latest steps: - - uses: actions/checkout@v5 + - uses: actions/checkout@v6 - uses: actions/setup-java@v5 with: distribution: 'temurin' @@ -75,10 +75,10 @@ jobs: name: 'Playwright Tests' runs-on: ubuntu-latest container: - image: mcr.microsoft.com/playwright/java:v1.60.0-noble + image: mcr.microsoft.com/playwright/java:v1.61.0-noble options: --user 1001 steps: - - uses: actions/checkout@v5 + - uses: actions/checkout@v6 - uses: actions/setup-java@v5 with: distribution: 'temurin' @@ -103,7 +103,7 @@ jobs: runs-on: ubuntu-latest if: github.event.deployment_status.state == 'success' steps: - - uses: actions/checkout@v5 + - uses: actions/checkout@v6 - uses: actions/setup-java@v5 with: distribution: 'temurin' @@ -160,7 +160,7 @@ trigger: pool: vmImage: ubuntu-latest -container: mcr.microsoft.com/playwright/java:v1.60.0-noble +container: mcr.microsoft.com/playwright/java:v1.61.0-noble steps: - task: JavaToolInstaller@1 @@ -183,7 +183,7 @@ Running Playwright on CircleCI is very similar to running on GitHub Actions. In executors: pw-noble-development: docker: - - image: mcr.microsoft.com/playwright/java:v1.60.0-noble + - image: mcr.microsoft.com/playwright/java:v1.61.0-noble ``` Note: When using the docker agent definition, you are specifying the resource class of where playwright runs to the 'medium' tier [here](https://circleci.com/docs/configuration-reference?#docker-execution-environment). The default behavior of Playwright is to set the number of workers to the detected core count (2 in the case of the medium tier). Overriding the number of workers to greater than this number will cause unnecessary timeouts and failures. @@ -194,7 +194,7 @@ Jenkins supports Docker agents for pipelines. Use the [Playwright Docker image]( ```groovy pipeline { - agent { docker { image 'mcr.microsoft.com/playwright/java:v1.60.0-noble' } } + agent { docker { image 'mcr.microsoft.com/playwright/java:v1.61.0-noble' } } stages { stage('e2e-tests') { steps { @@ -211,7 +211,7 @@ pipeline { Bitbucket Pipelines can use public [Docker images as build environments](https://confluence.atlassian.com/bitbucket/use-docker-images-as-build-environments-792298897.html). To run Playwright tests on Bitbucket, use our public Docker image ([see Dockerfile](./docker.mdx)). ```yml -image: mcr.microsoft.com/playwright/java:v1.60.0-noble +image: mcr.microsoft.com/playwright/java:v1.61.0-noble ``` ### GitLab CI @@ -224,7 +224,7 @@ stages: tests: stage: test - image: mcr.microsoft.com/playwright/java:v1.60.0-noble + image: mcr.microsoft.com/playwright/java:v1.61.0-noble script: ... ``` diff --git a/java/versioned_docs/version-stable/docker.mdx b/java/versioned_docs/version-stable/docker.mdx index c401cc3b9e..13dcb45168 100644 --- a/java/versioned_docs/version-stable/docker.mdx +++ b/java/versioned_docs/version-stable/docker.mdx @@ -22,7 +22,7 @@ This Docker image is intended to be used for testing and development purposes on ### Pull the image ```bash -docker pull mcr.microsoft.com/playwright/java:v1.60.0-noble +docker pull mcr.microsoft.com/playwright/java:v1.61.0-noble ``` ### Run the image @@ -34,7 +34,7 @@ By default, the Docker image will use the `root` user to run the browsers. This On trusted websites, you can avoid creating a separate user and use root for it since you trust the code which will run on the browsers. ```bash -docker run -it --rm --ipc=host mcr.microsoft.com/playwright/java:v1.60.0-noble /bin/bash +docker run -it --rm --ipc=host mcr.microsoft.com/playwright/java:v1.61.0-noble /bin/bash ``` #### Crawling and scraping @@ -42,7 +42,7 @@ docker run -it --rm --ipc=host mcr.microsoft.com/playwright/java:v1.60.0-noble / On untrusted websites, it's recommended to use a separate user for launching the browsers in combination with the seccomp profile. Inside the container or if you are using the Docker image as a base image you have to use `adduser` for it. ```bash -docker run -it --rm --ipc=host --user pwuser --security-opt seccomp=seccomp_profile.json mcr.microsoft.com/playwright/java:v1.60.0-noble /bin/bash +docker run -it --rm --ipc=host --user pwuser --security-opt seccomp=seccomp_profile.json mcr.microsoft.com/playwright/java:v1.61.0-noble /bin/bash ``` [`seccomp_profile.json`](https://github.com/microsoft/playwright/blob/main/utils/docker/seccomp_profile.json) is needed to run Chromium with sandbox. This is a [default Docker seccomp profile](https://github.com/docker/engine/blob/d0d99b04cf6e00ed3fc27e81fc3d94e7eda70af3/profiles/seccomp/default.json) with extra user namespace cloning permissions: @@ -82,7 +82,7 @@ You can run Playwright Server in Docker while keeping your tests running on the Start the Playwright Server in Docker: ```bash -docker run -p 3000:3000 --rm --init -it --workdir /home/pwuser --user pwuser mcr.microsoft.com/playwright:v1.60.0-noble /bin/sh -c "npx -y playwright@1.60.0 run-server --port 3000 --host 0.0.0.0" +docker run -p 3000:3000 --rm --init -it --workdir /home/pwuser --user pwuser mcr.microsoft.com/playwright:v1.61.0-noble /bin/sh -c "npx -y playwright@1.61.0 run-server --port 3000 --host 0.0.0.0" ``` #### Connecting to the Server @@ -107,7 +107,7 @@ public class App { If you need to access local servers from within the Docker container: ```bash -docker run --add-host=hostmachine:host-gateway -p 3000:3000 --rm --init -it --workdir /home/pwuser --user pwuser mcr.microsoft.com/playwright:v1.60.0-noble /bin/sh -c "npx -y playwright@1.60.0 run-server --port 3000 --host 0.0.0.0" +docker run --add-host=hostmachine:host-gateway -p 3000:3000 --rm --init -it --workdir /home/pwuser --user pwuser mcr.microsoft.com/playwright:v1.61.0-noble /bin/sh -c "npx -y playwright@1.61.0 run-server --port 3000 --host 0.0.0.0" ``` This makes `hostmachine` point to the host's localhost. Your tests should use `hostmachine` instead of `localhost` when accessing local servers. @@ -140,9 +140,10 @@ Once this is enabled you can open the port specified in a new browser tab and yo See [all available image tags]. We currently publish images with the following tags: -- `:v1.60.0` - Playwright v1.60.0 release docker image based on Ubuntu 24.04 LTS (Noble Numbat). -- `:v1.60.0-noble` - Playwright v1.60.0 release docker image based on Ubuntu 24.04 LTS (Noble Numbat). -- `:v1.60.0-jammy` - Playwright v1.60.0 release docker image based on Ubuntu 22.04 LTS (Jammy Jellyfish). +- `:v1.61.0` - Playwright v1.61.0 release docker image based on Ubuntu 24.04 LTS (Noble Numbat). +- `:v1.61.0-noble` - Playwright v1.61.0 release docker image based on Ubuntu 24.04 LTS (Noble Numbat). +- `:v1.61.0-jammy` - Playwright v1.61.0 release docker image based on Ubuntu 22.04 LTS (Jammy Jellyfish). +- `:v1.61.0-resolute` - Playwright v1.61.0 release docker image based on Ubuntu 26.04 LTS (Resolute Raccoon). :::note @@ -152,6 +153,7 @@ It is recommended to always pin your Docker image to a specific version if possi ### Base images We currently publish images based on the following [Ubuntu](https://hub.docker.com/_/ubuntu) versions: +- **Ubuntu 26.04 LTS** (Resolute Raccoon), image tags include `resolute` - **Ubuntu 24.04 LTS** (Noble Numbat), image tags include `noble` - **Ubuntu 22.04 LTS** (Jammy Jellyfish), image tags include `jammy` diff --git a/java/versioned_docs/version-stable/getting-started-cli.mdx b/java/versioned_docs/version-stable/getting-started-cli.mdx index 36ffe77e57..10bd768b9b 100644 --- a/java/versioned_docs/version-stable/getting-started-cli.mdx +++ b/java/versioned_docs/version-stable/getting-started-cli.mdx @@ -17,7 +17,7 @@ Playwright comes with `playwright-cli`, a command-line interface for browser aut ## Prerequisites Before you begin, make sure you have the following installed: -- [Node.js](https://nodejs.org/) 18 or newer +- [Node.js](https://nodejs.org/) 20 or newer - A coding agent: Claude Code, GitHub Copilot, or similar ## Installation @@ -32,6 +32,7 @@ playwright-cli --help Alternatively, install `@playwright/cli` as a local dependency and use `npx`: ```bash +npm install -D @playwright/cli@latest npx playwright-cli --help ``` @@ -131,6 +132,7 @@ playwright-cli snapshot --filename=f # save snapshot to specific file playwright-cli screenshot # screenshot of the current page playwright-cli screenshot [ref] # screenshot of a specific element playwright-cli screenshot --filename=f # save with specific filename +playwright-cli screenshot --hires # capture using device pixels playwright-cli pdf # save page as PDF ``` diff --git a/java/versioned_docs/version-stable/getting-started-mcp.mdx b/java/versioned_docs/version-stable/getting-started-mcp.mdx index c1d766e4cf..999c3eb16b 100644 --- a/java/versioned_docs/version-stable/getting-started-mcp.mdx +++ b/java/versioned_docs/version-stable/getting-started-mcp.mdx @@ -13,7 +13,7 @@ The Playwright MCP server provides browser automation capabilities through the [ ## Prerequisites Before you begin, make sure you have the following installed: -- [Node.js](https://nodejs.org/) 18 or newer +- [Node.js](https://nodejs.org/) 20 or newer - An MCP client: VS Code, Cursor, Windsurf, Claude Code, Claude Desktop, or similar ## Getting Started @@ -194,6 +194,8 @@ When running a headed browser on a system without a display or from IDE worker p npx @playwright/mcp@latest --port 8931 ``` +HTTP sessions use a five-second heartbeat timeout. If your MCP client or proxy does not answer server-initiated pings, set `PLAYWRIGHT_MCP_PING_TIMEOUT_MS` to a longer timeout in milliseconds. Set it to `0` to disable the heartbeat. + Then point your MCP client to the HTTP endpoint: ```json diff --git a/java/versioned_docs/version-stable/intro.mdx b/java/versioned_docs/version-stable/intro.mdx index cf3766a4c8..512c32c5b4 100644 --- a/java/versioned_docs/version-stable/intro.mdx +++ b/java/versioned_docs/version-stable/intro.mdx @@ -58,7 +58,7 @@ public class App { com.microsoft.playwright playwright - 1.60.0 + 1.61.0 diff --git a/java/versioned_docs/version-stable/navigations.mdx b/java/versioned_docs/version-stable/navigations.mdx index ca04efa537..5a7f3a90fd 100644 --- a/java/versioned_docs/version-stable/navigations.mdx +++ b/java/versioned_docs/version-stable/navigations.mdx @@ -60,6 +60,16 @@ page.getByText("Click me").click(); page.waitForURL("**/login"); ``` +## Back/Forward Cache (BFCache) + +Modern browsers utilize a Back/Forward Cache (BFCache) to instantly load a page when a user navigates back or forward. This is achieved by freezing the page's DOM and JavaScript heap in memory, and thawing it upon return. + +By default, Playwright disables the BFCache across all browsers to ensure consistent, clean testing environments. + +Even if you explicitly enable BFCache, **testing BFCache restorations is not supported**. Because a BFCache restore skips the network fetch phase, the browser does not fire standard navigation lifecycle events (such as `commit`, `domcontentloaded`, or `load`). Playwright's internal `Page` state heavily relies on these network-level events to stay synchronized. + +Consequently, triggering a BFCache restore (e.g., via `page.goBack()`) will bypass Playwright's lifecycle tracking, resulting in timeouts and a completely desynchronized `Page` object where subsequent interactions will fail. + ## Navigation events Playwright splits the process of showing a new document in a page into **navigation** and **loading**. diff --git a/java/versioned_docs/version-stable/test-runners.mdx b/java/versioned_docs/version-stable/test-runners.mdx index 7a2f856cf5..1bde5a455c 100644 --- a/java/versioned_docs/version-stable/test-runners.mdx +++ b/java/versioned_docs/version-stable/test-runners.mdx @@ -198,7 +198,7 @@ repositories { } dependencies { - implementation 'com.microsoft.playwright:playwright:1.60.0' + implementation 'com.microsoft.playwright:playwright:1.61.0' } application { @@ -231,7 +231,7 @@ repositories { } dependencies { - implementation("com.microsoft.playwright:playwright:1.60.0") + implementation("com.microsoft.playwright:playwright:1.61.0") } application { diff --git a/nodejs/versioned_docs/version-stable/accessibility-testing.mdx b/nodejs/versioned_docs/version-stable/accessibility-testing.mdx index 030ed604db..3a1f39e910 100644 --- a/nodejs/versioned_docs/version-stable/accessibility-testing.mdx +++ b/nodejs/versioned_docs/version-stable/accessibility-testing.mdx @@ -404,6 +404,7 @@ test('example using custom fixture', async ({ page, makeAxeBuilder }) => { [TestCase]: /api/class-testcase.mdx "TestCase" [TestError]: /api/class-testerror.mdx "TestError" [TestResult]: /api/class-testresult.mdx "TestResult" +[TestRun]: /api/class-testrun.mdx "TestRun" [TestStep]: /api/class-teststep.mdx "TestStep" [Element]: https://developer.mozilla.org/en-US/docs/Web/API/element "Element" [EvaluationArgument]: /evaluating.mdx#evaluation-argument "EvaluationArgument" diff --git a/nodejs/versioned_docs/version-stable/actionability.mdx b/nodejs/versioned_docs/version-stable/actionability.mdx index dcacda102c..900585a789 100644 --- a/nodejs/versioned_docs/version-stable/actionability.mdx +++ b/nodejs/versioned_docs/version-stable/actionability.mdx @@ -194,6 +194,7 @@ For example, consider a scenario where Playwright will click `Sign Up` button re [TestCase]: /api/class-testcase.mdx "TestCase" [TestError]: /api/class-testerror.mdx "TestError" [TestResult]: /api/class-testresult.mdx "TestResult" +[TestRun]: /api/class-testrun.mdx "TestRun" [TestStep]: /api/class-teststep.mdx "TestStep" [Element]: https://developer.mozilla.org/en-US/docs/Web/API/element "Element" [EvaluationArgument]: /evaluating.mdx#evaluation-argument "EvaluationArgument" diff --git a/nodejs/versioned_docs/version-stable/api-testing.mdx b/nodejs/versioned_docs/version-stable/api-testing.mdx index f520e9ac06..f0938cc717 100644 --- a/nodejs/versioned_docs/version-stable/api-testing.mdx +++ b/nodejs/versioned_docs/version-stable/api-testing.mdx @@ -445,6 +445,7 @@ test('global context request has isolated cookie storage', async ({ [TestCase]: /api/class-testcase.mdx "TestCase" [TestError]: /api/class-testerror.mdx "TestError" [TestResult]: /api/class-testresult.mdx "TestResult" +[TestRun]: /api/class-testrun.mdx "TestRun" [TestStep]: /api/class-teststep.mdx "TestStep" [Element]: https://developer.mozilla.org/en-US/docs/Web/API/element "Element" [EvaluationArgument]: /evaluating.mdx#evaluation-argument "EvaluationArgument" diff --git a/nodejs/versioned_docs/version-stable/api/class-android.mdx b/nodejs/versioned_docs/version-stable/api/class-android.mdx index 7545a54ca1..116a20d5a3 100644 --- a/nodejs/versioned_docs/version-stable/api/class-android.mdx +++ b/nodejs/versioned_docs/version-stable/api/class-android.mdx @@ -315,6 +315,7 @@ android.setDefaultTimeout(timeout); [TestCase]: /api/class-testcase.mdx "TestCase" [TestError]: /api/class-testerror.mdx "TestError" [TestResult]: /api/class-testresult.mdx "TestResult" +[TestRun]: /api/class-testrun.mdx "TestRun" [TestStep]: /api/class-teststep.mdx "TestStep" [Element]: https://developer.mozilla.org/en-US/docs/Web/API/element "Element" [EvaluationArgument]: /evaluating.mdx#evaluation-argument "EvaluationArgument" diff --git a/nodejs/versioned_docs/version-stable/api/class-androiddevice.mdx b/nodejs/versioned_docs/version-stable/api/class-androiddevice.mdx index 9168cb54f1..0a062e0be7 100644 --- a/nodejs/versioned_docs/version-stable/api/class-androiddevice.mdx +++ b/nodejs/versioned_docs/version-stable/api/class-androiddevice.mdx @@ -344,6 +344,9 @@ await androidDevice.launchBrowser(options); - `fontSize` [number] *(optional)* Font size of the action title in pixels. Defaults to `24`. + - `cursor` "none" | "pointer" *(optional)* + + 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. If specified, enables visual annotations on interacted elements during video recording. @@ -1005,6 +1008,7 @@ androidDevice.on('webview', data => {}); [TestCase]: /api/class-testcase.mdx "TestCase" [TestError]: /api/class-testerror.mdx "TestError" [TestResult]: /api/class-testresult.mdx "TestResult" +[TestRun]: /api/class-testrun.mdx "TestRun" [TestStep]: /api/class-teststep.mdx "TestStep" [Element]: https://developer.mozilla.org/en-US/docs/Web/API/element "Element" [EvaluationArgument]: /evaluating.mdx#evaluation-argument "EvaluationArgument" diff --git a/nodejs/versioned_docs/version-stable/api/class-androidinput.mdx b/nodejs/versioned_docs/version-stable/api/class-androidinput.mdx index 70d665ea88..a5fac605e5 100644 --- a/nodejs/versioned_docs/version-stable/api/class-androidinput.mdx +++ b/nodejs/versioned_docs/version-stable/api/class-androidinput.mdx @@ -229,6 +229,7 @@ await androidInput.type(text); [TestCase]: /api/class-testcase.mdx "TestCase" [TestError]: /api/class-testerror.mdx "TestError" [TestResult]: /api/class-testresult.mdx "TestResult" +[TestRun]: /api/class-testrun.mdx "TestRun" [TestStep]: /api/class-teststep.mdx "TestStep" [Element]: https://developer.mozilla.org/en-US/docs/Web/API/element "Element" [EvaluationArgument]: /evaluating.mdx#evaluation-argument "EvaluationArgument" diff --git a/nodejs/versioned_docs/version-stable/api/class-androidsocket.mdx b/nodejs/versioned_docs/version-stable/api/class-androidsocket.mdx index 0fc32a0542..dff843aa45 100644 --- a/nodejs/versioned_docs/version-stable/api/class-androidsocket.mdx +++ b/nodejs/versioned_docs/version-stable/api/class-androidsocket.mdx @@ -156,6 +156,7 @@ androidSocket.on('data', data => {}); [TestCase]: /api/class-testcase.mdx "TestCase" [TestError]: /api/class-testerror.mdx "TestError" [TestResult]: /api/class-testresult.mdx "TestResult" +[TestRun]: /api/class-testrun.mdx "TestRun" [TestStep]: /api/class-teststep.mdx "TestStep" [Element]: https://developer.mozilla.org/en-US/docs/Web/API/element "Element" [EvaluationArgument]: /evaluating.mdx#evaluation-argument "EvaluationArgument" diff --git a/nodejs/versioned_docs/version-stable/api/class-androidwebview.mdx b/nodejs/versioned_docs/version-stable/api/class-androidwebview.mdx index 67df6a3344..09b1237099 100644 --- a/nodejs/versioned_docs/version-stable/api/class-androidwebview.mdx +++ b/nodejs/versioned_docs/version-stable/api/class-androidwebview.mdx @@ -151,6 +151,7 @@ androidWebView.on('close', data => {}); [TestCase]: /api/class-testcase.mdx "TestCase" [TestError]: /api/class-testerror.mdx "TestError" [TestResult]: /api/class-testresult.mdx "TestResult" +[TestRun]: /api/class-testrun.mdx "TestRun" [TestStep]: /api/class-teststep.mdx "TestStep" [Element]: https://developer.mozilla.org/en-US/docs/Web/API/element "Element" [EvaluationArgument]: /evaluating.mdx#evaluation-argument "EvaluationArgument" diff --git a/nodejs/versioned_docs/version-stable/api/class-apirequest.mdx b/nodejs/versioned_docs/version-stable/api/class-apirequest.mdx index 0194887fdf..79f824a0b8 100644 --- a/nodejs/versioned_docs/version-stable/api/class-apirequest.mdx +++ b/nodejs/versioned_docs/version-stable/api/class-apirequest.mdx @@ -239,6 +239,7 @@ await apiRequest.newContext(options); [TestCase]: /api/class-testcase.mdx "TestCase" [TestError]: /api/class-testerror.mdx "TestError" [TestResult]: /api/class-testresult.mdx "TestResult" +[TestRun]: /api/class-testrun.mdx "TestRun" [TestStep]: /api/class-teststep.mdx "TestStep" [Element]: https://developer.mozilla.org/en-US/docs/Web/API/element "Element" [EvaluationArgument]: /evaluating.mdx#evaluation-argument "EvaluationArgument" diff --git a/nodejs/versioned_docs/version-stable/api/class-apirequestcontext.mdx b/nodejs/versioned_docs/version-stable/api/class-apirequestcontext.mdx index 3b927b4297..65e383683e 100644 --- a/nodejs/versioned_docs/version-stable/api/class-apirequestcontext.mdx +++ b/nodejs/versioned_docs/version-stable/api/class-apirequestcontext.mdx @@ -80,6 +80,9 @@ await apiRequestContext.delete(url, options); - `params` [Object]<[string], [string] | [number] | [boolean]> | [URLSearchParams] | [string] *(optional)*# Query parameters to be sent with the URL. + - `signal` [AbortSignal] *(optional)* Added in: v1.62# + + 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()](/api/class-browsercontext.mdx#browser-context-set-default-timeout) or [page.setDefaultTimeout()](/api/class-page.mdx#page-set-default-timeout); pass `timeout: 0` to disable the timeout entirely. - `timeout` [number] *(optional)*# Request timeout in milliseconds. Defaults to `30000` (30 seconds). Pass `0` to disable timeout. @@ -191,6 +194,9 @@ await request.fetch('https://example.com/api/uploadForm', { - `params` [Object]<[string], [string] | [number] | [boolean]> | [URLSearchParams] | [string] *(optional)*# Query parameters to be sent with the URL. + - `signal` [AbortSignal] *(optional)* Added in: v1.62# + + 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()](/api/class-browsercontext.mdx#browser-context-set-default-timeout) or [page.setDefaultTimeout()](/api/class-page.mdx#page-set-default-timeout); pass `timeout: 0` to disable the timeout entirely. - `timeout` [number] *(optional)*# Request timeout in milliseconds. Defaults to `30000` (30 seconds). Pass `0` to disable timeout. @@ -272,6 +278,9 @@ await request.get('https://example.com/api/getText', { params: queryString }); - `params` [Object]<[string], [string] | [number] | [boolean]> | [URLSearchParams] | [string] *(optional)*# Query parameters to be sent with the URL. + - `signal` [AbortSignal] *(optional)* Added in: v1.62# + + 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()](/api/class-browsercontext.mdx#browser-context-set-default-timeout) or [page.setDefaultTimeout()](/api/class-page.mdx#page-set-default-timeout); pass `timeout: 0` to disable the timeout entirely. - `timeout` [number] *(optional)*# Request timeout in milliseconds. Defaults to `30000` (30 seconds). Pass `0` to disable timeout. @@ -335,6 +344,9 @@ await apiRequestContext.head(url, options); - `params` [Object]<[string], [string] | [number] | [boolean]> | [URLSearchParams] | [string] *(optional)*# Query parameters to be sent with the URL. + - `signal` [AbortSignal] *(optional)* Added in: v1.62# + + 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()](/api/class-browsercontext.mdx#browser-context-set-default-timeout) or [page.setDefaultTimeout()](/api/class-page.mdx#page-set-default-timeout); pass `timeout: 0` to disable the timeout entirely. - `timeout` [number] *(optional)*# Request timeout in milliseconds. Defaults to `30000` (30 seconds). Pass `0` to disable timeout. @@ -398,6 +410,9 @@ await apiRequestContext.patch(url, options); - `params` [Object]<[string], [string] | [number] | [boolean]> | [URLSearchParams] | [string] *(optional)*# Query parameters to be sent with the URL. + - `signal` [AbortSignal] *(optional)* Added in: v1.62# + + 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()](/api/class-browsercontext.mdx#browser-context-set-default-timeout) or [page.setDefaultTimeout()](/api/class-page.mdx#page-set-default-timeout); pass `timeout: 0` to disable the timeout entirely. - `timeout` [number] *(optional)*# Request timeout in milliseconds. Defaults to `30000` (30 seconds). Pass `0` to disable timeout. @@ -492,6 +507,9 @@ await request.post('https://example.com/api/uploadForm', { - `params` [Object]<[string], [string] | [number] | [boolean]> | [URLSearchParams] | [string] *(optional)*# Query parameters to be sent with the URL. + - `signal` [AbortSignal] *(optional)* Added in: v1.62# + + 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()](/api/class-browsercontext.mdx#browser-context-set-default-timeout) or [page.setDefaultTimeout()](/api/class-page.mdx#page-set-default-timeout); pass `timeout: 0` to disable the timeout entirely. - `timeout` [number] *(optional)*# Request timeout in milliseconds. Defaults to `30000` (30 seconds). Pass `0` to disable timeout. @@ -555,6 +573,9 @@ await apiRequestContext.put(url, options); - `params` [Object]<[string], [string] | [number] | [boolean]> | [URLSearchParams] | [string] *(optional)*# Query parameters to be sent with the URL. + - `signal` [AbortSignal] *(optional)* Added in: v1.62# + + 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()](/api/class-browsercontext.mdx#browser-context-set-default-timeout) or [page.setDefaultTimeout()](/api/class-page.mdx#page-set-default-timeout); pass `timeout: 0` to disable the timeout entirely. - `timeout` [number] *(optional)*# Request timeout in milliseconds. Defaults to `30000` (30 seconds). Pass `0` to disable timeout. @@ -716,6 +737,7 @@ apiRequestContext.tracing [TestCase]: /api/class-testcase.mdx "TestCase" [TestError]: /api/class-testerror.mdx "TestError" [TestResult]: /api/class-testresult.mdx "TestResult" +[TestRun]: /api/class-testrun.mdx "TestRun" [TestStep]: /api/class-teststep.mdx "TestStep" [Element]: https://developer.mozilla.org/en-US/docs/Web/API/element "Element" [EvaluationArgument]: /evaluating.mdx#evaluation-argument "EvaluationArgument" diff --git a/nodejs/versioned_docs/version-stable/api/class-apiresponse.mdx b/nodejs/versioned_docs/version-stable/api/class-apiresponse.mdx index 1fead65723..0378facd66 100644 --- a/nodejs/versioned_docs/version-stable/api/class-apiresponse.mdx +++ b/nodejs/versioned_docs/version-stable/api/class-apiresponse.mdx @@ -229,6 +229,50 @@ await apiResponse.text(); --- +### timing {/* #api-response-timing */} + +Added in: v1.62apiResponse.timing + +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](../mock.mdx#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). + +**Usage** + +```js +apiResponse.timing(); +``` + +**Returns** +- [Object]# + - `startTime` [number] + + Request start time in milliseconds elapsed since January 1, 1970 00:00:00 UTC + - `domainLookupStart` [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. + - `domainLookupEnd` [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. + - `connectStart` [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. + - `secureConnectionStart` [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. + - `connectEnd` [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. + - `requestStart` [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. + - `responseStart` [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. + - `responseEnd` [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. + +--- + ### url {/* #api-response-url */} Added in: v1.16apiResponse.url @@ -316,6 +360,7 @@ apiResponse.url(); [TestCase]: /api/class-testcase.mdx "TestCase" [TestError]: /api/class-testerror.mdx "TestError" [TestResult]: /api/class-testresult.mdx "TestResult" +[TestRun]: /api/class-testrun.mdx "TestRun" [TestStep]: /api/class-teststep.mdx "TestStep" [Element]: https://developer.mozilla.org/en-US/docs/Web/API/element "Element" [EvaluationArgument]: /evaluating.mdx#evaluation-argument "EvaluationArgument" diff --git a/nodejs/versioned_docs/version-stable/api/class-apiresponseassertions.mdx b/nodejs/versioned_docs/version-stable/api/class-apiresponseassertions.mdx index 1f094b4434..7a9f8ca9f1 100644 --- a/nodejs/versioned_docs/version-stable/api/class-apiresponseassertions.mdx +++ b/nodejs/versioned_docs/version-stable/api/class-apiresponseassertions.mdx @@ -132,6 +132,7 @@ await expect(response).not.toBeOK(); [TestCase]: /api/class-testcase.mdx "TestCase" [TestError]: /api/class-testerror.mdx "TestError" [TestResult]: /api/class-testresult.mdx "TestResult" +[TestRun]: /api/class-testrun.mdx "TestRun" [TestStep]: /api/class-teststep.mdx "TestStep" [Element]: https://developer.mozilla.org/en-US/docs/Web/API/element "Element" [EvaluationArgument]: /evaluating.mdx#evaluation-argument "EvaluationArgument" diff --git a/nodejs/versioned_docs/version-stable/api/class-browser.mdx b/nodejs/versioned_docs/version-stable/api/class-browser.mdx index cd019629b1..fec045f621 100644 --- a/nodejs/versioned_docs/version-stable/api/class-browser.mdx +++ b/nodejs/versioned_docs/version-stable/api/class-browser.mdx @@ -379,6 +379,9 @@ If directly using this method to create [BrowserContext]s, it is best practice t - `fontSize` [number] *(optional)* Font size of the action title in pixels. Defaults to `24`. + - `cursor` "none" | "pointer" *(optional)* + + 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. If specified, enables visual annotations on interacted elements during video recording. @@ -667,6 +670,9 @@ await browser.newPage(options); - `fontSize` [number] *(optional)* Font size of the action title in pixels. Defaults to `24`. + - `cursor` "none" | "pointer" *(optional)* + + 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. If specified, enables visual annotations on interacted elements during video recording. @@ -993,6 +999,7 @@ browser.on('disconnected', data => {}); [TestCase]: /api/class-testcase.mdx "TestCase" [TestError]: /api/class-testerror.mdx "TestError" [TestResult]: /api/class-testresult.mdx "TestResult" +[TestRun]: /api/class-testrun.mdx "TestRun" [TestStep]: /api/class-teststep.mdx "TestStep" [Element]: https://developer.mozilla.org/en-US/docs/Web/API/element "Element" [EvaluationArgument]: /evaluating.mdx#evaluation-argument "EvaluationArgument" diff --git a/nodejs/versioned_docs/version-stable/api/class-browsercontext.mdx b/nodejs/versioned_docs/version-stable/api/class-browsercontext.mdx index 83d35a1a7f..f0bbd99af7 100644 --- a/nodejs/versioned_docs/version-stable/api/class-browsercontext.mdx +++ b/nodejs/versioned_docs/version-stable/api/class-browsercontext.mdx @@ -121,6 +121,10 @@ The order of evaluation of multiple scripts installed via [browserContext.addIni - `arg` [Serializable] *(optional)*# Optional argument to pass to [script](/api/class-browsercontext.mdx#browser-context-add-init-script-option-script) (only supported when passing a function). +- `options` [Object] *(optional)* + - `exposeFunctions` [boolean] *(optional)* Added in: v1.62# + + When set to `true`, functions passed inside [arg](/api/class-browsercontext.mdx#browser-context-add-init-script-option-arg) are exposed in the page and can be called from the init script. Calling one returns a [Promise] of its result. Under the hood, each function is exposed via [page.exposeFunction()](/api/class-page.mdx#page-expose-function), so it is technically accessible from all frames and worlds of the page. Unlike functions passed to [page.evaluate()](/api/class-page.mdx#page-evaluate), functions passed to an init script are exposed in every new document, so they survive navigations. Defaults to `false`, in which case functions are not serializable and are silently dropped. **Returns** - [Promise]<[Disposable]># @@ -842,7 +846,7 @@ await browserContext.setOffline(offline); Added in: v1.59browserContext.setStorageState -Clears the existing cookies, local storage and IndexedDB entries for all origins and sets the new storage state. +Clears the existing cookies, local storage, IndexedDB 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()](/api/class-credentials.mdx#credentials-install)), preventing all real authenticators from working in this context. **Usage** @@ -907,7 +911,7 @@ await context.setStorageState('state.json'); Added before v1.9browserContext.storageState -Returns storage state for this browser context, contains current cookies, local storage snapshot and IndexedDB snapshot. +Returns storage state for this browser context, contains current cookies, local storage snapshot, IndexedDB snapshot and virtual WebAuthn credentials. **Usage** @@ -918,6 +922,9 @@ await browserContext.storageState(options); **Arguments** - `options` [Object] *(optional)* + - `credentials` [boolean] *(optional)* Added in: v1.61# + + Set to `true` to include the context's virtual WebAuthn [browserContext.credentials](/api/class-browsercontext.mdx#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](/api/class-browser.mdx#browser-new-context-option-storage-state) option or [browserContext.setStorageState()](/api/class-browsercontext.mdx#browser-context-set-storage-state). Note that restoring the storage state that contains credentials will automatically install the virtual WebAuthn authenticator (see [credentials.install()](/api/class-credentials.mdx#credentials-install)), and prevent all real authenticators from working in this context. - `indexedDB` [boolean] *(optional)* Added in: v1.51# 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. @@ -1052,6 +1059,9 @@ const page = await pagePromise; - `predicate` [function] *(optional)*# Receives the event data and resolves to truthy value when the waiting should resolve. + - `signal` [AbortSignal] *(optional)* Added in: v1.62# + + 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()](/api/class-browsercontext.mdx#browser-context-set-default-timeout); pass `timeout: 0` to disable the timeout entirely. **Returns** - [Promise]<[Object]># @@ -1609,6 +1619,7 @@ await browserContext.setHTTPCredentials(httpCredentials); [TestCase]: /api/class-testcase.mdx "TestCase" [TestError]: /api/class-testerror.mdx "TestError" [TestResult]: /api/class-testresult.mdx "TestResult" +[TestRun]: /api/class-testrun.mdx "TestRun" [TestStep]: /api/class-teststep.mdx "TestStep" [Element]: https://developer.mozilla.org/en-US/docs/Web/API/element "Element" [EvaluationArgument]: /evaluating.mdx#evaluation-argument "EvaluationArgument" diff --git a/nodejs/versioned_docs/version-stable/api/class-browserserver.mdx b/nodejs/versioned_docs/version-stable/api/class-browserserver.mdx index 3a484b69bf..e84cbf8b05 100644 --- a/nodejs/versioned_docs/version-stable/api/class-browserserver.mdx +++ b/nodejs/versioned_docs/version-stable/api/class-browserserver.mdx @@ -168,6 +168,7 @@ browserServer.on('close', data => {}); [TestCase]: /api/class-testcase.mdx "TestCase" [TestError]: /api/class-testerror.mdx "TestError" [TestResult]: /api/class-testresult.mdx "TestResult" +[TestRun]: /api/class-testrun.mdx "TestRun" [TestStep]: /api/class-teststep.mdx "TestStep" [Element]: https://developer.mozilla.org/en-US/docs/Web/API/element "Element" [EvaluationArgument]: /evaluating.mdx#evaluation-argument "EvaluationArgument" diff --git a/nodejs/versioned_docs/version-stable/api/class-browsertype.mdx b/nodejs/versioned_docs/version-stable/api/class-browsertype.mdx index 61b9d47f3c..ec53f95c99 100644 --- a/nodejs/versioned_docs/version-stable/api/class-browsertype.mdx +++ b/nodejs/versioned_docs/version-stable/api/class-browsertype.mdx @@ -94,6 +94,10 @@ Connecting over the Chrome DevTools Protocol is only supported for Chromium-base This connection is significantly lower fidelity than the Playwright protocol connection via [browserType.connect()](/api/class-browsertype.mdx#browser-type-connect). If you are experiencing issues or attempting to use advanced functionality, you probably want to use [browserType.connect()](/api/class-browsertype.mdx#browser-type-connect). ::: +:::warning +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 @@ -518,6 +522,9 @@ await browserType.launchPersistentContext(userDataDir, options); - `fontSize` [number] *(optional)* Font size of the action title in pixels. Defaults to `24`. + - `cursor` "none" | "pointer" *(optional)* + + 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. If specified, enables visual annotations on interacted elements during video recording. @@ -786,6 +793,7 @@ browserType.name(); [TestCase]: /api/class-testcase.mdx "TestCase" [TestError]: /api/class-testerror.mdx "TestError" [TestResult]: /api/class-testresult.mdx "TestResult" +[TestRun]: /api/class-testrun.mdx "TestRun" [TestStep]: /api/class-teststep.mdx "TestStep" [Element]: https://developer.mozilla.org/en-US/docs/Web/API/element "Element" [EvaluationArgument]: /evaluating.mdx#evaluation-argument "EvaluationArgument" diff --git a/nodejs/versioned_docs/version-stable/api/class-cdpsession.mdx b/nodejs/versioned_docs/version-stable/api/class-cdpsession.mdx index a57f43485b..5f114a4883 100644 --- a/nodejs/versioned_docs/version-stable/api/class-cdpsession.mdx +++ b/nodejs/versioned_docs/version-stable/api/class-cdpsession.mdx @@ -100,8 +100,8 @@ Emitted for every CDP event received from the session. Allows subscribing to all **Usage** ```js -session.on('event', ({ name, params }) => { - console.log(`CDP event: ${name}`, params); +session.on('event', ({ method, params }) => { + console.log(`CDP event: ${method}`, params); }); ``` @@ -186,6 +186,7 @@ session.on('event', ({ name, params }) => { [TestCase]: /api/class-testcase.mdx "TestCase" [TestError]: /api/class-testerror.mdx "TestError" [TestResult]: /api/class-testresult.mdx "TestResult" +[TestRun]: /api/class-testrun.mdx "TestRun" [TestStep]: /api/class-teststep.mdx "TestStep" [Element]: https://developer.mozilla.org/en-US/docs/Web/API/element "Element" [EvaluationArgument]: /evaluating.mdx#evaluation-argument "EvaluationArgument" diff --git a/nodejs/versioned_docs/version-stable/api/class-clock.mdx b/nodejs/versioned_docs/version-stable/api/class-clock.mdx index c48e430f41..75df769d1b 100644 --- a/nodejs/versioned_docs/version-stable/api/class-clock.mdx +++ b/nodejs/versioned_docs/version-stable/api/class-clock.mdx @@ -270,6 +270,7 @@ await page.clock.setSystemTime('2020-02-02'); [TestCase]: /api/class-testcase.mdx "TestCase" [TestError]: /api/class-testerror.mdx "TestError" [TestResult]: /api/class-testresult.mdx "TestResult" +[TestRun]: /api/class-testrun.mdx "TestRun" [TestStep]: /api/class-teststep.mdx "TestStep" [Element]: https://developer.mozilla.org/en-US/docs/Web/API/element "Element" [EvaluationArgument]: /evaluating.mdx#evaluation-argument "EvaluationArgument" diff --git a/nodejs/versioned_docs/version-stable/api/class-consolemessage.mdx b/nodejs/versioned_docs/version-stable/api/class-consolemessage.mdx index 33c3214a27..eb1a0dcee3 100644 --- a/nodejs/versioned_docs/version-stable/api/class-consolemessage.mdx +++ b/nodejs/versioned_docs/version-stable/api/class-consolemessage.mdx @@ -236,6 +236,7 @@ consoleMessage.worker(); [TestCase]: /api/class-testcase.mdx "TestCase" [TestError]: /api/class-testerror.mdx "TestError" [TestResult]: /api/class-testresult.mdx "TestResult" +[TestRun]: /api/class-testrun.mdx "TestRun" [TestStep]: /api/class-teststep.mdx "TestStep" [Element]: https://developer.mozilla.org/en-US/docs/Web/API/element "Element" [EvaluationArgument]: /evaluating.mdx#evaluation-argument "EvaluationArgument" diff --git a/nodejs/versioned_docs/version-stable/api/class-coverage.mdx b/nodejs/versioned_docs/version-stable/api/class-coverage.mdx index 098a8c9a4a..5145aa4815 100644 --- a/nodejs/versioned_docs/version-stable/api/class-coverage.mdx +++ b/nodejs/versioned_docs/version-stable/api/class-coverage.mdx @@ -90,7 +90,12 @@ await coverage.startJSCoverage(options); Whether anonymous scripts generated by the page should be reported. Defaults to `false`. - `resetOnNavigation` [boolean] *(optional)*# - Whether to reset coverage on every navigation. Defaults to `true`. + :::warning[Discouraged] + Settings this to `false` may still reset on navigations. + ::: + + + Whether to reset coverage on every navigation. Defaults to `true`. Note that passing `false` does not guarantee that coverage persists through navigations, due to browser architecture limitations. **Returns** - [Promise]<[void]># @@ -254,6 +259,7 @@ await coverage.stopJSCoverage(); [TestCase]: /api/class-testcase.mdx "TestCase" [TestError]: /api/class-testerror.mdx "TestError" [TestResult]: /api/class-testresult.mdx "TestResult" +[TestRun]: /api/class-testrun.mdx "TestRun" [TestStep]: /api/class-teststep.mdx "TestStep" [Element]: https://developer.mozilla.org/en-US/docs/Web/API/element "Element" [EvaluationArgument]: /evaluating.mdx#evaluation-argument "EvaluationArgument" diff --git a/nodejs/versioned_docs/version-stable/api/class-credentials.mdx b/nodejs/versioned_docs/version-stable/api/class-credentials.mdx index d701138c76..8115885620 100644 --- a/nodejs/versioned_docs/version-stable/api/class-credentials.mdx +++ b/nodejs/versioned_docs/version-stable/api/class-credentials.mdx @@ -9,7 +9,7 @@ import HTMLCard from '@site/src/components/HTMLCard'; `Credentials` is a virtual WebAuthn authenticator scoped to a [BrowserContext]. It lets tests register passkeys and answer `navigator.credentials.create()` / `navigator.credentials.get()` ceremonies in the page, without a real authenticator or hardware security key. -There are two common ways to use it: +There are three common ways to use it: **Usage: seed a known credential** @@ -30,10 +30,10 @@ await page.goto('https://example.com/login'); // The page's navigator.credentials.get() is answered with the seeded passkey. ``` -**Usage: capture a passkey, then reuse it** +**Usage: capture a credential, then reuse it** ```js -// setup test: let the app register a passkey, then save it. +// setup test: let the app register a passkey, then save the storage state with it. const context = await browser.newContext(); await context.credentials.install(); @@ -58,6 +58,10 @@ await page.goto('https://example.com/login'); // navigator.credentials.get() resolves the captured passkey — already signed in. ``` +**Usage: save credentials in the storage state, restore later** + +See [authentication guide](../auth.mdx) for examples of using saving and resotring the storage state. + **Defaults** @@ -276,6 +280,7 @@ await credentials.install(); [TestCase]: /api/class-testcase.mdx "TestCase" [TestError]: /api/class-testerror.mdx "TestError" [TestResult]: /api/class-testresult.mdx "TestResult" +[TestRun]: /api/class-testrun.mdx "TestRun" [TestStep]: /api/class-teststep.mdx "TestStep" [Element]: https://developer.mozilla.org/en-US/docs/Web/API/element "Element" [EvaluationArgument]: /evaluating.mdx#evaluation-argument "EvaluationArgument" diff --git a/nodejs/versioned_docs/version-stable/api/class-debugger.mdx b/nodejs/versioned_docs/version-stable/api/class-debugger.mdx index 2972638c57..3d5bd7e669 100644 --- a/nodejs/versioned_docs/version-stable/api/class-debugger.mdx +++ b/nodejs/versioned_docs/version-stable/api/class-debugger.mdx @@ -215,6 +215,7 @@ debugger.on('pausedstatechanged', data => {}); [TestCase]: /api/class-testcase.mdx "TestCase" [TestError]: /api/class-testerror.mdx "TestError" [TestResult]: /api/class-testresult.mdx "TestResult" +[TestRun]: /api/class-testrun.mdx "TestRun" [TestStep]: /api/class-teststep.mdx "TestStep" [Element]: https://developer.mozilla.org/en-US/docs/Web/API/element "Element" [EvaluationArgument]: /evaluating.mdx#evaluation-argument "EvaluationArgument" diff --git a/nodejs/versioned_docs/version-stable/api/class-dialog.mdx b/nodejs/versioned_docs/version-stable/api/class-dialog.mdx index ee9403dead..98931f6a5b 100644 --- a/nodejs/versioned_docs/version-stable/api/class-dialog.mdx +++ b/nodejs/versioned_docs/version-stable/api/class-dialog.mdx @@ -213,6 +213,7 @@ dialog.type(); [TestCase]: /api/class-testcase.mdx "TestCase" [TestError]: /api/class-testerror.mdx "TestError" [TestResult]: /api/class-testresult.mdx "TestResult" +[TestRun]: /api/class-testrun.mdx "TestRun" [TestStep]: /api/class-teststep.mdx "TestStep" [Element]: https://developer.mozilla.org/en-US/docs/Web/API/element "Element" [EvaluationArgument]: /evaluating.mdx#evaluation-argument "EvaluationArgument" diff --git a/nodejs/versioned_docs/version-stable/api/class-disposable.mdx b/nodejs/versioned_docs/version-stable/api/class-disposable.mdx index 8f229921e1..5dc11c5f69 100644 --- a/nodejs/versioned_docs/version-stable/api/class-disposable.mdx +++ b/nodejs/versioned_docs/version-stable/api/class-disposable.mdx @@ -101,6 +101,7 @@ await disposable.dispose(); [TestCase]: /api/class-testcase.mdx "TestCase" [TestError]: /api/class-testerror.mdx "TestError" [TestResult]: /api/class-testresult.mdx "TestResult" +[TestRun]: /api/class-testrun.mdx "TestRun" [TestStep]: /api/class-teststep.mdx "TestStep" [Element]: https://developer.mozilla.org/en-US/docs/Web/API/element "Element" [EvaluationArgument]: /evaluating.mdx#evaluation-argument "EvaluationArgument" diff --git a/nodejs/versioned_docs/version-stable/api/class-download.mdx b/nodejs/versioned_docs/version-stable/api/class-download.mdx index 47de637650..7c0bf5026f 100644 --- a/nodejs/versioned_docs/version-stable/api/class-download.mdx +++ b/nodejs/versioned_docs/version-stable/api/class-download.mdx @@ -263,6 +263,7 @@ download.url(); [TestCase]: /api/class-testcase.mdx "TestCase" [TestError]: /api/class-testerror.mdx "TestError" [TestResult]: /api/class-testresult.mdx "TestResult" +[TestRun]: /api/class-testrun.mdx "TestRun" [TestStep]: /api/class-teststep.mdx "TestStep" [Element]: https://developer.mozilla.org/en-US/docs/Web/API/element "Element" [EvaluationArgument]: /evaluating.mdx#evaluation-argument "EvaluationArgument" diff --git a/nodejs/versioned_docs/version-stable/api/class-electron.mdx b/nodejs/versioned_docs/version-stable/api/class-electron.mdx index 39620f84fe..6dcb32e52b 100644 --- a/nodejs/versioned_docs/version-stable/api/class-electron.mdx +++ b/nodejs/versioned_docs/version-stable/api/class-electron.mdx @@ -203,6 +203,9 @@ await electron.launch(options); - `fontSize` [number] *(optional)* Font size of the action title in pixels. Defaults to `24`. + - `cursor` "none" | "pointer" *(optional)* + + 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. If specified, enables visual annotations on interacted elements during video recording. @@ -292,6 +295,7 @@ await electron.launch(options); [TestCase]: /api/class-testcase.mdx "TestCase" [TestError]: /api/class-testerror.mdx "TestError" [TestResult]: /api/class-testresult.mdx "TestResult" +[TestRun]: /api/class-testrun.mdx "TestRun" [TestStep]: /api/class-teststep.mdx "TestStep" [Element]: https://developer.mozilla.org/en-US/docs/Web/API/element "Element" [EvaluationArgument]: /evaluating.mdx#evaluation-argument "EvaluationArgument" diff --git a/nodejs/versioned_docs/version-stable/api/class-electronapplication.mdx b/nodejs/versioned_docs/version-stable/api/class-electronapplication.mdx index ced01b78ec..f287300060 100644 --- a/nodejs/versioned_docs/version-stable/api/class-electronapplication.mdx +++ b/nodejs/versioned_docs/version-stable/api/class-electronapplication.mdx @@ -382,6 +382,7 @@ electronApplication.on('window', data => {}); [TestCase]: /api/class-testcase.mdx "TestCase" [TestError]: /api/class-testerror.mdx "TestError" [TestResult]: /api/class-testresult.mdx "TestResult" +[TestRun]: /api/class-testrun.mdx "TestRun" [TestStep]: /api/class-teststep.mdx "TestStep" [Element]: https://developer.mozilla.org/en-US/docs/Web/API/element "Element" [EvaluationArgument]: /evaluating.mdx#evaluation-argument "EvaluationArgument" diff --git a/nodejs/versioned_docs/version-stable/api/class-elementhandle.mdx b/nodejs/versioned_docs/version-stable/api/class-elementhandle.mdx index d64834f93a..92f27ac393 100644 --- a/nodejs/versioned_docs/version-stable/api/class-elementhandle.mdx +++ b/nodejs/versioned_docs/version-stable/api/class-elementhandle.mdx @@ -147,6 +147,9 @@ await elementHandle.waitForElementState(state, options); A state to wait for, see below for more details. - `options` [Object] *(optional)* + - `signal` [AbortSignal] *(optional)* Added in: v1.62# + + 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()](/api/class-browsercontext.mdx#browser-context-set-default-timeout) or [page.setDefaultTimeout()](/api/class-page.mdx#page-set-default-timeout); pass `timeout: 0` to disable the timeout entirely. - `timeout` [number] *(optional)*# 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()](/api/class-browsercontext.mdx#browser-context-set-default-timeout) or [page.setDefaultTimeout()](/api/class-page.mdx#page-set-default-timeout) methods. @@ -356,6 +359,12 @@ await elementHandle.check(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. + - `scroll` "auto" | "none" *(optional)* Added in: v1.62# + + 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. + - `signal` [AbortSignal] *(optional)* Added in: v1.62# + + 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()](/api/class-browsercontext.mdx#browser-context-set-default-timeout) or [page.setDefaultTimeout()](/api/class-page.mdx#page-set-default-timeout); pass `timeout: 0` to disable the timeout entirely. - `timeout` [number] *(optional)*# 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()](/api/class-browsercontext.mdx#browser-context-set-default-timeout) or [page.setDefaultTimeout()](/api/class-page.mdx#page-set-default-timeout) methods. @@ -429,6 +438,12 @@ await elementHandle.click(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. + - `scroll` "auto" | "none" *(optional)* Added in: v1.62# + + 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. + - `signal` [AbortSignal] *(optional)* Added in: v1.62# + + 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()](/api/class-browsercontext.mdx#browser-context-set-default-timeout) or [page.setDefaultTimeout()](/api/class-page.mdx#page-set-default-timeout); pass `timeout: 0` to disable the timeout entirely. - `steps` [number] *(optional)* Added in: v1.57# 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. @@ -506,6 +521,12 @@ await elementHandle.dblclick(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. + - `scroll` "auto" | "none" *(optional)* Added in: v1.62# + + 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. + - `signal` [AbortSignal] *(optional)* Added in: v1.62# + + 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()](/api/class-browsercontext.mdx#browser-context-set-default-timeout) or [page.setDefaultTimeout()](/api/class-page.mdx#page-set-default-timeout); pass `timeout: 0` to disable the timeout entirely. - `steps` [number] *(optional)* Added in: v1.57# 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. @@ -615,6 +636,9 @@ await elementHandle.fill(value, options); This option has no effect. + - `signal` [AbortSignal] *(optional)* Added in: v1.62# + + 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()](/api/class-browsercontext.mdx#browser-context-set-default-timeout) or [page.setDefaultTimeout()](/api/class-page.mdx#page-set-default-timeout); pass `timeout: 0` to disable the timeout entirely. - `timeout` [number] *(optional)*# 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()](/api/class-browsercontext.mdx#browser-context-set-default-timeout) or [page.setDefaultTimeout()](/api/class-page.mdx#page-set-default-timeout) methods. @@ -728,6 +752,12 @@ await elementHandle.hover(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. + - `scroll` "auto" | "none" *(optional)* Added in: v1.62# + + 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. + - `signal` [AbortSignal] *(optional)* Added in: v1.62# + + 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()](/api/class-browsercontext.mdx#browser-context-set-default-timeout) or [page.setDefaultTimeout()](/api/class-page.mdx#page-set-default-timeout); pass `timeout: 0` to disable the timeout entirely. - `timeout` [number] *(optional)*# 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()](/api/class-browsercontext.mdx#browser-context-set-default-timeout) or [page.setDefaultTimeout()](/api/class-page.mdx#page-set-default-timeout) methods. @@ -814,7 +844,10 @@ await elementHandle.inputValue(options); - `options` [Object] *(optional)* - `timeout` [number] *(optional)*# - 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()](/api/class-browsercontext.mdx#browser-context-set-default-timeout) or [page.setDefaultTimeout()](/api/class-page.mdx#page-set-default-timeout) methods. + :::warning[Deprecated] + This option is ignored. The value is returned immediately. + ::: + **Returns** - [Promise]<[string]># @@ -1013,6 +1046,9 @@ await elementHandle.press(key, options); 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`. + - `signal` [AbortSignal] *(optional)* Added in: v1.62# + + 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()](/api/class-browsercontext.mdx#browser-context-set-default-timeout) or [page.setDefaultTimeout()](/api/class-page.mdx#page-set-default-timeout); pass `timeout: 0` to disable the timeout entirely. - `timeout` [number] *(optional)*# 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()](/api/class-browsercontext.mdx#browser-context-set-default-timeout) or [page.setDefaultTimeout()](/api/class-page.mdx#page-set-default-timeout) methods. @@ -1072,19 +1108,22 @@ await elementHandle.screenshot(options); The file path to save the image to. The screenshot type will be inferred from file extension. If [path](/api/class-elementhandle.mdx#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. - `quality` [number] *(optional)*# - The quality of the image, between 0-100. Not applicable to `png` images. + 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. - `scale` "css" | "device" *(optional)*# 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"`. + - `signal` [AbortSignal] *(optional)* Added in: v1.62# + + 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()](/api/class-browsercontext.mdx#browser-context-set-default-timeout) or [page.setDefaultTimeout()](/api/class-page.mdx#page-set-default-timeout); pass `timeout: 0` to disable the timeout entirely. - `style` [string] *(optional)* Added in: v1.41# 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. - `timeout` [number] *(optional)*# 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()](/api/class-browsercontext.mdx#browser-context-set-default-timeout) or [page.setDefaultTimeout()](/api/class-page.mdx#page-set-default-timeout) methods. - - `type` "png" | "jpeg" *(optional)*# + - `type` "png" | "jpeg" | "webp" *(optional)*# Specify screenshot type, defaults to `png`. @@ -1119,6 +1158,9 @@ await elementHandle.scrollIntoViewIfNeeded(options); **Arguments** - `options` [Object] *(optional)* + - `signal` [AbortSignal] *(optional)* Added in: v1.62# + + 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()](/api/class-browsercontext.mdx#browser-context-set-default-timeout) or [page.setDefaultTimeout()](/api/class-page.mdx#page-set-default-timeout); pass `timeout: 0` to disable the timeout entirely. - `timeout` [number] *(optional)*# 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()](/api/class-browsercontext.mdx#browser-context-set-default-timeout) or [page.setDefaultTimeout()](/api/class-page.mdx#page-set-default-timeout) methods. @@ -1185,6 +1227,9 @@ handle.selectOption(['red', 'green', 'blue']); This option has no effect. + - `signal` [AbortSignal] *(optional)* Added in: v1.62# + + 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()](/api/class-browsercontext.mdx#browser-context-set-default-timeout) or [page.setDefaultTimeout()](/api/class-page.mdx#page-set-default-timeout); pass `timeout: 0` to disable the timeout entirely. - `timeout` [number] *(optional)*# 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()](/api/class-browsercontext.mdx#browser-context-set-default-timeout) or [page.setDefaultTimeout()](/api/class-page.mdx#page-set-default-timeout) methods. @@ -1221,6 +1266,9 @@ await elementHandle.selectText(options); - `force` [boolean] *(optional)* Added in: v1.13# Whether to bypass the [actionability](../actionability.mdx) checks. Defaults to `false`. + - `signal` [AbortSignal] *(optional)* Added in: v1.62# + + 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()](/api/class-browsercontext.mdx#browser-context-set-default-timeout) or [page.setDefaultTimeout()](/api/class-page.mdx#page-set-default-timeout); pass `timeout: 0` to disable the timeout entirely. - `timeout` [number] *(optional)*# 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()](/api/class-browsercontext.mdx#browser-context-set-default-timeout) or [page.setDefaultTimeout()](/api/class-page.mdx#page-set-default-timeout) methods. @@ -1282,6 +1330,12 @@ await elementHandle.setChecked(checked, 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. + - `scroll` "auto" | "none" *(optional)* Added in: v1.62# + + 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. + - `signal` [AbortSignal] *(optional)* Added in: v1.62# + + 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()](/api/class-browsercontext.mdx#browser-context-set-default-timeout) or [page.setDefaultTimeout()](/api/class-page.mdx#page-set-default-timeout); pass `timeout: 0` to disable the timeout entirely. - `timeout` [number] *(optional)*# 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()](/api/class-browsercontext.mdx#browser-context-set-default-timeout) or [page.setDefaultTimeout()](/api/class-page.mdx#page-set-default-timeout) methods. @@ -1336,6 +1390,9 @@ await elementHandle.setInputFiles(files, options); This option has no effect. + - `signal` [AbortSignal] *(optional)* Added in: v1.62# + + 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()](/api/class-browsercontext.mdx#browser-context-set-default-timeout) or [page.setDefaultTimeout()](/api/class-page.mdx#page-set-default-timeout); pass `timeout: 0` to disable the timeout entirely. - `timeout` [number] *(optional)*# 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()](/api/class-browsercontext.mdx#browser-context-set-default-timeout) or [page.setDefaultTimeout()](/api/class-page.mdx#page-set-default-timeout) methods. @@ -1401,6 +1458,12 @@ await elementHandle.tap(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. + - `scroll` "auto" | "none" *(optional)* Added in: v1.62# + + 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. + - `signal` [AbortSignal] *(optional)* Added in: v1.62# + + 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()](/api/class-browsercontext.mdx#browser-context-set-default-timeout) or [page.setDefaultTimeout()](/api/class-page.mdx#page-set-default-timeout); pass `timeout: 0` to disable the timeout entirely. - `timeout` [number] *(optional)*# 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()](/api/class-browsercontext.mdx#browser-context-set-default-timeout) or [page.setDefaultTimeout()](/api/class-page.mdx#page-set-default-timeout) methods. @@ -1470,6 +1533,9 @@ To press a special key, like `Control` or `ArrowDown`, use [elementHandle.press( This option has no effect. + - `signal` [AbortSignal] *(optional)* Added in: v1.62# + + 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()](/api/class-browsercontext.mdx#browser-context-set-default-timeout) or [page.setDefaultTimeout()](/api/class-page.mdx#page-set-default-timeout); pass `timeout: 0` to disable the timeout entirely. - `timeout` [number] *(optional)*# 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()](/api/class-browsercontext.mdx#browser-context-set-default-timeout) or [page.setDefaultTimeout()](/api/class-page.mdx#page-set-default-timeout) methods. @@ -1529,6 +1595,12 @@ await elementHandle.uncheck(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. + - `scroll` "auto" | "none" *(optional)* Added in: v1.62# + + 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. + - `signal` [AbortSignal] *(optional)* Added in: v1.62# + + 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()](/api/class-browsercontext.mdx#browser-context-set-default-timeout) or [page.setDefaultTimeout()](/api/class-page.mdx#page-set-default-timeout); pass `timeout: 0` to disable the timeout entirely. - `timeout` [number] *(optional)*# 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()](/api/class-browsercontext.mdx#browser-context-set-default-timeout) or [page.setDefaultTimeout()](/api/class-page.mdx#page-set-default-timeout) methods. @@ -1574,6 +1646,9 @@ This method does not work across navigations, use [page.waitForSelector()](/api/ A selector to query for. - `options` [Object] *(optional)* + - `signal` [AbortSignal] *(optional)* Added in: v1.62# + + 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()](/api/class-browsercontext.mdx#browser-context-set-default-timeout) or [page.setDefaultTimeout()](/api/class-page.mdx#page-set-default-timeout); pass `timeout: 0` to disable the timeout entirely. - `state` "attached" | "detached" | "visible" | "hidden" *(optional)*# Defaults to `'visible'`. Can be either: @@ -1663,6 +1738,7 @@ This method does not work across navigations, use [page.waitForSelector()](/api/ [TestCase]: /api/class-testcase.mdx "TestCase" [TestError]: /api/class-testerror.mdx "TestError" [TestResult]: /api/class-testresult.mdx "TestResult" +[TestRun]: /api/class-testrun.mdx "TestRun" [TestStep]: /api/class-teststep.mdx "TestStep" [Element]: https://developer.mozilla.org/en-US/docs/Web/API/element "Element" [EvaluationArgument]: /evaluating.mdx#evaluation-argument "EvaluationArgument" diff --git a/nodejs/versioned_docs/version-stable/api/class-filechooser.mdx b/nodejs/versioned_docs/version-stable/api/class-filechooser.mdx index a1f5accb63..00f7b30c7b 100644 --- a/nodejs/versioned_docs/version-stable/api/class-filechooser.mdx +++ b/nodejs/versioned_docs/version-stable/api/class-filechooser.mdx @@ -106,6 +106,9 @@ await fileChooser.setFiles(files, options); This option has no effect. + - `signal` [AbortSignal] *(optional)* Added in: v1.62# + + 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()](/api/class-browsercontext.mdx#browser-context-set-default-timeout) or [page.setDefaultTimeout()](/api/class-page.mdx#page-set-default-timeout); pass `timeout: 0` to disable the timeout entirely. - `timeout` [number] *(optional)*# 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()](/api/class-browsercontext.mdx#browser-context-set-default-timeout) or [page.setDefaultTimeout()](/api/class-page.mdx#page-set-default-timeout) methods. @@ -185,6 +188,7 @@ await fileChooser.setFiles(files, options); [TestCase]: /api/class-testcase.mdx "TestCase" [TestError]: /api/class-testerror.mdx "TestError" [TestResult]: /api/class-testresult.mdx "TestResult" +[TestRun]: /api/class-testrun.mdx "TestRun" [TestStep]: /api/class-teststep.mdx "TestStep" [Element]: https://developer.mozilla.org/en-US/docs/Web/API/element "Element" [EvaluationArgument]: /evaluating.mdx#evaluation-argument "EvaluationArgument" diff --git a/nodejs/versioned_docs/version-stable/api/class-fixtures.mdx b/nodejs/versioned_docs/version-stable/api/class-fixtures.mdx index d12be27a16..85681cd365 100644 --- a/nodejs/versioned_docs/version-stable/api/class-fixtures.mdx +++ b/nodejs/versioned_docs/version-stable/api/class-fixtures.mdx @@ -24,6 +24,54 @@ Given the test above, Playwright Test will set up the `page` fixture before runn 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](/api/class-fixtures.mdx#fixtures-browser), [fixtures.context](/api/class-fixtures.mdx#fixtures-context) and [fixtures.page](/api/class-fixtures.mdx#fixtures-page). +--- + +## Methods + +### mount {/* #fixtures-mount */} + +Added in: v1.62fixtures.mount + +Mounts a component story and returns a [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](/api/class-testoptions.mdx#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()](/api/class-fixtures.mdx#fixtures-mount) navigates to [testOptions.baseURL](/api/class-testoptions.mdx#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('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. + +**Arguments** +- `storyId` [string]# + + 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'`. +- `props` [Object] *(optional)*# + + Optional plain, serializable props passed to the story. + +**Returns** +- [Locator]# + --- ## Properties @@ -218,6 +266,7 @@ test('basic test', async ({ request }) => { [TestCase]: /api/class-testcase.mdx "TestCase" [TestError]: /api/class-testerror.mdx "TestError" [TestResult]: /api/class-testresult.mdx "TestResult" +[TestRun]: /api/class-testrun.mdx "TestRun" [TestStep]: /api/class-teststep.mdx "TestStep" [Element]: https://developer.mozilla.org/en-US/docs/Web/API/element "Element" [EvaluationArgument]: /evaluating.mdx#evaluation-argument "EvaluationArgument" diff --git a/nodejs/versioned_docs/version-stable/api/class-frame.mdx b/nodejs/versioned_docs/version-stable/api/class-frame.mdx index 8f17bd48a5..7484809317 100644 --- a/nodejs/versioned_docs/version-stable/api/class-frame.mdx +++ b/nodejs/versioned_docs/version-stable/api/class-frame.mdx @@ -168,6 +168,12 @@ await frame.dragAndDrop(source, target, options); This option has no effect. + - `scroll` "auto" | "none" *(optional)* Added in: v1.62# + + 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. + - `signal` [AbortSignal] *(optional)* Added in: v1.62# + + 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()](/api/class-browsercontext.mdx#browser-context-set-default-timeout) or [page.setDefaultTimeout()](/api/class-page.mdx#page-set-default-timeout); pass `timeout: 0` to disable the timeout entirely. - `sourcePosition` [Object] *(optional)* Added in: v1.14# - `x` [number] @@ -244,6 +250,10 @@ await bodyHandle.dispose(); - `arg` [EvaluationArgument] *(optional)*# Optional argument to pass to [pageFunction](/api/class-frame.mdx#frame-evaluate-option-expression). +- `options` [Object] *(optional)* + - `exposeFunctions` [boolean] *(optional)* Added in: v1.62# + + When set to `true`, functions passed inside [arg](/api/class-frame.mdx#frame-evaluate-option-arg) are exposed in the page and can be called from the page function. Calling one returns a [Promise] of its result. Under the hood, each function is exposed via [page.exposeFunction()](/api/class-page.mdx#page-expose-function), so it is technically accessible from all frames and worlds of the page. Exposed functions are cleared upon the top-level navigation. Defaults to `false`, in which case functions are not serializable and passing one throws an error. **Returns** - [Promise]<[Serializable]># @@ -291,6 +301,10 @@ await resultHandle.dispose(); - `arg` [EvaluationArgument] *(optional)*# Optional argument to pass to [pageFunction](/api/class-frame.mdx#frame-evaluate-handle-option-expression). +- `options` [Object] *(optional)* + - `exposeFunctions` [boolean] *(optional)* Added in: v1.62# + + When set to `true`, functions passed inside [arg](/api/class-frame.mdx#frame-evaluate-handle-option-arg) are exposed in the page and can be called from the page function. Calling one returns a [Promise] of its result. Under the hood, each function is exposed via [page.exposeFunction()](/api/class-page.mdx#page-expose-function), so it is technically accessible from all frames and worlds of the page. Exposed functions are cleared upon the top-level navigation. Defaults to `false`, in which case functions are not serializable and passing one throws an error. **Returns** - [Promise]<[JSHandle]># @@ -720,6 +734,9 @@ await frame.goto(url, options); - `referer` [string] *(optional)*# Referer header value. If provided it will take preference over the referer header value set by [page.setExtraHTTPHeaders()](/api/class-page.mdx#page-set-extra-http-headers). + - `signal` [AbortSignal] *(optional)* Added in: v1.62# + + 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()](/api/class-browsercontext.mdx#browser-context-set-default-timeout) or [page.setDefaultTimeout()](/api/class-page.mdx#page-set-default-timeout); pass `timeout: 0` to disable the timeout entirely. - `timeout` [number] *(optional)*# 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()](/api/class-browsercontext.mdx#browser-context-set-default-navigation-timeout), [browserContext.setDefaultTimeout()](/api/class-browsercontext.mdx#browser-context-set-default-timeout), [page.setDefaultNavigationTimeout()](/api/class-page.mdx#page-set-default-navigation-timeout) or [page.setDefaultTimeout()](/api/class-page.mdx#page-set-default-timeout) methods. @@ -771,6 +788,9 @@ await frame.isEnabled(selector, options); A selector to search for an element. If there are multiple elements satisfying the selector, the first will be used. - `options` [Object] *(optional)* + - `signal` [AbortSignal] *(optional)* Added in: v1.62# + + 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()](/api/class-browsercontext.mdx#browser-context-set-default-timeout) or [page.setDefaultTimeout()](/api/class-page.mdx#page-set-default-timeout); pass `timeout: 0` to disable the timeout entirely. - `strict` [boolean] *(optional)* Added in: v1.14# 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. @@ -905,6 +925,9 @@ await frame.setContent(html, options); HTML markup to assign to the page. - `options` [Object] *(optional)* + - `signal` [AbortSignal] *(optional)* Added in: v1.62# + + 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()](/api/class-browsercontext.mdx#browser-context-set-default-timeout) or [page.setDefaultTimeout()](/api/class-page.mdx#page-set-default-timeout); pass `timeout: 0` to disable the timeout entirely. - `timeout` [number] *(optional)*# 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()](/api/class-browsercontext.mdx#browser-context-set-default-navigation-timeout), [browserContext.setDefaultTimeout()](/api/class-browsercontext.mdx#browser-context-set-default-timeout), [page.setDefaultNavigationTimeout()](/api/class-page.mdx#page-set-default-navigation-timeout) or [page.setDefaultTimeout()](/api/class-page.mdx#page-set-default-timeout) methods. @@ -996,6 +1019,9 @@ await frame.waitForFunction(selector => !!document.querySelector(selector), sele - `polling` [number] | "raf" *(optional)*# If [polling](/api/class-frame.mdx#frame-wait-for-function-option-polling) is `'raf'`, then [pageFunction](/api/class-frame.mdx#frame-wait-for-function-option-expression) is constantly executed in `requestAnimationFrame` callback. If [polling](/api/class-frame.mdx#frame-wait-for-function-option-polling) is a number, then it is treated as an interval in milliseconds at which the function would be executed. Defaults to `raf`. + - `signal` [AbortSignal] *(optional)* Added in: v1.62# + + 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()](/api/class-browsercontext.mdx#browser-context-set-default-timeout) or [page.setDefaultTimeout()](/api/class-page.mdx#page-set-default-timeout); pass `timeout: 0` to disable the timeout entirely. - `timeout` [number] *(optional)*# Maximum time to wait for 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()](/api/class-browsercontext.mdx#browser-context-set-default-timeout) or [page.setDefaultTimeout()](/api/class-page.mdx#page-set-default-timeout) methods. @@ -1033,6 +1059,9 @@ await frame.waitForLoadState(); // Waits for 'load' state by default. * `'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. - `options` [Object] *(optional)* + - `signal` [AbortSignal] *(optional)* Added in: v1.62# + + 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()](/api/class-browsercontext.mdx#browser-context-set-default-timeout); pass `timeout: 0` to disable the timeout entirely. - `timeout` [number] *(optional)*# 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()](/api/class-browsercontext.mdx#browser-context-set-default-navigation-timeout), [browserContext.setDefaultTimeout()](/api/class-browsercontext.mdx#browser-context-set-default-timeout), [page.setDefaultNavigationTimeout()](/api/class-page.mdx#page-set-default-navigation-timeout) or [page.setDefaultTimeout()](/api/class-page.mdx#page-set-default-timeout) methods. @@ -1060,6 +1089,9 @@ await frame.waitForURL('**/target.html'); 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. - `options` [Object] *(optional)* + - `signal` [AbortSignal] *(optional)* Added in: v1.62# + + 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()](/api/class-browsercontext.mdx#browser-context-set-default-timeout); pass `timeout: 0` to disable the timeout entirely. - `timeout` [number] *(optional)*# 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()](/api/class-browsercontext.mdx#browser-context-set-default-navigation-timeout), [browserContext.setDefaultTimeout()](/api/class-browsercontext.mdx#browser-context-set-default-timeout), [page.setDefaultNavigationTimeout()](/api/class-page.mdx#page-set-default-navigation-timeout) or [page.setDefaultTimeout()](/api/class-page.mdx#page-set-default-timeout) methods. @@ -1291,6 +1323,12 @@ await frame.check(selector, 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. + - `scroll` "auto" | "none" *(optional)* Added in: v1.62# + + 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. + - `signal` [AbortSignal] *(optional)* Added in: v1.62# + + 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()](/api/class-browsercontext.mdx#browser-context-set-default-timeout) or [page.setDefaultTimeout()](/api/class-page.mdx#page-set-default-timeout); pass `timeout: 0` to disable the timeout entirely. - `strict` [boolean] *(optional)* Added in: v1.14# 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. @@ -1369,6 +1407,12 @@ await frame.click(selector, 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. + - `scroll` "auto" | "none" *(optional)* Added in: v1.62# + + 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. + - `signal` [AbortSignal] *(optional)* Added in: v1.62# + + 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()](/api/class-browsercontext.mdx#browser-context-set-default-timeout) or [page.setDefaultTimeout()](/api/class-page.mdx#page-set-default-timeout); pass `timeout: 0` to disable the timeout entirely. - `strict` [boolean] *(optional)* Added in: v1.14# 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. @@ -1448,6 +1492,12 @@ await frame.dblclick(selector, 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. + - `scroll` "auto" | "none" *(optional)* Added in: v1.62# + + 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. + - `signal` [AbortSignal] *(optional)* Added in: v1.62# + + 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()](/api/class-browsercontext.mdx#browser-context-set-default-timeout) or [page.setDefaultTimeout()](/api/class-page.mdx#page-set-default-timeout); pass `timeout: 0` to disable the timeout entirely. - `strict` [boolean] *(optional)* Added in: v1.14# 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. @@ -1515,6 +1565,9 @@ await frame.dispatchEvent('#source', 'dragstart', { dataTransfer }); Optional event-specific initialization properties. - `options` [Object] *(optional)* + - `signal` [AbortSignal] *(optional)* Added in: v1.62# + + 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()](/api/class-browsercontext.mdx#browser-context-set-default-timeout) or [page.setDefaultTimeout()](/api/class-page.mdx#page-set-default-timeout); pass `timeout: 0` to disable the timeout entirely. - `strict` [boolean] *(optional)* Added in: v1.14# 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. @@ -1570,6 +1623,9 @@ await frame.fill(selector, value, options); This option has no effect. + - `signal` [AbortSignal] *(optional)* Added in: v1.62# + + 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()](/api/class-browsercontext.mdx#browser-context-set-default-timeout) or [page.setDefaultTimeout()](/api/class-page.mdx#page-set-default-timeout); pass `timeout: 0` to disable the timeout entirely. - `strict` [boolean] *(optional)* Added in: v1.14# 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. @@ -1607,6 +1663,9 @@ await frame.focus(selector, options); A selector to search for an element. If there are multiple elements satisfying the selector, the first will be used. - `options` [Object] *(optional)* + - `signal` [AbortSignal] *(optional)* Added in: v1.62# + + 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()](/api/class-browsercontext.mdx#browser-context-set-default-timeout) or [page.setDefaultTimeout()](/api/class-page.mdx#page-set-default-timeout); pass `timeout: 0` to disable the timeout entirely. - `strict` [boolean] *(optional)* Added in: v1.14# 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. @@ -1647,6 +1706,9 @@ await frame.getAttribute(selector, name, options); Attribute name to get the value for. - `options` [Object] *(optional)* + - `signal` [AbortSignal] *(optional)* Added in: v1.62# + + 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()](/api/class-browsercontext.mdx#browser-context-set-default-timeout) or [page.setDefaultTimeout()](/api/class-page.mdx#page-set-default-timeout); pass `timeout: 0` to disable the timeout entirely. - `strict` [boolean] *(optional)* Added in: v1.14# 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. @@ -1712,6 +1774,12 @@ await frame.hover(selector, 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. + - `scroll` "auto" | "none" *(optional)* Added in: v1.62# + + 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. + - `signal` [AbortSignal] *(optional)* Added in: v1.62# + + 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()](/api/class-browsercontext.mdx#browser-context-set-default-timeout) or [page.setDefaultTimeout()](/api/class-page.mdx#page-set-default-timeout); pass `timeout: 0` to disable the timeout entirely. - `strict` [boolean] *(optional)* Added in: v1.14# 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. @@ -1752,6 +1820,9 @@ await frame.innerHTML(selector, options); A selector to search for an element. If there are multiple elements satisfying the selector, the first will be used. - `options` [Object] *(optional)* + - `signal` [AbortSignal] *(optional)* Added in: v1.62# + + 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()](/api/class-browsercontext.mdx#browser-context-set-default-timeout) or [page.setDefaultTimeout()](/api/class-page.mdx#page-set-default-timeout); pass `timeout: 0` to disable the timeout entirely. - `strict` [boolean] *(optional)* Added in: v1.14# 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. @@ -1789,6 +1860,9 @@ await frame.innerText(selector, options); A selector to search for an element. If there are multiple elements satisfying the selector, the first will be used. - `options` [Object] *(optional)* + - `signal` [AbortSignal] *(optional)* Added in: v1.62# + + 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()](/api/class-browsercontext.mdx#browser-context-set-default-timeout) or [page.setDefaultTimeout()](/api/class-page.mdx#page-set-default-timeout); pass `timeout: 0` to disable the timeout entirely. - `strict` [boolean] *(optional)* Added in: v1.14# 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. @@ -1828,6 +1902,9 @@ await frame.inputValue(selector, options); A selector to search for an element. If there are multiple elements satisfying the selector, the first will be used. - `options` [Object] *(optional)* + - `signal` [AbortSignal] *(optional)* Added in: v1.62# + + 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()](/api/class-browsercontext.mdx#browser-context-set-default-timeout) or [page.setDefaultTimeout()](/api/class-page.mdx#page-set-default-timeout); pass `timeout: 0` to disable the timeout entirely. - `strict` [boolean] *(optional)* Added in: v1.14# 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. @@ -1865,6 +1942,9 @@ await frame.isChecked(selector, options); A selector to search for an element. If there are multiple elements satisfying the selector, the first will be used. - `options` [Object] *(optional)* + - `signal` [AbortSignal] *(optional)* Added in: v1.62# + + 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()](/api/class-browsercontext.mdx#browser-context-set-default-timeout) or [page.setDefaultTimeout()](/api/class-page.mdx#page-set-default-timeout); pass `timeout: 0` to disable the timeout entirely. - `strict` [boolean] *(optional)* Added in: v1.14# 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. @@ -1902,6 +1982,9 @@ await frame.isDisabled(selector, options); A selector to search for an element. If there are multiple elements satisfying the selector, the first will be used. - `options` [Object] *(optional)* + - `signal` [AbortSignal] *(optional)* Added in: v1.62# + + 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()](/api/class-browsercontext.mdx#browser-context-set-default-timeout) or [page.setDefaultTimeout()](/api/class-page.mdx#page-set-default-timeout); pass `timeout: 0` to disable the timeout entirely. - `strict` [boolean] *(optional)* Added in: v1.14# 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. @@ -1939,6 +2022,9 @@ await frame.isEditable(selector, options); A selector to search for an element. If there are multiple elements satisfying the selector, the first will be used. - `options` [Object] *(optional)* + - `signal` [AbortSignal] *(optional)* Added in: v1.62# + + 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()](/api/class-browsercontext.mdx#browser-context-set-default-timeout) or [page.setDefaultTimeout()](/api/class-page.mdx#page-set-default-timeout); pass `timeout: 0` to disable the timeout entirely. - `strict` [boolean] *(optional)* Added in: v1.14# 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. @@ -2080,6 +2166,9 @@ await frame.press(selector, key, options); 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`. + - `signal` [AbortSignal] *(optional)* Added in: v1.62# + + 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()](/api/class-browsercontext.mdx#browser-context-set-default-timeout) or [page.setDefaultTimeout()](/api/class-page.mdx#page-set-default-timeout); pass `timeout: 0` to disable the timeout entirely. - `strict` [boolean] *(optional)* Added in: v1.14# 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. @@ -2152,6 +2241,9 @@ frame.selectOption('select#colors', 'red', 'green', 'blue'); This option has no effect. + - `signal` [AbortSignal] *(optional)* Added in: v1.62# + + 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()](/api/class-browsercontext.mdx#browser-context-set-default-timeout) or [page.setDefaultTimeout()](/api/class-page.mdx#page-set-default-timeout); pass `timeout: 0` to disable the timeout entirely. - `strict` [boolean] *(optional)* Added in: v1.14# 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. @@ -2220,6 +2312,12 @@ await frame.setChecked(selector, checked, 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. + - `scroll` "auto" | "none" *(optional)* Added in: v1.62# + + 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. + - `signal` [AbortSignal] *(optional)* Added in: v1.62# + + 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()](/api/class-browsercontext.mdx#browser-context-set-default-timeout) or [page.setDefaultTimeout()](/api/class-page.mdx#page-set-default-timeout); pass `timeout: 0` to disable the timeout entirely. - `strict` [boolean] *(optional)*# 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. @@ -2280,6 +2378,9 @@ await frame.setInputFiles(selector, files, options); This option has no effect. + - `signal` [AbortSignal] *(optional)* Added in: v1.62# + + 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()](/api/class-browsercontext.mdx#browser-context-set-default-timeout) or [page.setDefaultTimeout()](/api/class-page.mdx#page-set-default-timeout); pass `timeout: 0` to disable the timeout entirely. - `strict` [boolean] *(optional)* Added in: v1.14# 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. @@ -2350,6 +2451,12 @@ await frame.tap(selector, 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. + - `scroll` "auto" | "none" *(optional)* Added in: v1.62# + + 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. + - `signal` [AbortSignal] *(optional)* Added in: v1.62# + + 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()](/api/class-browsercontext.mdx#browser-context-set-default-timeout) or [page.setDefaultTimeout()](/api/class-page.mdx#page-set-default-timeout); pass `timeout: 0` to disable the timeout entirely. - `strict` [boolean] *(optional)* Added in: v1.14# 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. @@ -2390,6 +2497,9 @@ await frame.textContent(selector, options); A selector to search for an element. If there are multiple elements satisfying the selector, the first will be used. - `options` [Object] *(optional)* + - `signal` [AbortSignal] *(optional)* Added in: v1.62# + + 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()](/api/class-browsercontext.mdx#browser-context-set-default-timeout) or [page.setDefaultTimeout()](/api/class-page.mdx#page-set-default-timeout); pass `timeout: 0` to disable the timeout entirely. - `strict` [boolean] *(optional)* Added in: v1.14# 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. @@ -2438,6 +2548,9 @@ To press a special key, like `Control` or `ArrowDown`, use [keyboard.press()](/a This option has no effect. + - `signal` [AbortSignal] *(optional)* Added in: v1.62# + + 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()](/api/class-browsercontext.mdx#browser-context-set-default-timeout) or [page.setDefaultTimeout()](/api/class-page.mdx#page-set-default-timeout); pass `timeout: 0` to disable the timeout entirely. - `strict` [boolean] *(optional)* Added in: v1.14# 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. @@ -2502,6 +2615,12 @@ await frame.uncheck(selector, 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. + - `scroll` "auto" | "none" *(optional)* Added in: v1.62# + + 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. + - `signal` [AbortSignal] *(optional)* Added in: v1.62# + + 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()](/api/class-browsercontext.mdx#browser-context-set-default-timeout) or [page.setDefaultTimeout()](/api/class-page.mdx#page-set-default-timeout); pass `timeout: 0` to disable the timeout entirely. - `strict` [boolean] *(optional)* Added in: v1.14# 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. @@ -2547,6 +2666,9 @@ Usage of the [History API](https://developer.mozilla.org/en-US/docs/Web/API/Hist **Arguments** - `options` [Object] *(optional)* + - `signal` [AbortSignal] *(optional)* Added in: v1.62# + + 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()](/api/class-browsercontext.mdx#browser-context-set-default-timeout); pass `timeout: 0` to disable the timeout entirely. - `timeout` [number] *(optional)*# 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()](/api/class-browsercontext.mdx#browser-context-set-default-navigation-timeout), [browserContext.setDefaultTimeout()](/api/class-browsercontext.mdx#browser-context-set-default-timeout), [page.setDefaultNavigationTimeout()](/api/class-page.mdx#page-set-default-navigation-timeout) or [page.setDefaultTimeout()](/api/class-page.mdx#page-set-default-timeout) methods. @@ -2610,6 +2732,9 @@ const { chromium } = require('playwright'); // Or 'firefox' or 'webkit'. A selector to query for. - `options` [Object] *(optional)* + - `signal` [AbortSignal] *(optional)* Added in: v1.62# + + 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()](/api/class-browsercontext.mdx#browser-context-set-default-timeout) or [page.setDefaultTimeout()](/api/class-page.mdx#page-set-default-timeout); pass `timeout: 0` to disable the timeout entirely. - `state` "attached" | "detached" | "visible" | "hidden" *(optional)*# Defaults to `'visible'`. Can be either: @@ -2730,6 +2855,7 @@ await frame.waitForTimeout(timeout); [TestCase]: /api/class-testcase.mdx "TestCase" [TestError]: /api/class-testerror.mdx "TestError" [TestResult]: /api/class-testresult.mdx "TestResult" +[TestRun]: /api/class-testrun.mdx "TestRun" [TestStep]: /api/class-teststep.mdx "TestStep" [Element]: https://developer.mozilla.org/en-US/docs/Web/API/element "Element" [EvaluationArgument]: /evaluating.mdx#evaluation-argument "EvaluationArgument" diff --git a/nodejs/versioned_docs/version-stable/api/class-framelocator.mdx b/nodejs/versioned_docs/version-stable/api/class-framelocator.mdx index e446eba54e..a4d413e143 100644 --- a/nodejs/versioned_docs/version-stable/api/class-framelocator.mdx +++ b/nodejs/versioned_docs/version-stable/api/class-framelocator.mdx @@ -612,6 +612,7 @@ frameLocator.nth(index); [TestCase]: /api/class-testcase.mdx "TestCase" [TestError]: /api/class-testerror.mdx "TestError" [TestResult]: /api/class-testresult.mdx "TestResult" +[TestRun]: /api/class-testrun.mdx "TestRun" [TestStep]: /api/class-teststep.mdx "TestStep" [Element]: https://developer.mozilla.org/en-US/docs/Web/API/element "Element" [EvaluationArgument]: /evaluating.mdx#evaluation-argument "EvaluationArgument" diff --git a/nodejs/versioned_docs/version-stable/api/class-fullconfig.mdx b/nodejs/versioned_docs/version-stable/api/class-fullconfig.mdx index 6a0910cf4d..58fb200d07 100644 --- a/nodejs/versioned_docs/version-stable/api/class-fullconfig.mdx +++ b/nodejs/versioned_docs/version-stable/api/class-fullconfig.mdx @@ -527,6 +527,7 @@ fullConfig.workers [TestCase]: /api/class-testcase.mdx "TestCase" [TestError]: /api/class-testerror.mdx "TestError" [TestResult]: /api/class-testresult.mdx "TestResult" +[TestRun]: /api/class-testrun.mdx "TestRun" [TestStep]: /api/class-teststep.mdx "TestStep" [Element]: https://developer.mozilla.org/en-US/docs/Web/API/element "Element" [EvaluationArgument]: /evaluating.mdx#evaluation-argument "EvaluationArgument" diff --git a/nodejs/versioned_docs/version-stable/api/class-fullproject.mdx b/nodejs/versioned_docs/version-stable/api/class-fullproject.mdx index 86a5f80079..7a6102cb0a 100644 --- a/nodejs/versioned_docs/version-stable/api/class-fullproject.mdx +++ b/nodejs/versioned_docs/version-stable/api/class-fullproject.mdx @@ -356,6 +356,7 @@ fullProject.use [TestCase]: /api/class-testcase.mdx "TestCase" [TestError]: /api/class-testerror.mdx "TestError" [TestResult]: /api/class-testresult.mdx "TestResult" +[TestRun]: /api/class-testrun.mdx "TestRun" [TestStep]: /api/class-teststep.mdx "TestStep" [Element]: https://developer.mozilla.org/en-US/docs/Web/API/element "Element" [EvaluationArgument]: /evaluating.mdx#evaluation-argument "EvaluationArgument" diff --git a/nodejs/versioned_docs/version-stable/api/class-genericassertions.mdx b/nodejs/versioned_docs/version-stable/api/class-genericassertions.mdx index 283cbdbdf8..db33a4725f 100644 --- a/nodejs/versioned_docs/version-stable/api/class-genericassertions.mdx +++ b/nodejs/versioned_docs/version-stable/api/class-genericassertions.mdx @@ -904,6 +904,7 @@ expect(value).resolves [TestCase]: /api/class-testcase.mdx "TestCase" [TestError]: /api/class-testerror.mdx "TestError" [TestResult]: /api/class-testresult.mdx "TestResult" +[TestRun]: /api/class-testrun.mdx "TestRun" [TestStep]: /api/class-teststep.mdx "TestStep" [Element]: https://developer.mozilla.org/en-US/docs/Web/API/element "Element" [EvaluationArgument]: /evaluating.mdx#evaluation-argument "EvaluationArgument" diff --git a/nodejs/versioned_docs/version-stable/api/class-jshandle.mdx b/nodejs/versioned_docs/version-stable/api/class-jshandle.mdx index b93deba0c8..2672c8dd61 100644 --- a/nodejs/versioned_docs/version-stable/api/class-jshandle.mdx +++ b/nodejs/versioned_docs/version-stable/api/class-jshandle.mdx @@ -81,6 +81,10 @@ expect(await tweetHandle.evaluate(node => node.innerText)).toBe('10 retweets'); - `arg` [EvaluationArgument] *(optional)*# Optional argument to pass to [pageFunction](/api/class-jshandle.mdx#js-handle-evaluate-option-expression). +- `options` [Object] *(optional)* + - `exposeFunctions` [boolean] *(optional)* Added in: v1.62# + + When set to `true`, functions passed inside [arg](/api/class-jshandle.mdx#js-handle-evaluate-option-arg) are exposed in the page and can be called from the page function. Calling one returns a [Promise] of its result. Under the hood, each function is exposed via [page.exposeFunction()](/api/class-page.mdx#page-expose-function), so it is technically accessible from all frames and worlds of the page. Exposed functions are cleared upon the top-level navigation. Defaults to `false`, in which case functions are not serializable and passing one throws an error. **Returns** - [Promise]<[Serializable]># @@ -105,7 +109,7 @@ See [page.evaluateHandle()](/api/class-page.mdx#page-evaluate-handle) for more d ```js await jsHandle.evaluateHandle(pageFunction); -await jsHandle.evaluateHandle(pageFunction, arg); +await jsHandle.evaluateHandle(pageFunction, arg, options); ``` **Arguments** @@ -115,6 +119,10 @@ await jsHandle.evaluateHandle(pageFunction, arg); - `arg` [EvaluationArgument] *(optional)*# Optional argument to pass to [pageFunction](/api/class-jshandle.mdx#js-handle-evaluate-handle-option-expression). +- `options` [Object] *(optional)* + - `exposeFunctions` [boolean] *(optional)* Added in: v1.62# + + When set to `true`, functions passed inside [arg](/api/class-jshandle.mdx#js-handle-evaluate-handle-option-arg) are exposed in the page and can be called from the page function. Calling one returns a [Promise] of its result. Under the hood, each function is exposed via [page.exposeFunction()](/api/class-page.mdx#page-expose-function), so it is technically accessible from all frames and worlds of the page. Exposed functions are cleared upon the top-level navigation. Defaults to `false`, in which case functions are not serializable and passing one throws an error. **Returns** - [Promise]<[JSHandle]># @@ -256,6 +264,7 @@ await jsHandle.jsonValue(); [TestCase]: /api/class-testcase.mdx "TestCase" [TestError]: /api/class-testerror.mdx "TestError" [TestResult]: /api/class-testresult.mdx "TestResult" +[TestRun]: /api/class-testrun.mdx "TestRun" [TestStep]: /api/class-teststep.mdx "TestStep" [Element]: https://developer.mozilla.org/en-US/docs/Web/API/element "Element" [EvaluationArgument]: /evaluating.mdx#evaluation-argument "EvaluationArgument" diff --git a/nodejs/versioned_docs/version-stable/api/class-keyboard.mdx b/nodejs/versioned_docs/version-stable/api/class-keyboard.mdx index aed63c6a94..096234a119 100644 --- a/nodejs/versioned_docs/version-stable/api/class-keyboard.mdx +++ b/nodejs/versioned_docs/version-stable/api/class-keyboard.mdx @@ -297,6 +297,7 @@ await keyboard.up(key); [TestCase]: /api/class-testcase.mdx "TestCase" [TestError]: /api/class-testerror.mdx "TestError" [TestResult]: /api/class-testresult.mdx "TestResult" +[TestRun]: /api/class-testrun.mdx "TestRun" [TestStep]: /api/class-teststep.mdx "TestStep" [Element]: https://developer.mozilla.org/en-US/docs/Web/API/element "Element" [EvaluationArgument]: /evaluating.mdx#evaluation-argument "EvaluationArgument" diff --git a/nodejs/versioned_docs/version-stable/api/class-location.mdx b/nodejs/versioned_docs/version-stable/api/class-location.mdx index 69e7deab7a..2a7640391b 100644 --- a/nodejs/versioned_docs/version-stable/api/class-location.mdx +++ b/nodejs/versioned_docs/version-stable/api/class-location.mdx @@ -135,6 +135,7 @@ location.line [TestCase]: /api/class-testcase.mdx "TestCase" [TestError]: /api/class-testerror.mdx "TestError" [TestResult]: /api/class-testresult.mdx "TestResult" +[TestRun]: /api/class-testrun.mdx "TestRun" [TestStep]: /api/class-teststep.mdx "TestStep" [Element]: https://developer.mozilla.org/en-US/docs/Web/API/element "Element" [EvaluationArgument]: /evaluating.mdx#evaluation-argument "EvaluationArgument" diff --git a/nodejs/versioned_docs/version-stable/api/class-locator.mdx b/nodejs/versioned_docs/version-stable/api/class-locator.mdx index bb1a9da6a6..b74c62456a 100644 --- a/nodejs/versioned_docs/version-stable/api/class-locator.mdx +++ b/nodejs/versioned_docs/version-stable/api/class-locator.mdx @@ -134,6 +134,9 @@ await page.getByRole('link').ariaSnapshot(); - `mode` "ai" | "default" *(optional)* Added in: v1.59# When set to `"ai"`, returns a snapshot optimized for AI consumption. Defaults to `"default"`. See details for more information. + - `signal` [AbortSignal] *(optional)* Added in: v1.62# + + 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()](/api/class-browsercontext.mdx#browser-context-set-default-timeout) or [page.setDefaultTimeout()](/api/class-page.mdx#page-set-default-timeout); pass `timeout: 0` to disable the timeout entirely. - `timeout` [number] *(optional)*# 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()](/api/class-browsercontext.mdx#browser-context-set-default-timeout) or [page.setDefaultTimeout()](/api/class-page.mdx#page-set-default-timeout) methods. @@ -187,6 +190,9 @@ await locator.blur(options); **Arguments** - `options` [Object] *(optional)* + - `signal` [AbortSignal] *(optional)* Added in: v1.62# + + 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()](/api/class-browsercontext.mdx#browser-context-set-default-timeout) or [page.setDefaultTimeout()](/api/class-page.mdx#page-set-default-timeout); pass `timeout: 0` to disable the timeout entirely. - `timeout` [number] *(optional)*# 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()](/api/class-browsercontext.mdx#browser-context-set-default-timeout) or [page.setDefaultTimeout()](/api/class-page.mdx#page-set-default-timeout) methods. @@ -211,6 +217,9 @@ await page.mouse.click(box.x + box.width / 2, box.y + box.height / 2); **Arguments** - `options` [Object] *(optional)* + - `signal` [AbortSignal] *(optional)* Added in: v1.62# + + 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()](/api/class-browsercontext.mdx#browser-context-set-default-timeout) or [page.setDefaultTimeout()](/api/class-page.mdx#page-set-default-timeout); pass `timeout: 0` to disable the timeout entirely. - `timeout` [number] *(optional)*# 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()](/api/class-browsercontext.mdx#browser-context-set-default-timeout) or [page.setDefaultTimeout()](/api/class-page.mdx#page-set-default-timeout) methods. @@ -273,6 +282,12 @@ await page.getByRole('checkbox').check(); A point to use relative to the top-left corner of element padding box. If not specified, uses some visible point of the element. + - `scroll` "auto" | "none" *(optional)* Added in: v1.62# + + 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. + - `signal` [AbortSignal] *(optional)* Added in: v1.62# + + 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()](/api/class-browsercontext.mdx#browser-context-set-default-timeout) or [page.setDefaultTimeout()](/api/class-page.mdx#page-set-default-timeout); pass `timeout: 0` to disable the timeout entirely. - `timeout` [number] *(optional)*# 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()](/api/class-browsercontext.mdx#browser-context-set-default-timeout) or [page.setDefaultTimeout()](/api/class-page.mdx#page-set-default-timeout) methods. @@ -323,6 +338,9 @@ await page.getByRole('textbox').clear(); This option has no effect. + - `signal` [AbortSignal] *(optional)* Added in: v1.62# + + 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()](/api/class-browsercontext.mdx#browser-context-set-default-timeout) or [page.setDefaultTimeout()](/api/class-page.mdx#page-set-default-timeout); pass `timeout: 0` to disable the timeout entirely. - `timeout` [number] *(optional)*# 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()](/api/class-browsercontext.mdx#browser-context-set-default-timeout) or [page.setDefaultTimeout()](/api/class-page.mdx#page-set-default-timeout) methods. @@ -395,6 +413,12 @@ await page.locator('canvas').click({ A point to use relative to the top-left corner of element padding box. If not specified, uses some visible point of the element. + - `scroll` "auto" | "none" *(optional)* Added in: v1.62# + + 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. + - `signal` [AbortSignal] *(optional)* Added in: v1.62# + + 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()](/api/class-browsercontext.mdx#browser-context-set-default-timeout) or [page.setDefaultTimeout()](/api/class-page.mdx#page-set-default-timeout); pass `timeout: 0` to disable the timeout entirely. - `steps` [number] *(optional)* Added in: v1.57# 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. @@ -511,6 +535,12 @@ await locator.dblclick(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. + - `scroll` "auto" | "none" *(optional)* Added in: v1.62# + + 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. + - `signal` [AbortSignal] *(optional)* Added in: v1.62# + + 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()](/api/class-browsercontext.mdx#browser-context-set-default-timeout) or [page.setDefaultTimeout()](/api/class-page.mdx#page-set-default-timeout); pass `timeout: 0` to disable the timeout entirely. - `steps` [number] *(optional)* Added in: v1.57# 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. @@ -606,6 +636,9 @@ await locator.dispatchEvent('click'); Optional event-specific initialization properties. - `options` [Object] *(optional)* + - `signal` [AbortSignal] *(optional)* Added in: v1.62# + + 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()](/api/class-browsercontext.mdx#browser-context-set-default-timeout) or [page.setDefaultTimeout()](/api/class-page.mdx#page-set-default-timeout); pass `timeout: 0` to disable the timeout entirely. - `timeout` [number] *(optional)*# 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()](/api/class-browsercontext.mdx#browser-context-set-default-timeout) or [page.setDefaultTimeout()](/api/class-page.mdx#page-set-default-timeout) methods. @@ -676,6 +709,12 @@ await source.dragTo(target, { This option has no effect. + - `scroll` "auto" | "none" *(optional)* Added in: v1.62# + + 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. + - `signal` [AbortSignal] *(optional)* Added in: v1.62# + + 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()](/api/class-browsercontext.mdx#browser-context-set-default-timeout) or [page.setDefaultTimeout()](/api/class-page.mdx#page-set-default-timeout); pass `timeout: 0` to disable the timeout entirely. - `sourcePosition` [Object] *(optional)*# - `x` [number] @@ -765,6 +804,9 @@ await page.locator('#dropzone').drop({ A point to use relative to the top-left corner of element padding box. If not specified, uses some visible point of the element. + - `signal` [AbortSignal] *(optional)* Added in: v1.62# + + 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()](/api/class-browsercontext.mdx#browser-context-set-default-timeout) or [page.setDefaultTimeout()](/api/class-page.mdx#page-set-default-timeout); pass `timeout: 0` to disable the timeout entirely. - `timeout` [number] *(optional)*# 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()](/api/class-browsercontext.mdx#browser-context-set-default-timeout) or [page.setDefaultTimeout()](/api/class-page.mdx#page-set-default-timeout) methods. @@ -805,6 +847,12 @@ console.log(result); // prints "myId text 56" Optional argument to pass to [pageFunction](/api/class-locator.mdx#locator-evaluate-option-expression). - `options` [Object] *(optional)* + - `exposeFunctions` [boolean] *(optional)* Added in: v1.62# + + When set to `true`, functions passed inside [arg](/api/class-locator.mdx#locator-evaluate-option-arg) are exposed in the page and can be called from the page function. Calling one returns a [Promise] of its result. Under the hood, each function is exposed via [page.exposeFunction()](/api/class-page.mdx#page-expose-function), so it is technically accessible from all frames and worlds of the page. Exposed functions are cleared upon the top-level navigation. Defaults to `false`, in which case functions are not serializable and passing one throws an error. + - `signal` [AbortSignal] *(optional)* Added in: v1.62# + + 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()](/api/class-browsercontext.mdx#browser-context-set-default-timeout) or [page.setDefaultTimeout()](/api/class-page.mdx#page-set-default-timeout); pass `timeout: 0` to disable the timeout entirely. - `timeout` [number] *(optional)*# Maximum time in milliseconds to wait for the locator before evaluating. Note that after locator is resolved, evaluation itself is not limited by the timeout. Defaults to `0` - no timeout. @@ -877,6 +925,12 @@ await locator.evaluateHandle(pageFunction, arg, options); Optional argument to pass to [pageFunction](/api/class-locator.mdx#locator-evaluate-handle-option-expression). - `options` [Object] *(optional)* + - `exposeFunctions` [boolean] *(optional)* Added in: v1.62# + + When set to `true`, functions passed inside [arg](/api/class-locator.mdx#locator-evaluate-handle-option-arg) are exposed in the page and can be called from the page function. Calling one returns a [Promise] of its result. Under the hood, each function is exposed via [page.exposeFunction()](/api/class-page.mdx#page-expose-function), so it is technically accessible from all frames and worlds of the page. Exposed functions are cleared upon the top-level navigation. Defaults to `false`, in which case functions are not serializable and passing one throws an error. + - `signal` [AbortSignal] *(optional)* Added in: v1.62# + + 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()](/api/class-browsercontext.mdx#browser-context-set-default-timeout) or [page.setDefaultTimeout()](/api/class-page.mdx#page-set-default-timeout); pass `timeout: 0` to disable the timeout entirely. - `timeout` [number] *(optional)*# Maximum time in milliseconds to wait for the locator before evaluating. Note that after locator is resolved, evaluation itself is not limited by the timeout. Defaults to `0` - no timeout. @@ -926,6 +980,9 @@ await page.getByRole('textbox').fill('example value'); This option has no effect. + - `signal` [AbortSignal] *(optional)* Added in: v1.62# + + 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()](/api/class-browsercontext.mdx#browser-context-set-default-timeout) or [page.setDefaultTimeout()](/api/class-page.mdx#page-set-default-timeout); pass `timeout: 0` to disable the timeout entirely. - `timeout` [number] *(optional)*# 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()](/api/class-browsercontext.mdx#browser-context-set-default-timeout) or [page.setDefaultTimeout()](/api/class-page.mdx#page-set-default-timeout) methods. @@ -1021,6 +1078,9 @@ await locator.focus(options); **Arguments** - `options` [Object] *(optional)* + - `signal` [AbortSignal] *(optional)* Added in: v1.62# + + 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()](/api/class-browsercontext.mdx#browser-context-set-default-timeout) or [page.setDefaultTimeout()](/api/class-page.mdx#page-set-default-timeout); pass `timeout: 0` to disable the timeout entirely. - `timeout` [number] *(optional)*# 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()](/api/class-browsercontext.mdx#browser-context-set-default-timeout) or [page.setDefaultTimeout()](/api/class-page.mdx#page-set-default-timeout) methods. @@ -1076,6 +1136,9 @@ await locator.getAttribute(name, options); Attribute name to get the value for. - `options` [Object] *(optional)* + - `signal` [AbortSignal] *(optional)* Added in: v1.62# + + 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()](/api/class-browsercontext.mdx#browser-context-set-default-timeout) or [page.setDefaultTimeout()](/api/class-page.mdx#page-set-default-timeout); pass `timeout: 0` to disable the timeout entirely. - `timeout` [number] *(optional)*# 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()](/api/class-browsercontext.mdx#browser-context-set-default-timeout) or [page.setDefaultTimeout()](/api/class-page.mdx#page-set-default-timeout) methods. @@ -1503,6 +1566,12 @@ await page.getByRole('link').hover(); A point to use relative to the top-left corner of element padding box. If not specified, uses some visible point of the element. + - `scroll` "auto" | "none" *(optional)* Added in: v1.62# + + 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. + - `signal` [AbortSignal] *(optional)* Added in: v1.62# + + 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()](/api/class-browsercontext.mdx#browser-context-set-default-timeout) or [page.setDefaultTimeout()](/api/class-page.mdx#page-set-default-timeout); pass `timeout: 0` to disable the timeout entirely. - `timeout` [number] *(optional)*# 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()](/api/class-browsercontext.mdx#browser-context-set-default-timeout) or [page.setDefaultTimeout()](/api/class-page.mdx#page-set-default-timeout) methods. @@ -1541,6 +1610,9 @@ await locator.innerHTML(options); **Arguments** - `options` [Object] *(optional)* + - `signal` [AbortSignal] *(optional)* Added in: v1.62# + + 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()](/api/class-browsercontext.mdx#browser-context-set-default-timeout) or [page.setDefaultTimeout()](/api/class-page.mdx#page-set-default-timeout); pass `timeout: 0` to disable the timeout entirely. - `timeout` [number] *(optional)*# 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()](/api/class-browsercontext.mdx#browser-context-set-default-timeout) or [page.setDefaultTimeout()](/api/class-page.mdx#page-set-default-timeout) methods. @@ -1570,6 +1642,9 @@ await locator.innerText(options); **Arguments** - `options` [Object] *(optional)* + - `signal` [AbortSignal] *(optional)* Added in: v1.62# + + 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()](/api/class-browsercontext.mdx#browser-context-set-default-timeout) or [page.setDefaultTimeout()](/api/class-page.mdx#page-set-default-timeout); pass `timeout: 0` to disable the timeout entirely. - `timeout` [number] *(optional)*# 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()](/api/class-browsercontext.mdx#browser-context-set-default-timeout) or [page.setDefaultTimeout()](/api/class-page.mdx#page-set-default-timeout) methods. @@ -1598,6 +1673,9 @@ const value = await page.getByRole('textbox').inputValue(); **Arguments** - `options` [Object] *(optional)* + - `signal` [AbortSignal] *(optional)* Added in: v1.62# + + 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()](/api/class-browsercontext.mdx#browser-context-set-default-timeout) or [page.setDefaultTimeout()](/api/class-page.mdx#page-set-default-timeout); pass `timeout: 0` to disable the timeout entirely. - `timeout` [number] *(optional)*# 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()](/api/class-browsercontext.mdx#browser-context-set-default-timeout) or [page.setDefaultTimeout()](/api/class-page.mdx#page-set-default-timeout) methods. @@ -1630,6 +1708,9 @@ const checked = await page.getByRole('checkbox').isChecked(); **Arguments** - `options` [Object] *(optional)* + - `signal` [AbortSignal] *(optional)* Added in: v1.62# + + 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()](/api/class-browsercontext.mdx#browser-context-set-default-timeout) or [page.setDefaultTimeout()](/api/class-page.mdx#page-set-default-timeout); pass `timeout: 0` to disable the timeout entirely. - `timeout` [number] *(optional)*# 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()](/api/class-browsercontext.mdx#browser-context-set-default-timeout) or [page.setDefaultTimeout()](/api/class-page.mdx#page-set-default-timeout) methods. @@ -1658,6 +1739,9 @@ const disabled = await page.getByRole('button').isDisabled(); **Arguments** - `options` [Object] *(optional)* + - `signal` [AbortSignal] *(optional)* Added in: v1.62# + + 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()](/api/class-browsercontext.mdx#browser-context-set-default-timeout) or [page.setDefaultTimeout()](/api/class-page.mdx#page-set-default-timeout); pass `timeout: 0` to disable the timeout entirely. - `timeout` [number] *(optional)*# 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()](/api/class-browsercontext.mdx#browser-context-set-default-timeout) or [page.setDefaultTimeout()](/api/class-page.mdx#page-set-default-timeout) methods. @@ -1686,6 +1770,9 @@ const editable = await page.getByRole('textbox').isEditable(); **Arguments** - `options` [Object] *(optional)* + - `signal` [AbortSignal] *(optional)* Added in: v1.62# + + 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()](/api/class-browsercontext.mdx#browser-context-set-default-timeout) or [page.setDefaultTimeout()](/api/class-page.mdx#page-set-default-timeout); pass `timeout: 0` to disable the timeout entirely. - `timeout` [number] *(optional)*# 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()](/api/class-browsercontext.mdx#browser-context-set-default-timeout) or [page.setDefaultTimeout()](/api/class-page.mdx#page-set-default-timeout) methods. @@ -1714,6 +1801,9 @@ const enabled = await page.getByRole('button').isEnabled(); **Arguments** - `options` [Object] *(optional)* + - `signal` [AbortSignal] *(optional)* Added in: v1.62# + + 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()](/api/class-browsercontext.mdx#browser-context-set-default-timeout) or [page.setDefaultTimeout()](/api/class-page.mdx#page-set-default-timeout); pass `timeout: 0` to disable the timeout entirely. - `timeout` [number] *(optional)*# 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()](/api/class-browsercontext.mdx#browser-context-set-default-timeout) or [page.setDefaultTimeout()](/api/class-page.mdx#page-set-default-timeout) methods. @@ -1964,6 +2054,9 @@ await page.getByRole('textbox').press('Backspace'); 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`. + - `signal` [AbortSignal] *(optional)* Added in: v1.62# + + 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()](/api/class-browsercontext.mdx#browser-context-set-default-timeout) or [page.setDefaultTimeout()](/api/class-page.mdx#page-set-default-timeout); pass `timeout: 0` to disable the timeout entirely. - `timeout` [number] *(optional)*# 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()](/api/class-browsercontext.mdx#browser-context-set-default-timeout) or [page.setDefaultTimeout()](/api/class-page.mdx#page-set-default-timeout) methods. @@ -2033,6 +2126,9 @@ await locator.press('Enter'); This option has no effect. + - `signal` [AbortSignal] *(optional)* Added in: v1.62# + + 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()](/api/class-browsercontext.mdx#browser-context-set-default-timeout) or [page.setDefaultTimeout()](/api/class-page.mdx#page-set-default-timeout); pass `timeout: 0` to disable the timeout entirely. - `timeout` [number] *(optional)*# 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()](/api/class-browsercontext.mdx#browser-context-set-default-timeout) or [page.setDefaultTimeout()](/api/class-page.mdx#page-set-default-timeout) methods. @@ -2086,19 +2182,22 @@ await page.getByRole('link').screenshot({ animations: 'disabled', path: 'link.pn The file path to save the image to. The screenshot type will be inferred from file extension. If [path](/api/class-locator.mdx#locator-screenshot-option-path) is a relative path, then it is resolved relative to the current working directory. If no path is provided, the image won't be saved to the disk. - `quality` [number] *(optional)*# - The quality of the image, between 0-100. Not applicable to `png` images. + 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. - `scale` "css" | "device" *(optional)*# 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"`. + - `signal` [AbortSignal] *(optional)* Added in: v1.62# + + 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()](/api/class-browsercontext.mdx#browser-context-set-default-timeout) or [page.setDefaultTimeout()](/api/class-page.mdx#page-set-default-timeout); pass `timeout: 0` to disable the timeout entirely. - `style` [string] *(optional)* Added in: v1.41# 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. - `timeout` [number] *(optional)*# 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()](/api/class-browsercontext.mdx#browser-context-set-default-timeout) or [page.setDefaultTimeout()](/api/class-page.mdx#page-set-default-timeout) methods. - - `type` "png" | "jpeg" *(optional)*# + - `type` "png" | "jpeg" | "webp" *(optional)*# Specify screenshot type, defaults to `png`. @@ -2132,6 +2231,9 @@ await locator.scrollIntoViewIfNeeded(options); **Arguments** - `options` [Object] *(optional)* + - `signal` [AbortSignal] *(optional)* Added in: v1.62# + + 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()](/api/class-browsercontext.mdx#browser-context-set-default-timeout) or [page.setDefaultTimeout()](/api/class-page.mdx#page-set-default-timeout); pass `timeout: 0` to disable the timeout entirely. - `timeout` [number] *(optional)*# 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()](/api/class-browsercontext.mdx#browser-context-set-default-timeout) or [page.setDefaultTimeout()](/api/class-page.mdx#page-set-default-timeout) methods. @@ -2193,6 +2295,9 @@ element.selectOption(['red', 'green', 'blue']); This option has no effect. + - `signal` [AbortSignal] *(optional)* Added in: v1.62# + + 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()](/api/class-browsercontext.mdx#browser-context-set-default-timeout) or [page.setDefaultTimeout()](/api/class-page.mdx#page-set-default-timeout); pass `timeout: 0` to disable the timeout entirely. - `timeout` [number] *(optional)*# 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()](/api/class-browsercontext.mdx#browser-context-set-default-timeout) or [page.setDefaultTimeout()](/api/class-page.mdx#page-set-default-timeout) methods. @@ -2232,6 +2337,9 @@ await locator.selectText(options); - `force` [boolean] *(optional)*# Whether to bypass the [actionability](../actionability.mdx) checks. Defaults to `false`. + - `signal` [AbortSignal] *(optional)* Added in: v1.62# + + 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()](/api/class-browsercontext.mdx#browser-context-set-default-timeout) or [page.setDefaultTimeout()](/api/class-page.mdx#page-set-default-timeout); pass `timeout: 0` to disable the timeout entirely. - `timeout` [number] *(optional)*# 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()](/api/class-browsercontext.mdx#browser-context-set-default-timeout) or [page.setDefaultTimeout()](/api/class-page.mdx#page-set-default-timeout) methods. @@ -2277,6 +2385,12 @@ await page.getByRole('checkbox').setChecked(true); A point to use relative to the top-left corner of element padding box. If not specified, uses some visible point of the element. + - `scroll` "auto" | "none" *(optional)* Added in: v1.62# + + 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. + - `signal` [AbortSignal] *(optional)* Added in: v1.62# + + 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()](/api/class-browsercontext.mdx#browser-context-set-default-timeout) or [page.setDefaultTimeout()](/api/class-page.mdx#page-set-default-timeout); pass `timeout: 0` to disable the timeout entirely. - `timeout` [number] *(optional)*# 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()](/api/class-browsercontext.mdx#browser-context-set-default-timeout) or [page.setDefaultTimeout()](/api/class-page.mdx#page-set-default-timeout) methods. @@ -2353,6 +2467,9 @@ await page.getByLabel('Upload file').setInputFiles({ This option has no effect. + - `signal` [AbortSignal] *(optional)* Added in: v1.62# + + 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()](/api/class-browsercontext.mdx#browser-context-set-default-timeout) or [page.setDefaultTimeout()](/api/class-page.mdx#page-set-default-timeout); pass `timeout: 0` to disable the timeout entirely. - `timeout` [number] *(optional)*# 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()](/api/class-browsercontext.mdx#browser-context-set-default-timeout) or [page.setDefaultTimeout()](/api/class-page.mdx#page-set-default-timeout) methods. @@ -2405,6 +2522,12 @@ await locator.tap(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. + - `scroll` "auto" | "none" *(optional)* Added in: v1.62# + + 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. + - `signal` [AbortSignal] *(optional)* Added in: v1.62# + + 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()](/api/class-browsercontext.mdx#browser-context-set-default-timeout) or [page.setDefaultTimeout()](/api/class-page.mdx#page-set-default-timeout); pass `timeout: 0` to disable the timeout entirely. - `timeout` [number] *(optional)*# 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()](/api/class-browsercontext.mdx#browser-context-set-default-timeout) or [page.setDefaultTimeout()](/api/class-page.mdx#page-set-default-timeout) methods. @@ -2453,6 +2576,9 @@ await locator.textContent(options); **Arguments** - `options` [Object] *(optional)* + - `signal` [AbortSignal] *(optional)* Added in: v1.62# + + 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()](/api/class-browsercontext.mdx#browser-context-set-default-timeout) or [page.setDefaultTimeout()](/api/class-page.mdx#page-set-default-timeout); pass `timeout: 0` to disable the timeout entirely. - `timeout` [number] *(optional)*# 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()](/api/class-browsercontext.mdx#browser-context-set-default-timeout) or [page.setDefaultTimeout()](/api/class-page.mdx#page-set-default-timeout) methods. @@ -2512,6 +2638,12 @@ await page.getByRole('checkbox').uncheck(); A point to use relative to the top-left corner of element padding box. If not specified, uses some visible point of the element. + - `scroll` "auto" | "none" *(optional)* Added in: v1.62# + + 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. + - `signal` [AbortSignal] *(optional)* Added in: v1.62# + + 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()](/api/class-browsercontext.mdx#browser-context-set-default-timeout) or [page.setDefaultTimeout()](/api/class-page.mdx#page-set-default-timeout); pass `timeout: 0` to disable the timeout entirely. - `timeout` [number] *(optional)*# 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()](/api/class-browsercontext.mdx#browser-context-set-default-timeout) or [page.setDefaultTimeout()](/api/class-page.mdx#page-set-default-timeout) methods. @@ -2554,6 +2686,9 @@ await orderSent.waitFor(); **Arguments** - `options` [Object] *(optional)* + - `signal` [AbortSignal] *(optional)* Added in: v1.62# + + 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()](/api/class-browsercontext.mdx#browser-context-set-default-timeout) or [page.setDefaultTimeout()](/api/class-page.mdx#page-set-default-timeout); pass `timeout: 0` to disable the timeout entirely. - `state` "attached" | "detached" | "visible" | "hidden" *(optional)*# Defaults to `'visible'`. Can be either: @@ -2570,6 +2705,56 @@ await orderSent.waitFor(); --- +### waitForFunction {/* #locator-wait-for-function */} + +Added in: v1.62locator.waitForFunction + +Returns when [pageFunction](/api/class-locator.mdx#locator-wait-for-function-option-expression) returns a truthy value, called with the matching element as a first argument, and [arg](/api/class-locator.mdx#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](/api/class-locator.mdx#locator-wait-for-function-option-expression) returns a [Promise], this method will wait for the promise to resolve before checking its value. + +If [pageFunction](/api/class-locator.mdx#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](/api/class-locator.mdx#locator-wait-for-function-option-expression): + +```js +await page.getByTestId('status').waitForFunction((element, value) => { + return element.textContent === value; +}, 'Ready'); +``` + +**Arguments** +- `pageFunction` [function] | [string]# + + Function to be evaluated in the page context. +- `arg` [EvaluationArgument] *(optional)*# + + Optional argument to pass to [pageFunction](/api/class-locator.mdx#locator-wait-for-function-option-expression). +- `options` [Object] *(optional)* + - `signal` [AbortSignal] *(optional)*# + + 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()](/api/class-browsercontext.mdx#browser-context-set-default-timeout) or [page.setDefaultTimeout()](/api/class-page.mdx#page-set-default-timeout); pass `timeout: 0` to disable the timeout entirely. + - `timeout` [number] *(optional)*# + + Maximum time to wait for 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()](/api/class-browsercontext.mdx#browser-context-set-default-timeout) or [page.setDefaultTimeout()](/api/class-page.mdx#page-set-default-timeout) methods. + +**Returns** +- [Promise]<[void]># + +--- + ## Deprecated ### elementHandle {/* #locator-element-handle */} @@ -2594,6 +2779,9 @@ await locator.elementHandle(options); **Arguments** - `options` [Object] *(optional)* + - `signal` [AbortSignal] *(optional)* Added in: v1.62# + + 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()](/api/class-browsercontext.mdx#browser-context-set-default-timeout) or [page.setDefaultTimeout()](/api/class-page.mdx#page-set-default-timeout); pass `timeout: 0` to disable the timeout entirely. - `timeout` [number] *(optional)*# 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()](/api/class-browsercontext.mdx#browser-context-set-default-timeout) or [page.setDefaultTimeout()](/api/class-page.mdx#page-set-default-timeout) methods. @@ -2660,6 +2848,9 @@ To press a special key, like `Control` or `ArrowDown`, use [locator.press()](/ap This option has no effect. + - `signal` [AbortSignal] *(optional)* Added in: v1.62# + + 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()](/api/class-browsercontext.mdx#browser-context-set-default-timeout) or [page.setDefaultTimeout()](/api/class-page.mdx#page-set-default-timeout); pass `timeout: 0` to disable the timeout entirely. - `timeout` [number] *(optional)*# 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()](/api/class-browsercontext.mdx#browser-context-set-default-timeout) or [page.setDefaultTimeout()](/api/class-page.mdx#page-set-default-timeout) methods. @@ -2739,6 +2930,7 @@ To press a special key, like `Control` or `ArrowDown`, use [locator.press()](/ap [TestCase]: /api/class-testcase.mdx "TestCase" [TestError]: /api/class-testerror.mdx "TestError" [TestResult]: /api/class-testresult.mdx "TestResult" +[TestRun]: /api/class-testrun.mdx "TestRun" [TestStep]: /api/class-teststep.mdx "TestStep" [Element]: https://developer.mozilla.org/en-US/docs/Web/API/element "Element" [EvaluationArgument]: /evaluating.mdx#evaluation-argument "EvaluationArgument" diff --git a/nodejs/versioned_docs/version-stable/api/class-locatorassertions.mdx b/nodejs/versioned_docs/version-stable/api/class-locatorassertions.mdx index 6dad82a7ed..8b421e744d 100644 --- a/nodejs/versioned_docs/version-stable/api/class-locatorassertions.mdx +++ b/nodejs/versioned_docs/version-stable/api/class-locatorassertions.mdx @@ -39,6 +39,9 @@ await expect(page.getByText('Hidden text')).toBeAttached(); **Arguments** - `options` [Object] *(optional)* - `attached` [boolean] *(optional)*# + - `signal` [AbortSignal] *(optional)* Added in: v1.62# + + An optional [`AbortSignal`](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal) that can cancel the assertion. Aborting the signal fails the assertion like a timeout: if the signal is aborted while the assertion is retrying, or is already aborted before the assertion starts, the assertion fails without retrying further. - `timeout` [number] *(optional)*# Time to retry the assertion for in milliseconds. Defaults to `timeout` in `TestConfig.expect`. @@ -69,6 +72,9 @@ await expect(locator).toBeChecked(); - `indeterminate` [boolean] *(optional)* Added in: v1.50# Asserts that the element is in the indeterminate (mixed) state. Only supported for checkboxes and radio buttons. This option can't be true when [checked](/api/class-locatorassertions.mdx#locator-assertions-to-be-checked-option-checked) is provided. + - `signal` [AbortSignal] *(optional)* Added in: v1.62# + + An optional [`AbortSignal`](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal) that can cancel the assertion. Aborting the signal fails the assertion like a timeout: if the signal is aborted while the assertion is retrying, or is already aborted before the assertion starts, the assertion fails without retrying further. - `timeout` [number] *(optional)* Added in: v1.18# Time to retry the assertion for in milliseconds. Defaults to `timeout` in `TestConfig.expect`. @@ -93,6 +99,9 @@ await expect(locator).toBeDisabled(); **Arguments** - `options` [Object] *(optional)* + - `signal` [AbortSignal] *(optional)* Added in: v1.62# + + An optional [`AbortSignal`](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal) that can cancel the assertion. Aborting the signal fails the assertion like a timeout: if the signal is aborted while the assertion is retrying, or is already aborted before the assertion starts, the assertion fails without retrying further. - `timeout` [number] *(optional)* Added in: v1.18# Time to retry the assertion for in milliseconds. Defaults to `timeout` in `TestConfig.expect`. @@ -118,6 +127,9 @@ await expect(locator).toBeEditable(); **Arguments** - `options` [Object] *(optional)* - `editable` [boolean] *(optional)* Added in: v1.26# + - `signal` [AbortSignal] *(optional)* Added in: v1.62# + + An optional [`AbortSignal`](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal) that can cancel the assertion. Aborting the signal fails the assertion like a timeout: if the signal is aborted while the assertion is retrying, or is already aborted before the assertion starts, the assertion fails without retrying further. - `timeout` [number] *(optional)* Added in: v1.18# Time to retry the assertion for in milliseconds. Defaults to `timeout` in `TestConfig.expect`. @@ -142,6 +154,9 @@ await expect(locator).toBeEmpty(); **Arguments** - `options` [Object] *(optional)* + - `signal` [AbortSignal] *(optional)* Added in: v1.62# + + An optional [`AbortSignal`](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal) that can cancel the assertion. Aborting the signal fails the assertion like a timeout: if the signal is aborted while the assertion is retrying, or is already aborted before the assertion starts, the assertion fails without retrying further. - `timeout` [number] *(optional)* Added in: v1.18# Time to retry the assertion for in milliseconds. Defaults to `timeout` in `TestConfig.expect`. @@ -167,6 +182,9 @@ await expect(locator).toBeEnabled(); **Arguments** - `options` [Object] *(optional)* - `enabled` [boolean] *(optional)* Added in: v1.26# + - `signal` [AbortSignal] *(optional)* Added in: v1.62# + + An optional [`AbortSignal`](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal) that can cancel the assertion. Aborting the signal fails the assertion like a timeout: if the signal is aborted while the assertion is retrying, or is already aborted before the assertion starts, the assertion fails without retrying further. - `timeout` [number] *(optional)* Added in: v1.18# Time to retry the assertion for in milliseconds. Defaults to `timeout` in `TestConfig.expect`. @@ -191,6 +209,9 @@ await expect(locator).toBeFocused(); **Arguments** - `options` [Object] *(optional)* + - `signal` [AbortSignal] *(optional)* Added in: v1.62# + + An optional [`AbortSignal`](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal) that can cancel the assertion. Aborting the signal fails the assertion like a timeout: if the signal is aborted while the assertion is retrying, or is already aborted before the assertion starts, the assertion fails without retrying further. - `timeout` [number] *(optional)* Added in: v1.18# Time to retry the assertion for in milliseconds. Defaults to `timeout` in `TestConfig.expect`. @@ -215,6 +236,9 @@ await expect(locator).toBeHidden(); **Arguments** - `options` [Object] *(optional)* + - `signal` [AbortSignal] *(optional)* Added in: v1.62# + + An optional [`AbortSignal`](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal) that can cancel the assertion. Aborting the signal fails the assertion like a timeout: if the signal is aborted while the assertion is retrying, or is already aborted before the assertion starts, the assertion fails without retrying further. - `timeout` [number] *(optional)* Added in: v1.18# Time to retry the assertion for in milliseconds. Defaults to `timeout` in `TestConfig.expect`. @@ -247,6 +271,9 @@ await expect(locator).toBeInViewport({ ratio: 0.5 }); - `ratio` [number] *(optional)*# The minimal ratio of the element to intersect viewport. If equals to `0`, then element should intersect viewport at any positive ratio. Defaults to `0`. + - `signal` [AbortSignal] *(optional)* Added in: v1.62# + + An optional [`AbortSignal`](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal) that can cancel the assertion. Aborting the signal fails the assertion like a timeout: if the signal is aborted while the assertion is retrying, or is already aborted before the assertion starts, the assertion fails without retrying further. - `timeout` [number] *(optional)*# Time to retry the assertion for in milliseconds. Defaults to `timeout` in `TestConfig.expect`. @@ -283,6 +310,9 @@ await expect( **Arguments** - `options` [Object] *(optional)* + - `signal` [AbortSignal] *(optional)* Added in: v1.62# + + An optional [`AbortSignal`](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal) that can cancel the assertion. Aborting the signal fails the assertion like a timeout: if the signal is aborted while the assertion is retrying, or is already aborted before the assertion starts, the assertion fails without retrying further. - `timeout` [number] *(optional)* Added in: v1.18# Time to retry the assertion for in milliseconds. Defaults to `timeout` in `TestConfig.expect`. @@ -332,6 +362,9 @@ await expect(locator).toContainClass(['inactive', 'active', 'inactive']); A string containing expected class names, separated by spaces, or a list of such strings to assert multiple elements. - `options` [Object] *(optional)* + - `signal` [AbortSignal] *(optional)* Added in: v1.62# + + An optional [`AbortSignal`](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal) that can cancel the assertion. Aborting the signal fails the assertion like a timeout: if the signal is aborted while the assertion is retrying, or is already aborted before the assertion starts, the assertion fails without retrying further. - `timeout` [number] *(optional)*# Time to retry the assertion for in milliseconds. Defaults to `timeout` in `TestConfig.expect`. @@ -395,6 +428,9 @@ await expect(page.locator('ul')).toContainText(['Text 3']); - `ignoreCase` [boolean] *(optional)* Added in: v1.23# Whether to perform case-insensitive match. [ignoreCase](/api/class-locatorassertions.mdx#locator-assertions-to-contain-text-option-ignore-case) option takes precedence over the corresponding regular expression flag if specified. + - `signal` [AbortSignal] *(optional)* Added in: v1.62# + + An optional [`AbortSignal`](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal) that can cancel the assertion. Aborting the signal fails the assertion like a timeout: if the signal is aborted while the assertion is retrying, or is already aborted before the assertion starts, the assertion fails without retrying further. - `timeout` [number] *(optional)* Added in: v1.18# Time to retry the assertion for in milliseconds. Defaults to `timeout` in `TestConfig.expect`. @@ -432,6 +468,9 @@ await expect(locator).toHaveAccessibleDescription('Save results to disk'); - `ignoreCase` [boolean] *(optional)*# Whether to perform case-insensitive match. [ignoreCase](/api/class-locatorassertions.mdx#locator-assertions-to-have-accessible-description-option-ignore-case) option takes precedence over the corresponding regular expression flag if specified. + - `signal` [AbortSignal] *(optional)* Added in: v1.62# + + An optional [`AbortSignal`](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal) that can cancel the assertion. Aborting the signal fails the assertion like a timeout: if the signal is aborted while the assertion is retrying, or is already aborted before the assertion starts, the assertion fails without retrying further. - `timeout` [number] *(optional)*# Time to retry the assertion for in milliseconds. Defaults to `timeout` in `TestConfig.expect`. @@ -462,6 +501,9 @@ await expect(locator).toHaveAccessibleErrorMessage('Username is required.'); - `ignoreCase` [boolean] *(optional)*# Whether to perform case-insensitive match. [ignoreCase](/api/class-locatorassertions.mdx#locator-assertions-to-have-accessible-error-message-option-ignore-case) option takes precedence over the corresponding regular expression flag if specified. + - `signal` [AbortSignal] *(optional)* Added in: v1.62# + + An optional [`AbortSignal`](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal) that can cancel the assertion. Aborting the signal fails the assertion like a timeout: if the signal is aborted while the assertion is retrying, or is already aborted before the assertion starts, the assertion fails without retrying further. - `timeout` [number] *(optional)*# Time to retry the assertion for in milliseconds. Defaults to `timeout` in `TestConfig.expect`. @@ -492,6 +534,9 @@ await expect(locator).toHaveAccessibleName('Save to disk'); - `ignoreCase` [boolean] *(optional)*# Whether to perform case-insensitive match. [ignoreCase](/api/class-locatorassertions.mdx#locator-assertions-to-have-accessible-name-option-ignore-case) option takes precedence over the corresponding regular expression flag if specified. + - `signal` [AbortSignal] *(optional)* Added in: v1.62# + + An optional [`AbortSignal`](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal) that can cancel the assertion. Aborting the signal fails the assertion like a timeout: if the signal is aborted while the assertion is retrying, or is already aborted before the assertion starts, the assertion fails without retrying further. - `timeout` [number] *(optional)*# Time to retry the assertion for in milliseconds. Defaults to `timeout` in `TestConfig.expect`. @@ -525,6 +570,9 @@ await expect(locator).toHaveAttribute('type', 'text'); - `ignoreCase` [boolean] *(optional)* Added in: v1.40# Whether to perform case-insensitive match. [ignoreCase](/api/class-locatorassertions.mdx#locator-assertions-to-have-attribute-option-ignore-case) option takes precedence over the corresponding regular expression flag if specified. + - `signal` [AbortSignal] *(optional)* Added in: v1.62# + + An optional [`AbortSignal`](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal) that can cancel the assertion. Aborting the signal fails the assertion like a timeout: if the signal is aborted while the assertion is retrying, or is already aborted before the assertion starts, the assertion fails without retrying further. - `timeout` [number] *(optional)* Added in: v1.18# Time to retry the assertion for in milliseconds. Defaults to `timeout` in `TestConfig.expect`. @@ -559,6 +607,9 @@ await expect(locator).toHaveAttribute(name, options); Attribute name. - `options` [Object] *(optional)* + - `signal` [AbortSignal] *(optional)* Added in: v1.62# + + An optional [`AbortSignal`](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal) that can cancel the assertion. Aborting the signal fails the assertion like a timeout: if the signal is aborted while the assertion is retrying, or is already aborted before the assertion starts, the assertion fails without retrying further. - `timeout` [number] *(optional)*# Time to retry the assertion for in milliseconds. Defaults to `timeout` in `TestConfig.expect`. @@ -598,6 +649,9 @@ await expect(locator).toHaveClass(['component', 'component selected', 'component Expected class or RegExp or a list of those. - `options` [Object] *(optional)* + - `signal` [AbortSignal] *(optional)* Added in: v1.62# + + An optional [`AbortSignal`](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal) that can cancel the assertion. Aborting the signal fails the assertion like a timeout: if the signal is aborted while the assertion is retrying, or is already aborted before the assertion starts, the assertion fails without retrying further. - `timeout` [number] *(optional)* Added in: v1.18# Time to retry the assertion for in milliseconds. Defaults to `timeout` in `TestConfig.expect`. @@ -625,6 +679,9 @@ await expect(list).toHaveCount(3); Expected count. - `options` [Object] *(optional)* + - `signal` [AbortSignal] *(optional)* Added in: v1.62# + + An optional [`AbortSignal`](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal) that can cancel the assertion. Aborting the signal fails the assertion like a timeout: if the signal is aborted while the assertion is retrying, or is already aborted before the assertion starts, the assertion fails without retrying further. - `timeout` [number] *(optional)* Added in: v1.18# Time to retry the assertion for in milliseconds. Defaults to `timeout` in `TestConfig.expect`. @@ -658,6 +715,9 @@ await expect(locator).toHaveCSS('display', 'flex'); - `pseudo` "before" | "after" *(optional)* Added in: v1.60# Pseudo-element to read computed styles from. + - `signal` [AbortSignal] *(optional)* Added in: v1.62# + + An optional [`AbortSignal`](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal) that can cancel the assertion. Aborting the signal fails the assertion like a timeout: if the signal is aborted while the assertion is retrying, or is already aborted before the assertion starts, the assertion fails without retrying further. - `timeout` [number] *(optional)* Added in: v1.18# Time to retry the assertion for in milliseconds. Defaults to `timeout` in `TestConfig.expect`. @@ -685,6 +745,9 @@ await expect(locator).toHaveId('lastname'); Element id. - `options` [Object] *(optional)* + - `signal` [AbortSignal] *(optional)* Added in: v1.62# + + An optional [`AbortSignal`](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal) that can cancel the assertion. Aborting the signal fails the assertion like a timeout: if the signal is aborted while the assertion is retrying, or is already aborted before the assertion starts, the assertion fails without retrying further. - `timeout` [number] *(optional)* Added in: v1.18# Time to retry the assertion for in milliseconds. Defaults to `timeout` in `TestConfig.expect`. @@ -715,6 +778,9 @@ await expect(locator).toHaveJSProperty('loaded', true); Property value. - `options` [Object] *(optional)* + - `signal` [AbortSignal] *(optional)* Added in: v1.62# + + An optional [`AbortSignal`](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal) that can cancel the assertion. Aborting the signal fails the assertion like a timeout: if the signal is aborted while the assertion is retrying, or is already aborted before the assertion starts, the assertion fails without retrying further. - `timeout` [number] *(optional)* Added in: v1.18# Time to retry the assertion for in milliseconds. Defaults to `timeout` in `TestConfig.expect`. @@ -744,6 +810,9 @@ await expect(locator).toHaveRole('button'); Required aria role. - `options` [Object] *(optional)* + - `signal` [AbortSignal] *(optional)* Added in: v1.62# + + An optional [`AbortSignal`](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal) that can cancel the assertion. Aborting the signal fails the assertion like a timeout: if the signal is aborted while the assertion is retrying, or is already aborted before the assertion starts, the assertion fails without retrying further. - `timeout` [number] *(optional)*# Time to retry the assertion for in milliseconds. Defaults to `timeout` in `TestConfig.expect`. @@ -764,6 +833,9 @@ This function will wait until two consecutive locator screenshots yield the same ```js const locator = page.getByRole('button'); await expect(locator).toHaveScreenshot('image.png'); + +// Store the snapshot in the WebP format. +await expect(locator).toHaveScreenshot('image.webp'); ``` Note that screenshot assertions only work with Playwright test runner. @@ -771,7 +843,7 @@ Note that screenshot assertions only work with Playwright test runner. **Arguments** - `name` [string] | [Array]<[string]># - Snapshot name. + Snapshot name. Must have a `.png` or `.webp` extension, the screenshot is captured in the corresponding format. Both formats are lossless. - `options` [Object] *(optional)* - `animations` "disabled" | "allow" *(optional)*# @@ -803,6 +875,9 @@ Note that screenshot assertions only work with Playwright test runner. 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 `"css"`. + - `signal` [AbortSignal] *(optional)* Added in: v1.62# + + An optional [`AbortSignal`](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal) that can cancel the assertion. Aborting the signal fails the assertion like a timeout: if the signal is aborted while the assertion is retrying, or is already aborted before the assertion starts, the assertion fails without retrying further. - `stylePath` [string] | [Array]<[string]> *(optional)* Added in: v1.41# File name containing the stylesheet to apply while making the screenshot. This is where you can hide dynamic elements, make elements invisible or change their properties to help you creating repeatable screenshots. This stylesheet pierces the Shadow DOM and applies to the inner frames. @@ -824,6 +899,8 @@ Note that screenshot assertions only work with Playwright test runner. This function will wait until two consecutive locator screenshots yield the same result, and then compare the last screenshot with the expectation. +The snapshot is stored in the PNG format. To store it in the WebP format instead, pass a snapshot name with the `.webp` extension. + **Usage** ```js @@ -865,6 +942,9 @@ Note that screenshot assertions only work with Playwright test runner. 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 `"css"`. + - `signal` [AbortSignal] *(optional)* Added in: v1.62# + + An optional [`AbortSignal`](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal) that can cancel the assertion. Aborting the signal fails the assertion like a timeout: if the signal is aborted while the assertion is retrying, or is already aborted before the assertion starts, the assertion fails without retrying further. - `stylePath` [string] | [Array]<[string]> *(optional)* Added in: v1.41# File name containing the stylesheet to apply while making the screenshot. This is where you can hide dynamic elements, make elements invisible or change their properties to help you creating repeatable screenshots. This stylesheet pierces the Shadow DOM and applies to the inner frames. @@ -933,6 +1013,9 @@ await expect(page.locator('ul')).toHaveText(['Text 1', 'Text 2', 'Text 3']); - `ignoreCase` [boolean] *(optional)* Added in: v1.23# Whether to perform case-insensitive match. [ignoreCase](/api/class-locatorassertions.mdx#locator-assertions-to-have-text-option-ignore-case) option takes precedence over the corresponding regular expression flag if specified. + - `signal` [AbortSignal] *(optional)* Added in: v1.62# + + An optional [`AbortSignal`](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal) that can cancel the assertion. Aborting the signal fails the assertion like a timeout: if the signal is aborted while the assertion is retrying, or is already aborted before the assertion starts, the assertion fails without retrying further. - `timeout` [number] *(optional)* Added in: v1.18# Time to retry the assertion for in milliseconds. Defaults to `timeout` in `TestConfig.expect`. @@ -967,6 +1050,9 @@ await expect(locator).toHaveValue(/[0-9]/); Expected value. - `options` [Object] *(optional)* + - `signal` [AbortSignal] *(optional)* Added in: v1.62# + + An optional [`AbortSignal`](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal) that can cancel the assertion. Aborting the signal fails the assertion like a timeout: if the signal is aborted while the assertion is retrying, or is already aborted before the assertion starts, the assertion fails without retrying further. - `timeout` [number] *(optional)* Added in: v1.18# Time to retry the assertion for in milliseconds. Defaults to `timeout` in `TestConfig.expect`. @@ -1005,6 +1091,9 @@ await expect(locator).toHaveValues([/R/, /G/]); Expected options currently selected. - `options` [Object] *(optional)* + - `signal` [AbortSignal] *(optional)* Added in: v1.62# + + An optional [`AbortSignal`](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal) that can cancel the assertion. Aborting the signal fails the assertion like a timeout: if the signal is aborted while the assertion is retrying, or is already aborted before the assertion starts, the assertion fails without retrying further. - `timeout` [number] *(optional)*# Time to retry the assertion for in milliseconds. Defaults to `timeout` in `TestConfig.expect`. @@ -1033,6 +1122,9 @@ await expect(page.locator('body')).toMatchAriaSnapshot(` **Arguments** - `expected` [string]# - `options` [Object] *(optional)* + - `signal` [AbortSignal] *(optional)* Added in: v1.62# + + An optional [`AbortSignal`](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal) that can cancel the assertion. Aborting the signal fails the assertion like a timeout: if the signal is aborted while the assertion is retrying, or is already aborted before the assertion starts, the assertion fails without retrying further. - `timeout` [number] *(optional)*# Time to retry the assertion for in milliseconds. Defaults to `timeout` in `TestConfig.expect`. @@ -1062,6 +1154,9 @@ await expect(page.locator('body')).toMatchAriaSnapshot({ name: 'body.aria.yml' } - `name` [string] *(optional)*# Name of the snapshot to store in the snapshot folder corresponding to this test. Generates sequential names if not specified. + - `signal` [AbortSignal] *(optional)* Added in: v1.62# + + An optional [`AbortSignal`](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal) that can cancel the assertion. Aborting the signal fails the assertion like a timeout: if the signal is aborted while the assertion is retrying, or is already aborted before the assertion starts, the assertion fails without retrying further. - `timeout` [number] *(optional)*# Time to retry the assertion for in milliseconds. Defaults to `timeout` in `TestConfig.expect`. @@ -1162,6 +1257,7 @@ await expect(locator).not.toContainText('error'); [TestCase]: /api/class-testcase.mdx "TestCase" [TestError]: /api/class-testerror.mdx "TestError" [TestResult]: /api/class-testresult.mdx "TestResult" +[TestRun]: /api/class-testrun.mdx "TestRun" [TestStep]: /api/class-teststep.mdx "TestStep" [Element]: https://developer.mozilla.org/en-US/docs/Web/API/element "Element" [EvaluationArgument]: /evaluating.mdx#evaluation-argument "EvaluationArgument" diff --git a/nodejs/versioned_docs/version-stable/api/class-logger.mdx b/nodejs/versioned_docs/version-stable/api/class-logger.mdx index 1ccc47132e..f1f6307def 100644 --- a/nodejs/versioned_docs/version-stable/api/class-logger.mdx +++ b/nodejs/versioned_docs/version-stable/api/class-logger.mdx @@ -156,6 +156,7 @@ logger.log(name, severity, message, args, hints); [TestCase]: /api/class-testcase.mdx "TestCase" [TestError]: /api/class-testerror.mdx "TestError" [TestResult]: /api/class-testresult.mdx "TestResult" +[TestRun]: /api/class-testrun.mdx "TestRun" [TestStep]: /api/class-teststep.mdx "TestStep" [Element]: https://developer.mozilla.org/en-US/docs/Web/API/element "Element" [EvaluationArgument]: /evaluating.mdx#evaluation-argument "EvaluationArgument" diff --git a/nodejs/versioned_docs/version-stable/api/class-mouse.mdx b/nodejs/versioned_docs/version-stable/api/class-mouse.mdx index 4c0300d8eb..8fbbe6d65c 100644 --- a/nodejs/versioned_docs/version-stable/api/class-mouse.mdx +++ b/nodejs/versioned_docs/version-stable/api/class-mouse.mdx @@ -285,6 +285,7 @@ await mouse.wheel(deltaX, deltaY); [TestCase]: /api/class-testcase.mdx "TestCase" [TestError]: /api/class-testerror.mdx "TestError" [TestResult]: /api/class-testresult.mdx "TestResult" +[TestRun]: /api/class-testrun.mdx "TestRun" [TestStep]: /api/class-teststep.mdx "TestStep" [Element]: https://developer.mozilla.org/en-US/docs/Web/API/element "Element" [EvaluationArgument]: /evaluating.mdx#evaluation-argument "EvaluationArgument" diff --git a/nodejs/versioned_docs/version-stable/api/class-page.mdx b/nodejs/versioned_docs/version-stable/api/class-page.mdx index 5f420ec10d..9cff3523d8 100644 --- a/nodejs/versioned_docs/version-stable/api/class-page.mdx +++ b/nodejs/versioned_docs/version-stable/api/class-page.mdx @@ -95,6 +95,10 @@ The order of evaluation of multiple scripts installed via [browserContext.addIni - `arg` [Serializable] *(optional)*# Optional argument to pass to [script](/api/class-page.mdx#page-add-init-script-option-script) (only supported when passing a function). +- `options` [Object] *(optional)* + - `exposeFunctions` [boolean] *(optional)* Added in: v1.62# + + When set to `true`, functions passed inside [arg](/api/class-page.mdx#page-add-init-script-option-arg) are exposed in the page and can be called from the init script. Calling one returns a [Promise] of its result. Under the hood, each function is exposed via [page.exposeFunction()](/api/class-page.mdx#page-expose-function), so it is technically accessible from all frames and worlds of the page. Unlike functions passed to [page.evaluate()](/api/class-page.mdx#page-evaluate), functions passed to an init script are exposed in every new document, so they survive navigations. Defaults to `false`, in which case functions are not serializable and are silently dropped. **Returns** - [Promise]<[Disposable]># @@ -281,6 +285,9 @@ await page.ariaSnapshot(options); - `mode` "ai" | "default" *(optional)*# When set to `"ai"`, returns a snapshot optimized for AI consumption: including element references like `[ref=e2]` and snapshots of `