From 6816b7063de0d1d1720d0726505218d2b87d94e8 Mon Sep 17 00:00:00 2001 From: github-actions <41898282+github-actions[bot]@users.noreply.github.com> Date: Thu, 26 Sep 2024 13:23:10 +0000 Subject: [PATCH] feat(roll): roll to ToT Playwright (26-09-24) --- dotnet/docs/api/class-accessibility.mdx | 1 + dotnet/docs/api/class-apirequest.mdx | 1 + dotnet/docs/api/class-browser.mdx | 7 ++ dotnet/docs/api/class-browsercontext.mdx | 10 ++ dotnet/docs/api/class-browsertype.mdx | 5 + dotnet/docs/api/class-elementhandle.mdx | 3 + dotnet/docs/api/class-frame.mdx | 9 ++ dotnet/docs/api/class-framelocator.mdx | 1 + dotnet/docs/api/class-jshandle.mdx | 1 + dotnet/docs/api/class-keyboard.mdx | 3 + dotnet/docs/api/class-locator.mdx | 24 ++++- dotnet/docs/api/class-mouse.mdx | 1 + dotnet/docs/api/class-page.mdx | 72 +++++++++---- dotnet/docs/api/class-request.mdx | 1 + dotnet/docs/api/class-touchscreen.mdx | 1 + dotnet/docs/browsers.mdx | 2 + dotnet/docs/clock.mdx | 14 ++- dotnet/docs/debug.mdx | 1 + dotnet/docs/dialogs.mdx | 1 + dotnet/docs/docker.mdx | 2 + dotnet/docs/downloads.mdx | 2 + dotnet/docs/handles.mdx | 2 + dotnet/docs/input.mdx | 1 + dotnet/docs/locators.mdx | 3 + dotnet/docs/navigations.mdx | 1 + dotnet/docs/other-locators.mdx | 16 +++ dotnet/docs/selenium-grid.mdx | 15 ++- dotnet/docs/trace-viewer.mdx | 2 - java/docs/api/class-apirequest.mdx | 1 + java/docs/api/class-browser.mdx | 9 ++ java/docs/api/class-browsercontext.mdx | 10 ++ java/docs/api/class-browsertype.mdx | 5 + java/docs/api/class-elementhandle.mdx | 3 + java/docs/api/class-frame.mdx | 9 ++ java/docs/api/class-framelocator.mdx | 1 + java/docs/api/class-jshandle.mdx | 1 + java/docs/api/class-keyboard.mdx | 3 + java/docs/api/class-locator.mdx | 24 ++++- java/docs/api/class-mouse.mdx | 1 + java/docs/api/class-page.mdx | 71 +++++++++---- java/docs/api/class-request.mdx | 1 + java/docs/api/class-touchscreen.mdx | 1 + java/docs/browsers.mdx | 2 + java/docs/ci.mdx | 12 +-- java/docs/clock.mdx | 14 ++- java/docs/debug.mdx | 1 + java/docs/dialogs.mdx | 1 + java/docs/docker.mdx | 16 +-- java/docs/downloads.mdx | 2 + java/docs/handles.mdx | 2 + java/docs/input.mdx | 1 + java/docs/intro.mdx | 2 +- java/docs/locators.mdx | 3 + java/docs/navigations.mdx | 1 + java/docs/other-locators.mdx | 16 +++ java/docs/selenium-grid.mdx | 15 ++- java/docs/test-runners.mdx | 4 +- java/docs/trace-viewer.mdx | 2 - nodejs/docs/accessibility-testing.mdx | 5 +- nodejs/docs/api/class-accessibility.mdx | 1 + nodejs/docs/api/class-android.mdx | 1 + nodejs/docs/api/class-androiddevice.mdx | 2 + nodejs/docs/api/class-apirequest.mdx | 1 + nodejs/docs/api/class-browser.mdx | 9 ++ nodejs/docs/api/class-browsercontext.mdx | 12 +++ nodejs/docs/api/class-browsertype.mdx | 7 ++ nodejs/docs/api/class-coverage.mdx | 4 + nodejs/docs/api/class-elementhandle.mdx | 3 + nodejs/docs/api/class-frame.mdx | 9 ++ nodejs/docs/api/class-framelocator.mdx | 1 + nodejs/docs/api/class-jshandle.mdx | 1 + nodejs/docs/api/class-keyboard.mdx | 3 + nodejs/docs/api/class-locator.mdx | 24 ++++- nodejs/docs/api/class-mouse.mdx | 1 + nodejs/docs/api/class-page.mdx | 72 +++++++++---- nodejs/docs/api/class-request.mdx | 1 + nodejs/docs/api/class-snapshotassertions.mdx | 2 + nodejs/docs/api/class-test.mdx | 3 + nodejs/docs/api/class-testconfig.mdx | 1 + nodejs/docs/api/class-testinfo.mdx | 1 + nodejs/docs/api/class-testoptions.mdx | 3 + nodejs/docs/api/class-touchscreen.mdx | 1 + nodejs/docs/browsers.mdx | 3 + nodejs/docs/canary-releases.mdx | 5 +- nodejs/docs/chrome-extensions.mdx | 2 + nodejs/docs/ci-intro.mdx | 1 + nodejs/docs/clock.mdx | 14 ++- nodejs/docs/debug.mdx | 1 + nodejs/docs/dialogs.mdx | 1 + nodejs/docs/docker.mdx | 2 + nodejs/docs/downloads.mdx | 2 + nodejs/docs/handles.mdx | 2 + nodejs/docs/input.mdx | 1 + nodejs/docs/locators.mdx | 3 + nodejs/docs/navigations.mdx | 1 + nodejs/docs/other-locators.mdx | 16 +++ nodejs/docs/selenium-grid.mdx | 15 ++- ...ce-workers-experimental-network-events.mdx | 2 + nodejs/docs/test-assertions.mdx | 1 + nodejs/docs/test-global-setup-teardown.mdx | 1 + nodejs/docs/test-parallel.mdx | 2 + nodejs/docs/test-parameterize.mdx | 1 + nodejs/docs/test-retries.mdx | 1 + nodejs/docs/test-use-options.mdx | 1 + nodejs/docs/testing-library.mdx | 1 + nodejs/docs/trace-viewer.mdx | 2 - python/docs/api/class-accessibility.mdx | 1 + python/docs/api/class-apirequest.mdx | 1 + python/docs/api/class-browser.mdx | 7 ++ python/docs/api/class-browsercontext.mdx | 16 +++ python/docs/api/class-browsertype.mdx | 4 + python/docs/api/class-dialog.mdx | 1 + python/docs/api/class-elementhandle.mdx | 4 + python/docs/api/class-frame.mdx | 10 ++ python/docs/api/class-framelocator.mdx | 1 + python/docs/api/class-jshandle.mdx | 1 + python/docs/api/class-keyboard.mdx | 5 + python/docs/api/class-locator.mdx | 24 ++++- python/docs/api/class-mouse.mdx | 1 + python/docs/api/class-page.mdx | 100 ++++++++++++++---- python/docs/api/class-request.mdx | 1 + python/docs/api/class-touchscreen.mdx | 1 + python/docs/api/class-websocket.mdx | 1 + python/docs/browsers.mdx | 2 + python/docs/chrome-extensions.mdx | 2 + python/docs/clock.mdx | 14 ++- python/docs/debug.mdx | 1 + python/docs/dialogs.mdx | 3 + python/docs/docker.mdx | 2 + python/docs/downloads.mdx | 2 + python/docs/handles.mdx | 2 + python/docs/input.mdx | 2 + python/docs/library.mdx | 1 + python/docs/locators.mdx | 11 ++ python/docs/navigations.mdx | 1 + python/docs/other-locators.mdx | 19 ++++ python/docs/selenium-grid.mdx | 15 ++- python/docs/trace-viewer.mdx | 2 - python/docs/videos.mdx | 1 + src/documentation.js | 7 +- src/markdown.js | 26 +++-- 141 files changed, 854 insertions(+), 123 deletions(-) diff --git a/dotnet/docs/api/class-accessibility.mdx b/dotnet/docs/api/class-accessibility.mdx index 3567eebc71..fd17197b10 100644 --- a/dotnet/docs/api/class-accessibility.mdx +++ b/dotnet/docs/api/class-accessibility.mdx @@ -34,6 +34,7 @@ This method is deprecated. Please use other libraries such as [Axe](https://www. Captures the current state of the accessibility tree. The returned object represents the root accessible node of the page. :::note + The Chromium accessibility tree contains nodes that go unused on most platforms and by most screen readers. Playwright will discard them as well for an easier to process tree, unless [InterestingOnly](/api/class-accessibility.mdx#accessibility-snapshot-option-interesting-only) is set to `false`. ::: diff --git a/dotnet/docs/api/class-apirequest.mdx b/dotnet/docs/api/class-apirequest.mdx index b03c2e3a9e..786cc84283 100644 --- a/dotnet/docs/api/class-apirequest.mdx +++ b/dotnet/docs/api/class-apirequest.mdx @@ -67,6 +67,7 @@ await ApiRequest.NewContextAsync(options); An array of client certificates to be used. Each certificate object must have either both `certPath` and `keyPath`, a single `pfxPath`, or their corresponding direct value equivalents (`cert` and `key`, or `pfx`). Optionally, `passphrase` property should be provided if the certificate is encrypted. The `origin` property should be provided with an exact match to the request origin that the certificate is valid for. :::note + When using WebKit on macOS, accessing `localhost` will not pick up client certificates. You can make it work by replacing `localhost` with `local.playwright`. ::: diff --git a/dotnet/docs/api/class-browser.mdx b/dotnet/docs/api/class-browser.mdx index 9bf5205d13..39641cbc10 100644 --- a/dotnet/docs/api/class-browser.mdx +++ b/dotnet/docs/api/class-browser.mdx @@ -51,6 +51,7 @@ In case this browser is obtained using [BrowserType.LaunchAsync()](/api/class-br In case this browser is connected to, clears all created contexts belonging to this browser and disconnects from the browser server. :::note + This is similar to force quitting the browser. Therefore, you should call [BrowserContext.CloseAsync()](/api/class-browsercontext.mdx#browser-context-close) on any [BrowserContext]'s you explicitly created earlier with [Browser.NewContextAsync()](/api/class-browser.mdx#browser-new-context) **before** calling [Browser.CloseAsync()](/api/class-browser.mdx#browser-close). ::: @@ -116,6 +117,7 @@ Browser.IsConnected Added in: v1.11browser.NewBrowserCDPSessionAsync :::note + CDP Sessions are only supported on Chromium-based browsers. ::: @@ -139,6 +141,7 @@ await Browser.NewBrowserCDPSessionAsync(); Creates a new browser context. It won't share cookies/cache with other browser contexts. :::note + If directly using this method to create [BrowserContext]s, it is best practice to explicitly close the returned context via [BrowserContext.CloseAsync()](/api/class-browsercontext.mdx#browser-context-close) when your code is done with the [BrowserContext], and before calling [Browser.CloseAsync()](/api/class-browser.mdx#browser-close). This will ensure the `context` is closed gracefully and any artifacts—like HARs and videos—are fully flushed and saved. ::: @@ -205,6 +208,7 @@ await browser.CloseAsync(); An array of client certificates to be used. Each certificate object must have either both `certPath` and `keyPath`, a single `pfxPath`, or their corresponding direct value equivalents (`cert` and `key`, or `pfx`). Optionally, `passphrase` property should be provided if the certificate is encrypted. The `origin` property should be provided with an exact match to the request origin that the certificate is valid for. :::note + When using WebKit on macOS, accessing `localhost` will not pick up client certificates. You can make it work by replacing `localhost` with `local.playwright`. ::: @@ -349,6 +353,7 @@ await browser.CloseAsync(); Emulates consistent viewport for each page. Defaults to an 1280x720 viewport. Use `ViewportSize.NoViewport` to disable the consistent viewport emulation. Learn more about [viewport emulation](../emulation.mdx#viewport). :::note + The `ViewportSize.NoViewport` value opts out from the default presets, makes viewport depend on the host window size defined by the operating system. It makes the execution of the tests non-deterministic. ::: @@ -418,6 +423,7 @@ await Browser.NewPageAsync(options); An array of client certificates to be used. Each certificate object must have either both `certPath` and `keyPath`, a single `pfxPath`, or their corresponding direct value equivalents (`cert` and `key`, or `pfx`). Optionally, `passphrase` property should be provided if the certificate is encrypted. The `origin` property should be provided with an exact match to the request origin that the certificate is valid for. :::note + When using WebKit on macOS, accessing `localhost` will not pick up client certificates. You can make it work by replacing `localhost` with `local.playwright`. ::: @@ -562,6 +568,7 @@ await Browser.NewPageAsync(options); Emulates consistent viewport for each page. Defaults to an 1280x720 viewport. Use `ViewportSize.NoViewport` to disable the consistent viewport emulation. Learn more about [viewport emulation](../emulation.mdx#viewport). :::note + The `ViewportSize.NoViewport` value opts out from the default presets, makes viewport depend on the host window size defined by the operating system. It makes the execution of the tests non-deterministic. ::: diff --git a/dotnet/docs/api/class-browsercontext.mdx b/dotnet/docs/api/class-browsercontext.mdx index fa87d6e9f0..52c3809a3c 100644 --- a/dotnet/docs/api/class-browsercontext.mdx +++ b/dotnet/docs/api/class-browsercontext.mdx @@ -119,6 +119,7 @@ The order of evaluation of multiple scripts installed via [BrowserContext.AddIni Added in: v1.11browserContext.BackgroundPages :::note + Background pages are only supported on Chromium-based browsers. ::: @@ -214,6 +215,7 @@ await context.ClearPermissionsAsync(); Closes the browser context. All the pages that belong to the browser context will be closed. :::note + The default browser context cannot be closed. ::: @@ -443,6 +445,7 @@ await BrowserContext.GrantPermissionsAsync(permissions, options); Added in: v1.11browserContext.NewCDPSessionAsync :::note + CDP sessions are only supported on Chromium-based browsers. ::: @@ -505,6 +508,7 @@ BrowserContext.Pages Routing provides the capability to modify network requests that are made by any page in the browser context. Once route is enabled, every request matching the url pattern will stall unless it's continued, fulfilled or aborted. :::note + [BrowserContext.RouteAsync()](/api/class-browsercontext.mdx#browser-context-route) will not intercept requests intercepted by Service Worker. See [this](https://github.com/microsoft/playwright/issues/1090) issue. We recommend disabling Service Workers when using request interception by setting [ServiceWorkers](/api/class-browser.mdx#browser-new-context-option-service-workers) to `'block'`. ::: @@ -547,6 +551,7 @@ Page routes (set up with [Page.RouteAsync()](/api/class-page.mdx#page-route)) ta To remove a route with its handler you can use [BrowserContext.UnrouteAsync()](/api/class-browsercontext.mdx#browser-context-unroute). :::note + Enabling routing disables http cache. ::: @@ -768,6 +773,7 @@ This setting will change the default maximum navigation time for the following m * [Page.RunAndWaitForNavigationAsync()](/api/class-page.mdx#page-wait-for-navigation) :::note + [Page.SetDefaultNavigationTimeout()](/api/class-page.mdx#page-set-default-navigation-timeout) and [Page.SetDefaultTimeout()](/api/class-page.mdx#page-set-default-timeout) take priority over [BrowserContext.SetDefaultNavigationTimeout()](/api/class-browsercontext.mdx#browser-context-set-default-navigation-timeout). ::: @@ -791,6 +797,7 @@ BrowserContext.SetDefaultNavigationTimeout(timeout); This setting will change the default maximum time for all the methods accepting [timeout](/api/class-browsercontext.mdx#browser-context-set-default-timeout-option-timeout) option. :::note + [Page.SetDefaultNavigationTimeout()](/api/class-page.mdx#page-set-default-navigation-timeout), [Page.SetDefaultTimeout()](/api/class-page.mdx#page-set-default-timeout) and [BrowserContext.SetDefaultNavigationTimeout()](/api/class-browsercontext.mdx#browser-context-set-default-navigation-timeout) take priority over [BrowserContext.SetDefaultTimeout()](/api/class-browsercontext.mdx#browser-context-set-default-timeout). ::: @@ -814,6 +821,7 @@ BrowserContext.SetDefaultTimeout(timeout); The extra HTTP headers will be sent with every request initiated by any page in the context. These headers are merged with page-specific extra HTTP headers set with [Page.SetExtraHTTPHeadersAsync()](/api/class-page.mdx#page-set-extra-http-headers). If page overrides a particular header, page-specific header value will be used instead of the browser context header value. :::note + [BrowserContext.SetExtraHTTPHeadersAsync()](/api/class-browsercontext.mdx#browser-context-set-extra-http-headers) does not guarantee the order of headers in the outgoing requests. ::: @@ -1022,6 +1030,7 @@ BrowserContext.Tracing Added in: v1.11browserContext.event BackgroundPage :::note + Only works with Chromium browser's persistent context. ::: @@ -1172,6 +1181,7 @@ BrowserContext.Request += async (_, request) => {}; Emitted when a request fails, for example by timing out. To only listen for failed requests from a particular page, use [Page.RequestFailed](/api/class-page.mdx#page-event-request-failed). :::note + HTTP Error responses, such as 404 or 503, are still successful responses from HTTP standpoint, so request will complete with [BrowserContext.RequestFinished](/api/class-browsercontext.mdx#browser-context-event-request-finished) event and not with [BrowserContext.RequestFailed](/api/class-browsercontext.mdx#browser-context-event-request-failed). ::: diff --git a/dotnet/docs/api/class-browsertype.mdx b/dotnet/docs/api/class-browsertype.mdx index 3eeee6ebcb..a11a73a8a3 100644 --- a/dotnet/docs/api/class-browsertype.mdx +++ b/dotnet/docs/api/class-browsertype.mdx @@ -87,6 +87,7 @@ This method attaches Playwright to an existing browser instance using the Chrome The default browser context is accessible via [Browser.Contexts](/api/class-browser.mdx#browser-contexts). :::note + Connecting over the Chrome DevTools Protocol is only supported for Chromium-based browsers. ::: @@ -162,6 +163,7 @@ var browser = await playwright.Chromium.LaunchAsync(new() { - `Args` [IEnumerable]?<[string]> *(optional)*# :::warning + Use custom browser args at your own risk, as some of them may break Playwright functionality. ::: @@ -265,6 +267,7 @@ await BrowserType.LaunchPersistentContextAsync(userDataDir, options); - `Args` [IEnumerable]?<[string]> *(optional)*# :::warning + Use custom browser args at your own risk, as some of them may break Playwright functionality. ::: @@ -317,6 +320,7 @@ await BrowserType.LaunchPersistentContextAsync(userDataDir, options); An array of client certificates to be used. Each certificate object must have either both `certPath` and `keyPath`, a single `pfxPath`, or their corresponding direct value equivalents (`cert` and `key`, or `pfx`). Optionally, `passphrase` property should be provided if the certificate is encrypted. The `origin` property should be provided with an exact match to the request origin that the certificate is valid for. :::note + When using WebKit on macOS, accessing `localhost` will not pick up client certificates. You can make it work by replacing `localhost` with `local.playwright`. ::: @@ -502,6 +506,7 @@ await BrowserType.LaunchPersistentContextAsync(userDataDir, options); Emulates consistent viewport for each page. Defaults to an 1280x720 viewport. Use `ViewportSize.NoViewport` to disable the consistent viewport emulation. Learn more about [viewport emulation](../emulation.mdx#viewport). :::note + The `ViewportSize.NoViewport` value opts out from the default presets, makes viewport depend on the host window size defined by the operating system. It makes the execution of the tests non-deterministic. ::: diff --git a/dotnet/docs/api/class-elementhandle.mdx b/dotnet/docs/api/class-elementhandle.mdx index f13c690611..c4472b5197 100644 --- a/dotnet/docs/api/class-elementhandle.mdx +++ b/dotnet/docs/api/class-elementhandle.mdx @@ -11,6 +11,7 @@ import HTMLCard from '@site/src/components/HTMLCard'; ElementHandle represents an in-page DOM element. ElementHandles can be created with the [Page.QuerySelectorAsync()](/api/class-page.mdx#page-query-selector) method. :::warning[Discouraged] + The use of ElementHandle is discouraged, use [Locator] objects and web-first assertions instead. ::: @@ -308,6 +309,7 @@ If the element is detached from the DOM at any moment during the action, this me When all steps combined have not finished during the specified [Timeout](/api/class-elementhandle.mdx#element-handle-dblclick-option-timeout), this method throws a [TimeoutError]. Passing zero timeout disables this. :::note + `elementHandle.dblclick()` dispatches two `click` events and a single `dblclick` event. ::: @@ -1346,6 +1348,7 @@ If the element is detached from the DOM at any moment during the action, this me When all steps combined have not finished during the specified [Timeout](/api/class-elementhandle.mdx#element-handle-tap-option-timeout), this method throws a [TimeoutError]. Passing zero timeout disables this. :::note + `elementHandle.tap()` requires that the `hasTouch` option of the browser context be set to true. ::: diff --git a/dotnet/docs/api/class-frame.mdx b/dotnet/docs/api/class-frame.mdx index 5702e3ceda..fa9dd74c8a 100644 --- a/dotnet/docs/api/class-frame.mdx +++ b/dotnet/docs/api/class-frame.mdx @@ -496,6 +496,7 @@ await page An attribute that is usually set by `aria-disabled` or `disabled`. :::note + Unlike most other attributes, `disabled` is inherited through the DOM hierarchy. Learn more about [`aria-disabled`](https://www.w3.org/TR/wai-aria-1.2/#aria-disabled). ::: @@ -684,6 +685,7 @@ The method will throw an error if: The method will not throw an error when any valid HTTP status code is returned by the remote server, including 404 "Not Found" and 500 "Internal Server Error". The status code for such responses can be retrieved by calling [Response.Status](/api/class-response.mdx#response-status). :::note + The method either throws an error or returns a main resource response. The only exceptions are navigation to `about:blank` or navigation to the same URL with a different hash, which would succeed and return `null`. ::: @@ -821,6 +823,7 @@ Returns frame's name attribute as specified in the tag. If the name is empty, returns the id attribute instead. :::note + This value is calculated once when the frame is created, and will not update if the attribute is changed later. ::: @@ -999,6 +1002,7 @@ Waits for the required load state to be reached. This returns when the frame reaches a required load state, `load` by default. The navigation must have been committed when this method is called. If current document has already reached the required state, resolves immediately. :::note + Most of the time, this method is not needed because Playwright [auto-waits before every action](../actionability.mdx). ::: @@ -1225,6 +1229,7 @@ This method double clicks an element matching [selector](/api/class-frame.mdx#fr When all steps combined have not finished during the specified [Timeout](/api/class-frame.mdx#frame-dblclick-option-timeout), this method throws a [TimeoutError]. Passing zero timeout disables this. :::note + `frame.dblclick()` dispatches two `click` events and a single `dblclick` event. ::: @@ -1996,6 +2001,7 @@ Use locator-based [Frame.Locator()](/api/class-frame.mdx#frame-locator) instead. Returns the ElementHandle pointing to the frame element. :::caution + The use of [ElementHandle] is discouraged, use [Locator] objects and web-first assertions instead. ::: @@ -2035,6 +2041,7 @@ Use locator-based [Frame.Locator()](/api/class-frame.mdx#frame-locator) instead. Returns the ElementHandles pointing to the frame elements. :::caution + The use of [ElementHandle] is discouraged, use [Locator] objects instead. ::: @@ -2379,6 +2386,7 @@ This method taps an element matching [selector](/api/class-frame.mdx#frame-tap-o When all steps combined have not finished during the specified [Timeout](/api/class-frame.mdx#frame-tap-option-timeout), this method throws a [TimeoutError]. Passing zero timeout disables this. :::note + `frame.tap()` requires that the `hasTouch` option of the browser context be set to true. ::: @@ -2594,6 +2602,7 @@ Use web assertions that assert visibility or a locator-based [Locator.WaitForAsy Returns when element specified by selector satisfies [State](/api/class-frame.mdx#frame-wait-for-selector-option-state) option. Returns `null` if waiting for `hidden` or `detached`. :::note + Playwright automatically waits for element to be ready before performing an action. Using [Locator] objects and web-first assertions make the code wait-for-selector-free. ::: diff --git a/dotnet/docs/api/class-framelocator.mdx b/dotnet/docs/api/class-framelocator.mdx index b2c4bf8693..af26c54057 100644 --- a/dotnet/docs/api/class-framelocator.mdx +++ b/dotnet/docs/api/class-framelocator.mdx @@ -216,6 +216,7 @@ await page An attribute that is usually set by `aria-disabled` or `disabled`. :::note + Unlike most other attributes, `disabled` is inherited through the DOM hierarchy. Learn more about [`aria-disabled`](https://www.w3.org/TR/wai-aria-1.2/#aria-disabled). ::: diff --git a/dotnet/docs/api/class-jshandle.mdx b/dotnet/docs/api/class-jshandle.mdx index bc58e678c5..685b735293 100644 --- a/dotnet/docs/api/class-jshandle.mdx +++ b/dotnet/docs/api/class-jshandle.mdx @@ -169,6 +169,7 @@ await JsHandle.GetPropertyAsync(propertyName); Returns a JSON representation of the object. If the object has a `toJSON` function, it **will not be called**. :::note + The method will return an empty JSON object if the referenced object is not stringifiable. It will throw an error if the object has circular references. ::: diff --git a/dotnet/docs/api/class-keyboard.mdx b/dotnet/docs/api/class-keyboard.mdx index 020e4ddac6..ee60dbbf68 100644 --- a/dotnet/docs/api/class-keyboard.mdx +++ b/dotnet/docs/api/class-keyboard.mdx @@ -70,6 +70,7 @@ If [key](/api/class-keyboard.mdx#keyboard-down-option-key) is a modifier key, `S After the key is pressed once, subsequent calls to [Keyboard.DownAsync()](/api/class-keyboard.mdx#keyboard-down) will have [repeat](https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/repeat) set to true. To release the key, use [Keyboard.UpAsync()](/api/class-keyboard.mdx#keyboard-up). :::note + Modifier keys DO influence `keyboard.down`. Holding down `Shift` will type the text in upper case. ::: @@ -120,6 +121,7 @@ Modifier keys DO NOT effect `keyboard.insertText`. Holding down `Shift` will not Added before v1.9keyboard.PressAsync :::tip + In most cases, you should use [Locator.PressAsync()](/api/class-locator.mdx#locator-press) instead. ::: @@ -169,6 +171,7 @@ Shortcut for [Keyboard.DownAsync()](/api/class-keyboard.mdx#keyboard-down) and [ Added before v1.9keyboard.TypeAsync :::caution + In most cases, you should use [Locator.FillAsync()](/api/class-locator.mdx#locator-fill) instead. You only need to press keys one by one if there is special keyboard handling on the page - in this case use [Locator.PressSequentiallyAsync()](/api/class-locator.mdx#locator-press-sequentially). ::: diff --git a/dotnet/docs/api/class-locator.mdx b/dotnet/docs/api/class-locator.mdx index 795d1ebcb6..8465be00a6 100644 --- a/dotnet/docs/api/class-locator.mdx +++ b/dotnet/docs/api/class-locator.mdx @@ -23,7 +23,12 @@ Locators are the central piece of Playwright's auto-waiting and retry-ability. I When the locator points to a list of elements, this returns an array of locators, pointing to their respective elements. :::note -[Locator.AllAsync()](/api/class-locator.mdx#locator-all) does not wait for elements to match the locator, and instead immediately returns whatever is present in the page. When the list of elements changes dynamically, [Locator.AllAsync()](/api/class-locator.mdx#locator-all) will produce unpredictable and flaky results. When the list of elements is stable, but loaded dynamically, wait for the full list to finish loading before calling [Locator.AllAsync()](/api/class-locator.mdx#locator-all). + +[Locator.AllAsync()](/api/class-locator.mdx#locator-all) does not wait for elements to match the locator, and instead immediately returns whatever is present in the page. + +When the list of elements changes dynamically, [Locator.AllAsync()](/api/class-locator.mdx#locator-all) will produce unpredictable and flaky results. + +When the list of elements is stable, but loaded dynamically, wait for the full list to finish loading before calling [Locator.AllAsync()](/api/class-locator.mdx#locator-all). ::: **Usage** @@ -45,6 +50,7 @@ foreach (var li in await page.GetByRole("listitem").AllAsync()) Returns an array of `node.innerText` values for all matching nodes. :::warning[Asserting text] + If you need to assert text on the page, prefer [Expect(Locator).ToHaveTextAsync()](/api/class-locatorassertions.mdx#locator-assertions-to-have-text) with [UseInnerText](/api/class-locatorassertions.mdx#locator-assertions-to-have-text-option-use-inner-text) option to avoid flakiness. See [assertions guide](../test-assertions.mdx) for more details. ::: @@ -66,6 +72,7 @@ var texts = await page.GetByRole(AriaRole.Link).AllInnerTextsAsync(); Returns an array of `node.textContent` values for all matching nodes. :::warning[Asserting text] + If you need to assert text on the page, prefer [Expect(Locator).ToHaveTextAsync()](/api/class-locatorassertions.mdx#locator-assertions-to-have-text) to avoid flakiness. See [assertions guide](../test-assertions.mdx) for more details. ::: @@ -381,6 +388,7 @@ await frameLocator.GetByRole(AriaRole.Button).ClickAsync(); Returns the number of elements matching the locator. :::warning[Asserting count] + If you need to assert the number of elements on the page, prefer [Expect(Locator).ToHaveCountAsync()](/api/class-locatorassertions.mdx#locator-assertions-to-have-count) to avoid flakiness. See [assertions guide](../test-assertions.mdx) for more details. ::: @@ -459,6 +467,7 @@ If the element is detached from the DOM at any moment during the action, this me When all steps combined have not finished during the specified [Timeout](/api/class-locator.mdx#locator-dblclick-option-timeout), this method throws a [TimeoutError]. Passing zero timeout disables this. :::note + `element.dblclick()` dispatches two `click` events and a single `dblclick` event. ::: @@ -863,6 +872,7 @@ await locator.ClickAsync(); Returns the matching element's attribute value. :::warning[Asserting attributes] + If you need to assert an element's attribute, prefer [Expect(Locator).ToHaveAttributeAsync()](/api/class-locatorassertions.mdx#locator-assertions-to-have-attribute) to avoid flakiness. See [assertions guide](../test-assertions.mdx) for more details. ::: @@ -1041,6 +1051,7 @@ await page An attribute that is usually set by `aria-disabled` or `disabled`. :::note + Unlike most other attributes, `disabled` is inherited through the DOM hierarchy. Learn more about [`aria-disabled`](https://www.w3.org/TR/wai-aria-1.2/#aria-disabled). ::: @@ -1319,6 +1330,7 @@ await Locator.InnerHTMLAsync(options); Returns the [`element.innerText`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/innerText). :::warning[Asserting text] + If you need to assert text on the page, prefer [Expect(Locator).ToHaveTextAsync()](/api/class-locatorassertions.mdx#locator-assertions-to-have-text) with [UseInnerText](/api/class-locatorassertions.mdx#locator-assertions-to-have-text-option-use-inner-text) option to avoid flakiness. See [assertions guide](../test-assertions.mdx) for more details. ::: @@ -1346,6 +1358,7 @@ await Locator.InnerTextAsync(options); Returns the value for the matching `` or `