diff --git a/dotnet/docs/api/class-browsercontext.mdx b/dotnet/docs/api/class-browsercontext.mdx index 2499945640..71d36105ea 100644 --- a/dotnet/docs/api/class-browsercontext.mdx +++ b/dotnet/docs/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/docs/api/class-credentials.mdx b/dotnet/docs/api/class-credentials.mdx index a80ab3288b..651ece10e1 100644 --- a/dotnet/docs/api/class-credentials.mdx +++ b/dotnet/docs/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/docs/api/class-elementhandle.mdx b/dotnet/docs/api/class-elementhandle.mdx index fffa2f817f..8cc84ec85b 100644 --- a/dotnet/docs/api/class-elementhandle.mdx +++ b/dotnet/docs/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. @@ -1271,6 +1283,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 +1403,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 +1533,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/docs/api/class-frame.mdx b/dotnet/docs/api/class-frame.mdx index 15c70e31f1..12e81e4d6b 100644 --- a/dotnet/docs/api/class-frame.mdx +++ b/dotnet/docs/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] @@ -489,6 +492,11 @@ await page Required aria role. - `options` `FrameGetByRoleOptions?` *(optional)* + - `Busy` [bool]? *(optional)* Added in: v1.61# + + An attribute that is usually set by `aria-busy`. + + Learn more about [`aria-busy`](https://www.w3.org/TR/wai-aria-1.2/#aria-busy). - `Checked` [bool]? *(optional)*# An attribute that is usually set by `aria-checked` or native `` controls. @@ -1125,6 +1133,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 +1213,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 +1294,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 +1641,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 +2323,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 +2454,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 +2607,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/docs/api/class-framelocator.mdx b/dotnet/docs/api/class-framelocator.mdx index 30a08b164e..ea174e8d30 100644 --- a/dotnet/docs/api/class-framelocator.mdx +++ b/dotnet/docs/api/class-framelocator.mdx @@ -206,6 +206,11 @@ await page Required aria role. - `options` `FrameLocatorGetByRoleOptions?` *(optional)* + - `Busy` [bool]? *(optional)* Added in: v1.61# + + An attribute that is usually set by `aria-busy`. + + Learn more about [`aria-busy`](https://www.w3.org/TR/wai-aria-1.2/#aria-busy). - `Checked` [bool]? *(optional)*# An attribute that is usually set by `aria-checked` or native `` controls. diff --git a/dotnet/docs/api/class-locator.mdx b/dotnet/docs/api/class-locator.mdx index ea563477ff..991a5c42b9 100644 --- a/dotnet/docs/api/class-locator.mdx +++ b/dotnet/docs/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] @@ -1214,6 +1226,11 @@ await page Required aria role. - `options` `LocatorGetByRoleOptions?` *(optional)* + - `Busy` [bool]? *(optional)* Added in: v1.61# + + An attribute that is usually set by `aria-busy`. + + Learn more about [`aria-busy`](https://www.w3.org/TR/wai-aria-1.2/#aria-busy). - `Checked` [bool]? *(optional)*# An attribute that is usually set by `aria-checked` or native `` controls. @@ -1478,6 +1495,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. @@ -2248,6 +2268,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 +2396,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 +2488,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 +2549,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/docs/api/class-page.mdx b/dotnet/docs/api/class-page.mdx index 1a8e3ab0c2..b1c6c4a17d 100644 --- a/dotnet/docs/api/class-page.mdx +++ b/dotnet/docs/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] @@ -1015,6 +1018,11 @@ await page Required aria role. - `options` `PageGetByRoleOptions?` *(optional)* + - `Busy` [bool]? *(optional)* Added in: v1.61# + + An attribute that is usually set by `aria-busy`. + + Learn more about [`aria-busy`](https://www.w3.org/TR/wai-aria-1.2/#aria-busy). - `Checked` [bool]? *(optional)*# An attribute that is usually set by `aria-checked` or native `` controls. @@ -3471,6 +3479,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 +3559,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 +3640,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 +3982,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 +4695,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 +4826,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 +4979,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/docs/auth.mdx b/dotnet/docs/auth.mdx index e3a858646e..01826619fc 100644 --- a/dotnet/docs/auth.mdx +++ b/dotnet/docs/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/docs/ci.mdx b/dotnet/docs/ci.mdx index 862e37f0df..70ae0ce978 100644 --- a/dotnet/docs/ci.mdx +++ b/dotnet/docs/ci.mdx @@ -76,7 +76,7 @@ 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 @@ -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/docs/docker.mdx b/dotnet/docs/docker.mdx index 294027150e..c4c21db04f 100644 --- a/dotnet/docs/docker.mdx +++ b/dotnet/docs/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,10 +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.60.0-resolute` - Playwright v1.60.0 release docker image based on Ubuntu 26.04 LTS (Resolute Raccoon). +- `: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 diff --git a/java/docs/api/class-browsercontext.mdx b/java/docs/api/class-browsercontext.mdx index 5ee4b460b5..733835fe36 100644 --- a/java/docs/api/class-browsercontext.mdx +++ b/java/docs/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/docs/api/class-credentials.mdx b/java/docs/api/class-credentials.mdx index cf6fd16892..63d0660522 100644 --- a/java/docs/api/class-credentials.mdx +++ b/java/docs/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/docs/api/class-elementhandle.mdx b/java/docs/api/class-elementhandle.mdx index f874bdcab0..e293a262b4 100644 --- a/java/docs/api/class-elementhandle.mdx +++ b/java/docs/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. @@ -1278,6 +1290,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 +1412,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 +1543,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/docs/api/class-frame.mdx b/java/docs/api/class-frame.mdx index 7a755a47fe..27c0b84e8a 100644 --- a/java/docs/api/class-frame.mdx +++ b/java/docs/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] @@ -489,6 +492,11 @@ page.getByRole(AriaRole.BUTTON, Required aria role. - `options` `Frame.GetByRoleOptions` *(optional)* + - `setBusy` [boolean] *(optional)* Added in: v1.61# + + An attribute that is usually set by `aria-busy`. + + Learn more about [`aria-busy`](https://www.w3.org/TR/wai-aria-1.2/#aria-busy). - `setChecked` [boolean] *(optional)*# An attribute that is usually set by `aria-checked` or native `` controls. @@ -1130,6 +1138,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 +1219,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 +1301,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 +1654,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 +2240,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 +2373,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 +2528,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/docs/api/class-framelocator.mdx b/java/docs/api/class-framelocator.mdx index 406f921089..73c31b8d76 100644 --- a/java/docs/api/class-framelocator.mdx +++ b/java/docs/api/class-framelocator.mdx @@ -204,6 +204,11 @@ page.getByRole(AriaRole.BUTTON, Required aria role. - `options` `FrameLocator.GetByRoleOptions` *(optional)* + - `setBusy` [boolean] *(optional)* Added in: v1.61# + + An attribute that is usually set by `aria-busy`. + + Learn more about [`aria-busy`](https://www.w3.org/TR/wai-aria-1.2/#aria-busy). - `setChecked` [boolean] *(optional)*# An attribute that is usually set by `aria-checked` or native `` controls. diff --git a/java/docs/api/class-locator.mdx b/java/docs/api/class-locator.mdx index 13a378886d..0135fa50b9 100644 --- a/java/docs/api/class-locator.mdx +++ b/java/docs/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] @@ -1214,6 +1226,11 @@ page.getByRole(AriaRole.BUTTON, Required aria role. - `options` `Locator.GetByRoleOptions` *(optional)* + - `setBusy` [boolean] *(optional)* Added in: v1.61# + + An attribute that is usually set by `aria-busy`. + + Learn more about [`aria-busy`](https://www.w3.org/TR/wai-aria-1.2/#aria-busy). - `setChecked` [boolean] *(optional)*# An attribute that is usually set by `aria-checked` or native `` controls. @@ -1479,6 +1496,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. @@ -2253,6 +2273,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 +2398,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 +2491,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 +2552,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/docs/api/class-page.mdx b/java/docs/api/class-page.mdx index 25a3ec9bf2..581cd892b2 100644 --- a/java/docs/api/class-page.mdx +++ b/java/docs/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] @@ -1019,6 +1022,11 @@ page.getByRole(AriaRole.BUTTON, Required aria role. - `options` `Page.GetByRoleOptions` *(optional)* + - `setBusy` [boolean] *(optional)* Added in: v1.61# + + An attribute that is usually set by `aria-busy`. + + Learn more about [`aria-busy`](https://www.w3.org/TR/wai-aria-1.2/#aria-busy). - `setChecked` [boolean] *(optional)*# An attribute that is usually set by `aria-checked` or native `` controls. @@ -3339,6 +3347,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 +3428,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 +3510,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 +3859,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 +4476,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 +4609,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 +4764,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/docs/auth.mdx b/java/docs/auth.mdx index ee32fbdbe5..a4d43695ed 100644 --- a/java/docs/auth.mdx +++ b/java/docs/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/nodejs/docs/api/class-browsercontext.mdx b/nodejs/docs/api/class-browsercontext.mdx index 0a742780cf..496bd41de6 100644 --- a/nodejs/docs/api/class-browsercontext.mdx +++ b/nodejs/docs/api/class-browsercontext.mdx @@ -842,7 +842,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 +907,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 +918,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. diff --git a/nodejs/docs/api/class-credentials.mdx b/nodejs/docs/api/class-credentials.mdx index 199a9c0123..67daf6f66d 100644 --- a/nodejs/docs/api/class-credentials.mdx +++ b/nodejs/docs/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** diff --git a/nodejs/docs/api/class-elementhandle.mdx b/nodejs/docs/api/class-elementhandle.mdx index aeb75e198b..fca9fe2de8 100644 --- a/nodejs/docs/api/class-elementhandle.mdx +++ b/nodejs/docs/api/class-elementhandle.mdx @@ -356,6 +356,9 @@ 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. - `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 +432,9 @@ 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. - `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 +512,9 @@ 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. - `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. @@ -728,6 +737,9 @@ 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. - `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 +1294,9 @@ 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. - `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 +1416,9 @@ 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. - `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 +1547,9 @@ 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. - `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. diff --git a/nodejs/docs/api/class-frame.mdx b/nodejs/docs/api/class-frame.mdx index 05ad899007..a89bdbc3f8 100644 --- a/nodejs/docs/api/class-frame.mdx +++ b/nodejs/docs/api/class-frame.mdx @@ -168,6 +168,9 @@ 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. - `sourcePosition` [Object] *(optional)* Added in: v1.14# - `x` [number] @@ -482,6 +485,11 @@ await page.getByRole('button', { name: /submit/i }).click(); Required aria role. - `options` [Object] *(optional)* + - `busy` [boolean] *(optional)* Added in: v1.61# + + An attribute that is usually set by `aria-busy`. + + Learn more about [`aria-busy`](https://www.w3.org/TR/wai-aria-1.2/#aria-busy). - `checked` [boolean] *(optional)*# An attribute that is usually set by `aria-checked` or native `` controls. @@ -1297,6 +1305,9 @@ 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. - `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. @@ -1375,6 +1386,9 @@ 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. - `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. @@ -1454,6 +1468,9 @@ 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. - `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. @@ -1718,6 +1735,9 @@ 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. - `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. @@ -2226,6 +2246,9 @@ 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. - `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. @@ -2356,6 +2379,9 @@ 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. - `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. @@ -2508,6 +2534,9 @@ 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. - `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. diff --git a/nodejs/docs/api/class-framelocator.mdx b/nodejs/docs/api/class-framelocator.mdx index 765ca05c57..1d1b7c394a 100644 --- a/nodejs/docs/api/class-framelocator.mdx +++ b/nodejs/docs/api/class-framelocator.mdx @@ -198,6 +198,11 @@ await page.getByRole('button', { name: /submit/i }).click(); Required aria role. - `options` [Object] *(optional)* + - `busy` [boolean] *(optional)* Added in: v1.61# + + An attribute that is usually set by `aria-busy`. + + Learn more about [`aria-busy`](https://www.w3.org/TR/wai-aria-1.2/#aria-busy). - `checked` [boolean] *(optional)*# An attribute that is usually set by `aria-checked` or native `` controls. diff --git a/nodejs/docs/api/class-locator.mdx b/nodejs/docs/api/class-locator.mdx index aa483e900e..7299475e61 100644 --- a/nodejs/docs/api/class-locator.mdx +++ b/nodejs/docs/api/class-locator.mdx @@ -273,6 +273,9 @@ 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. - `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 +398,9 @@ 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. - `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 +517,9 @@ 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. - `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. @@ -676,6 +685,9 @@ 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. - `sourcePosition` [Object] *(optional)*# - `x` [number] @@ -1222,6 +1234,11 @@ await page.getByRole('button', { name: /submit/i }).click(); Required aria role. - `options` [Object] *(optional)* + - `busy` [boolean] *(optional)* Added in: v1.61# + + An attribute that is usually set by `aria-busy`. + + Learn more about [`aria-busy`](https://www.w3.org/TR/wai-aria-1.2/#aria-busy). - `checked` [boolean] *(optional)*# An attribute that is usually set by `aria-checked` or native `` controls. @@ -1503,6 +1520,9 @@ 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. - `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 +2297,9 @@ 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. - `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 +2428,9 @@ 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. - `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 +2538,9 @@ 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. - `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. @@ -2570,6 +2599,53 @@ 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)* + - `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 */} diff --git a/nodejs/docs/api/class-page.mdx b/nodejs/docs/api/class-page.mdx index dcc52ffbcf..ef02dd82d7 100644 --- a/nodejs/docs/api/class-page.mdx +++ b/nodejs/docs/api/class-page.mdx @@ -486,6 +486,9 @@ await page.dragAndDrop('#source', '#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. - `sourcePosition` [Object] *(optional)* Added in: v1.14# - `x` [number] @@ -994,6 +997,11 @@ await page.getByRole('button', { name: /submit/i }).click(); Required aria role. - `options` [Object] *(optional)* + - `busy` [boolean] *(optional)* Added in: v1.61# + + An attribute that is usually set by `aria-busy`. + + Learn more about [`aria-busy`](https://www.w3.org/TR/wai-aria-1.2/#aria-busy). - `checked` [boolean] *(optional)*# An attribute that is usually set by `aria-checked` or native `` controls. @@ -3292,6 +3300,9 @@ await 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. + - `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. - `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. @@ -3370,6 +3381,9 @@ await 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. + - `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. - `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. @@ -3449,6 +3463,9 @@ await 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. + - `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. - `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. @@ -3713,6 +3730,9 @@ await 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. + - `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. - `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. @@ -4268,6 +4288,9 @@ await 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. + - `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. - `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. @@ -4398,6 +4421,9 @@ await 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. + - `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. - `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. @@ -4550,6 +4576,9 @@ await 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. + - `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. - `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. diff --git a/nodejs/docs/api/class-testconfig.mdx b/nodejs/docs/api/class-testconfig.mdx index 6ae75ed957..25659cdb2e 100644 --- a/nodejs/docs/api/class-testconfig.mdx +++ b/nodejs/docs/api/class-testconfig.mdx @@ -674,6 +674,32 @@ export default defineConfig({ --- +### retryStrategy {/* #test-config-retry-strategy */} + +Added in: v1.62testConfig.retryStrategy + +Controls when failed tests are retried. Defaults to `'immediate'`. +* `'immediate'` - A failed test is retried as soon as a worker is available, interleaved with the rest of the run. This is the default. +* `'deferred'` - Retries are run only after all tests have had their first attempt, in parallel up to the configured number of [workers](#test-config-workers). + +Learn more about [test retries](../test-retries.mdx#retries). + +**Usage** + +```js title="playwright.config.ts" +import { defineConfig } from '@playwright/test'; + +export default defineConfig({ + retries: 2, + retryStrategy: 'deferred', +}); +``` + +**Type** +- "immediate" | "deferred" + +--- + ### shard {/* #test-config-shard */} Added in: v1.10testConfig.shard diff --git a/nodejs/docs/auth.mdx b/nodejs/docs/auth.mdx index 9341c481f2..2db5854a86 100644 --- a/nodejs/docs/auth.mdx +++ b/nodejs/docs/auth.mdx @@ -307,73 +307,6 @@ export const test = baseTest.extend<{}, { workerStorageState: string }>({ }); ``` -### Passkeys (WebAuthn) - -**When to use** -- Your app signs users in with passkeys (WebAuthn), and you want tests to start already enrolled. - -**Details** - -[browserContext.credentials](/api/class-browsercontext.mdx#browser-context-credentials) is a virtual WebAuthn authenticator. Unlike cookie or local storage state, a passkey is seeded **imperatively** with [credentials.create()](/api/class-credentials.mdx#credentials-create) and [credentials.install()](/api/class-credentials.mdx#credentials-install), so it lives in a [`context` fixture override](./test-fixtures.mdx#overriding-fixtures) rather than in the `storageState` config option. - -If your backend already provisioned a passkey for the test user, seed it directly — no setup project required: - -```js title="playwright/fixtures.ts" -import { test as baseTest } from '@playwright/test'; -export * from '@playwright/test'; - -export const test = baseTest.extend({ - context: async ({ context }, use) => { - // A passkey your backend provisioned for the test user. - await context.credentials.create('example.com', { - id: process.env.PASSKEY_ID, - userHandle: process.env.PASSKEY_USER_HANDLE, - privateKey: process.env.PASSKEY_PRIVATE_KEY, - publicKey: process.env.PASSKEY_PUBLIC_KEY, - }); - await context.credentials.install(); - await use(context); - }, -}); -``` - -Otherwise, let the app register a passkey once in a [setup project](#basic-shared-account-in-all-tests), capture it with [credentials.get()](/api/class-credentials.mdx#credentials-get), and save it to disk: - -```js title="tests/passkey.setup.ts" -import { test as setup } from '@playwright/test'; -import fs from 'fs'; - -setup('enroll passkey', async ({ context, page }) => { - await context.credentials.install(); - await page.goto('https://example.com/register'); - // The app calls navigator.credentials.create() to register the passkey. - await page.getByRole('button', { name: 'Create a passkey' }).click(); - - // Read back the registered passkey, including its private key, and save it. - const [credential] = await context.credentials.get({ rpId: 'example.com' }); - fs.writeFileSync('playwright/.auth/passkey.json', JSON.stringify(credential)); -}); -``` - -Then seed the captured passkey into every test's context: - -```js title="playwright/fixtures.ts" -import { test as baseTest } from '@playwright/test'; -import fs from 'fs'; -export * from '@playwright/test'; - -export const test = baseTest.extend({ - context: async ({ context }, use) => { - const credential = JSON.parse(fs.readFileSync('playwright/.auth/passkey.json', 'utf8')); - await context.credentials.create(credential.rpId, credential); - await context.credentials.install(); - await use(context); - }, -}); -``` - -Declare the `setup` project as a [dependency](./test-projects.mdx#dependencies) of your testing projects, just like in the [basic flow](#basic-shared-account-in-all-tests). The saved `passkey.json` contains a private key, so keep it under `playwright/.auth` and out of source control (see [Core concepts](#core-concepts)). - ### Multiple signed in roles **When to use** @@ -561,7 +494,7 @@ test('admin and user', async ({ adminPage, userPage }) => { ### 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. ```js // Get session storage and store as env variable diff --git a/nodejs/docs/ci.mdx b/nodejs/docs/ci.mdx index 6fe0ef9def..d4cda871e2 100644 --- a/nodejs/docs/ci.mdx +++ b/nodejs/docs/ci.mdx @@ -101,7 +101,7 @@ jobs: name: 'Playwright Tests' runs-on: ubuntu-latest container: - image: mcr.microsoft.com/playwright:v1.61.0-noble + image: mcr.microsoft.com/playwright:v1.61.1-noble options: --user 1001 steps: - uses: actions/checkout@v5 @@ -335,7 +335,7 @@ trigger: pool: vmImage: ubuntu-latest -container: mcr.microsoft.com/playwright:v1.61.0-noble +container: mcr.microsoft.com/playwright:v1.61.1-noble steps: - task: UseNode@1 @@ -359,7 +359,7 @@ Running Playwright on CircleCI is very similar to running on GitHub Actions. In executors: pw-noble-development: docker: - - image: mcr.microsoft.com/playwright:v1.61.0-noble + - image: mcr.microsoft.com/playwright:v1.61.1-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. @@ -382,7 +382,7 @@ Jenkins supports Docker agents for pipelines. Use the [Playwright Docker image]( ```groovy pipeline { - agent { docker { image 'mcr.microsoft.com/playwright:v1.61.0-noble' } } + agent { docker { image 'mcr.microsoft.com/playwright:v1.61.1-noble' } } stages { stage('e2e-tests') { steps { @@ -399,7 +399,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:v1.61.0-noble +image: mcr.microsoft.com/playwright:v1.61.1-noble ``` ### GitLab CI @@ -412,7 +412,7 @@ stages: tests: stage: test - image: mcr.microsoft.com/playwright:v1.61.0-noble + image: mcr.microsoft.com/playwright:v1.61.1-noble script: ... ``` @@ -427,7 +427,7 @@ stages: tests: stage: test - image: mcr.microsoft.com/playwright:v1.61.0-noble + image: mcr.microsoft.com/playwright:v1.61.1-noble parallel: 7 script: - npm ci @@ -442,7 +442,7 @@ stages: tests: stage: test - image: mcr.microsoft.com/playwright:v1.61.0-noble + image: mcr.microsoft.com/playwright:v1.61.1-noble parallel: matrix: - PROJECT: ['chromium', 'webkit'] @@ -458,7 +458,7 @@ To run Playwright tests on Google Cloud Build, use our public Docker image ([see ```yml steps: -- name: mcr.microsoft.com/playwright:v1.61.0-noble +- name: mcr.microsoft.com/playwright:v1.61.1-noble script: ... env: @@ -476,7 +476,7 @@ type: docker steps: - name: test - image: mcr.microsoft.com/playwright:v1.61.0-noble + image: mcr.microsoft.com/playwright:v1.61.1-noble commands: - npx playwright test ``` diff --git a/nodejs/docs/docker.mdx b/nodejs/docs/docker.mdx index 5da6482d6e..2017637c37 100644 --- a/nodejs/docs/docker.mdx +++ b/nodejs/docs/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:v1.61.0-noble +docker pull mcr.microsoft.com/playwright:v1.61.1-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:v1.61.0-noble /bin/bash +docker run -it --rm --ipc=host mcr.microsoft.com/playwright:v1.61.1-noble /bin/bash ``` #### Crawling and scraping @@ -42,7 +42,7 @@ docker run -it --rm --ipc=host mcr.microsoft.com/playwright:v1.61.0-noble /bin/b 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:v1.61.0-noble /bin/bash +docker run -it --rm --ipc=host --user pwuser --security-opt seccomp=seccomp_profile.json mcr.microsoft.com/playwright:v1.61.1-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.61.0-noble /bin/sh -c "npx -y playwright@1.61.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.1-noble /bin/sh -c "npx -y playwright@1.61.1 run-server --port 3000 --host 0.0.0.0" ``` #### Connecting to the Server @@ -105,7 +105,7 @@ const browser = await playwright['chromium'].connect('ws://127.0.0.1:3000/'); 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.61.0-noble /bin/sh -c "npx -y playwright@1.61.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.1-noble /bin/sh -c "npx -y playwright@1.61.1 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. @@ -138,10 +138,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.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). +- `:v1.61.1` - Playwright v1.61.1 release docker image based on Ubuntu 24.04 LTS (Noble Numbat). +- `:v1.61.1-noble` - Playwright v1.61.1 release docker image based on Ubuntu 24.04 LTS (Noble Numbat). +- `:v1.61.1-jammy` - Playwright v1.61.1 release docker image based on Ubuntu 22.04 LTS (Jammy Jellyfish). +- `:v1.61.1-resolute` - Playwright v1.61.1 release docker image based on Ubuntu 26.04 LTS (Resolute Raccoon). :::note @@ -166,7 +166,7 @@ To run Playwright inside Docker, you need to have Node.js, [Playwright browsers] ```Dockerfile FROM node:20-bookworm -RUN npx -y playwright@1.61.0 install --with-deps +RUN npx -y playwright@1.61.1 install --with-deps ``` diff --git a/python/docs/api/class-browsercontext.mdx b/python/docs/api/class-browsercontext.mdx index c4c8679d94..a9c85afa1f 100644 --- a/python/docs/api/class-browsercontext.mdx +++ b/python/docs/api/class-browsercontext.mdx @@ -1177,7 +1177,7 @@ browser_context.set_offline(offline) Added in: v1.59browserContext.set_storage_state -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** @@ -1263,7 +1263,7 @@ await context.set_storage_state("state.json") Added before v1.9browserContext.storage_state -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** @@ -1273,6 +1273,9 @@ browser_context.storage_state(**kwargs) ``` **Arguments** +- `credentials` [bool] *(optional)* Added in: v1.61# + + Set to `true` to include the context's virtual WebAuthn [browser_context.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 [storage_state](/api/class-browser.mdx#browser-new-context-option-storage-state) option or [browser_context.set_storage_state()](/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. - `indexed_db` [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/python/docs/api/class-credentials.mdx b/python/docs/api/class-credentials.mdx index d25bc8efee..3eea7824c2 100644 --- a/python/docs/api/class-credentials.mdx +++ b/python/docs/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** @@ -65,7 +65,7 @@ await page.goto("https://example.com/login") -**Usage: capture a passkey, then reuse it** +**Usage: capture a credential, then reuse it** +**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/python/docs/api/class-elementhandle.mdx b/python/docs/api/class-elementhandle.mdx index d27bdf3572..f7e34fce44 100644 --- a/python/docs/api/class-elementhandle.mdx +++ b/python/docs/api/class-elementhandle.mdx @@ -290,6 +290,9 @@ element_handle.check(**kwargs) 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. - `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 [browser_context.set_default_timeout()](/api/class-browsercontext.mdx#browser-context-set-default-timeout) or [page.set_default_timeout()](/api/class-page.mdx#page-set-default-timeout) methods. @@ -362,6 +365,9 @@ element_handle.click(**kwargs) 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. - `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. @@ -438,6 +444,9 @@ element_handle.dblclick(**kwargs) 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. - `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. @@ -831,6 +840,9 @@ element_handle.hover(**kwargs) 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. - `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 [browser_context.set_default_timeout()](/api/class-browsercontext.mdx#browser-context-set-default-timeout) or [page.set_default_timeout()](/api/class-page.mdx#page-set-default-timeout) methods. @@ -1459,6 +1471,9 @@ element_handle.set_checked(checked, **kwargs) 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. - `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 [browser_context.set_default_timeout()](/api/class-browsercontext.mdx#browser-context-set-default-timeout) or [page.set_default_timeout()](/api/class-page.mdx#page-set-default-timeout) methods. @@ -1576,6 +1591,9 @@ element_handle.tap(**kwargs) 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. - `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 [browser_context.set_default_timeout()](/api/class-browsercontext.mdx#browser-context-set-default-timeout) or [page.set_default_timeout()](/api/class-page.mdx#page-set-default-timeout) methods. @@ -1702,6 +1720,9 @@ element_handle.uncheck(**kwargs) 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. - `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 [browser_context.set_default_timeout()](/api/class-browsercontext.mdx#browser-context-set-default-timeout) or [page.set_default_timeout()](/api/class-page.mdx#page-set-default-timeout) methods. diff --git a/python/docs/api/class-frame.mdx b/python/docs/api/class-frame.mdx index d876c11ecc..57cae4a20c 100644 --- a/python/docs/api/class-frame.mdx +++ b/python/docs/api/class-frame.mdx @@ -191,6 +191,9 @@ frame.drag_and_drop(source, target, **kwargs) 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. - `source_position` [Dict] *(optional)* Added in: v1.14# - `x` [float] @@ -752,6 +755,11 @@ await page.get_by_role("button", name=re.compile("submit", re.IGNORECASE)).click - `role` "alert" | "alertdialog" | "application" | "article" | "banner" | "blockquote" | "button" | "caption" | "cell" | "checkbox" | "code" | "columnheader" | "combobox" | "complementary" | "contentinfo" | "definition" | "deletion" | "dialog" | "directory" | "document" | "emphasis" | "feed" | "figure" | "form" | "generic" | "grid" | "gridcell" | "group" | "heading" | "img" | "insertion" | "link" | "list" | "listbox" | "listitem" | "log" | "main" | "marquee" | "math" | "meter" | "menu" | "menubar" | "menuitem" | "menuitemcheckbox" | "menuitemradio" | "navigation" | "none" | "note" | "option" | "paragraph" | "presentation" | "progressbar" | "radio" | "radiogroup" | "region" | "row" | "rowgroup" | "rowheader" | "scrollbar" | "search" | "searchbox" | "separator" | "slider" | "spinbutton" | "status" | "strong" | "subscript" | "superscript" | "switch" | "tab" | "table" | "tablist" | "tabpanel" | "term" | "textbox" | "time" | "timer" | "toolbar" | "tooltip" | "tree" | "treegrid" | "treeitem"# Required aria role. +- `busy` [bool] *(optional)* Added in: v1.61# + + An attribute that is usually set by `aria-busy`. + + Learn more about [`aria-busy`](https://www.w3.org/TR/wai-aria-1.2/#aria-busy). - `checked` [bool] *(optional)*# An attribute that is usually set by `aria-checked` or native `` controls. @@ -1568,6 +1576,9 @@ frame.check(selector, **kwargs) 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. - `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. @@ -1645,6 +1656,9 @@ frame.click(selector, **kwargs) 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. - `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. @@ -1723,6 +1737,9 @@ frame.dblclick(selector, **kwargs) 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. - `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. @@ -2219,6 +2236,9 @@ frame.hover(selector, **kwargs) 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. - `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. @@ -2815,6 +2835,9 @@ frame.set_checked(selector, checked, **kwargs) 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. - `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. @@ -2943,6 +2966,9 @@ frame.tap(selector, **kwargs) 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. - `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. @@ -3092,6 +3118,9 @@ frame.uncheck(selector, **kwargs) 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. - `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/python/docs/api/class-framelocator.mdx b/python/docs/api/class-framelocator.mdx index 3f8e9e400e..24afd2dc38 100644 --- a/python/docs/api/class-framelocator.mdx +++ b/python/docs/api/class-framelocator.mdx @@ -322,6 +322,11 @@ await page.get_by_role("button", name=re.compile("submit", re.IGNORECASE)).click - `role` "alert" | "alertdialog" | "application" | "article" | "banner" | "blockquote" | "button" | "caption" | "cell" | "checkbox" | "code" | "columnheader" | "combobox" | "complementary" | "contentinfo" | "definition" | "deletion" | "dialog" | "directory" | "document" | "emphasis" | "feed" | "figure" | "form" | "generic" | "grid" | "gridcell" | "group" | "heading" | "img" | "insertion" | "link" | "list" | "listbox" | "listitem" | "log" | "main" | "marquee" | "math" | "meter" | "menu" | "menubar" | "menuitem" | "menuitemcheckbox" | "menuitemradio" | "navigation" | "none" | "note" | "option" | "paragraph" | "presentation" | "progressbar" | "radio" | "radiogroup" | "region" | "row" | "rowgroup" | "rowheader" | "scrollbar" | "search" | "searchbox" | "separator" | "slider" | "spinbutton" | "status" | "strong" | "subscript" | "superscript" | "switch" | "tab" | "table" | "tablist" | "tabpanel" | "term" | "textbox" | "time" | "timer" | "toolbar" | "tooltip" | "tree" | "treegrid" | "treeitem"# Required aria role. +- `busy` [bool] *(optional)* Added in: v1.61# + + An attribute that is usually set by `aria-busy`. + + Learn more about [`aria-busy`](https://www.w3.org/TR/wai-aria-1.2/#aria-busy). - `checked` [bool] *(optional)*# An attribute that is usually set by `aria-checked` or native `` controls. diff --git a/python/docs/api/class-locator.mdx b/python/docs/api/class-locator.mdx index 2f16c84256..96e9cd7fa7 100644 --- a/python/docs/api/class-locator.mdx +++ b/python/docs/api/class-locator.mdx @@ -411,6 +411,9 @@ await page.get_by_role("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. - `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 [browser_context.set_default_timeout()](/api/class-browsercontext.mdx#browser-context-set-default-timeout) or [page.set_default_timeout()](/api/class-page.mdx#page-set-default-timeout) methods. @@ -591,6 +594,9 @@ 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. - `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. @@ -702,6 +708,9 @@ locator.dblclick(**kwargs) 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. - `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. @@ -936,6 +945,9 @@ await source.drag_to( 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. - `source_position` [Dict] *(optional)*# - `x` [float] @@ -1627,6 +1639,11 @@ await page.get_by_role("button", name=re.compile("submit", re.IGNORECASE)).click - `role` "alert" | "alertdialog" | "application" | "article" | "banner" | "blockquote" | "button" | "caption" | "cell" | "checkbox" | "code" | "columnheader" | "combobox" | "complementary" | "contentinfo" | "definition" | "deletion" | "dialog" | "directory" | "document" | "emphasis" | "feed" | "figure" | "form" | "generic" | "grid" | "gridcell" | "group" | "heading" | "img" | "insertion" | "link" | "list" | "listbox" | "listitem" | "log" | "main" | "marquee" | "math" | "meter" | "menu" | "menubar" | "menuitem" | "menuitemcheckbox" | "menuitemradio" | "navigation" | "none" | "note" | "option" | "paragraph" | "presentation" | "progressbar" | "radio" | "radiogroup" | "region" | "row" | "rowgroup" | "rowheader" | "scrollbar" | "search" | "searchbox" | "separator" | "slider" | "spinbutton" | "status" | "strong" | "subscript" | "superscript" | "switch" | "tab" | "table" | "tablist" | "tabpanel" | "term" | "textbox" | "time" | "timer" | "toolbar" | "tooltip" | "tree" | "treegrid" | "treeitem"# Required aria role. +- `busy` [bool] *(optional)* Added in: v1.61# + + An attribute that is usually set by `aria-busy`. + + Learn more about [`aria-busy`](https://www.w3.org/TR/wai-aria-1.2/#aria-busy). - `checked` [bool] *(optional)*# An attribute that is usually set by `aria-checked` or native `` controls. @@ -1981,6 +1998,9 @@ await page.get_by_role("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. - `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 [browser_context.set_default_timeout()](/api/class-browsercontext.mdx#browser-context-set-default-timeout) or [page.set_default_timeout()](/api/class-page.mdx#page-set-default-timeout) methods. @@ -3035,6 +3055,9 @@ await page.get_by_role("checkbox").set_checked(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. - `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 [browser_context.set_default_timeout()](/api/class-browsercontext.mdx#browser-context-set-default-timeout) or [page.set_default_timeout()](/api/class-page.mdx#page-set-default-timeout) methods. @@ -3195,6 +3218,9 @@ locator.tap(**kwargs) 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. - `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 [browser_context.set_default_timeout()](/api/class-browsercontext.mdx#browser-context-set-default-timeout) or [page.set_default_timeout()](/api/class-page.mdx#page-set-default-timeout) methods. @@ -3303,6 +3329,9 @@ await page.get_by_role("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. - `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 [browser_context.set_default_timeout()](/api/class-browsercontext.mdx#browser-context-set-default-timeout) or [page.set_default_timeout()](/api/class-page.mdx#page-set-default-timeout) methods. @@ -3381,6 +3410,40 @@ await order_sent.wait_for() --- +### wait_for_function {/* #locator-wait-for-function */} + +Added in: v1.62locator.wait_for_function + +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` [str]# + + 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). +- `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 [browser_context.set_default_timeout()](/api/class-browsercontext.mdx#browser-context-set-default-timeout) or [page.set_default_timeout()](/api/class-page.mdx#page-set-default-timeout) methods. + +**Returns** +- [NoneType]# + +--- + ## Properties ### content_frame {/* #locator-content-frame */} diff --git a/python/docs/api/class-page.mdx b/python/docs/api/class-page.mdx index 7436478859..7edd8c80dd 100644 --- a/python/docs/api/class-page.mdx +++ b/python/docs/api/class-page.mdx @@ -641,6 +641,9 @@ await page.drag_and_drop( 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. - `source_position` [Dict] *(optional)* Added in: v1.14# - `x` [float] @@ -1866,6 +1869,11 @@ await page.get_by_role("button", name=re.compile("submit", re.IGNORECASE)).click - `role` "alert" | "alertdialog" | "application" | "article" | "banner" | "blockquote" | "button" | "caption" | "cell" | "checkbox" | "code" | "columnheader" | "combobox" | "complementary" | "contentinfo" | "definition" | "deletion" | "dialog" | "directory" | "document" | "emphasis" | "feed" | "figure" | "form" | "generic" | "grid" | "gridcell" | "group" | "heading" | "img" | "insertion" | "link" | "list" | "listbox" | "listitem" | "log" | "main" | "marquee" | "math" | "meter" | "menu" | "menubar" | "menuitem" | "menuitemcheckbox" | "menuitemradio" | "navigation" | "none" | "note" | "option" | "paragraph" | "presentation" | "progressbar" | "radio" | "radiogroup" | "region" | "row" | "rowgroup" | "rowheader" | "scrollbar" | "search" | "searchbox" | "separator" | "slider" | "spinbutton" | "status" | "strong" | "subscript" | "superscript" | "switch" | "tab" | "table" | "tablist" | "tabpanel" | "term" | "textbox" | "time" | "timer" | "toolbar" | "tooltip" | "tree" | "treegrid" | "treeitem"# Required aria role. +- `busy` [bool] *(optional)* Added in: v1.61# + + An attribute that is usually set by `aria-busy`. + + Learn more about [`aria-busy`](https://www.w3.org/TR/wai-aria-1.2/#aria-busy). - `checked` [bool] *(optional)*# An attribute that is usually set by `aria-checked` or native `` controls. @@ -4336,6 +4344,9 @@ page.check(selector, **kwargs) 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. - `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. @@ -4413,6 +4424,9 @@ page.click(selector, **kwargs) 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. - `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. @@ -4491,6 +4505,9 @@ page.dblclick(selector, **kwargs) 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. - `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. @@ -4985,6 +5002,9 @@ page.hover(selector, **kwargs) 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. - `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. @@ -5640,6 +5660,9 @@ page.set_checked(selector, checked, **kwargs) 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. - `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. @@ -5768,6 +5791,9 @@ page.tap(selector, **kwargs) 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. - `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. @@ -5917,6 +5943,9 @@ page.uncheck(selector, **kwargs) 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. - `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/python/docs/auth.mdx b/python/docs/auth.mdx index 2d1ed82fb9..de5db136f4 100644 --- a/python/docs/auth.mdx +++ b/python/docs/auth.mdx @@ -107,9 +107,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 [browser_context.storage_state()](/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 [browser_context.storage_state()](/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. @@ -149,7 +149,7 @@ context = await browser.new_context(storage_state="state.json") ### 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.