Filip/playwright
1
0
Fork 0
Code Issues Pull requests Actions Packages Projects Releases Wiki Activity

docs: annotate deprecated methods (#19005)

Browse source
This commit is contained in:
Pavel Feldman 2022-11-23 08:40:47 -08:00 committed by GitHub
parent 31d45ad4dc
commit f97dcd4c79
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
11 changed files with 178 additions and 289 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

7
docs/src/api/class-accessibility.md
View file

@ -1,8 +1,7 @@
# class: Accessibility # class: Accessibility
* since: v1.8 * since: v1.8
* langs: csharp, js, python * langs: csharp, js, python
* deprecated: This class is deprecated. Please use other libraries such as [Axe](https://www.deque.com/axe/) if you need to test page accessibility. See our Node.js [guide](https://playwright.dev/docs/accessibility-testing) for integration with Axe.
**DEPRECATED** This class is deprecated. Please use other libraries such as [Axe](https://www.deque.com/axe/) if you need to test page accessibility. See our Node.js [guide](https://playwright.dev/docs/accessibility-testing) for integration with Axe.
The Accessibility class provides methods for inspecting Chromium's accessibility tree. The accessibility tree is used by The Accessibility class provides methods for inspecting Chromium's accessibility tree. The accessibility tree is used by
assistive technology such as [screen readers](https://en.wikipedia.org/wiki/Screen_reader) or assistive technology such as [screen readers](https://en.wikipedia.org/wiki/Screen_reader) or
@ -20,6 +19,8 @@ assistive technologies themselves. By default, Playwright tries to approximate t
## async method: Accessibility.snapshot ## async method: Accessibility.snapshot
* since: v1.8 * since: v1.8
* deprecated: This method is deprecated. Please use other libraries such as [Axe](https://www.deque.com/axe/) if you need to test page accessibility. See our Node.js [guide](https://playwright.dev/docs/accessibility-testing) for integration with Axe.
- returns: <[null]|[Object]> - returns: <[null]|[Object]>
- `role` <[string]> The [role](https://www.w3.org/TR/wai-aria/#usage_intro). - `role` <[string]> The [role](https://www.w3.org/TR/wai-aria/#usage_intro).
- `name` <[string]> A human readable name for the node. - `name` <[string]> A human readable name for the node.
@ -48,8 +49,6 @@ assistive technologies themselves. By default, Playwright tries to approximate t
- `orientation` <[string]> Whether the node is oriented horizontally or vertically, if applicable. - `orientation` <[string]> Whether the node is oriented horizontally or vertically, if applicable.
- `children` <[Array]<[Object]>> Child nodes, if any, if applicable. - `children` <[Array]<[Object]>> Child nodes, if any, if applicable.
**DEPRECATED** This method is deprecated. Please use other libraries such as [Axe](https://www.deque.com/axe/) if you need to test page accessibility. See our Node.js [guide](https://playwright.dev/docs/accessibility-testing) for integration with Axe.
Captures the current state of the accessibility tree. The returned object represents the root accessible node of the Captures the current state of the accessibility tree. The returned object represents the root accessible node of the
page. page.

3
docs/src/api/class-browsercontext.md
View file

@ -1223,8 +1223,7 @@ its geolocation.
## async method: BrowserContext.setHTTPCredentials ## async method: BrowserContext.setHTTPCredentials
* since: v1.8 * since: v1.8
* langs: js * langs: js
* deprecated: Browsers may cache credentials after successful authentication. Create a new browser context instead.
**DEPRECATED** Browsers may cache credentials after successful authentication. Create a new browser context instead.
### param: BrowserContext.setHTTPCredentials.httpCredentials ### param: BrowserContext.setHTTPCredentials.httpCredentials
* since: v1.8 * since: v1.8

34
docs/src/api/class-frame.md
View file

@ -188,6 +188,7 @@ Raw CSS content to be injected into frame.
## async method: Frame.check ## async method: Frame.check
* since: v1.8 * since: v1.8
* discouraged: Use locator-based [`method: Locator.check`] instead.
This method checks an element matching [`param: selector`] by performing the following steps: This method checks an element matching [`param: selector`] by performing the following steps:
1. Find an element matching [`param: selector`]. If there is none, wait until a matching element is attached to 1. Find an element matching [`param: selector`]. If there is none, wait until a matching element is attached to
@ -231,6 +232,7 @@ When all steps combined have not finished during the specified [`option: timeout
## async method: Frame.click ## async method: Frame.click
* since: v1.8 * since: v1.8
* discouraged: Use locator-based [`method: Locator.click`] instead.
This method clicks an element matching [`param: selector`] by performing the following steps: This method clicks an element matching [`param: selector`] by performing the following steps:
1. Find an element matching [`param: selector`]. If there is none, wait until a matching element is attached to 1. Find an element matching [`param: selector`]. If there is none, wait until a matching element is attached to
@ -285,6 +287,7 @@ Gets the full HTML contents of the frame, including the doctype.
## async method: Frame.dblclick ## async method: Frame.dblclick
* since: v1.8 * since: v1.8
* discouraged: Use locator-based [`method: Locator.dblclick`] instead.
* langs: * langs:
- alias-csharp: DblClickAsync - alias-csharp: DblClickAsync
@ -337,6 +340,7 @@ When all steps combined have not finished during the specified [`option: timeout
## async method: Frame.dispatchEvent ## async method: Frame.dispatchEvent
* since: v1.8 * since: v1.8
* discouraged: Use locator-based [`method: Locator.dispatchEvent`] instead.
The snippet below dispatches the `click` event on the element. Regardless of the visibility state of the element, `click` The snippet below dispatches the `click` event on the element. Regardless of the visibility state of the element, `click`
is dispatched. This is equivalent to calling is dispatched. This is equivalent to calling
@ -465,6 +469,7 @@ Optional event-specific initialization properties.
## async method: Frame.evalOnSelector ## async method: Frame.evalOnSelector
* since: v1.9 * since: v1.9
* discouraged: Use locator-based [`method: Locator.evaluate`] instead.
* langs: * langs:
- alias-python: eval_on_selector - alias-python: eval_on_selector
- alias-js: $eval - alias-js: $eval
@ -533,6 +538,7 @@ Optional argument to pass to [`param: expression`].
## async method: Frame.evalOnSelectorAll ## async method: Frame.evalOnSelectorAll
* since: v1.9 * since: v1.9
* discouraged: Use locator-based [`method: Locator.evaluateAll`] instead.
* langs: * langs:
- alias-python: eval_on_selector_all - alias-python: eval_on_selector_all
- alias-js: $$eval - alias-js: $$eval
@ -805,6 +811,7 @@ Optional argument to pass to [`param: expression`].
## async method: Frame.fill ## async method: Frame.fill
* since: v1.8 * since: v1.8
* discouraged: Use locator-based [`method: Locator.fill`] instead.
This method waits for an element matching [`param: selector`], waits for [actionability](../actionability.md) checks, focuses the element, fills it and triggers an `input` event after filling. Note that you can pass an empty string to clear the input field. This method waits for an element matching [`param: selector`], waits for [actionability](../actionability.md) checks, focuses the element, fills it and triggers an `input` event after filling. Note that you can pass an empty string to clear the input field.
@ -835,6 +842,7 @@ Value to fill for the `<input>`, `<textarea>` or `[contenteditable]` element.
## async method: Frame.focus ## async method: Frame.focus
* since: v1.8 * since: v1.8
* discouraged: Use locator-based [`method: Locator.focus`] instead.
This method fetches an element with [`param: selector`] and focuses it. If there's no element matching This method fetches an element with [`param: selector`] and focuses it. If there's no element matching
[`param: selector`], the method waits until a matching element appears in the DOM. [`param: selector`], the method waits until a matching element appears in the DOM.
@ -932,6 +940,7 @@ await locator.ClickAsync();
## async method: Frame.getAttribute ## async method: Frame.getAttribute
* since: v1.8 * since: v1.8
* discouraged: Use locator-based [`method: Locator.getAttribute`] instead.
- returns: <[null]|[string]> - returns: <[null]|[string]>
Returns element attribute value. Returns element attribute value.
@ -1074,6 +1083,7 @@ Referer header value. If provided it will take preference over the referer heade
## async method: Frame.hover ## async method: Frame.hover
* since: v1.8 * since: v1.8
* discouraged: Use locator-based [`method: Locator.hover`] instead.
This method hovers over an element matching [`param: selector`] by performing the following steps: This method hovers over an element matching [`param: selector`] by performing the following steps:
1. Find an element matching [`param: selector`]. If there is none, wait until a matching element is attached to 1. Find an element matching [`param: selector`]. If there is none, wait until a matching element is attached to
@ -1113,6 +1123,7 @@ When all steps combined have not finished during the specified [`option: timeout
## async method: Frame.innerHTML ## async method: Frame.innerHTML
* since: v1.8 * since: v1.8
* discouraged: Use locator-based [`method: Locator.innerHTML`] instead.
- returns: <[string]> - returns: <[string]>
Returns `element.innerHTML`. Returns `element.innerHTML`.
@ -1128,6 +1139,7 @@ Returns `element.innerHTML`.
## async method: Frame.innerText ## async method: Frame.innerText
* since: v1.8 * since: v1.8
* discouraged: Use locator-based [`method: Locator.innerText`] instead.
- returns: <[string]> - returns: <[string]>
Returns `element.innerText`. Returns `element.innerText`.
@ -1143,6 +1155,7 @@ Returns `element.innerText`.
## async method: Frame.inputValue ## async method: Frame.inputValue
* since: v1.13 * since: v1.13
* discouraged: Use locator-based [`method: Locator.inputValue`] instead.
- returns: <[string]> - returns: <[string]>
Returns `input.value` for the selected `<input>` or `<textarea>` or `<select>` element. Returns `input.value` for the selected `<input>` or `<textarea>` or `<select>` element.
@ -1160,6 +1173,7 @@ Throws for non-input elements. However, if the element is inside the `<label>` e
## async method: Frame.isChecked ## async method: Frame.isChecked
* since: v1.8 * since: v1.8
* discouraged: Use locator-based [`method: Locator.isChecked`] instead.
- returns: <[boolean]> - returns: <[boolean]>
Returns whether the element is checked. Throws if the element is not a checkbox or radio input. Returns whether the element is checked. Throws if the element is not a checkbox or radio input.
@ -1181,6 +1195,7 @@ Returns `true` if the frame has been detached, or `false` otherwise.
## async method: Frame.isDisabled ## async method: Frame.isDisabled
* since: v1.8 * since: v1.8
* discouraged: Use locator-based [`method: Locator.isDisabled`] instead.
- returns: <[boolean]> - returns: <[boolean]>
Returns whether the element is disabled, the opposite of [enabled](../actionability.md#enabled). Returns whether the element is disabled, the opposite of [enabled](../actionability.md#enabled).
@ -1196,6 +1211,7 @@ Returns whether the element is disabled, the opposite of [enabled](../actionabil
## async method: Frame.isEditable ## async method: Frame.isEditable
* since: v1.8 * since: v1.8
* discouraged: Use locator-based [`method: Locator.isEditable`] instead.
- returns: <[boolean]> - returns: <[boolean]>
Returns whether the element is [editable](../actionability.md#editable). Returns whether the element is [editable](../actionability.md#editable).
@ -1226,6 +1242,7 @@ Returns whether the element is [enabled](../actionability.md#enabled).
## async method: Frame.isHidden ## async method: Frame.isHidden
* since: v1.8 * since: v1.8
* discouraged: Use locator-based [`method: Locator.isHidden`] instead.
- returns: <[boolean]> - returns: <[boolean]>
Returns whether the element is hidden, the opposite of [visible](../actionability.md#visible). [`option: selector`] that does not match any elements is considered hidden. Returns whether the element is hidden, the opposite of [visible](../actionability.md#visible). [`option: selector`] that does not match any elements is considered hidden.
@ -1238,12 +1255,12 @@ Returns whether the element is hidden, the opposite of [visible](../actionabilit
### option: Frame.isHidden.timeout ### option: Frame.isHidden.timeout
* since: v1.8 * since: v1.8
* deprecated: This option is ignored. [`method: Frame.isHidden`] does not wait for the element to become hidden and returns immediately.
- `timeout` <[float]> - `timeout` <[float]>
**DEPRECATED** This option is ignored. [`method: Frame.isHidden`] does not wait for the element to become hidden and returns immediately.
## async method: Frame.isVisible ## async method: Frame.isVisible
* since: v1.8 * since: v1.8
* discouraged: Use locator-based [`method: Locator.isVisible`] instead.
- returns: <[boolean]> - returns: <[boolean]>
Returns whether the element is [visible](../actionability.md#visible). [`option: selector`] that does not match any elements is considered not visible. Returns whether the element is [visible](../actionability.md#visible). [`option: selector`] that does not match any elements is considered not visible.
@ -1256,10 +1273,9 @@ Returns whether the element is [visible](../actionability.md#visible). [`option:
### option: Frame.isVisible.timeout ### option: Frame.isVisible.timeout
* since: v1.8 * since: v1.8
* deprecated: This option is ignored. [`method: Frame.isVisible`] does not wait for the element to become visible and returns immediately.
- `timeout` <[float]> - `timeout` <[float]>
**DEPRECATED** This option is ignored. [`method: Frame.isVisible`] does not wait for the element to become visible and returns immediately.
## method: Frame.locator ## method: Frame.locator
* since: v1.14 * since: v1.14
- returns: <[Locator]> - returns: <[Locator]>
@ -1300,6 +1316,7 @@ Parent frame, if any. Detached frames and main frames return `null`.
## async method: Frame.press ## async method: Frame.press
* since: v1.8 * since: v1.8
* discouraged: Use locator-based [`method: Locator.press`] instead.
[`param: key`] can specify the intended [`param: key`] can specify the intended
[keyboardEvent.key](https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/key) value or a single character to [keyboardEvent.key](https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/key) value or a single character to
@ -1345,6 +1362,7 @@ Time to wait between `keydown` and `keyup` in milliseconds. Defaults to 0.
## async method: Frame.querySelector ## async method: Frame.querySelector
* since: v1.9 * since: v1.9
* discouraged: Use locator-based [`method: Frame.locator`] instead.
* langs: * langs:
- alias-python: query_selector - alias-python: query_selector
- alias-js: $ - alias-js: $
@ -1368,6 +1386,7 @@ returns `null`.
## async method: Frame.querySelectorAll ## async method: Frame.querySelectorAll
* since: v1.9 * since: v1.9
* discouraged: Use locator-based [`method: Frame.locator`] instead.
* langs: * langs:
- alias-python: query_selector_all - alias-python: query_selector_all
- alias-js: $$ - alias-js: $$
@ -1388,6 +1407,7 @@ returns empty array.
## async method: Frame.selectOption ## async method: Frame.selectOption
* since: v1.8 * since: v1.8
* discouraged: Use locator-based [`method: Locator.selectOption`] instead.
- returns: <[Array]<[string]>> - returns: <[Array]<[string]>>
This method waits for an element matching [`param: selector`], waits for [actionability](../actionability.md) checks, waits until all specified options are present in the `<select>` element and selects these options. This method waits for an element matching [`param: selector`], waits for [actionability](../actionability.md) checks, waits until all specified options are present in the `<select>` element and selects these options.
@ -1467,6 +1487,7 @@ await frame.SelectOptionAsync("select#colors", new[] { "red", "green", "blue" })
## async method: Frame.setChecked ## async method: Frame.setChecked
* since: v1.15 * since: v1.15
* discouraged: Use locator-based [`method: Locator.setChecked`] instead.
This method checks or unchecks an element matching [`param: selector`] by performing the following steps: This method checks or unchecks an element matching [`param: selector`] by performing the following steps:
1. Find an element matching [`param: selector`]. If there is none, wait until a matching element is attached to 1. Find an element matching [`param: selector`]. If there is none, wait until a matching element is attached to
@ -1524,6 +1545,7 @@ HTML markup to assign to the page.
## async method: Frame.setInputFiles ## async method: Frame.setInputFiles
* since: v1.8 * since: v1.8
* discouraged: Use locator-based [`method: Locator.setInputFiles`] instead.
Sets the value of the file input to these file paths or files. If some of the `filePaths` are relative paths, then they Sets the value of the file input to these file paths or files. If some of the `filePaths` are relative paths, then they
are resolved relative to the current working directory. For empty array, clears the selected files. are resolved relative to the current working directory. For empty array, clears the selected files.
@ -1548,6 +1570,7 @@ This method expects [`param: selector`] to point to an
## async method: Frame.tap ## async method: Frame.tap
* since: v1.8 * since: v1.8
* discouraged: Use locator-based [`method: Locator.tap`] instead.
This method taps an element matching [`param: selector`] by performing the following steps: This method taps an element matching [`param: selector`] by performing the following steps:
1. Find an element matching [`param: selector`]. If there is none, wait until a matching element is attached to 1. Find an element matching [`param: selector`]. If there is none, wait until a matching element is attached to
@ -1591,6 +1614,7 @@ When all steps combined have not finished during the specified [`option: timeout
## async method: Frame.textContent ## async method: Frame.textContent
* since: v1.8 * since: v1.8
* discouraged: Use locator-based [`method: Locator.textContent`] instead.
- returns: <[null]|[string]> - returns: <[null]|[string]>
Returns `element.textContent`. Returns `element.textContent`.
@ -1612,6 +1636,7 @@ Returns the page title.
## async method: Frame.type ## async method: Frame.type
* since: v1.8 * since: v1.8
* discouraged: Use locator-based [`method: Locator.type`] instead.
Sends a `keydown`, `keypress`/`input`, and `keyup` event for each character in the text. `frame.type` can be used to Sends a `keydown`, `keypress`/`input`, and `keyup` event for each character in the text. `frame.type` can be used to
send fine-grained keyboard events. To fill values in form fields, use [`method: Frame.fill`]. send fine-grained keyboard events. To fill values in form fields, use [`method: Frame.fill`].
@ -1673,6 +1698,7 @@ Time to wait between key presses in milliseconds. Defaults to 0.
## async method: Frame.uncheck ## async method: Frame.uncheck
* since: v1.8 * since: v1.8
* discouraged: Use locator-based [`method: Locator.uncheck`] instead.
This method checks an element matching [`param: selector`] by performing the following steps: This method checks an element matching [`param: selector`] by performing the following steps:
1. Find an element matching [`param: selector`]. If there is none, wait until a matching element is attached to 1. Find an element matching [`param: selector`]. If there is none, wait until a matching element is attached to

6
docs/src/api/class-locator.md
View file

@ -876,10 +876,9 @@ Returns whether the element is hidden, the opposite of [visible](../actionabilit
### option: Locator.isHidden.timeout ### option: Locator.isHidden.timeout
* since: v1.14 * since: v1.14
* deprecated: This option is ignored. [`method: Locator.isHidden`] does not wait for the element to become hidden and returns immediately.
- `timeout` <[float]> - `timeout` <[float]>
**DEPRECATED** This option is ignored. [`method: Locator.isHidden`] does not wait for the element to become hidden and returns immediately.
## async method: Locator.isVisible ## async method: Locator.isVisible
* since: v1.14 * since: v1.14
- returns: <[boolean]> - returns: <[boolean]>
@ -888,10 +887,9 @@ Returns whether the element is [visible](../actionability.md#visible).
### option: Locator.isVisible.timeout ### option: Locator.isVisible.timeout
* since: v1.14 * since: v1.14
* deprecated: This option is ignored. [`method: Locator.isVisible`] does not wait for the element to become visible and returns immediately.
- `timeout` <[float]> - `timeout` <[float]>
**DEPRECATED** This option is ignored. [`method: Locator.isVisible`] does not wait for the element to become visible and returns immediately.
## method: Locator.last ## method: Locator.last
* since: v1.14 * since: v1.14
- returns: <[Locator]> - returns: <[Locator]>

99
docs/src/api/class-page.md
View file

@ -558,10 +558,10 @@ page.
## property: Page.accessibility ## property: Page.accessibility
* since: v1.8 * since: v1.8
* langs: csharp, js, python * langs: csharp, js, python
* deprecated: This property is discouraged. Please use other libraries such as
[Axe](https://www.deque.com/axe/) if you need to test page accessibility. See our Node.js [guide](https://playwright.dev/docs/accessibility-testing) for integration with Axe.
- type: <[Accessibility]> - type: <[Accessibility]>
**DEPRECATED** This property is deprecated. Please use other libraries such as [Axe](https://www.deque.com/axe/) if you need to test page accessibility. See our Node.js [guide](https://playwright.dev/docs/accessibility-testing) for integration with Axe.
## async method: Page.addInitScript ## async method: Page.addInitScript
* since: v1.8 * since: v1.8
@ -642,8 +642,6 @@ Optional argument to pass to [`param: script`] (only supported when passing a fu
Adds a `<script>` tag into the page with the desired url or content. Returns the added tag when the script's onload Adds a `<script>` tag into the page with the desired url or content. Returns the added tag when the script's onload
fires or when the script content was injected into frame. fires or when the script content was injected into frame.
Shortcut for main frame's [`method: Frame.addScriptTag`].
### option: Page.addScriptTag.url ### option: Page.addScriptTag.url
* since: v1.8 * since: v1.8
- `url` <[string]> - `url` <[string]>
@ -677,8 +675,6 @@ Script type. Use 'module' in order to load a Javascript ES6 module. See
Adds a `<link rel="stylesheet">` tag into the page with the desired url or a `<style type="text/css">` tag with the Adds a `<link rel="stylesheet">` tag into the page with the desired url or a `<style type="text/css">` tag with the
content. Returns the added tag when the stylesheet's onload fires or when the CSS content was injected into frame. content. Returns the added tag when the stylesheet's onload fires or when the CSS content was injected into frame.
Shortcut for main frame's [`method: Frame.addStyleTag`].
### option: Page.addStyleTag.url ### option: Page.addStyleTag.url
* since: v1.8 * since: v1.8
- `url` <[string]> - `url` <[string]>
@ -705,6 +701,7 @@ Brings page to front (activates tab).
## async method: Page.check ## async method: Page.check
* since: v1.8 * since: v1.8
* discouraged: Use locator-based [`method: Locator.check`] instead.
This method checks an element matching [`param: selector`] by performing the following steps: This method checks an element matching [`param: selector`] by performing the following steps:
1. Find an element matching [`param: selector`]. If there is none, wait until a matching element is attached to 1. Find an element matching [`param: selector`]. If there is none, wait until a matching element is attached to
@ -721,8 +718,6 @@ This method checks an element matching [`param: selector`] by performing the fol
When all steps combined have not finished during the specified [`option: timeout`], this method throws a When all steps combined have not finished during the specified [`option: timeout`], this method throws a
[TimeoutError]. Passing zero timeout disables this. [TimeoutError]. Passing zero timeout disables this.
Shortcut for main frame's [`method: Frame.check`].
### param: Page.check.selector = %%-input-selector-%% ### param: Page.check.selector = %%-input-selector-%%
* since: v1.8 * since: v1.8
@ -746,6 +741,7 @@ Shortcut for main frame's [`method: Frame.check`].
## async method: Page.click ## async method: Page.click
* since: v1.8 * since: v1.8
* discouraged: Use locator-based [`method: Locator.click`] instead.
This method clicks an element matching [`param: selector`] by performing the following steps: This method clicks an element matching [`param: selector`] by performing the following steps:
1. Find an element matching [`param: selector`]. If there is none, wait until a matching element is attached to 1. Find an element matching [`param: selector`]. If there is none, wait until a matching element is attached to
@ -759,8 +755,6 @@ This method clicks an element matching [`param: selector`] by performing the fol
When all steps combined have not finished during the specified [`option: timeout`], this method throws a When all steps combined have not finished during the specified [`option: timeout`], this method throws a
[TimeoutError]. Passing zero timeout disables this. [TimeoutError]. Passing zero timeout disables this.
Shortcut for main frame's [`method: Frame.click`].
### param: Page.click.selector = %%-input-selector-%% ### param: Page.click.selector = %%-input-selector-%%
* since: v1.8 * since: v1.8
@ -839,6 +833,7 @@ Browser-specific Coverage implementation. See [Coverage](#class-coverage) for mo
## async method: Page.dblclick ## async method: Page.dblclick
* since: v1.8 * since: v1.8
* discouraged: Use locator-based [`method: Locator.dblclick`] instead.
* langs: * langs:
- alias-csharp: DblClickAsync - alias-csharp: DblClickAsync
@ -859,8 +854,6 @@ When all steps combined have not finished during the specified [`option: timeout
`page.dblclick()` dispatches two `click` events and a single `dblclick` event. `page.dblclick()` dispatches two `click` events and a single `dblclick` event.
::: :::
Shortcut for main frame's [`method: Frame.dblclick`].
### param: Page.dblclick.selector = %%-input-selector-%% ### param: Page.dblclick.selector = %%-input-selector-%%
* since: v1.8 * since: v1.8
@ -893,6 +886,7 @@ Shortcut for main frame's [`method: Frame.dblclick`].
## async method: Page.dispatchEvent ## async method: Page.dispatchEvent
* since: v1.8 * since: v1.8
* discouraged: Use locator-based [`method: Locator.dispatchEvent`] instead.
The snippet below dispatches the `click` event on the element. Regardless of the visibility state of the element, `click` The snippet below dispatches the `click` event on the element. Regardless of the visibility state of the element, `click`
is dispatched. This is equivalent to calling is dispatched. This is equivalent to calling
@ -1283,6 +1277,7 @@ Emulates `'forced-colors'` media feature, supported values are `'active'` and `'
## async method: Page.evalOnSelector ## async method: Page.evalOnSelector
* since: v1.9 * since: v1.9
* discouraged: Use locator-based [`method: Locator.evaluate`] instead.
* langs: * langs:
- alias-python: eval_on_selector - alias-python: eval_on_selector
- alias-js: $eval - alias-js: $eval
@ -1334,8 +1329,6 @@ var preloadHref = await page.EvalOnSelectorAsync<string>("link[rel=preload]", "e
var html = await page.EvalOnSelectorAsync(".main-container", "(e, suffix) => e.outerHTML + suffix", "hello"); var html = await page.EvalOnSelectorAsync(".main-container", "(e, suffix) => e.outerHTML + suffix", "hello");
``` ```
Shortcut for main frame's [`method: Frame.evalOnSelector`].
### param: Page.evalOnSelector.selector = %%-query-selector-%% ### param: Page.evalOnSelector.selector = %%-query-selector-%%
* since: v1.9 * since: v1.9
@ -1353,6 +1346,7 @@ Optional argument to pass to [`param: expression`].
## async method: Page.evalOnSelectorAll ## async method: Page.evalOnSelectorAll
* since: v1.9 * since: v1.9
* discouraged: Use locator-based [`method: Locator.evaluateAll`] instead.
* langs: * langs:
- alias-python: eval_on_selector_all - alias-python: eval_on_selector_all
- alias-js: $$eval - alias-js: $$eval
@ -1508,8 +1502,6 @@ var html = await page.EvaluateAsync<string>("([body, suffix]) => body.innerHTML
await bodyHandle.DisposeAsync(); await bodyHandle.DisposeAsync();
``` ```
Shortcut for main frame's [`method: Frame.evaluate`].
### param: Page.evaluate.expression = %%-evaluate-expression-%% ### param: Page.evaluate.expression = %%-evaluate-expression-%%
* since: v1.8 * since: v1.8
@ -2054,6 +2046,7 @@ Callback function which will be called in Playwright's context.
## async method: Page.fill ## async method: Page.fill
* since: v1.8 * since: v1.8
* discouraged: Use locator-based [`method: Locator.fill`] instead.
This method waits for an element matching [`param: selector`], waits for [actionability](../actionability.md) checks, focuses the element, fills it and triggers an `input` event after filling. Note that you can pass an empty string to clear the input field. This method waits for an element matching [`param: selector`], waits for [actionability](../actionability.md) checks, focuses the element, fills it and triggers an `input` event after filling. Note that you can pass an empty string to clear the input field.
@ -2061,8 +2054,6 @@ If the target element is not an `<input>`, `<textarea>` or `[contenteditable]` e
To send fine-grained keyboard events, use [`method: Page.type`]. To send fine-grained keyboard events, use [`method: Page.type`].
Shortcut for main frame's [`method: Frame.fill`].
### param: Page.fill.selector = %%-input-selector-%% ### param: Page.fill.selector = %%-input-selector-%%
* since: v1.8 * since: v1.8
@ -2086,12 +2077,11 @@ Value to fill for the `<input>`, `<textarea>` or `[contenteditable]` element.
## async method: Page.focus ## async method: Page.focus
* since: v1.8 * since: v1.8
* discouraged: Use locator-based [`method: Locator.focus`] instead.
This method fetches an element with [`param: selector`] and focuses it. If there's no element matching This method fetches an element with [`param: selector`] and focuses it. If there's no element matching
[`param: selector`], the method waits until a matching element appears in the DOM. [`param: selector`], the method waits until a matching element appears in the DOM.
Shortcut for main frame's [`method: Frame.focus`].
### param: Page.focus.selector = %%-input-selector-%% ### param: Page.focus.selector = %%-input-selector-%%
* since: v1.8 * since: v1.8
@ -2220,6 +2210,7 @@ An array of all frames attached to the page.
## async method: Page.getAttribute ## async method: Page.getAttribute
* since: v1.8 * since: v1.8
* discouraged: Use locator-based [`method: Locator.getAttribute`] instead.
- returns: <[null]|[string]> - returns: <[null]|[string]>
Returns element attribute value. Returns element attribute value.
@ -2371,8 +2362,6 @@ Headless mode doesn't support navigation to a PDF document. See the
[upstream issue](https://bugs.chromium.org/p/chromium/issues/detail?id=761295). [upstream issue](https://bugs.chromium.org/p/chromium/issues/detail?id=761295).
::: :::
Shortcut for main frame's [`method: Frame.goto`]
### param: Page.goto.url ### param: Page.goto.url
* since: v1.8 * since: v1.8
- `url` <[string]> - `url` <[string]>
@ -2396,6 +2385,7 @@ Referer header value. If provided it will take preference over the referer heade
## async method: Page.hover ## async method: Page.hover
* since: v1.8 * since: v1.8
* discouraged: Use locator-based [`method: Locator.hover`] instead.
This method hovers over an element matching [`param: selector`] by performing the following steps: This method hovers over an element matching [`param: selector`] by performing the following steps:
1. Find an element matching [`param: selector`]. If there is none, wait until a matching element is attached to 1. Find an element matching [`param: selector`]. If there is none, wait until a matching element is attached to
@ -2409,8 +2399,6 @@ This method hovers over an element matching [`param: selector`] by performing th
When all steps combined have not finished during the specified [`option: timeout`], this method throws a When all steps combined have not finished during the specified [`option: timeout`], this method throws a
[TimeoutError]. Passing zero timeout disables this. [TimeoutError]. Passing zero timeout disables this.
Shortcut for main frame's [`method: Frame.hover`].
### param: Page.hover.selector = %%-input-selector-%% ### param: Page.hover.selector = %%-input-selector-%%
* since: v1.8 * since: v1.8
@ -2437,6 +2425,7 @@ Shortcut for main frame's [`method: Frame.hover`].
## async method: Page.innerHTML ## async method: Page.innerHTML
* since: v1.8 * since: v1.8
* discouraged: Use locator-based [`method: Locator.innerHTML`] instead.
- returns: <[string]> - returns: <[string]>
Returns `element.innerHTML`. Returns `element.innerHTML`.
@ -2452,6 +2441,7 @@ Returns `element.innerHTML`.
## async method: Page.innerText ## async method: Page.innerText
* since: v1.8 * since: v1.8
* discouraged: Use locator-based [`method: Locator.innerText`] instead.
- returns: <[string]> - returns: <[string]>
Returns `element.innerText`. Returns `element.innerText`.
@ -2467,6 +2457,7 @@ Returns `element.innerText`.
## async method: Page.inputValue ## async method: Page.inputValue
* since: v1.13 * since: v1.13
* discouraged: Use locator-based [`method: Locator.inputValue`] instead.
- returns: <[string]> - returns: <[string]>
Returns `input.value` for the selected `<input>` or `<textarea>` or `<select>` element. Returns `input.value` for the selected `<input>` or `<textarea>` or `<select>` element.
@ -2484,6 +2475,7 @@ Throws for non-input elements. However, if the element is inside the `<label>` e
## async method: Page.isChecked ## async method: Page.isChecked
* since: v1.8 * since: v1.8
* discouraged: Use locator-based [`method: Locator.isChecked`] instead.
- returns: <[boolean]> - returns: <[boolean]>
Returns whether the element is checked. Throws if the element is not a checkbox or radio input. Returns whether the element is checked. Throws if the element is not a checkbox or radio input.
@ -2505,6 +2497,7 @@ Indicates that the page has been closed.
## async method: Page.isDisabled ## async method: Page.isDisabled
* since: v1.8 * since: v1.8
* discouraged: Use locator-based [`method: Locator.isDisabled`] instead.
- returns: <[boolean]> - returns: <[boolean]>
Returns whether the element is disabled, the opposite of [enabled](../actionability.md#enabled). Returns whether the element is disabled, the opposite of [enabled](../actionability.md#enabled).
@ -2520,6 +2513,7 @@ Returns whether the element is disabled, the opposite of [enabled](../actionabil
## async method: Page.isEditable ## async method: Page.isEditable
* since: v1.8 * since: v1.8
* discouraged: Use locator-based [`method: Locator.isEditable`] instead.
- returns: <[boolean]> - returns: <[boolean]>
Returns whether the element is [editable](../actionability.md#editable). Returns whether the element is [editable](../actionability.md#editable).
@ -2535,6 +2529,7 @@ Returns whether the element is [editable](../actionability.md#editable).
## async method: Page.isEnabled ## async method: Page.isEnabled
* since: v1.8 * since: v1.8
* discouraged: Use locator-based [`method: Locator.isEnabled`] instead.
- returns: <[boolean]> - returns: <[boolean]>
Returns whether the element is [enabled](../actionability.md#enabled). Returns whether the element is [enabled](../actionability.md#enabled).
@ -2550,6 +2545,7 @@ Returns whether the element is [enabled](../actionability.md#enabled).
## async method: Page.isHidden ## async method: Page.isHidden
* since: v1.8 * since: v1.8
* discouraged: Use locator-based [`method: Locator.isHidden`] instead.
- returns: <[boolean]> - returns: <[boolean]>
Returns whether the element is hidden, the opposite of [visible](../actionability.md#visible). [`option: selector`] that does not match any elements is considered hidden. Returns whether the element is hidden, the opposite of [visible](../actionability.md#visible). [`option: selector`] that does not match any elements is considered hidden.
@ -2562,12 +2558,13 @@ Returns whether the element is hidden, the opposite of [visible](../actionabilit
### option: Page.isHidden.timeout ### option: Page.isHidden.timeout
* since: v1.8 * since: v1.8
* deprecated: This option is ignored. [`method: Page.isHidden`] does not wait for the
element to become hidden and returns immediately.
- `timeout` <[float]> - `timeout` <[float]>
**DEPRECATED** This option is ignored. [`method: Page.isHidden`] does not wait for the element to become hidden and returns immediately.
## async method: Page.isVisible ## async method: Page.isVisible
* since: v1.8 * since: v1.8
* discouraged: Use locator-based [`method: Locator.isVisible`] instead.
- returns: <[boolean]> - returns: <[boolean]>
Returns whether the element is [visible](../actionability.md#visible). [`option: selector`] that does not match any elements is considered not visible. Returns whether the element is [visible](../actionability.md#visible). [`option: selector`] that does not match any elements is considered not visible.
@ -2580,10 +2577,10 @@ Returns whether the element is [visible](../actionability.md#visible). [`option:
### option: Page.isVisible.timeout ### option: Page.isVisible.timeout
* since: v1.8 * since: v1.8
* deprecated: This option is ignored. [`method: Page.isVisible`] does not wait
for the element to become visible and returns immediately.
- `timeout` <[float]> - `timeout` <[float]>
**DEPRECATED** This option is ignored. [`method: Page.isVisible`] does not wait for the element to become visible and returns immediately.
## property: Page.keyboard ## property: Page.keyboard
* since: v1.8 * since: v1.8
- type: <[Keyboard]> - type: <[Keyboard]>
@ -2834,6 +2831,7 @@ size.
## async method: Page.press ## async method: Page.press
* since: v1.8 * since: v1.8
* discouraged: Use locator-based [`method: Locator.press`] instead.
Focuses the element, and then uses [`method: Keyboard.down`] and [`method: Keyboard.up`]. Focuses the element, and then uses [`method: Keyboard.down`] and [`method: Keyboard.up`].
@ -2941,20 +2939,15 @@ Time to wait between `keydown` and `keyup` in milliseconds. Defaults to 0.
## async method: Page.querySelector ## async method: Page.querySelector
* since: v1.9 * since: v1.9
* discouraged: Use locator-based [`method: Page.locator`] instead.
* langs: * langs:
- alias-python: query_selector - alias-python: query_selector
- alias-js: $ - alias-js: $
- returns: <[null]|[ElementHandle]> - returns: <[null]|[ElementHandle]>
:::caution
The use of [ElementHandle] is discouraged, use [Locator] objects and web-first assertions instead.
:::
The method finds an element matching the specified selector within the page. If no elements match the selector, the The method finds an element matching the specified selector within the page. If no elements match the selector, the
return value resolves to `null`. To wait for an element on the page, use [`method: Locator.waitFor`]. return value resolves to `null`. To wait for an element on the page, use [`method: Locator.waitFor`].
Shortcut for main frame's [`method: Frame.querySelector`].
### param: Page.querySelector.selector = %%-query-selector-%% ### param: Page.querySelector.selector = %%-query-selector-%%
* since: v1.9 * since: v1.9
@ -2963,20 +2956,15 @@ Shortcut for main frame's [`method: Frame.querySelector`].
## async method: Page.querySelectorAll ## async method: Page.querySelectorAll
* since: v1.9 * since: v1.9
* discouraged: Use locator-based [`method: Page.locator`] instead.
* langs: * langs:
- alias-python: query_selector_all - alias-python: query_selector_all
- alias-js: $$ - alias-js: $$
- returns: <[Array]<[ElementHandle]>> - returns: <[Array]<[ElementHandle]>>
:::caution
The use of [ElementHandle] is discouraged, use [Locator] objects and web-first assertions instead.
:::
The method finds all elements matching the specified selector within the page. If no elements match the selector, the The method finds all elements matching the specified selector within the page. If no elements match the selector, the
return value resolves to `[]`. return value resolves to `[]`.
Shortcut for main frame's [`method: Frame.querySelectorAll`].
### param: Page.querySelectorAll.selector = %%-query-selector-%% ### param: Page.querySelectorAll.selector = %%-query-selector-%%
* since: v1.9 * since: v1.9
@ -3227,6 +3215,7 @@ Returns the buffer with the captured screenshot.
## async method: Page.selectOption ## async method: Page.selectOption
* since: v1.8 * since: v1.8
* discouraged: Use locator-based [`method: Locator.selectOption`] instead.
- returns: <[Array]<[string]>> - returns: <[Array]<[string]>>
This method waits for an element matching [`param: selector`], waits for [actionability](../actionability.md) checks, waits until all specified options are present in the `<select>` element and selects these options. This method waits for an element matching [`param: selector`], waits for [actionability](../actionability.md) checks, waits until all specified options are present in the `<select>` element and selects these options.
@ -3287,8 +3276,6 @@ await page.SelectOptionAsync("select#colors", new[] { new SelectOptionValue() {
await page.SelectOptionAsync("select#colors", new[] { "red", "green", "blue" }); await page.SelectOptionAsync("select#colors", new[] { "red", "green", "blue" });
``` ```
Shortcut for main frame's [`method: Frame.selectOption`].
### param: Page.selectOption.selector = %%-input-selector-%% ### param: Page.selectOption.selector = %%-input-selector-%%
* since: v1.8 * since: v1.8
@ -3309,6 +3296,7 @@ Shortcut for main frame's [`method: Frame.selectOption`].
## async method: Page.setChecked ## async method: Page.setChecked
* since: v1.15 * since: v1.15
* discouraged: Use locator-based [`method: Locator.setChecked`] instead.
This method checks or unchecks an element matching [`param: selector`] by performing the following steps: This method checks or unchecks an element matching [`param: selector`] by performing the following steps:
1. Find an element matching [`param: selector`]. If there is none, wait until a matching element is attached to 1. Find an element matching [`param: selector`]. If there is none, wait until a matching element is attached to
@ -3325,8 +3313,6 @@ This method checks or unchecks an element matching [`param: selector`] by perfor
When all steps combined have not finished during the specified [`option: timeout`], this method throws a When all steps combined have not finished during the specified [`option: timeout`], this method throws a
[TimeoutError]. Passing zero timeout disables this. [TimeoutError]. Passing zero timeout disables this.
Shortcut for main frame's [`method: Frame.setChecked`].
### param: Page.setChecked.selector = %%-input-selector-%% ### param: Page.setChecked.selector = %%-input-selector-%%
* since: v1.15 * since: v1.15
@ -3421,6 +3407,7 @@ An object containing additional HTTP headers to be sent with every request. All
## async method: Page.setInputFiles ## async method: Page.setInputFiles
* since: v1.8 * since: v1.8
* discouraged: Use locator-based [`method: Locator.setInputFiles`] instead.
Sets the value of the file input to these file paths or files. If some of the `filePaths` are relative paths, then they Sets the value of the file input to these file paths or files. If some of the `filePaths` are relative paths, then they
are resolved relative to the current working directory. For empty array, clears the selected files. are resolved relative to the current working directory. For empty array, clears the selected files.
@ -3506,6 +3493,7 @@ await page.GotoAsync("https://www.microsoft.com");
## async method: Page.tap ## async method: Page.tap
* since: v1.8 * since: v1.8
* discouraged: Use locator-based [`method: Locator.tap`] instead.
This method taps an element matching [`param: selector`] by performing the following steps: This method taps an element matching [`param: selector`] by performing the following steps:
1. Find an element matching [`param: selector`]. If there is none, wait until a matching element is attached to 1. Find an element matching [`param: selector`]. If there is none, wait until a matching element is attached to
@ -3523,8 +3511,6 @@ When all steps combined have not finished during the specified [`option: timeout
[`method: Page.tap`] requires that the [`option: hasTouch`] option of the browser context be set to true. [`method: Page.tap`] requires that the [`option: hasTouch`] option of the browser context be set to true.
::: :::
Shortcut for main frame's [`method: Frame.tap`].
### param: Page.tap.selector = %%-input-selector-%% ### param: Page.tap.selector = %%-input-selector-%%
* since: v1.8 * since: v1.8
@ -3551,6 +3537,7 @@ Shortcut for main frame's [`method: Frame.tap`].
## async method: Page.textContent ## async method: Page.textContent
* since: v1.8 * since: v1.8
* discouraged: Use locator-based [`method: Locator.textContent`] instead.
- returns: <[null]|[string]> - returns: <[null]|[string]>
Returns `element.textContent`. Returns `element.textContent`.
@ -3568,7 +3555,7 @@ Returns `element.textContent`.
* since: v1.8 * since: v1.8
- returns: <[string]> - returns: <[string]>
Returns the page's title. Shortcut for main frame's [`method: Frame.title`]. Returns the page's title.
## property: Page.touchscreen ## property: Page.touchscreen
* since: v1.8 * since: v1.8
@ -3576,6 +3563,7 @@ Returns the page's title. Shortcut for main frame's [`method: Frame.title`].
## async method: Page.type ## async method: Page.type
* since: v1.8 * since: v1.8
* discouraged: Use locator-based [`method: Locator.type`] instead.
Sends a `keydown`, `keypress`/`input`, and `keyup` event for each character in the text. `page.type` can be used to send Sends a `keydown`, `keypress`/`input`, and `keyup` event for each character in the text. `page.type` can be used to send
fine-grained keyboard events. To fill values in form fields, use [`method: Page.fill`]. fine-grained keyboard events. To fill values in form fields, use [`method: Page.fill`].
@ -3611,8 +3599,6 @@ await page.TypeAsync("#mytextarea", "hello"); // types instantly
await page.TypeAsync("#mytextarea", "world", new() { Delay = 100 }); // types slower, like a user await page.TypeAsync("#mytextarea", "world", new() { Delay = 100 }); // types slower, like a user
``` ```
Shortcut for main frame's [`method: Frame.type`].
### param: Page.type.selector = %%-input-selector-%% ### param: Page.type.selector = %%-input-selector-%%
* since: v1.8 * since: v1.8
@ -3639,6 +3625,7 @@ Time to wait between key presses in milliseconds. Defaults to 0.
## async method: Page.uncheck ## async method: Page.uncheck
* since: v1.8 * since: v1.8
* discouraged: Use locator-based [`method: Locator.uncheck`] instead.
This method unchecks an element matching [`param: selector`] by performing the following steps: This method unchecks an element matching [`param: selector`] by performing the following steps:
1. Find an element matching [`param: selector`]. If there is none, wait until a matching element is attached to 1. Find an element matching [`param: selector`]. If there is none, wait until a matching element is attached to
@ -3655,8 +3642,6 @@ This method unchecks an element matching [`param: selector`] by performing the f
When all steps combined have not finished during the specified [`option: timeout`], this method throws a When all steps combined have not finished during the specified [`option: timeout`], this method throws a
[TimeoutError]. Passing zero timeout disables this. [TimeoutError]. Passing zero timeout disables this.
Shortcut for main frame's [`method: Frame.uncheck`].
### param: Page.uncheck.selector = %%-input-selector-%% ### param: Page.uncheck.selector = %%-input-selector-%%
* since: v1.8 * since: v1.8
@ -3708,8 +3693,6 @@ Optional handler function to route the request.
* since: v1.8 * since: v1.8
- returns: <[string]> - returns: <[string]>
Shortcut for main frame's [`method: Frame.url`].
## method: Page.video ## method: Page.video
* since: v1.8 * since: v1.8
- returns: <[null]|[Video]> - returns: <[null]|[Video]>
@ -3956,8 +3939,6 @@ var selector = ".foo";
await page.WaitForFunctionAsync("selector => !!document.querySelector(selector)", selector); await page.WaitForFunctionAsync("selector => !!document.querySelector(selector)", selector);
``` ```
Shortcut for main frame's [`method: Frame.waitForFunction`].
### param: Page.waitForFunction.expression = %%-evaluate-expression-%% ### param: Page.waitForFunction.expression = %%-evaluate-expression-%%
* since: v1.8 * since: v1.8
@ -4057,8 +4038,6 @@ await popup.WaitForLoadStateAsync(LoadState.DOMContentLoaded);
Console.WriteLine(await popup.TitleAsync()); // popup is ready to use. Console.WriteLine(await popup.TitleAsync()); // popup is ready to use.
``` ```
Shortcut for main frame's [`method: Frame.waitForLoadState`].
### param: Page.waitForLoadState.state = %%-wait-for-load-state-state-%% ### param: Page.waitForLoadState.state = %%-wait-for-load-state-state-%%
* since: v1.8 * since: v1.8
@ -4127,8 +4106,6 @@ Usage of the [History API](https://developer.mozilla.org/en-US/docs/Web/API/Hist
a navigation. a navigation.
::: :::
Shortcut for main frame's [`method: Frame.waitForNavigation`].
### option: Page.waitForNavigation.url = %%-wait-for-navigation-url-%% ### option: Page.waitForNavigation.url = %%-wait-for-navigation-url-%%
* since: v1.8 * since: v1.8
@ -4559,8 +4536,6 @@ page.wait_for_timeout(1000)
await page.WaitForTimeoutAsync(1000); await page.WaitForTimeoutAsync(1000);
``` ```
Shortcut for main frame's [`method: Frame.waitForTimeout`].
### param: Page.waitForTimeout.timeout ### param: Page.waitForTimeout.timeout
* since: v1.8 * since: v1.8
- `timeout` <[float]> - `timeout` <[float]>
@ -4599,8 +4574,6 @@ await page.ClickAsync("a.delayed-navigation"); // clicking the link will indirec
await page.WaitForURLAsync("**/target.html"); await page.WaitForURLAsync("**/target.html");
``` ```
Shortcut for main frame's [`method: Frame.waitForURL`].
### param: Page.waitForURL.url = %%-wait-for-navigation-url-%% ### param: Page.waitForURL.url = %%-wait-for-navigation-url-%%
* since: v1.11 * since: v1.11

6
docs/src/api/params.md
View file

@ -568,18 +568,16 @@ Logger sink for Playwright logging.
## context-option-videospath ## context-option-videospath
* langs: js * langs: js
* deprecated: Use [`option: recordVideo`] instead.
- `videosPath` <[path]> - `videosPath` <[path]>
**DEPRECATED** Use [`option: recordVideo`] instead.
## context-option-videosize ## context-option-videosize
* langs: js * langs: js
* deprecated: Use [`option: recordVideo`] instead.
- `videoSize` <[Object]> - `videoSize` <[Object]>
- `width` <[int]> Video frame width. - `width` <[int]> Video frame width.
- `height` <[int]> Video frame height. - `height` <[int]> Video frame height.
**DEPRECATED** Use [`option: recordVideo`] instead.
## context-option-recordhar ## context-option-recordhar
* langs: js * langs: js
- `recordHar` <[Object]> - `recordHar` <[Object]>

162
packages/playwright-core/types/types.d.ts vendored
View file

@ -116,8 +116,6 @@ export interface Page {
* await bodyHandle.dispose(); * await bodyHandle.dispose();
* ``` * ```
* *
* Shortcut for main frame's
* [frame.evaluate(pageFunction[, arg])](https://playwright.dev/docs/api/class-frame#frame-evaluate).
* @param pageFunction Function to be evaluated in the page context. * @param pageFunction Function to be evaluated in the page context.
* @param arg Optional argument to pass to `pageFunction`. * @param arg Optional argument to pass to `pageFunction`.
*/ */
@ -165,8 +163,6 @@ export interface Page {
* await bodyHandle.dispose(); * await bodyHandle.dispose();
* ``` * ```
* *
* Shortcut for main frame's
* [frame.evaluate(pageFunction[, arg])](https://playwright.dev/docs/api/class-frame#frame-evaluate).
* @param pageFunction Function to be evaluated in the page context. * @param pageFunction Function to be evaluated in the page context.
* @param arg Optional argument to pass to `pageFunction`. * @param arg Optional argument to pass to `pageFunction`.
*/ */
@ -290,51 +286,31 @@ export interface Page {
addInitScript<Arg>(script: PageFunction<Arg, any> | { path?: string, content?: string }, arg?: Arg): Promise<void>; addInitScript<Arg>(script: PageFunction<Arg, any> | { path?: string, content?: string }, arg?: Arg): Promise<void>;
/** /**
* > NOTE: The use of [ElementHandle] is discouraged, use [Locator] objects and web-first assertions instead.
*
* The method finds an element matching the specified selector within the page. If no elements match the selector, the * The method finds an element matching the specified selector within the page. If no elements match the selector, the
* return value resolves to `null`. To wait for an element on the page, use * return value resolves to `null`. To wait for an element on the page, use
* [locator.waitFor([options])](https://playwright.dev/docs/api/class-locator#locator-wait-for). * [locator.waitFor([options])](https://playwright.dev/docs/api/class-locator#locator-wait-for).
*
* Shortcut for main frame's
* [frame.$(selector[, options])](https://playwright.dev/docs/api/class-frame#frame-query-selector).
* @param selector A selector to query for. See [working with selectors](https://playwright.dev/docs/selectors) for more details. * @param selector A selector to query for. See [working with selectors](https://playwright.dev/docs/selectors) for more details.
* @param options * @param options
*/ */
$<K extends keyof HTMLElementTagNameMap>(selector: K, options?: { strict: boolean }): Promise<ElementHandleForTag<K> | null>; $<K extends keyof HTMLElementTagNameMap>(selector: K, options?: { strict: boolean }): Promise<ElementHandleForTag<K> | null>;
/** /**
* > NOTE: The use of [ElementHandle] is discouraged, use [Locator] objects and web-first assertions instead.
*
* The method finds an element matching the specified selector within the page. If no elements match the selector, the * The method finds an element matching the specified selector within the page. If no elements match the selector, the
* return value resolves to `null`. To wait for an element on the page, use * return value resolves to `null`. To wait for an element on the page, use
* [locator.waitFor([options])](https://playwright.dev/docs/api/class-locator#locator-wait-for). * [locator.waitFor([options])](https://playwright.dev/docs/api/class-locator#locator-wait-for).
*
* Shortcut for main frame's
* [frame.$(selector[, options])](https://playwright.dev/docs/api/class-frame#frame-query-selector).
* @param selector A selector to query for. See [working with selectors](https://playwright.dev/docs/selectors) for more details. * @param selector A selector to query for. See [working with selectors](https://playwright.dev/docs/selectors) for more details.
* @param options * @param options
*/ */
$(selector: string, options?: { strict: boolean }): Promise<ElementHandle<SVGElement | HTMLElement> | null>; $(selector: string, options?: { strict: boolean }): Promise<ElementHandle<SVGElement | HTMLElement> | null>;
/** /**
* > NOTE: The use of [ElementHandle] is discouraged, use [Locator] objects and web-first assertions instead.
*
* The method finds all elements matching the specified selector within the page. If no elements match the selector, * The method finds all elements matching the specified selector within the page. If no elements match the selector,
* the return value resolves to `[]`. * the return value resolves to `[]`.
*
* Shortcut for main frame's
* [frame.$$(selector)](https://playwright.dev/docs/api/class-frame#frame-query-selector-all).
* @param selector A selector to query for. See [working with selectors](https://playwright.dev/docs/selectors) for more details. * @param selector A selector to query for. See [working with selectors](https://playwright.dev/docs/selectors) for more details.
*/ */
$$<K extends keyof HTMLElementTagNameMap>(selector: K): Promise<ElementHandleForTag<K>[]>; $$<K extends keyof HTMLElementTagNameMap>(selector: K): Promise<ElementHandleForTag<K>[]>;
/** /**
* > NOTE: The use of [ElementHandle] is discouraged, use [Locator] objects and web-first assertions instead.
*
* The method finds all elements matching the specified selector within the page. If no elements match the selector, * The method finds all elements matching the specified selector within the page. If no elements match the selector,
* the return value resolves to `[]`. * the return value resolves to `[]`.
*
* Shortcut for main frame's
* [frame.$$(selector)](https://playwright.dev/docs/api/class-frame#frame-query-selector-all).
* @param selector A selector to query for. See [working with selectors](https://playwright.dev/docs/selectors) for more details. * @param selector A selector to query for. See [working with selectors](https://playwright.dev/docs/selectors) for more details.
*/ */
$$(selector: string): Promise<ElementHandle<SVGElement | HTMLElement>[]>; $$(selector: string): Promise<ElementHandle<SVGElement | HTMLElement>[]>;
@ -362,8 +338,6 @@ export interface Page {
* const preloadHrefTS = await page.$eval('link[rel=preload]', (el: HTMLLinkElement) => el.href); * const preloadHrefTS = await page.$eval('link[rel=preload]', (el: HTMLLinkElement) => el.href);
* ``` * ```
* *
* Shortcut for main frame's
* [frame.$eval(selector, pageFunction[, arg, options])](https://playwright.dev/docs/api/class-frame#frame-eval-on-selector).
* @param selector A selector to query for. See [working with selectors](https://playwright.dev/docs/selectors) for more details. * @param selector A selector to query for. See [working with selectors](https://playwright.dev/docs/selectors) for more details.
* @param pageFunction Function to be evaluated in the page context. * @param pageFunction Function to be evaluated in the page context.
* @param arg Optional argument to pass to `pageFunction`. * @param arg Optional argument to pass to `pageFunction`.
@ -393,8 +367,6 @@ export interface Page {
* const preloadHrefTS = await page.$eval('link[rel=preload]', (el: HTMLLinkElement) => el.href); * const preloadHrefTS = await page.$eval('link[rel=preload]', (el: HTMLLinkElement) => el.href);
* ``` * ```
* *
* Shortcut for main frame's
* [frame.$eval(selector, pageFunction[, arg, options])](https://playwright.dev/docs/api/class-frame#frame-eval-on-selector).
* @param selector A selector to query for. See [working with selectors](https://playwright.dev/docs/selectors) for more details. * @param selector A selector to query for. See [working with selectors](https://playwright.dev/docs/selectors) for more details.
* @param pageFunction Function to be evaluated in the page context. * @param pageFunction Function to be evaluated in the page context.
* @param arg Optional argument to pass to `pageFunction`. * @param arg Optional argument to pass to `pageFunction`.
@ -424,8 +396,6 @@ export interface Page {
* const preloadHrefTS = await page.$eval('link[rel=preload]', (el: HTMLLinkElement) => el.href); * const preloadHrefTS = await page.$eval('link[rel=preload]', (el: HTMLLinkElement) => el.href);
* ``` * ```
* *
* Shortcut for main frame's
* [frame.$eval(selector, pageFunction[, arg, options])](https://playwright.dev/docs/api/class-frame#frame-eval-on-selector).
* @param selector A selector to query for. See [working with selectors](https://playwright.dev/docs/selectors) for more details. * @param selector A selector to query for. See [working with selectors](https://playwright.dev/docs/selectors) for more details.
* @param pageFunction Function to be evaluated in the page context. * @param pageFunction Function to be evaluated in the page context.
* @param arg Optional argument to pass to `pageFunction`. * @param arg Optional argument to pass to `pageFunction`.
@ -455,8 +425,6 @@ export interface Page {
* const preloadHrefTS = await page.$eval('link[rel=preload]', (el: HTMLLinkElement) => el.href); * const preloadHrefTS = await page.$eval('link[rel=preload]', (el: HTMLLinkElement) => el.href);
* ``` * ```
* *
* Shortcut for main frame's
* [frame.$eval(selector, pageFunction[, arg, options])](https://playwright.dev/docs/api/class-frame#frame-eval-on-selector).
* @param selector A selector to query for. See [working with selectors](https://playwright.dev/docs/selectors) for more details. * @param selector A selector to query for. See [working with selectors](https://playwright.dev/docs/selectors) for more details.
* @param pageFunction Function to be evaluated in the page context. * @param pageFunction Function to be evaluated in the page context.
* @param arg Optional argument to pass to `pageFunction`. * @param arg Optional argument to pass to `pageFunction`.
@ -588,8 +556,6 @@ export interface Page {
* await page.waitForFunction(selector => !!document.querySelector(selector), selector); * await page.waitForFunction(selector => !!document.querySelector(selector), selector);
* ``` * ```
* *
* Shortcut for main frame's
* [frame.waitForFunction(pageFunction[, arg, options])](https://playwright.dev/docs/api/class-frame#frame-wait-for-function).
* @param pageFunction Function to be evaluated in the page context. * @param pageFunction Function to be evaluated in the page context.
* @param arg Optional argument to pass to `pageFunction`. * @param arg Optional argument to pass to `pageFunction`.
* @param options * @param options
@ -626,8 +592,6 @@ export interface Page {
* await page.waitForFunction(selector => !!document.querySelector(selector), selector); * await page.waitForFunction(selector => !!document.querySelector(selector), selector);
* ``` * ```
* *
* Shortcut for main frame's
* [frame.waitForFunction(pageFunction[, arg, options])](https://playwright.dev/docs/api/class-frame#frame-wait-for-function).
* @param pageFunction Function to be evaluated in the page context. * @param pageFunction Function to be evaluated in the page context.
* @param arg Optional argument to pass to `pageFunction`. * @param arg Optional argument to pass to `pageFunction`.
* @param options * @param options
@ -1785,19 +1749,13 @@ export interface Page {
prependListener(event: 'worker', listener: (worker: Worker) => void): this; prependListener(event: 'worker', listener: (worker: Worker) => void): this;
/** /**
* **DEPRECATED** This property is deprecated. Please use other libraries such as [Axe](https://www.deque.com/axe/) if * @deprecated This property is discouraged. Please use other libraries such as↵[Axe](https://www.deque.com/axe/) if you need to test page accessibility. See our Node.js [guide](https://playwright.dev/docs/accessibility-testing) for integration with Axe.
* you need to test page accessibility. See our Node.js [guide](https://playwright.dev/docs/accessibility-testing) for
* integration with Axe.
* @deprecated
*/ */
accessibility: Accessibility; accessibility: Accessibility;
/** /**
* Adds a `<script>` tag into the page with the desired url or content. Returns the added tag when the script's onload * Adds a `<script>` tag into the page with the desired url or content. Returns the added tag when the script's onload
* fires or when the script content was injected into frame. * fires or when the script content was injected into frame.
*
* Shortcut for main frame's
* [frame.addScriptTag([options])](https://playwright.dev/docs/api/class-frame#frame-add-script-tag).
* @param options * @param options
*/ */
addScriptTag(options?: { addScriptTag(options?: {
@ -1827,9 +1785,6 @@ export interface Page {
/** /**
* Adds a `<link rel="stylesheet">` tag into the page with the desired url or a `<style type="text/css">` tag with the * Adds a `<link rel="stylesheet">` tag into the page with the desired url or a `<style type="text/css">` tag with the
* content. Returns the added tag when the stylesheet's onload fires or when the CSS content was injected into frame. * content. Returns the added tag when the stylesheet's onload fires or when the CSS content was injected into frame.
*
* Shortcut for main frame's
* [frame.addStyleTag([options])](https://playwright.dev/docs/api/class-frame#frame-add-style-tag).
* @param options * @param options
*/ */
addStyleTag(options?: { addStyleTag(options?: {
@ -1870,9 +1825,6 @@ export interface Page {
* *
* When all steps combined have not finished during the specified `timeout`, this method throws a [TimeoutError]. * When all steps combined have not finished during the specified `timeout`, this method throws a [TimeoutError].
* Passing zero timeout disables this. * Passing zero timeout disables this.
*
* Shortcut for main frame's
* [frame.check(selector[, options])](https://playwright.dev/docs/api/class-frame#frame-check).
* @param selector A selector to search for an element. If there are multiple elements satisfying the selector, the first will be used. See [working with selectors](https://playwright.dev/docs/selectors) for more details. * @param selector A selector to search for an element. If there are multiple elements satisfying the selector, the first will be used. See [working with selectors](https://playwright.dev/docs/selectors) for more details.
* @param options * @param options
*/ */
@ -1932,9 +1884,6 @@ export interface Page {
* *
* When all steps combined have not finished during the specified `timeout`, this method throws a [TimeoutError]. * When all steps combined have not finished during the specified `timeout`, this method throws a [TimeoutError].
* Passing zero timeout disables this. * Passing zero timeout disables this.
*
* Shortcut for main frame's
* [frame.click(selector[, options])](https://playwright.dev/docs/api/class-frame#frame-click).
* @param selector A selector to search for an element. If there are multiple elements satisfying the selector, the first will be used. See [working with selectors](https://playwright.dev/docs/selectors) for more details. * @param selector A selector to search for an element. If there are multiple elements satisfying the selector, the first will be used. See [working with selectors](https://playwright.dev/docs/selectors) for more details.
* @param options * @param options
*/ */
@ -2053,9 +2002,6 @@ export interface Page {
* Passing zero timeout disables this. * Passing zero timeout disables this.
* *
* > NOTE: `page.dblclick()` dispatches two `click` events and a single `dblclick` event. * > NOTE: `page.dblclick()` dispatches two `click` events and a single `dblclick` event.
*
* Shortcut for main frame's
* [frame.dblclick(selector[, options])](https://playwright.dev/docs/api/class-frame#frame-dblclick).
* @param selector A selector to search for an element. If there are multiple elements satisfying the selector, the first will be used. See [working with selectors](https://playwright.dev/docs/selectors) for more details. * @param selector A selector to search for an element. If there are multiple elements satisfying the selector, the first will be used. See [working with selectors](https://playwright.dev/docs/selectors) for more details.
* @param options * @param options
*/ */
@ -2363,9 +2309,6 @@ export interface Page {
* *
* To send fine-grained keyboard events, use * To send fine-grained keyboard events, use
* [page.type(selector, text[, options])](https://playwright.dev/docs/api/class-page#page-type). * [page.type(selector, text[, options])](https://playwright.dev/docs/api/class-page#page-type).
*
* Shortcut for main frame's
* [frame.fill(selector, value[, options])](https://playwright.dev/docs/api/class-frame#frame-fill).
* @param selector A selector to search for an element. If there are multiple elements satisfying the selector, the first will be used. See [working with selectors](https://playwright.dev/docs/selectors) for more details. * @param selector A selector to search for an element. If there are multiple elements satisfying the selector, the first will be used. See [working with selectors](https://playwright.dev/docs/selectors) for more details.
* @param value Value to fill for the `<input>`, `<textarea>` or `[contenteditable]` element. * @param value Value to fill for the `<input>`, `<textarea>` or `[contenteditable]` element.
* @param options * @param options
@ -2401,9 +2344,6 @@ export interface Page {
/** /**
* This method fetches an element with `selector` and focuses it. If there's no element matching `selector`, the * This method fetches an element with `selector` and focuses it. If there's no element matching `selector`, the
* method waits until a matching element appears in the DOM. * method waits until a matching element appears in the DOM.
*
* Shortcut for main frame's
* [frame.focus(selector[, options])](https://playwright.dev/docs/api/class-frame#frame-focus).
* @param selector A selector to search for an element. If there are multiple elements satisfying the selector, the first will be used. See [working with selectors](https://playwright.dev/docs/selectors) for more details. * @param selector A selector to search for an element. If there are multiple elements satisfying the selector, the first will be used. See [working with selectors](https://playwright.dev/docs/selectors) for more details.
* @param options * @param options
*/ */
@ -2793,8 +2733,6 @@ export interface Page {
* to `about:blank` or navigation to the same URL with a different hash, which would succeed and return `null`. * to `about:blank` or navigation to the same URL with a different hash, which would succeed and return `null`.
* > NOTE: Headless mode doesn't support navigation to a PDF document. See the * > NOTE: Headless mode doesn't support navigation to a PDF document. See the
* [upstream issue](https://bugs.chromium.org/p/chromium/issues/detail?id=761295). * [upstream issue](https://bugs.chromium.org/p/chromium/issues/detail?id=761295).
*
* Shortcut for main frame's [frame.goto(url[, options])](https://playwright.dev/docs/api/class-frame#frame-goto)
* @param url URL to navigate page to. The url should include scheme, e.g. `https://`. When a `baseURL` via the context options was provided and the passed URL is a path, it gets merged via the * @param url URL to navigate page to. The url should include scheme, e.g. `https://`. When a `baseURL` via the context options was provided and the passed URL is a path, it gets merged via the
* [`new URL()`](https://developer.mozilla.org/en-US/docs/Web/API/URL/URL) constructor. * [`new URL()`](https://developer.mozilla.org/en-US/docs/Web/API/URL/URL) constructor.
* @param options * @param options
@ -2840,9 +2778,6 @@ export interface Page {
* *
* When all steps combined have not finished during the specified `timeout`, this method throws a [TimeoutError]. * When all steps combined have not finished during the specified `timeout`, this method throws a [TimeoutError].
* Passing zero timeout disables this. * Passing zero timeout disables this.
*
* Shortcut for main frame's
* [frame.hover(selector[, options])](https://playwright.dev/docs/api/class-frame#frame-hover).
* @param selector A selector to search for an element. If there are multiple elements satisfying the selector, the first will be used. See [working with selectors](https://playwright.dev/docs/selectors) for more details. * @param selector A selector to search for an element. If there are multiple elements satisfying the selector, the first will be used. See [working with selectors](https://playwright.dev/docs/selectors) for more details.
* @param options * @param options
*/ */
@ -3066,10 +3001,7 @@ export interface Page {
strict?: boolean; strict?: boolean;
/** /**
* **DEPRECATED** This option is ignored. * @deprecated This option is ignored. [`method: Page.isHidden`] does not wait for the↵element to become hidden and returns immediately.
* [page.isHidden(selector[, options])](https://playwright.dev/docs/api/class-page#page-is-hidden) does not wait for
* the element to become hidden and returns immediately.
* @deprecated
*/ */
timeout?: number; timeout?: number;
}): Promise<boolean>; }): Promise<boolean>;
@ -3088,10 +3020,7 @@ export interface Page {
strict?: boolean; strict?: boolean;
/** /**
* **DEPRECATED** This option is ignored. * @deprecated This option is ignored. [`method: Page.isVisible`] does not wait↵for the element to become visible and returns immediately.
* [page.isVisible(selector[, options])](https://playwright.dev/docs/api/class-page#page-is-visible) does not wait for
* the element to become visible and returns immediately.
* @deprecated
*/ */
timeout?: number; timeout?: number;
}): Promise<boolean>; }): Promise<boolean>;
@ -3533,8 +3462,6 @@ export interface Page {
* *
* ``` * ```
* *
* Shortcut for main frame's
* [frame.selectOption(selector, values[, options])](https://playwright.dev/docs/api/class-frame#frame-select-option).
* @param selector A selector to search for an element. If there are multiple elements satisfying the selector, the first will be used. See [working with selectors](https://playwright.dev/docs/selectors) for more details. * @param selector A selector to search for an element. If there are multiple elements satisfying the selector, the first will be used. See [working with selectors](https://playwright.dev/docs/selectors) for more details.
* @param values Options to select. If the `<select>` has the `multiple` attribute, all matching options are selected, otherwise only the first option matching one of the passed options is selected. String values are equivalent to * @param values Options to select. If the `<select>` has the `multiple` attribute, all matching options are selected, otherwise only the first option matching one of the passed options is selected. String values are equivalent to
* `{value:'string'}`. Option is considered matching if all specified properties match. * `{value:'string'}`. Option is considered matching if all specified properties match.
@ -3613,9 +3540,6 @@ export interface Page {
* *
* When all steps combined have not finished during the specified `timeout`, this method throws a [TimeoutError]. * When all steps combined have not finished during the specified `timeout`, this method throws a [TimeoutError].
* Passing zero timeout disables this. * Passing zero timeout disables this.
*
* Shortcut for main frame's
* [frame.setChecked(selector, checked[, options])](https://playwright.dev/docs/api/class-frame#frame-set-checked).
* @param selector A selector to search for an element. If there are multiple elements satisfying the selector, the first will be used. See [working with selectors](https://playwright.dev/docs/selectors) for more details. * @param selector A selector to search for an element. If there are multiple elements satisfying the selector, the first will be used. See [working with selectors](https://playwright.dev/docs/selectors) for more details.
* @param checked Whether to check or uncheck the checkbox. * @param checked Whether to check or uncheck the checkbox.
* @param options * @param options
@ -3850,8 +3774,6 @@ export interface Page {
* *
* > NOTE: [page.tap(selector[, options])](https://playwright.dev/docs/api/class-page#page-tap) requires that the * > NOTE: [page.tap(selector[, options])](https://playwright.dev/docs/api/class-page#page-tap) requires that the
* `hasTouch` option of the browser context be set to true. * `hasTouch` option of the browser context be set to true.
*
* Shortcut for main frame's [frame.tap(selector[, options])](https://playwright.dev/docs/api/class-frame#frame-tap).
* @param selector A selector to search for an element. If there are multiple elements satisfying the selector, the first will be used. See [working with selectors](https://playwright.dev/docs/selectors) for more details. * @param selector A selector to search for an element. If there are multiple elements satisfying the selector, the first will be used. See [working with selectors](https://playwright.dev/docs/selectors) for more details.
* @param options * @param options
*/ */
@ -3927,8 +3849,7 @@ export interface Page {
}): Promise<null|string>; }): Promise<null|string>;
/** /**
* Returns the page's title. Shortcut for main frame's * Returns the page's title.
* [frame.title()](https://playwright.dev/docs/api/class-frame#frame-title).
*/ */
title(): Promise<string>; title(): Promise<string>;
@ -3949,8 +3870,6 @@ export interface Page {
* await page.type('#mytextarea', 'World', {delay: 100}); // Types slower, like a user * await page.type('#mytextarea', 'World', {delay: 100}); // Types slower, like a user
* ``` * ```
* *
* Shortcut for main frame's
* [frame.type(selector, text[, options])](https://playwright.dev/docs/api/class-frame#frame-type).
* @param selector A selector to search for an element. If there are multiple elements satisfying the selector, the first will be used. See [working with selectors](https://playwright.dev/docs/selectors) for more details. * @param selector A selector to search for an element. If there are multiple elements satisfying the selector, the first will be used. See [working with selectors](https://playwright.dev/docs/selectors) for more details.
* @param text A text to type into a focused element. * @param text A text to type into a focused element.
* @param options * @param options
@ -3998,9 +3917,6 @@ export interface Page {
* *
* When all steps combined have not finished during the specified `timeout`, this method throws a [TimeoutError]. * When all steps combined have not finished during the specified `timeout`, this method throws a [TimeoutError].
* Passing zero timeout disables this. * Passing zero timeout disables this.
*
* Shortcut for main frame's
* [frame.uncheck(selector[, options])](https://playwright.dev/docs/api/class-frame#frame-uncheck).
* @param selector A selector to search for an element. If there are multiple elements satisfying the selector, the first will be used. See [working with selectors](https://playwright.dev/docs/selectors) for more details. * @param selector A selector to search for an element. If there are multiple elements satisfying the selector, the first will be used. See [working with selectors](https://playwright.dev/docs/selectors) for more details.
* @param options * @param options
*/ */
@ -4057,9 +3973,6 @@ export interface Page {
*/ */
unroute(url: string|RegExp|((url: URL) => boolean), handler?: ((route: Route, request: Request) => void)): Promise<void>; unroute(url: string|RegExp|((url: URL) => boolean), handler?: ((route: Route, request: Request) => void)): Promise<void>;
/**
* Shortcut for main frame's [frame.url()](https://playwright.dev/docs/api/class-frame#frame-url).
*/
url(): string; url(): string;
/** /**
@ -4307,8 +4220,6 @@ export interface Page {
* console.log(await popup.title()); // Popup is ready to use. * console.log(await popup.title()); // Popup is ready to use.
* ``` * ```
* *
* Shortcut for main frame's
* [frame.waitForLoadState([state, options])](https://playwright.dev/docs/api/class-frame#frame-wait-for-load-state).
* @param state Optional load state to wait for, defaults to `load`. If the state has been already reached while loading current document, the method resolves immediately. Can be one of: * @param state Optional load state to wait for, defaults to `load`. If the state has been already reached while loading current document, the method resolves immediately. Can be one of:
* - `'load'` - wait for the `load` event to be fired. * - `'load'` - wait for the `load` event to be fired.
* - `'domcontentloaded'` - wait for the `DOMContentLoaded` event to be fired. * - `'domcontentloaded'` - wait for the `DOMContentLoaded` event to be fired.
@ -4351,9 +4262,6 @@ export interface Page {
* *
* > NOTE: Usage of the [History API](https://developer.mozilla.org/en-US/docs/Web/API/History_API) to change the URL * > NOTE: Usage of the [History API](https://developer.mozilla.org/en-US/docs/Web/API/History_API) to change the URL
* is considered a navigation. * is considered a navigation.
*
* Shortcut for main frame's
* [frame.waitForNavigation([options])](https://playwright.dev/docs/api/class-frame#frame-wait-for-navigation).
* @param options * @param options
*/ */
waitForNavigation(options?: { waitForNavigation(options?: {
@ -4475,8 +4383,6 @@ export interface Page {
* await page.waitForTimeout(1000); * await page.waitForTimeout(1000);
* ``` * ```
* *
* Shortcut for main frame's
* [frame.waitForTimeout(timeout)](https://playwright.dev/docs/api/class-frame#frame-wait-for-timeout).
* @param timeout A timeout to wait for * @param timeout A timeout to wait for
*/ */
waitForTimeout(timeout: number): Promise<void>; waitForTimeout(timeout: number): Promise<void>;
@ -4491,8 +4397,6 @@ export interface Page {
* await page.waitForURL('**\/target.html'); * await page.waitForURL('**\/target.html');
* ``` * ```
* *
* Shortcut for main frame's
* [frame.waitForURL(url[, options])](https://playwright.dev/docs/api/class-frame#frame-wait-for-url).
* @param url A glob pattern, regex pattern or predicate receiving [URL] to match while waiting for the navigation. Note that if the parameter is a string without wildcard characters, the method will wait for navigation to URL that is exactly * @param url A glob pattern, regex pattern or predicate receiving [URL] to match while waiting for the navigation. Note that if the parameter is a string without wildcard characters, the method will wait for navigation to URL that is exactly
* equal to the string. * equal to the string.
* @param options * @param options
@ -6231,10 +6135,7 @@ export interface Frame {
strict?: boolean; strict?: boolean;
/** /**
* **DEPRECATED** This option is ignored. * @deprecated This option is ignored. [`method: Frame.isHidden`] does not wait for the element to become hidden and returns immediately.
* [frame.isHidden(selector[, options])](https://playwright.dev/docs/api/class-frame#frame-is-hidden) does not wait
* for the element to become hidden and returns immediately.
* @deprecated
*/ */
timeout?: number; timeout?: number;
}): Promise<boolean>; }): Promise<boolean>;
@ -6253,10 +6154,7 @@ export interface Frame {
strict?: boolean; strict?: boolean;
/** /**
* **DEPRECATED** This option is ignored. * @deprecated This option is ignored. [`method: Frame.isVisible`] does not wait for the element to become visible and returns immediately.
* [frame.isVisible(selector[, options])](https://playwright.dev/docs/api/class-frame#frame-is-visible) does not wait
* for the element to become visible and returns immediately.
* @deprecated
*/ */
timeout?: number; timeout?: number;
}): Promise<boolean>; }): Promise<boolean>;
@ -7868,9 +7766,7 @@ export interface BrowserContext {
}): Promise<void>; }): Promise<void>;
/** /**
* **DEPRECATED** Browsers may cache credentials after successful authentication. Create a new browser context * @deprecated Browsers may cache credentials after successful authentication. Create a new browser context instead.
* instead.
* @deprecated
* @param httpCredentials * @param httpCredentials
*/ */
setHTTPCredentials(httpCredentials: null|{ setHTTPCredentials(httpCredentials: null|{
@ -10765,10 +10661,7 @@ export interface Locator {
*/ */
isHidden(options?: { isHidden(options?: {
/** /**
* **DEPRECATED** This option is ignored. * @deprecated This option is ignored. [`method: Locator.isHidden`] does not wait for the element to become hidden and returns immediately.
* [locator.isHidden([options])](https://playwright.dev/docs/api/class-locator#locator-is-hidden) does not wait for
* the element to become hidden and returns immediately.
* @deprecated
*/ */
timeout?: number; timeout?: number;
}): Promise<boolean>; }): Promise<boolean>;
@ -10779,10 +10672,7 @@ export interface Locator {
*/ */
isVisible(options?: { isVisible(options?: {
/** /**
* **DEPRECATED** This option is ignored. * @deprecated This option is ignored. [`method: Locator.isVisible`] does not wait for the element to become visible and returns immediately.
* [locator.isVisible([options])](https://playwright.dev/docs/api/class-locator#locator-is-visible) does not wait for
* the element to become visible and returns immediately.
* @deprecated
*/ */
timeout?: number; timeout?: number;
}): Promise<boolean>; }): Promise<boolean>;
@ -11828,8 +11718,7 @@ export interface BrowserType<Unused = {}> {
userAgent?: string; userAgent?: string;
/** /**
* **DEPRECATED** Use `recordVideo` instead. * @deprecated Use [`option: recordVideo`] instead.
* @deprecated
*/ */
videoSize?: { videoSize?: {
/** /**
@ -11844,8 +11733,7 @@ export interface BrowserType<Unused = {}> {
}; };
/** /**
* **DEPRECATED** Use `recordVideo` instead. * @deprecated Use [`option: recordVideo`] instead.
* @deprecated
*/ */
videosPath?: string; videosPath?: string;
@ -12117,10 +12005,6 @@ class TimeoutError extends Error {}
} }
/** /**
* **DEPRECATED** This class is deprecated. Please use other libraries such as [Axe](https://www.deque.com/axe/) if
* you need to test page accessibility. See our Node.js [guide](https://playwright.dev/docs/accessibility-testing) for
* integration with Axe.
*
* The Accessibility class provides methods for inspecting Chromium's accessibility tree. The accessibility tree is * The Accessibility class provides methods for inspecting Chromium's accessibility tree. The accessibility tree is
* used by assistive technology such as [screen readers](https://en.wikipedia.org/wiki/Screen_reader) or * used by assistive technology such as [screen readers](https://en.wikipedia.org/wiki/Screen_reader) or
* [switches](https://en.wikipedia.org/wiki/Switch_access). * [switches](https://en.wikipedia.org/wiki/Switch_access).
@ -12137,10 +12021,6 @@ class TimeoutError extends Error {}
*/ */
export interface Accessibility { export interface Accessibility {
/** /**
* **DEPRECATED** This method is deprecated. Please use other libraries such as [Axe](https://www.deque.com/axe/) if
* you need to test page accessibility. See our Node.js [guide](https://playwright.dev/docs/accessibility-testing) for
* integration with Axe.
*
* Captures the current state of the accessibility tree. The returned object represents the root accessible node of * Captures the current state of the accessibility tree. The returned object represents the root accessible node of
* the page. * the page.
* *
@ -12175,7 +12055,7 @@ export interface Accessibility {
* } * }
* ``` * ```
* *
* @deprecated * @deprecated This method is deprecated. Please use other libraries such as [Axe](https://www.deque.com/axe/) if you need to test page accessibility. See our Node.js [guide](https://playwright.dev/docs/accessibility-testing) for integration with Axe.
* @param options * @param options
*/ */
snapshot(options?: AccessibilitySnapshotOptions): Promise<null|AccessibilityNode>; snapshot(options?: AccessibilitySnapshotOptions): Promise<null|AccessibilityNode>;
@ -13164,8 +13044,7 @@ export interface AndroidDevice {
userAgent?: string; userAgent?: string;
/** /**
* **DEPRECATED** Use `recordVideo` instead. * @deprecated Use [`option: recordVideo`] instead.
* @deprecated
*/ */
videoSize?: { videoSize?: {
/** /**
@ -13180,8 +13059,7 @@ export interface AndroidDevice {
}; };
/** /**
* **DEPRECATED** Use `recordVideo` instead. * @deprecated Use [`option: recordVideo`] instead.
* @deprecated
*/ */
videosPath?: string; videosPath?: string;
@ -15066,8 +14944,7 @@ export interface Browser extends EventEmitter {
userAgent?: string; userAgent?: string;
/** /**
* **DEPRECATED** Use `recordVideo` instead. * @deprecated Use [`option: recordVideo`] instead.
* @deprecated
*/ */
videoSize?: { videoSize?: {
/** /**
@ -15082,8 +14959,7 @@ export interface Browser extends EventEmitter {
}; };
/** /**
* **DEPRECATED** Use `recordVideo` instead. * @deprecated Use [`option: recordVideo`] instead.
* @deprecated
*/ */
videosPath?: string; videosPath?: string;
@ -17976,8 +17852,7 @@ export interface BrowserContextOptions {
userAgent?: string; userAgent?: string;
/** /**
* **DEPRECATED** Use `recordVideo` instead. * @deprecated Use [`option: recordVideo`] instead.
* @deprecated
*/ */
videoSize?: { videoSize?: {
/** /**
@ -17992,8 +17867,7 @@ export interface BrowserContextOptions {
}; };
/** /**
* **DEPRECATED** Use `recordVideo` instead. * @deprecated Use [`option: recordVideo`] instead.
* @deprecated
*/ */
videosPath?: string; videosPath?: string;

33
utils/doclint/api_parser.js
View file

@ -45,7 +45,7 @@ class ApiParser {
const params = paramsPath ? md.parse(fs.readFileSync(paramsPath).toString()) : undefined; const params = paramsPath ? md.parse(fs.readFileSync(paramsPath).toString()) : undefined;
checkNoDuplicateParamEntries(params); checkNoDuplicateParamEntries(params);
const api = params ? applyTemplates(body, params) : body; const api = params ? applyTemplates(body, params) : body;
/** @type {Map<string, documentation.Class>} */ /** @type {Map<string, docs.Class>} */
this.classes = new Map(); this.classes = new Map();
md.visitAll(api, node => { md.visitAll(api, node => {
if (node.type === 'h1') if (node.type === 'h1')
@ -118,7 +118,7 @@ class ApiParser {
if (!member) if (!member)
throw new Error('Unknown member: ' + spec.text); throw new Error('Unknown member: ' + spec.text);
const clazz = /** @type {documentation.Class} */(this.classes.get(match[2])); const clazz = /** @type {docs.Class} */(this.classes.get(match[2]));
const existingMember = clazz.membersArray.find(m => m.name === name && m.kind === member.kind); const existingMember = clazz.membersArray.find(m => m.name === name && m.kind === member.kind);
if (existingMember && isTypeOverride(existingMember, member)) { if (existingMember && isTypeOverride(existingMember, member)) {
for (const lang of member?.langs?.only || []) { for (const lang of member?.langs?.only || []) {
@ -174,7 +174,7 @@ class ApiParser {
let options = method.argsArray.find(o => o.name === 'options'); let options = method.argsArray.find(o => o.name === 'options');
if (!options) { if (!options) {
const type = new docs.Type('Object', []); const type = new docs.Type('Object', []);
options = docs.Member.createProperty({ langs: {}, experimental: false, since: 'v1.0' }, 'options', type, undefined, false); options = docs.Member.createProperty({ langs: {}, experimental: false, since: 'v1.0', deprecated: undefined, discouraged: undefined }, 'options', type, undefined, false);
method.argsArray.push(options); method.argsArray.push(options);
} }
const p = this.parseProperty(spec); const p = this.parseProperty(spec);
@ -201,7 +201,7 @@ class ApiParser {
/** /**
* @param {MarkdownLiNode} spec * @param {MarkdownLiNode} spec
* @return {{ type: documentation.Type, optional: boolean, experimental: boolean }} * @return {{ type: docs.Type, optional: boolean, experimental: boolean }}
*/ */
parseType(spec) { parseType(spec) {
const arg = parseVariable(spec.text); const arg = parseVariable(spec.text);
@ -210,7 +210,7 @@ class ApiParser {
const { name, text } = parseVariable(/** @type {string} */(child.text)); const { name, text } = parseVariable(/** @type {string} */(child.text));
const comments = /** @type {MarkdownNode[]} */ ([{ type: 'text', text }]); const comments = /** @type {MarkdownNode[]} */ ([{ type: 'text', text }]);
const childType = this.parseType(child); const childType = this.parseType(child);
properties.push(docs.Member.createProperty({ langs: {}, experimental: childType.experimental, since: 'v1.0' }, name, childType.type, comments, !childType.optional)); properties.push(docs.Member.createProperty({ langs: {}, experimental: childType.experimental, since: 'v1.0', deprecated: undefined, discouraged: undefined }, name, childType.type, comments, !childType.optional));
} }
const type = docs.Type.parse(arg.type, properties); const type = docs.Type.parse(arg.type, properties);
return { type, optional: arg.optional, experimental: arg.experimental }; return { type, optional: arg.optional, experimental: arg.experimental };
@ -345,7 +345,9 @@ function extractMetainfo(spec) {
return { return {
langs: extractLangs(spec), langs: extractLangs(spec),
since: extractSince(spec), since: extractSince(spec),
experimental: extractExperimental(spec) experimental: extractExperimental(spec),
deprecated: extractAttribute(spec, 'deprecated'),
discouraged: extractAttribute(spec, 'discouraged'),
}; };
} }
@ -403,20 +405,33 @@ function extractSince(spec) {
return false; return false;
} }
/**
* @param {MarkdownHeaderNode} spec
* @param {string} name
* @returns {string | undefined}
*/
function extractAttribute(spec, name) {
for (const child of spec.children) {
if (child.type !== 'li' || child.liType !== 'bullet' || !child.text.startsWith(name + ':'))
continue;
return child.text.substring(child.text.indexOf(':') + 1).trim() || undefined;
}
}
/** /**
* @param {MarkdownHeaderNode} spec * @param {MarkdownHeaderNode} spec
* @returns {MarkdownNode[]} * @returns {MarkdownNode[]}
*/ */
function childrenWithoutProperties(spec) { function childrenWithoutProperties(spec) {
return (spec.children || []).filter(c => { return (spec.children || []).filter(c => {
const isProperty = c.type === 'li' && c.liType === 'bullet' && (c.text.startsWith('langs:') || c.text.startsWith('since:') || c.text === 'experimental'); const isProperty = c.type === 'li' && c.liType === 'bullet' && (c.text.startsWith('langs:') || c.text.startsWith('since:') || c.text.startsWith('deprecated:') || c.text.startsWith('discouraged:') || c.text === 'experimental');
return !isProperty; return !isProperty;
}); });
} }
/** /**
* @param {documentation.Member} existingMember * @param {docs.Member} existingMember
* @param {documentation.Member} member * @param {docs.Member} member
* @returns {boolean} * @returns {boolean}
*/ */
function isTypeOverride(existingMember, member) { function isTypeOverride(existingMember, member) {

2
utils/doclint/cli.js
View file

@ -192,7 +192,7 @@ async function run() {
// Validates code snippet groups. // Validates code snippet groups.
rootNode = docs.processCodeGroups(rootNode, lang, tabs => tabs.map(tab => tab.spec)); rootNode = docs.processCodeGroups(rootNode, lang, tabs => tabs.map(tab => tab.spec));
// Renders links. // Renders links.
documentation.renderLinksInText(rootNode); documentation.renderLinksInNodes(rootNode);
// Validate links. // Validate links.
{ {
md.visitAll(rootNode, node => { md.visitAll(rootNode, node => {

113
utils/doclint/documentation.js
View file

@ -55,6 +55,8 @@ const md = require('../markdown');
* @typedef {{ * @typedef {{
* langs: Langs, * langs: Langs,
* since: string, * since: string,
* deprecated: string | undefined,
* discouraged: string | undefined,
* experimental: boolean * experimental: boolean
* }} Metainfo * }} Metainfo
*/ */
@ -162,20 +164,33 @@ class Documentation {
membersMap.set(`${member.kind}: ${clazz.name}.${member.name}`, member); membersMap.set(`${member.kind}: ${clazz.name}.${member.name}`, member);
} }
/** /**
* @param {Class|Member|null} classOrMember * @param {Class|Member|undefined} classOrMember
* @param {MarkdownNode[] | undefined} nodes * @param {string} text
*/ */
this._patchLinks = (classOrMember, nodes) => patchLinks(classOrMember, nodes, classesMap, membersMap, linkRenderer); this._patchLinksInText = (classOrMember, text) => patchLinksInText(classOrMember, text, classesMap, membersMap, linkRenderer);
for (const clazz of this.classesArray) for (const clazz of this.classesArray)
clazz.visit(item => this._patchLinks?.(item, item.spec)); clazz.visit(item => item.spec && this.renderLinksInNodes(item.spec, item));
} }
/** /**
* @param {MarkdownNode[]} nodes * @param {MarkdownNode[]} nodes
* @param {Class|Member=} classOrMember
*/ */
renderLinksInText(nodes) { renderLinksInNodes(nodes, classOrMember) {
this._patchLinks?.(null, nodes); md.visitAll(nodes, node => {
if (!node.text)
return;
node.text = this.renderLinksInText(node.text, classOrMember);
});
}
/**
* @param {string} text
* @param {Class|Member=} classOrMember
*/
renderLinksInText(text, classOrMember) {
return this._patchLinksInText?.(classOrMember, text);
} }
/** /**
@ -214,6 +229,8 @@ class Documentation {
this.langs = metainfo.langs; this.langs = metainfo.langs;
this.experimental = metainfo.experimental; this.experimental = metainfo.experimental;
this.since = metainfo.since; this.since = metainfo.since;
this.deprecated = metainfo.deprecated;
this.discouraged = metainfo.discouraged;
this.name = name; this.name = name;
this.membersArray = membersArray; this.membersArray = membersArray;
this.spec = spec; this.spec = spec;
@ -265,7 +282,7 @@ class Documentation {
} }
clone() { clone() {
const cls = new Class({ langs: this.langs, experimental: this.experimental, since: this.since }, this.name, this.membersArray.map(m => m.clone()), this.extends, this.spec); const cls = new Class({ langs: this.langs, experimental: this.experimental, since: this.since, deprecated: this.deprecated, discouraged: this.discouraged }, this.name, this.membersArray.map(m => m.clone()), this.extends, this.spec);
cls.comment = this.comment; cls.comment = this.comment;
return cls; return cls;
} }
@ -369,6 +386,8 @@ class Member {
this.langs = metainfo.langs; this.langs = metainfo.langs;
this.experimental = metainfo.experimental; this.experimental = metainfo.experimental;
this.since = metainfo.since; this.since = metainfo.since;
this.deprecated = metainfo.deprecated;
this.discouraged = metainfo.discouraged;
this.name = name; this.name = name;
this.type = type; this.type = type;
this.spec = spec; this.spec = spec;
@ -382,13 +401,6 @@ class Member {
this.clazz = null; this.clazz = null;
/** @type {Member=} */ /** @type {Member=} */
this.enclosingMethod = undefined; this.enclosingMethod = undefined;
this.deprecated = false;
if (spec) {
md.visitAll(spec, node => {
if (node.text && node.text.includes('**DEPRECATED**'))
this.deprecated = true;
});
};
this.async = false; this.async = false;
this.alias = name; this.alias = name;
this.overloadIndex = 0; this.overloadIndex = 0;
@ -472,7 +484,7 @@ class Member {
} }
clone() { clone() {
const result = new Member(this.kind, { langs: this.langs, experimental: this.experimental, since: this.since }, this.name, this.type?.clone(), this.argsArray.map(arg => arg.clone()), this.spec, this.required); const result = new Member(this.kind, { langs: this.langs, experimental: this.experimental, since: this.since, deprecated: this.deprecated, discouraged: this.discouraged }, this.name, this.type?.clone(), this.argsArray.map(arg => arg.clone()), this.spec, this.required);
result.alias = this.alias; result.alias = this.alias;
result.async = this.async; result.async = this.async;
result.paramOrOption = this.paramOrOption; result.paramOrOption = this.paramOrOption;
@ -801,50 +813,45 @@ function matchingBracket(str, open, close) {
} }
/** /**
* @param {Class|Member|null} classOrMember * @param {Class|Member|undefined} classOrMember
* @param {MarkdownNode[]|undefined} spec * @param {string} text
* @param {Map<string, Class>} classesMap * @param {Map<string, Class>} classesMap
* @param {Map<string, Member>} membersMap * @param {Map<string, Member>} membersMap
* @param {Renderer} linkRenderer * @param {Renderer} linkRenderer
*/ */
function patchLinks(classOrMember, spec, classesMap, membersMap, linkRenderer) { function patchLinksInText(classOrMember, text, classesMap, membersMap, linkRenderer) {
if (!spec) text = text.replace(/\[`(\w+): ([^\]]+)`\](?:\(([^)]*?)\))?/g, (match, p1, p2, href) => {
return; if (['event', 'method', 'property'].includes(p1)) {
md.visitAll(spec, node => { const memberName = p1 + ': ' + p2;
if (!node.text) const member = membersMap.get(memberName);
return; if (!member)
node.text = node.text.replace(/\[`(\w+): ([^\]]+)`\](?:\(([^)]*?)\))?/g, (match, p1, p2, href) => { throw new Error('Undefined member references: ' + match);
if (['event', 'method', 'property'].includes(p1)) { return linkRenderer({ member, href }) || match;
const memberName = p1 + ': ' + p2; }
const member = membersMap.get(memberName); if (p1 === 'param') {
if (!member) let alias = p2;
throw new Error('Undefined member references: ' + match); if (classOrMember) {
return linkRenderer({ member, href }) || match; // param/option reference can only be in method or same method parameter comments.
// @ts-ignore
const method = classOrMember.enclosingMethod;
const param = method.argsArray.find(a => a.name === p2);
if (!param)
throw new Error(`Referenced parameter ${match} not found in the parent method ${method.name} `);
alias = param.alias;
} }
if (p1 === 'param') { return linkRenderer({ param: alias, href }) || match;
let alias = p2; }
if (classOrMember) { if (p1 === 'option')
// param/option reference can only be in method or same method parameter comments. return linkRenderer({ option: p2, href }) || match;
// @ts-ignore throw new Error(`Undefined link prefix, expected event|method|property|param|option, got: ` + match);
const method = classOrMember.enclosingMethod;
const param = method.argsArray.find(a => a.name === p2);
if (!param)
throw new Error(`Referenced parameter ${match} not found in the parent method ${method.name} `);
alias = param.alias;
}
return linkRenderer({ param: alias, href }) || match;
}
if (p1 === 'option')
return linkRenderer({ option: p2, href }) || match;
throw new Error(`Undefined link prefix, expected event|method|property|param|option, got: ` + match);
});
node.text = node.text.replace(/\[([\w]+)\](?:\(([^)]*?)\))?/g, (match, p1, href) => {
const clazz = classesMap.get(p1);
if (clazz)
return linkRenderer({ clazz, href }) || match;
return match;
});
}); });
text = text.replace(/\[([\w]+)\](?:\(([^)]*?)\))?/g, (match, p1, href) => {
const clazz = classesMap.get(p1);
if (clazz)
return linkRenderer({ clazz, href }) || match;
return match;
});
return text;
} }
/** /**

2
utils/generate_types/index.js
View file

@ -474,7 +474,7 @@ class TypesGenerator {
if (member.comment) if (member.comment)
lines.push(...member.comment.split('\n')); lines.push(...member.comment.split('\n'));
if (member.deprecated) if (member.deprecated)
lines.push('@deprecated'); lines.push('@deprecated ' + member.deprecated);
lines.push(...member.argsArray.map(arg => `@param ${arg.alias.replace(/\./g, '')} ${arg.comment.replace('\n', ' ')}`)); lines.push(...member.argsArray.map(arg => `@param ${arg.alias.replace(/\./g, '')} ${arg.comment.replace('\n', ' ')}`));
if (!lines.length) if (!lines.length)
return indent; return indent;