mirror of
https://github.com/microsoft/playwright.git
synced 2025-06-26 21:40:17 +00:00
docs: add actionability doc (#2577)
This commit is contained in:
Dmitry Gozman
GitHub
parent
f2c47b1d33
commit
fd9b1031fa
@ -54,6 +54,7 @@
|
||||
- [Loading a popup](./loading.md#loading-a-popup)
|
||||
- [Client-side redirects](./loading.md#unusual-client-side-redirects)
|
||||
- [Navigation after a timeout](./loading.md#click-triggers-navigation-after-a-timeout)
|
||||
1. [Actionability](./actionability.md)
|
||||
1. [Continuous Integration](./ci.md)
|
||||
- [Docker](./ci.md#docker)
|
||||
- [GitHub Actions](./ci.md#github-actions)
|
||||
|
||||
55
docs/actionability.md
Normal file
55
docs/actionability.md
Normal file
@ -0,0 +1,55 @@
|
||||
# Actionability
|
||||
|
||||
Playwright does a range of actionability checks on the elements before performing certain actions. These checks ensure that action behaves as expected, for example Playwright does not click on a disabled button.
|
||||
|
||||
Playwright waits until all the relevant actionability checks pass before performing an action. This means that action will fail with `TimeoutError` if checks do not pass within the specified `timeout`.
|
||||
|
||||
Some actions like `page.click()` support `{force: true}` option that disable non-essential actionability checks, for example passing `force` to `click()` method will not check that the target element actually receives click events.
|
||||
|
||||
| Actions | Performed checks |
|
||||
| ------ | ------- |
|
||||
| `check()`<br>`click()`<br>`dblclick()`<br>`hover()`<br>`uncheck()` | [Visible]<br>[Stable]<br>[Enabled]<br>[Receiving Events]<br>[Attached]† |
|
||||
| `fill()` | [Visible]<br>[Enabled]<br>[Editable]<br>[Attached]† |
|
||||
| `focus()`<br>`press()`<br>`setInputFiles()`<br>`selectOption()`<br>`type()` | [Attached]† |
|
||||
| `selectText()` | [Visible] |
|
||||
| `dispatchEvent()`<br>`scrollIntoViewIfNeeded()` | -- |
|
||||
| `getAttribute()`<br>`innerText()`<br>`innerHTML()`<br>`textContent()` | [Attached]† |
|
||||
|
||||
† [Attached] check is only performed during selector-based actions.
|
||||
|
||||
### Visibile
|
||||
|
||||
Element is considered visible when it has non-empty bounding box and does not have `visibility:hidden` computed style. Note that elements of zero size or with `display:none` are not considered visible.
|
||||
|
||||
### Stable
|
||||
|
||||
Element is considered stable when it has maintanined the same bounding box for at least two consecutive animation frames.
|
||||
|
||||
### Enabled
|
||||
|
||||
Element is considered enabled when it is not a `<button>`, `<select>` or `<input>` with a `disabled` property set.
|
||||
|
||||
### Editable
|
||||
|
||||
Element is considered editable when it does not have `readonly` property set.
|
||||
|
||||
### Receiving events
|
||||
|
||||
Element is considered receiving pointer events when it is the hit target of the pointer event at the action point. For example, when clicking at the point `(10;10)`, Playwright checks whether some other element (usually an overlay) will instead capture the click at `(10;10)`.
|
||||
|
||||
### Attached
|
||||
|
||||
Element is considered attached when it is [connected](https://developer.mozilla.org/en-US/docs/Web/API/Node/isConnected) to a Document or a ShadowRoot.
|
||||
|
||||
Attached check is performed during a selector-based action, like `page.click(selector, options)` as opposite to `elementHandle.click(options)`.
|
||||
|
||||
For example, consider a scenario where Playwright will click `Sign Up` button regardless of when the `page.click()` call was made:
|
||||
- page is checking that user name is unique and `Sign Up` button is disabled;
|
||||
- after checking with the server, the disabled `Sign Up` button is replaced with another one that is now enabled.
|
||||
|
||||
[Visible]: #visible "Visible"
|
||||
[Stable]: #stable "Stable"
|
||||
[Enabled]: #enabled "Enabled"
|
||||
[Editable]: #editable "Editable"
|
||||
[Receiving Events]: #receiving-events "Receiving Events"
|
||||
[Attached]: #attached "Attached"
|
||||
108
docs/api.md
108
docs/api.md
@ -986,17 +986,13 @@ Shortcut for [page.mainFrame().addStyleTag(options)](#frameaddstyletagoptions).
|
||||
#### page.check(selector, [options])
|
||||
- `selector` <[string]> A selector to search for checkbox or radio button to check. If there are multiple elements satisfying the selector, the first will be checked. See [working with selectors](#working-with-selectors) for more details.
|
||||
- `options` <[Object]>
|
||||
- `force` <[boolean]> Whether to bypass the actionability checks. By default actions wait until the element is:
|
||||
- displayed: has non-empty bounding box and no `visibility:hidden` (note that elements of zero size or with `display:none` are considered not displayed),
|
||||
- is not moving (for example, css transition has finished),
|
||||
- receives pointer events at the action point (for example, element is not covered by other elements).
|
||||
Even if the action is forced, it will wait for the element matching selector to be in the DOM. Defaults to `false`.
|
||||
- `force` <[boolean]> Whether to bypass the [actionability](./actionability.md) checks. Defaults to `false`.
|
||||
- `noWaitAfter` <[boolean]> Actions that initiate navigations are waiting for these navigations to happen and for pages to start loading. You can opt out of waiting via setting this flag. You would only need this option in the exceptional cases such as navigating to inaccessible pages. Defaults to `false`.
|
||||
- `timeout` <[number]> Maximum time in milliseconds, defaults to 30 seconds, pass `0` to disable timeout. The default value can be changed by using the [browserContext.setDefaultTimeout(timeout)](#browsercontextsetdefaulttimeouttimeout) or [page.setDefaultTimeout(timeout)](#pagesetdefaulttimeouttimeout) methods.
|
||||
- returns: <[Promise]> Promise which resolves when the element matching `selector` is successfully checked. The Promise will be rejected if there is no element matching `selector`.
|
||||
|
||||
This method fetches an element with `selector`, if element is not already checked, it scrolls it into view if needed, and then uses [page.click](#pageclickselector-options) to click in the center of the element.
|
||||
If there's no element matching `selector`, the method waits until a matching element appears in the DOM. If the element is detached during the actionability checks, the action is retried.
|
||||
If there's no element matching `selector`, the method waits until a matching element appears in the DOM. If the element is detached during the [actionability](./actionability.md) checks, the action is retried.
|
||||
|
||||
Shortcut for [page.mainFrame().check(selector[, options])](#framecheckselector-options).
|
||||
|
||||
@ -1010,17 +1006,13 @@ Shortcut for [page.mainFrame().check(selector[, options])](#framecheckselector-o
|
||||
- x <[number]>
|
||||
- y <[number]>
|
||||
- `modifiers` <[Array]<"Alt"|"Control"|"Meta"|"Shift">> Modifier keys to press. Ensures that only these modifiers are pressed during the click, and then restores current modifiers back. If not specified, currently pressed modifiers are used.
|
||||
- `force` <[boolean]> Whether to bypass the actionability checks. By default actions wait until the element is:
|
||||
- displayed: has non-empty bounding box and no `visibility:hidden` (note that elements of zero size or with `display:none` are considered not displayed),
|
||||
- is not moving (for example, css transition has finished),
|
||||
- receives pointer events at the action point (for example, element is not covered by other elements).
|
||||
Even if the action is forced, it will wait for the element matching selector to be in the DOM. Defaults to `false`.
|
||||
- `force` <[boolean]> Whether to bypass the [actionability](./actionability.md) checks. Defaults to `false`.
|
||||
- `noWaitAfter` <[boolean]> Actions that initiate navigations are waiting for these navigations to happen and for pages to start loading. You can opt out of waiting via setting this flag. You would only need this option in the exceptional cases such as navigating to inaccessible pages. Defaults to `false`.
|
||||
- `timeout` <[number]> Maximum time in milliseconds, defaults to 30 seconds, pass `0` to disable timeout. The default value can be changed by using the [browserContext.setDefaultTimeout(timeout)](#browsercontextsetdefaulttimeouttimeout) or [page.setDefaultTimeout(timeout)](#pagesetdefaulttimeouttimeout) methods.
|
||||
- returns: <[Promise]> Promise which resolves when the element matching `selector` is successfully clicked. The Promise will be rejected if there is no element matching `selector`.
|
||||
|
||||
This method fetches an element with `selector`, scrolls it into view if needed, and then uses [page.mouse](#pagemouse) to click in the center of the element.
|
||||
If there's no element matching `selector`, the method waits until a matching element appears in the DOM. If the element is detached during the actionability checks, the action is retried.
|
||||
If there's no element matching `selector`, the method waits until a matching element appears in the DOM. If the element is detached during the [actionability](./actionability.md) checks, the action is retried.
|
||||
|
||||
|
||||
Shortcut for [page.mainFrame().click(selector[, options])](#frameclickselector-options).
|
||||
@ -1063,17 +1055,13 @@ Browser-specific Coverage implementation, only available for Chromium atm. See [
|
||||
- x <[number]>
|
||||
- y <[number]>
|
||||
- `modifiers` <[Array]<"Alt"|"Control"|"Meta"|"Shift">> Modifier keys to press. Ensures that only these modifiers are pressed during the double click, and then restores current modifiers back. If not specified, currently pressed modifiers are used.
|
||||
- `force` <[boolean]> Whether to bypass the actionability checks. By default actions wait until the element is:
|
||||
- displayed: has non-empty bounding box and no `visibility:hidden` (note that elements of zero size or with `display:none` are considered not displayed),
|
||||
- is not moving (for example, css transition has finished),
|
||||
- receives pointer events at the action point (for example, element is not covered by other elements).
|
||||
Even if the action is forced, it will wait for the element matching selector to be in the DOM. Defaults to `false`.
|
||||
- `force` <[boolean]> Whether to bypass the [actionability](./actionability.md) checks. Defaults to `false`.
|
||||
- `noWaitAfter` <[boolean]> Actions that initiate navigations are waiting for these navigations to happen and for pages to start loading. You can opt out of waiting via setting this flag. You would only need this option in the exceptional cases such as navigating to inaccessible pages. Defaults to `false`.
|
||||
- `timeout` <[number]> Maximum time in milliseconds, defaults to 30 seconds, pass `0` to disable timeout. The default value can be changed by using the [browserContext.setDefaultTimeout(timeout)](#browsercontextsetdefaulttimeouttimeout) or [page.setDefaultTimeout(timeout)](#pagesetdefaulttimeouttimeout) methods.
|
||||
- returns: <[Promise]> Promise which resolves when the element matching `selector` is successfully double clicked. The Promise will be rejected if there is no element matching `selector`.
|
||||
|
||||
This method fetches an element with `selector`, scrolls it into view if needed, and then uses [page.mouse](#pagemouse) to double click in the center of the element.
|
||||
If there's no element matching `selector`, the method waits until a matching element appears in the DOM. If the element is detached during the actionability checks, the action is retried.
|
||||
If there's no element matching `selector`, the method waits until a matching element appears in the DOM. If the element is detached during the [actionability](./actionability.md) checks, the action is retried.
|
||||
|
||||
Bear in mind that if the first click of the `dblclick()` triggers a navigation event, there will be an exception.
|
||||
|
||||
@ -1419,16 +1407,12 @@ Shortcut for [page.mainFrame().goto(url[, options])](#framegotourl-options)
|
||||
- x <[number]>
|
||||
- y <[number]>
|
||||
- `modifiers` <[Array]<"Alt"|"Control"|"Meta"|"Shift">> Modifier keys to press. Ensures that only these modifiers are pressed during the hover, and then restores current modifiers back. If not specified, currently pressed modifiers are used.
|
||||
- `force` <[boolean]> Whether to bypass the actionability checks. By default actions wait until the element is:
|
||||
- displayed: has non-empty bounding box and no `visibility:hidden` (note that elements of zero size or with `display:none` are considered not displayed),
|
||||
- is not moving (for example, css transition has finished),
|
||||
- receives pointer events at the action point (for example, element is not covered by other elements).
|
||||
Even if the action is forced, it will wait for the element matching selector to be in the DOM. Defaults to `false`.
|
||||
- `force` <[boolean]> Whether to bypass the [actionability](./actionability.md) checks. Defaults to `false`.
|
||||
- `timeout` <[number]> Maximum time in milliseconds, defaults to 30 seconds, pass `0` to disable timeout. The default value can be changed by using the [browserContext.setDefaultTimeout(timeout)](#browsercontextsetdefaulttimeouttimeout) or [page.setDefaultTimeout(timeout)](#pagesetdefaulttimeouttimeout) methods.
|
||||
- returns: <[Promise]> Promise which resolves when the element matching `selector` is successfully hovered. Promise gets rejected if there's no element matching `selector`.
|
||||
|
||||
This method fetches an element with `selector`, scrolls it into view if needed, and then uses [page.mouse](#pagemouse) to hover over the center of the element.
|
||||
If there's no element matching `selector`, the method waits until a matching element appears in the DOM. If the element is detached during the actionability checks, the action is retried.
|
||||
If there's no element matching `selector`, the method waits until a matching element appears in the DOM. If the element is detached during the [actionability](./actionability.md) checks, the action is retried.
|
||||
|
||||
Shortcut for [page.mainFrame().hover(selector[, options])](#framehoverselector-options).
|
||||
|
||||
@ -1771,17 +1755,13 @@ Shortcut for [page.mainFrame().type(selector, text[, options])](#frametypeselect
|
||||
#### page.uncheck(selector, [options])
|
||||
- `selector` <[string]> A selector to search for uncheckbox to check. If there are multiple elements satisfying the selector, the first will be checked. See [working with selectors](#working-with-selectors) for more details.
|
||||
- `options` <[Object]>
|
||||
- `force` <[boolean]> Whether to bypass the actionability checks. By default actions wait until the element is:
|
||||
- displayed: has non-empty bounding box and no `visibility:hidden` (note that elements of zero size or with `display:none` are considered not displayed),
|
||||
- is not moving (for example, css transition has finished),
|
||||
- receives pointer events at the action point (for example, element is not covered by other elements).
|
||||
Even if the action is forced, it will wait for the element matching selector to be in the DOM. Defaults to `false`.
|
||||
- `force` <[boolean]> Whether to bypass the [actionability](./actionability.md) checks. Defaults to `false`.
|
||||
- `noWaitAfter` <[boolean]> Actions that initiate navigations are waiting for these navigations to happen and for pages to start loading. You can opt out of waiting via setting this flag. You would only need this option in the exceptional cases such as navigating to inaccessible pages. Defaults to `false`.
|
||||
- `timeout` <[number]> Maximum time in milliseconds, defaults to 30 seconds, pass `0` to disable timeout. The default value can be changed by using the [browserContext.setDefaultTimeout(timeout)](#browsercontextsetdefaulttimeouttimeout) or [page.setDefaultTimeout(timeout)](#pagesetdefaulttimeouttimeout) methods.
|
||||
- returns: <[Promise]> Promise which resolves when the element matching `selector` is successfully unchecked. The Promise will be rejected if there is no element matching `selector`.
|
||||
|
||||
This method fetches an element with `selector`, if element is not already unchecked, it scrolls it into view if needed, and then uses [page.click](#pageclickselector-options) to click in the center of the element.
|
||||
If there's no element matching `selector`, the method waits until a matching element appears in the DOM. If the element is detached during the actionability checks, the action is retried.
|
||||
If there's no element matching `selector`, the method waits until a matching element appears in the DOM. If the element is detached during the [actionability](./actionability.md) checks, the action is retried.
|
||||
|
||||
Shortcut for [page.mainFrame().uncheck(selector[, options])](#frameuncheckselector-options).
|
||||
|
||||
@ -2121,17 +2101,13 @@ Adds a `<link rel="stylesheet">` tag into the page with the desired url or a `<s
|
||||
#### frame.check(selector, [options])
|
||||
- `selector` <[string]> A selector to search for checkbox to check. If there are multiple elements satisfying the selector, the first will be checked. See [working with selectors](#working-with-selectors) for more details.
|
||||
- `options` <[Object]>
|
||||
- `force` <[boolean]> Whether to bypass the actionability checks. By default actions wait until the element is:
|
||||
- displayed: has non-empty bounding box and no `visibility:hidden` (note that elements of zero size or with `display:none` are considered not displayed),
|
||||
- is not moving (for example, css transition has finished),
|
||||
- receives pointer events at the action point (for example, element is not covered by other elements).
|
||||
Even if the action is forced, it will wait for the element matching selector to be in the DOM. Defaults to `false`.
|
||||
- `force` <[boolean]> Whether to bypass the [actionability](./actionability.md) checks. Defaults to `false`.
|
||||
- `noWaitAfter` <[boolean]> Actions that initiate navigations are waiting for these navigations to happen and for pages to start loading. You can opt out of waiting via setting this flag. You would only need this option in the exceptional cases such as navigating to inaccessible pages. Defaults to `false`.
|
||||
- `timeout` <[number]> Maximum time in milliseconds, defaults to 30 seconds, pass `0` to disable timeout. The default value can be changed by using the [browserContext.setDefaultTimeout(timeout)](#browsercontextsetdefaulttimeouttimeout) or [page.setDefaultTimeout(timeout)](#pagesetdefaulttimeouttimeout) methods.
|
||||
- returns: <[Promise]> Promise which resolves when the element matching `selector` is successfully checked. The Promise will be rejected if there is no element matching `selector`.
|
||||
|
||||
This method fetches an element with `selector`, if element is not already checked, it scrolls it into view if needed, and then uses [frame.click](#frameclickselector-options) to click in the center of the element.
|
||||
If there's no element matching `selector`, the method waits until a matching element appears in the DOM. If the element is detached during the actionability checks, the action is retried.
|
||||
If there's no element matching `selector`, the method waits until a matching element appears in the DOM. If the element is detached during the [actionability](./actionability.md) checks, the action is retried.
|
||||
|
||||
#### frame.childFrames()
|
||||
- returns: <[Array]<[Frame]>>
|
||||
@ -2146,17 +2122,13 @@ If there's no element matching `selector`, the method waits until a matching ele
|
||||
- x <[number]>
|
||||
- y <[number]>
|
||||
- `modifiers` <[Array]<"Alt"|"Control"|"Meta"|"Shift">> Modifier keys to press. Ensures that only these modifiers are pressed during the click, and then restores current modifiers back. If not specified, currently pressed modifiers are used.
|
||||
- `force` <[boolean]> Whether to bypass the actionability checks. By default actions wait until the element is:
|
||||
- displayed: has non-empty bounding box and no `visibility:hidden` (note that elements of zero size or with `display:none` are considered not displayed),
|
||||
- is not moving (for example, css transition has finished),
|
||||
- receives pointer events at the action point (for example, element is not covered by other elements).
|
||||
Even if the action is forced, it will wait for the element matching selector to be in the DOM. Defaults to `false`.
|
||||
- `force` <[boolean]> Whether to bypass the [actionability](./actionability.md) checks. Defaults to `false`.
|
||||
- `noWaitAfter` <[boolean]> Actions that initiate navigations are waiting for these navigations to happen and for pages to start loading. You can opt out of waiting via setting this flag. You would only need this option in the exceptional cases such as navigating to inaccessible pages. Defaults to `false`.
|
||||
- `timeout` <[number]> Maximum time in milliseconds, defaults to 30 seconds, pass `0` to disable timeout. The default value can be changed by using the [browserContext.setDefaultTimeout(timeout)](#browsercontextsetdefaulttimeouttimeout) or [page.setDefaultTimeout(timeout)](#pagesetdefaulttimeouttimeout) methods.
|
||||
- returns: <[Promise]> Promise which resolves when the element matching `selector` is successfully clicked. The Promise will be rejected if there is no element matching `selector`.
|
||||
|
||||
This method fetches an element with `selector`, scrolls it into view if needed, and then uses [page.mouse](#pagemouse) to click in the center of the element.
|
||||
If there's no element matching `selector`, the method waits until a matching element appears in the DOM. If the element is detached during the actionability checks, the action is retried.
|
||||
If there's no element matching `selector`, the method waits until a matching element appears in the DOM. If the element is detached during the [actionability](./actionability.md) checks, the action is retried.
|
||||
|
||||
#### frame.content()
|
||||
- returns: <[Promise]<[string]>>
|
||||
@ -2172,11 +2144,7 @@ Gets the full HTML contents of the frame, including the doctype.
|
||||
- x <[number]>
|
||||
- y <[number]>
|
||||
- `modifiers` <[Array]<"Alt"|"Control"|"Meta"|"Shift">> Modifier keys to press. Ensures that only these modifiers are pressed during the double click, and then restores current modifiers back. If not specified, currently pressed modifiers are used.
|
||||
- `force` <[boolean]> Whether to bypass the actionability checks. By default actions wait until the element is:
|
||||
- displayed: has non-empty bounding box and no `visibility:hidden` (note that elements of zero size or with `display:none` are considered not displayed),
|
||||
- is not moving (for example, css transition has finished),
|
||||
- receives pointer events at the action point (for example, element is not covered by other elements).
|
||||
Even if the action is forced, it will wait for the element matching selector to be in the DOM. Defaults to `false`.
|
||||
- `force` <[boolean]> Whether to bypass the [actionability](./actionability.md) checks. Defaults to `false`.
|
||||
- `noWaitAfter` <[boolean]> Actions that initiate navigations are waiting for these navigations to happen and for pages to start loading. You can opt out of waiting via setting this flag. You would only need this option in the exceptional cases such as navigating to inaccessible pages. Defaults to `false`.
|
||||
- `timeout` <[number]> Maximum time in milliseconds, defaults to 30 seconds, pass `0` to disable timeout. The default value can be changed by using the [browserContext.setDefaultTimeout(timeout)](#browsercontextsetdefaulttimeouttimeout) or [page.setDefaultTimeout(timeout)](#pagesetdefaulttimeouttimeout) methods.
|
||||
- returns: <[Promise]> Promise which resolves when the element matching `selector` is successfully double clicked. The Promise will be rejected if there is no element matching `selector`.
|
||||
@ -2354,16 +2322,12 @@ Returns element attribute value.
|
||||
- x <[number]>
|
||||
- y <[number]>
|
||||
- `modifiers` <[Array]<"Alt"|"Control"|"Meta"|"Shift">> Modifier keys to press. Ensures that only these modifiers are pressed during the hover, and then restores current modifiers back. If not specified, currently pressed modifiers are used.
|
||||
- `force` <[boolean]> Whether to bypass the actionability checks. By default actions wait until the element is:
|
||||
- displayed: has non-empty bounding box and no `visibility:hidden` (note that elements of zero size or with `display:none` are considered not displayed),
|
||||
- is not moving (for example, css transition has finished),
|
||||
- receives pointer events at the action point (for example, element is not covered by other elements).
|
||||
Even if the action is forced, it will wait for the element matching selector to be in the DOM. Defaults to `false`.
|
||||
- `force` <[boolean]> Whether to bypass the [actionability](./actionability.md) checks. Defaults to `false`.
|
||||
- `timeout` <[number]> Maximum time in milliseconds, defaults to 30 seconds, pass `0` to disable timeout. The default value can be changed by using the [browserContext.setDefaultTimeout(timeout)](#browsercontextsetdefaulttimeouttimeout) or [page.setDefaultTimeout(timeout)](#pagesetdefaulttimeouttimeout) methods.
|
||||
- returns: <[Promise]> Promise which resolves when the element matching `selector` is successfully hovered. Promise gets rejected if there's no element matching `selector`.
|
||||
|
||||
This method fetches an element with `selector`, scrolls it into view if needed, and then uses [page.mouse](#pagemouse) to hover over the center of the element.
|
||||
If there's no element matching `selector`, the method waits until a matching element appears in the DOM. If the element is detached during the actionability checks, the action is retried.
|
||||
If there's no element matching `selector`, the method waits until a matching element appears in the DOM. If the element is detached during the [actionability](./actionability.md) checks, the action is retried.
|
||||
|
||||
#### frame.innerHTML(selector[, options])
|
||||
- `selector` <[string]> A selector to search for an element. If there are multiple elements satisfying the selector, the first will be picked. See [working with selectors](#working-with-selectors) for more details.
|
||||
@ -2502,17 +2466,13 @@ await frame.type('#mytextarea', 'World', {delay: 100}); // Types slower, like a
|
||||
#### frame.uncheck(selector, [options])
|
||||
- `selector` <[string]> A selector to search for uncheckbox to check. If there are multiple elements satisfying the selector, the first will be checked. See [working with selectors](#working-with-selectors) for more details.
|
||||
- `options` <[Object]>
|
||||
- `force` <[boolean]> Whether to bypass the actionability checks. By default actions wait until the element is:
|
||||
- displayed: has non-empty bounding box and no `visibility:hidden` (note that elements of zero size or with `display:none` are considered not displayed),
|
||||
- is not moving (for example, css transition has finished),
|
||||
- receives pointer events at the action point (for example, element is not covered by other elements).
|
||||
Even if the action is forced, it will wait for the element matching selector to be in the DOM. Defaults to `false`.
|
||||
- `force` <[boolean]> Whether to bypass the [actionability](./actionability.md) checks. Defaults to `false`.
|
||||
- `noWaitAfter` <[boolean]> Actions that initiate navigations are waiting for these navigations to happen and for pages to start loading. You can opt out of waiting via setting this flag. You would only need this option in the exceptional cases such as navigating to inaccessible pages. Defaults to `false`.
|
||||
- `timeout` <[number]> Maximum time in milliseconds, defaults to 30 seconds, pass `0` to disable timeout. The default value can be changed by using the [browserContext.setDefaultTimeout(timeout)](#browsercontextsetdefaulttimeouttimeout) or [page.setDefaultTimeout(timeout)](#pagesetdefaulttimeouttimeout) methods.
|
||||
- returns: <[Promise]> Promise which resolves when the element matching `selector` is successfully unchecked. The Promise will be rejected if there is no element matching `selector`.
|
||||
|
||||
This method fetches an element with `selector`, if element is not already unchecked, it scrolls it into view if needed, and then uses [frame.click](#frameclickselector-options) to click in the center of the element.
|
||||
If there's no element matching `selector`, the method waits until a matching element appears in the DOM. If the element is detached during the actionability checks, the action is retried.
|
||||
If there's no element matching `selector`, the method waits until a matching element appears in the DOM. If the element is detached during the [actionability](./actionability.md) checks, the action is retried.
|
||||
|
||||
#### frame.url()
|
||||
- returns: <[string]>
|
||||
@ -2748,11 +2708,7 @@ This method returns the bounding box of the element (relative to the main frame)
|
||||
|
||||
#### elementHandle.check([options])
|
||||
- `options` <[Object]>
|
||||
- `force` <[boolean]> Whether to bypass the actionability checks. By default actions wait until the element is:
|
||||
- displayed: has non-empty bounding box and no `visibility:hidden` (note that elements of zero size or with `display:none` are considered not displayed),
|
||||
- is not moving (for example, css transition has finished),
|
||||
- receives pointer events at the action point (for example, element is not covered by other elements).
|
||||
Even if the action is forced, it will wait for the element matching selector to be in the DOM. Defaults to `false`.
|
||||
- `force` <[boolean]> Whether to bypass the [actionability](./actionability.md) checks. Defaults to `false`.
|
||||
- `noWaitAfter` <[boolean]> Actions that initiate navigations are waiting for these navigations to happen and for pages to start loading. You can opt out of waiting via setting this flag. You would only need this option in the exceptional cases such as navigating to inaccessible pages. Defaults to `false`.
|
||||
- `timeout` <[number]> Maximum time in milliseconds, defaults to 30 seconds, pass `0` to disable timeout. The default value can be changed by using the [browserContext.setDefaultTimeout(timeout)](#browsercontextsetdefaulttimeouttimeout) or [page.setDefaultTimeout(timeout)](#pagesetdefaulttimeouttimeout) methods.
|
||||
- returns: <[Promise]> Promise which resolves when the element is successfully checked. Promise gets rejected if the operation fails.
|
||||
@ -2768,11 +2724,7 @@ If element is not already checked, it scrolls it into view if needed, and then u
|
||||
- x <[number]>
|
||||
- y <[number]>
|
||||
- `modifiers` <[Array]<"Alt"|"Control"|"Meta"|"Shift">> Modifier keys to press. Ensures that only these modifiers are pressed during the click, and then restores current modifiers back. If not specified, currently pressed modifiers are used.
|
||||
- `force` <[boolean]> Whether to bypass the actionability checks. By default actions wait until the element is:
|
||||
- displayed: has non-empty bounding box and no `visibility:hidden` (note that elements of zero size or with `display:none` are considered not displayed),
|
||||
- is not moving (for example, css transition has finished),
|
||||
- receives pointer events at the action point (for example, element is not covered by other elements).
|
||||
Even if the action is forced, it will wait for the element matching selector to be in the DOM. Defaults to `false`.
|
||||
- `force` <[boolean]> Whether to bypass the [actionability](./actionability.md) checks. Defaults to `false`.
|
||||
- `noWaitAfter` <[boolean]> Actions that initiate navigations are waiting for these navigations to happen and for pages to start loading. You can opt out of waiting via setting this flag. You would only need this option in the exceptional cases such as navigating to inaccessible pages. Defaults to `false`.
|
||||
- `timeout` <[number]> Maximum time in milliseconds, defaults to 30 seconds, pass `0` to disable timeout. The default value can be changed by using the [browserContext.setDefaultTimeout(timeout)](#browsercontextsetdefaulttimeouttimeout) or [page.setDefaultTimeout(timeout)](#pagesetdefaulttimeouttimeout) methods.
|
||||
- returns: <[Promise]> Promise which resolves when the element is successfully clicked. Promise gets rejected if the element is detached from DOM.
|
||||
@ -2791,11 +2743,7 @@ If the element is detached from DOM, the method throws an error.
|
||||
- x <[number]>
|
||||
- y <[number]>
|
||||
- `modifiers` <[Array]<"Alt"|"Control"|"Meta"|"Shift">> Modifier keys to press. Ensures that only these modifiers are pressed during the double click, and then restores current modifiers back. If not specified, currently pressed modifiers are used.
|
||||
- `force` <[boolean]> Whether to bypass the actionability checks. By default actions wait until the element is:
|
||||
- displayed: has non-empty bounding box and no `visibility:hidden` (note that elements of zero size or with `display:none` are considered not displayed),
|
||||
- is not moving (for example, css transition has finished),
|
||||
- receives pointer events at the action point (for example, element is not covered by other elements).
|
||||
Even if the action is forced, it will wait for the element matching selector to be in the DOM. Defaults to `false`.
|
||||
- `force` <[boolean]> Whether to bypass the [actionability](./actionability.md) checks. Defaults to `false`.
|
||||
- `noWaitAfter` <[boolean]> Actions that initiate navigations are waiting for these navigations to happen and for pages to start loading. You can opt out of waiting via setting this flag. You would only need this option in the exceptional cases such as navigating to inaccessible pages. Defaults to `false`.
|
||||
- `timeout` <[number]> Maximum time in milliseconds, defaults to 30 seconds, pass `0` to disable timeout. The default value can be changed by using the [browserContext.setDefaultTimeout(timeout)](#browsercontextsetdefaulttimeouttimeout) or [page.setDefaultTimeout(timeout)](#pagesetdefaulttimeouttimeout) methods.
|
||||
- returns: <[Promise]> Promise which resolves when the element is successfully double clicked. Promise gets rejected if the element is detached from DOM.
|
||||
@ -2864,11 +2812,7 @@ Returns element attribute value.
|
||||
- x <[number]>
|
||||
- y <[number]>
|
||||
- `modifiers` <[Array]<"Alt"|"Control"|"Meta"|"Shift">> Modifier keys to press. Ensures that only these modifiers are pressed during the hover, and then restores current modifiers back. If not specified, currently pressed modifiers are used.
|
||||
- `force` <[boolean]> Whether to bypass the actionability checks. By default actions wait until the element is:
|
||||
- displayed: has non-empty bounding box and no `visibility:hidden` (note that elements of zero size or with `display:none` are considered not displayed),
|
||||
- is not moving (for example, css transition has finished),
|
||||
- receives pointer events at the action point (for example, element is not covered by other elements).
|
||||
Even if the action is forced, it will wait for the element matching selector to be in the DOM. Defaults to `false`.
|
||||
- `force` <[boolean]> Whether to bypass the [actionability](./actionability.md) checks. Defaults to `false`.
|
||||
- `timeout` <[number]> Maximum time in milliseconds, defaults to 30 seconds, pass `0` to disable timeout. The default value can be changed by using the [browserContext.setDefaultTimeout(timeout)](#browsercontextsetdefaulttimeouttimeout) or [page.setDefaultTimeout(timeout)](#pagesetdefaulttimeouttimeout) methods.
|
||||
- returns: <[Promise]> Promise which resolves when the element is successfully hovered.
|
||||
|
||||
@ -3003,11 +2947,7 @@ await elementHandle.press('Enter');
|
||||
|
||||
#### elementHandle.uncheck([options])
|
||||
- `options` <[Object]>
|
||||
- `force` <[boolean]> Whether to bypass the actionability checks. By default actions wait until the element is:
|
||||
- displayed: has non-empty bounding box and no `visibility:hidden` (note that elements of zero size or with `display:none` are considered not displayed),
|
||||
- is not moving (for example, css transition has finished),
|
||||
- receives pointer events at the action point (for example, element is not covered by other elements).
|
||||
Even if the action is forced, it will wait for the element matching selector to be in the DOM. Defaults to `false`.
|
||||
- `force` <[boolean]> Whether to bypass the [actionability](./actionability.md) checks. Defaults to `false`.
|
||||
- `noWaitAfter` <[boolean]> Actions that initiate navigations are waiting for these navigations to happen and for pages to start loading. You can opt out of waiting via setting this flag. You would only need this option in the exceptional cases such as navigating to inaccessible pages. Defaults to `false`.
|
||||
- `timeout` <[number]> Maximum time in milliseconds, defaults to 30 seconds, pass `0` to disable timeout. The default value can be changed by using the [browserContext.setDefaultTimeout(timeout)](#browsercontextsetdefaulttimeouttimeout) or [page.setDefaultTimeout(timeout)](#pagesetdefaulttimeouttimeout) methods.
|
||||
- returns: <[Promise]> Promise which resolves when the element is successfully unchecked. Promise gets rejected if the operation fails.
|
||||
|
||||
@ -182,9 +182,9 @@ const sectionText = await page.$eval('*css=section >> text=Selectors', e => e.te
|
||||
|
||||
## Auto-waiting
|
||||
|
||||
Actions like `click` and `fill` auto-wait for the element to be visible and actionable. For example, click will:
|
||||
Actions like `click` and `fill` auto-wait for the element to be visible and [actionable](./actionability.md). For example, click will:
|
||||
- wait for an element with the given selector to appear in the DOM
|
||||
- wait for it to become displayed: have non-empty bounding box and no `visibility:hidden`
|
||||
- wait for it to become visible: have non-empty bounding box and no `visibility:hidden`
|
||||
- wait for it to stop moving: for example, wait until css transition finishes
|
||||
- scroll the element into view
|
||||
- wait for it to receive pointer events at the action point: for example, wait until element becomes non-obscured by other elements
|
||||
|
||||
@ -125,7 +125,7 @@ Under the hood, this and other pointer-related methods:
|
||||
|
||||
#### Forcing the click
|
||||
|
||||
Sometimes, apps use non-trivial logic where hovering the element overlays it with another element that intercepts the click. This behavior is indistinguishable from a bug where element gets covered and the click is dispatched elsewhere. If you know this is taking place, you can bypass the actionability checks and force the click:
|
||||
Sometimes, apps use non-trivial logic where hovering the element overlays it with another element that intercepts the click. This behavior is indistinguishable from a bug where element gets covered and the click is dispatched elsewhere. If you know this is taking place, you can bypass the [actionability](./actionability.md) checks and force the click:
|
||||
|
||||
```js
|
||||
await page.click('button#submit', { force: true });
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user