playwright-ruby-client 0.6.0 → 0.6.1
Sign up to get free protection for your applications and to get access to all the features.
- checksums.yaml +4 -4
- data/documentation/README.md +33 -0
- data/documentation/babel.config.js +3 -0
- data/documentation/docs/api/accessibility.md +7 -0
- data/documentation/docs/api/browser.md +185 -0
- data/documentation/docs/api/browser_context.md +398 -0
- data/documentation/docs/api/browser_type.md +105 -0
- data/documentation/docs/api/cdp_session.md +7 -0
- data/documentation/docs/api/console_message.md +41 -0
- data/documentation/docs/api/dialog.md +74 -0
- data/documentation/docs/api/element_handle.md +640 -0
- data/documentation/docs/api/experimental/_category_.yml +3 -0
- data/documentation/docs/api/experimental/android.md +25 -0
- data/documentation/docs/api/experimental/android_device.md +91 -0
- data/documentation/docs/api/experimental/android_input.md +38 -0
- data/documentation/docs/api/experimental/android_socket.md +7 -0
- data/documentation/docs/api/experimental/android_web_view.md +7 -0
- data/documentation/docs/api/file_chooser.md +51 -0
- data/documentation/docs/api/frame.md +867 -0
- data/documentation/docs/api/js_handle.md +116 -0
- data/documentation/docs/api/keyboard.md +157 -0
- data/documentation/docs/api/mouse.md +69 -0
- data/documentation/docs/api/page.md +1469 -0
- data/documentation/docs/api/playwright.md +63 -0
- data/documentation/docs/api/request.md +188 -0
- data/documentation/docs/api/response.md +97 -0
- data/documentation/docs/api/route.md +80 -0
- data/documentation/docs/api/selectors.md +23 -0
- data/documentation/docs/api/touchscreen.md +8 -0
- data/documentation/docs/api/tracing.md +54 -0
- data/documentation/docs/api/web_socket.md +7 -0
- data/documentation/docs/api/worker.md +7 -0
- data/documentation/docs/article/api_coverage.mdx +11 -0
- data/documentation/docs/article/getting_started.md +152 -0
- data/documentation/docs/article/guides/_category_.yml +3 -0
- data/documentation/docs/article/guides/download_playwright_driver.md +49 -0
- data/documentation/docs/article/guides/launch_browser.md +119 -0
- data/documentation/docs/article/guides/rails_integration.md +51 -0
- data/{docs → documentation/docs/include}/api_coverage.md +0 -0
- data/documentation/docusaurus.config.js +107 -0
- data/documentation/package.json +39 -0
- data/documentation/sidebars.js +15 -0
- data/documentation/src/components/HomepageFeatures.js +61 -0
- data/documentation/src/components/HomepageFeatures.module.css +13 -0
- data/documentation/src/css/custom.css +44 -0
- data/documentation/src/pages/index.js +50 -0
- data/documentation/src/pages/index.module.css +41 -0
- data/documentation/src/pages/markdown-page.md +7 -0
- data/documentation/static/.nojekyll +0 -0
- data/documentation/static/img/playwright-logo.svg +9 -0
- data/documentation/static/img/undraw_dropdown_menu.svg +1 -0
- data/documentation/static/img/undraw_web_development.svg +1 -0
- data/documentation/static/img/undraw_windows.svg +1 -0
- data/documentation/yarn.lock +8805 -0
- data/lib/playwright/channel_owners/binding_call.rb +33 -0
- data/lib/playwright/channel_owners/browser_context.rb +2 -2
- data/lib/playwright/channel_owners/element_handle.rb +2 -10
- data/lib/playwright/channel_owners/frame.rb +6 -28
- data/lib/playwright/channel_owners/js_handle.rb +2 -10
- data/lib/playwright/channel_owners/page.rb +10 -1
- data/lib/playwright/input_files.rb +0 -8
- data/lib/playwright/javascript.rb +0 -10
- data/lib/playwright/javascript/expression.rb +2 -7
- data/lib/playwright/version.rb +1 -1
- data/lib/playwright_api/accessibility.rb +7 -89
- data/lib/playwright_api/android.rb +7 -64
- data/lib/playwright_api/android_device.rb +8 -8
- data/lib/playwright_api/browser.rb +15 -169
- data/lib/playwright_api/browser_context.rb +47 -609
- data/lib/playwright_api/browser_type.rb +13 -103
- data/lib/playwright_api/cdp_session.rb +2 -25
- data/lib/playwright_api/console_message.rb +6 -6
- data/lib/playwright_api/dialog.rb +11 -92
- data/lib/playwright_api/element_handle.rb +60 -362
- data/lib/playwright_api/file_chooser.rb +0 -28
- data/lib/playwright_api/frame.rb +74 -713
- data/lib/playwright_api/js_handle.rb +16 -90
- data/lib/playwright_api/keyboard.rb +21 -213
- data/lib/playwright_api/mouse.rb +1 -45
- data/lib/playwright_api/page.rb +155 -1635
- data/lib/playwright_api/playwright.rb +14 -117
- data/lib/playwright_api/request.rb +15 -121
- data/lib/playwright_api/response.rb +9 -9
- data/lib/playwright_api/route.rb +8 -105
- data/lib/playwright_api/selectors.rb +6 -97
- data/lib/playwright_api/tracing.rb +1 -61
- data/lib/playwright_api/web_socket.rb +1 -1
- data/lib/playwright_api/worker.rb +6 -42
- metadata +55 -4
- data/lib/playwright/javascript/function.rb +0 -67
@@ -0,0 +1,105 @@
|
|
1
|
+
---
|
2
|
+
sidebar_position: 10
|
3
|
+
---
|
4
|
+
|
5
|
+
# BrowserType
|
6
|
+
|
7
|
+
BrowserType provides methods to launch a specific browser instance or connect to an existing one. The following is a
|
8
|
+
typical example of using Playwright to drive automation:
|
9
|
+
|
10
|
+
```ruby
|
11
|
+
chromium = playwright.chromium
|
12
|
+
chromium.launch do |browser|
|
13
|
+
page = browser.new_page
|
14
|
+
page.goto('https://example.com/')
|
15
|
+
|
16
|
+
# other actions
|
17
|
+
|
18
|
+
end
|
19
|
+
```
|
20
|
+
|
21
|
+
|
22
|
+
|
23
|
+
## connect_over_cdp
|
24
|
+
|
25
|
+
```
|
26
|
+
def connect_over_cdp(
|
27
|
+
endpointURL,
|
28
|
+
headers: nil,
|
29
|
+
slowMo: nil,
|
30
|
+
timeout: nil,
|
31
|
+
&block)
|
32
|
+
```
|
33
|
+
|
34
|
+
This methods attaches Playwright to an existing browser instance using the Chrome DevTools Protocol.
|
35
|
+
|
36
|
+
The default browser context is accessible via [Browser#contexts](./browser#contexts).
|
37
|
+
|
38
|
+
> NOTE: Connecting over the Chrome DevTools Protocol is only supported for Chromium-based browsers.
|
39
|
+
|
40
|
+
## executable_path
|
41
|
+
|
42
|
+
```
|
43
|
+
def executable_path
|
44
|
+
```
|
45
|
+
|
46
|
+
A path where Playwright expects to find a bundled browser executable.
|
47
|
+
|
48
|
+
## launch
|
49
|
+
|
50
|
+
```
|
51
|
+
def launch(
|
52
|
+
args: nil,
|
53
|
+
channel: nil,
|
54
|
+
chromiumSandbox: nil,
|
55
|
+
devtools: nil,
|
56
|
+
downloadsPath: nil,
|
57
|
+
env: nil,
|
58
|
+
executablePath: nil,
|
59
|
+
firefoxUserPrefs: nil,
|
60
|
+
handleSIGHUP: nil,
|
61
|
+
handleSIGINT: nil,
|
62
|
+
handleSIGTERM: nil,
|
63
|
+
headless: nil,
|
64
|
+
ignoreDefaultArgs: nil,
|
65
|
+
proxy: nil,
|
66
|
+
slowMo: nil,
|
67
|
+
timeout: nil,
|
68
|
+
traceDir: nil,
|
69
|
+
&block)
|
70
|
+
```
|
71
|
+
|
72
|
+
Returns the browser instance.
|
73
|
+
|
74
|
+
You can use `ignoreDefaultArgs` to filter out `--mute-audio` from default arguments:
|
75
|
+
|
76
|
+
```ruby
|
77
|
+
browser = playwright.chromium.launch( # or "firefox" or "webkit".
|
78
|
+
ignoreDefaultArgs: ["--mute-audio"]
|
79
|
+
)
|
80
|
+
|
81
|
+
browser.close
|
82
|
+
```
|
83
|
+
|
84
|
+
> **Chromium-only** Playwright can also be used to control the Google Chrome or Microsoft Edge browsers, but it works
|
85
|
+
best with the version of Chromium it is bundled with. There is no guarantee it will work with any other version. Use
|
86
|
+
`executablePath` option with extreme caution.
|
87
|
+
>
|
88
|
+
> If Google Chrome (rather than Chromium) is preferred, a
|
89
|
+
[Chrome Canary](https://www.google.com/chrome/browser/canary.html) or
|
90
|
+
[Dev Channel](https://www.chromium.org/getting-involved/dev-channel) build is suggested.
|
91
|
+
>
|
92
|
+
> Stock browsers like Google Chrome and Microsoft Edge are suitable for tests that require proprietary media codecs for
|
93
|
+
video playback. See
|
94
|
+
[this article](https://www.howtogeek.com/202825/what%E2%80%99s-the-difference-between-chromium-and-chrome/) for other
|
95
|
+
differences between Chromium and Chrome.
|
96
|
+
[This article](https://chromium.googlesource.com/chromium/src/+/lkgr/docs/chromium_browser_vs_google_chrome.md)
|
97
|
+
describes some differences for Linux users.
|
98
|
+
|
99
|
+
## name
|
100
|
+
|
101
|
+
```
|
102
|
+
def name
|
103
|
+
```
|
104
|
+
|
105
|
+
Returns browser name. For example: `'chromium'`, `'webkit'` or `'firefox'`.
|
@@ -0,0 +1,41 @@
|
|
1
|
+
---
|
2
|
+
sidebar_position: 10
|
3
|
+
---
|
4
|
+
|
5
|
+
# ConsoleMessage
|
6
|
+
|
7
|
+
[ConsoleMessage](./console_message) objects are dispatched by page via the [`event: Page.console`] event.
|
8
|
+
|
9
|
+
## args
|
10
|
+
|
11
|
+
```
|
12
|
+
def args
|
13
|
+
```
|
14
|
+
|
15
|
+
List of arguments passed to a `console` function call. See also [`event: Page.console`].
|
16
|
+
|
17
|
+
## location
|
18
|
+
|
19
|
+
```
|
20
|
+
def location
|
21
|
+
```
|
22
|
+
|
23
|
+
|
24
|
+
|
25
|
+
## text
|
26
|
+
|
27
|
+
```
|
28
|
+
def text
|
29
|
+
```
|
30
|
+
|
31
|
+
The text of the console message.
|
32
|
+
|
33
|
+
## type
|
34
|
+
|
35
|
+
```
|
36
|
+
def type
|
37
|
+
```
|
38
|
+
|
39
|
+
One of the following values: `'log'`, `'debug'`, `'info'`, `'error'`, `'warning'`, `'dir'`, `'dirxml'`, `'table'`,
|
40
|
+
`'trace'`, `'clear'`, `'startGroup'`, `'startGroupCollapsed'`, `'endGroup'`, `'assert'`, `'profile'`, `'profileEnd'`,
|
41
|
+
`'count'`, `'timeEnd'`.
|
@@ -0,0 +1,74 @@
|
|
1
|
+
---
|
2
|
+
sidebar_position: 10
|
3
|
+
---
|
4
|
+
|
5
|
+
# Dialog
|
6
|
+
|
7
|
+
[Dialog](./dialog) objects are dispatched by page via the [`event: Page.dialog`] event.
|
8
|
+
|
9
|
+
An example of using [Dialog](./dialog) class:
|
10
|
+
|
11
|
+
```python sync title=example_c954c35627e62be69e1f138f25d7377b13e18d08039d476946217827fa95db52.py
|
12
|
+
from playwright.sync_api import sync_playwright
|
13
|
+
|
14
|
+
def handle_dialog(dialog):
|
15
|
+
print(dialog.message)
|
16
|
+
dialog.dismiss()
|
17
|
+
|
18
|
+
def run(playwright):
|
19
|
+
chromium = playwright.chromium
|
20
|
+
browser = chromium.launch()
|
21
|
+
page = browser.new_page()
|
22
|
+
page.on("dialog", handle_dialog)
|
23
|
+
page.evaluate("alert('1')")
|
24
|
+
browser.close()
|
25
|
+
|
26
|
+
with sync_playwright() as playwright:
|
27
|
+
run(playwright)
|
28
|
+
|
29
|
+
```
|
30
|
+
|
31
|
+
> NOTE: Dialogs are dismissed automatically, unless there is a [`event: Page.dialog`] listener. When listener is
|
32
|
+
present, it **must** either [Dialog#accept](./dialog#accept) or [Dialog#dismiss](./dialog#dismiss) the dialog - otherwise the page will
|
33
|
+
[freeze](https://developer.mozilla.org/en-US/docs/Web/JavaScript/EventLoop#never_blocking) waiting for the dialog, and
|
34
|
+
actions like click will never finish.
|
35
|
+
|
36
|
+
## accept
|
37
|
+
|
38
|
+
```
|
39
|
+
def accept(promptText: nil)
|
40
|
+
```
|
41
|
+
|
42
|
+
Returns when the dialog has been accepted.
|
43
|
+
|
44
|
+
## default_value
|
45
|
+
|
46
|
+
```
|
47
|
+
def default_value
|
48
|
+
```
|
49
|
+
|
50
|
+
If dialog is prompt, returns default prompt value. Otherwise, returns empty string.
|
51
|
+
|
52
|
+
## dismiss
|
53
|
+
|
54
|
+
```
|
55
|
+
def dismiss
|
56
|
+
```
|
57
|
+
|
58
|
+
Returns when the dialog has been dismissed.
|
59
|
+
|
60
|
+
## message
|
61
|
+
|
62
|
+
```
|
63
|
+
def message
|
64
|
+
```
|
65
|
+
|
66
|
+
A message displayed in the dialog.
|
67
|
+
|
68
|
+
## type
|
69
|
+
|
70
|
+
```
|
71
|
+
def type
|
72
|
+
```
|
73
|
+
|
74
|
+
Returns dialog's type, can be one of `alert`, `beforeunload`, `confirm` or `prompt`.
|
@@ -0,0 +1,640 @@
|
|
1
|
+
---
|
2
|
+
sidebar_position: 10
|
3
|
+
---
|
4
|
+
|
5
|
+
# ElementHandle
|
6
|
+
|
7
|
+
- extends: [JSHandle](./js_handle)
|
8
|
+
|
9
|
+
ElementHandle represents an in-page DOM element. ElementHandles can be created with the [Page#query_selector](./page#query_selector)
|
10
|
+
method.
|
11
|
+
|
12
|
+
```python sync title=example_5ba38bdc5d9e5ce7cfc9c8841eb0176efbb4690d18962066f9ee67f1e8b7b050.py
|
13
|
+
from playwright.sync_api import sync_playwright
|
14
|
+
|
15
|
+
def run(playwright):
|
16
|
+
chromium = playwright.chromium
|
17
|
+
browser = chromium.launch()
|
18
|
+
page = browser.new_page()
|
19
|
+
page.goto("https://example.com")
|
20
|
+
href_element = page.query_selector("a")
|
21
|
+
href_element.click()
|
22
|
+
# ...
|
23
|
+
|
24
|
+
with sync_playwright() as playwright:
|
25
|
+
run(playwright)
|
26
|
+
|
27
|
+
```
|
28
|
+
|
29
|
+
ElementHandle prevents DOM element from garbage collection unless the handle is disposed with
|
30
|
+
[JSHandle#dispose](./js_handle#dispose). ElementHandles are auto-disposed when their origin frame gets navigated.
|
31
|
+
|
32
|
+
ElementHandle instances can be used as an argument in [Page#eval_on_selector](./page#eval_on_selector) and [Page#evaluate](./page#evaluate)
|
33
|
+
methods.
|
34
|
+
|
35
|
+
## bounding_box
|
36
|
+
|
37
|
+
```
|
38
|
+
def bounding_box
|
39
|
+
```
|
40
|
+
|
41
|
+
This method returns the bounding box of the element, or `null` if the element is not visible. The bounding box is
|
42
|
+
calculated relative to the main frame viewport - which is usually the same as the browser window.
|
43
|
+
|
44
|
+
Scrolling affects the returned bonding box, similarly to
|
45
|
+
[Element.getBoundingClientRect](https://developer.mozilla.org/en-US/docs/Web/API/Element/getBoundingClientRect). That
|
46
|
+
means `x` and/or `y` may be negative.
|
47
|
+
|
48
|
+
Elements from child frames return the bounding box relative to the main frame, unlike the
|
49
|
+
[Element.getBoundingClientRect](https://developer.mozilla.org/en-US/docs/Web/API/Element/getBoundingClientRect).
|
50
|
+
|
51
|
+
Assuming the page is static, it is safe to use bounding box coordinates to perform input. For example, the following
|
52
|
+
snippet should click the center of the element.
|
53
|
+
|
54
|
+
```python sync title=example_8382aa7cfb42a9a17e348e2f738279f1bd9a038f1ea35cc3cb244cc64d768f93.py
|
55
|
+
box = element_handle.bounding_box()
|
56
|
+
page.mouse.click(box["x"] + box["width"] / 2, box["y"] + box["height"] / 2)
|
57
|
+
|
58
|
+
```
|
59
|
+
|
60
|
+
|
61
|
+
|
62
|
+
## check
|
63
|
+
|
64
|
+
```
|
65
|
+
def check(
|
66
|
+
force: nil,
|
67
|
+
noWaitAfter: nil,
|
68
|
+
position: nil,
|
69
|
+
timeout: nil,
|
70
|
+
trial: nil)
|
71
|
+
```
|
72
|
+
|
73
|
+
This method checks the element by performing the following steps:
|
74
|
+
1. Ensure that element is a checkbox or a radio input. If not, this method throws. If the element is already checked,
|
75
|
+
this method returns immediately.
|
76
|
+
1. Wait for [actionability](https://playwright.dev/python/docs/actionability) checks on the element, unless `force` option is set.
|
77
|
+
1. Scroll the element into view if needed.
|
78
|
+
1. Use [Page#mouse](./page#mouse) to click in the center of the element.
|
79
|
+
1. Wait for initiated navigations to either succeed or fail, unless `noWaitAfter` option is set.
|
80
|
+
1. Ensure that the element is now checked. If not, this method throws.
|
81
|
+
|
82
|
+
If the element is detached from the DOM at any moment during the action, this method throws.
|
83
|
+
|
84
|
+
When all steps combined have not finished during the specified `timeout`, this method throws a `TimeoutError`. Passing
|
85
|
+
zero timeout disables this.
|
86
|
+
|
87
|
+
## click
|
88
|
+
|
89
|
+
```
|
90
|
+
def click(
|
91
|
+
button: nil,
|
92
|
+
clickCount: nil,
|
93
|
+
delay: nil,
|
94
|
+
force: nil,
|
95
|
+
modifiers: nil,
|
96
|
+
noWaitAfter: nil,
|
97
|
+
position: nil,
|
98
|
+
timeout: nil,
|
99
|
+
trial: nil)
|
100
|
+
```
|
101
|
+
|
102
|
+
This method clicks the element by performing the following steps:
|
103
|
+
1. Wait for [actionability](https://playwright.dev/python/docs/actionability) checks on the element, unless `force` option is set.
|
104
|
+
1. Scroll the element into view if needed.
|
105
|
+
1. Use [Page#mouse](./page#mouse) to click in the center of the element, or the specified `position`.
|
106
|
+
1. Wait for initiated navigations to either succeed or fail, unless `noWaitAfter` option is set.
|
107
|
+
|
108
|
+
If the element is detached from the DOM at any moment during the action, this method throws.
|
109
|
+
|
110
|
+
When all steps combined have not finished during the specified `timeout`, this method throws a `TimeoutError`. Passing
|
111
|
+
zero timeout disables this.
|
112
|
+
|
113
|
+
## content_frame
|
114
|
+
|
115
|
+
```
|
116
|
+
def content_frame
|
117
|
+
```
|
118
|
+
|
119
|
+
Returns the content frame for element handles referencing iframe nodes, or `null` otherwise
|
120
|
+
|
121
|
+
## dblclick
|
122
|
+
|
123
|
+
```
|
124
|
+
def dblclick(
|
125
|
+
button: nil,
|
126
|
+
delay: nil,
|
127
|
+
force: nil,
|
128
|
+
modifiers: nil,
|
129
|
+
noWaitAfter: nil,
|
130
|
+
position: nil,
|
131
|
+
timeout: nil,
|
132
|
+
trial: nil)
|
133
|
+
```
|
134
|
+
|
135
|
+
This method double clicks the element by performing the following steps:
|
136
|
+
1. Wait for [actionability](https://playwright.dev/python/docs/actionability) checks on the element, unless `force` option is set.
|
137
|
+
1. Scroll the element into view if needed.
|
138
|
+
1. Use [Page#mouse](./page#mouse) to double click in the center of the element, or the specified `position`.
|
139
|
+
1. Wait for initiated navigations to either succeed or fail, unless `noWaitAfter` option is set. Note that if the
|
140
|
+
first click of the `dblclick()` triggers a navigation event, this method will throw.
|
141
|
+
|
142
|
+
If the element is detached from the DOM at any moment during the action, this method throws.
|
143
|
+
|
144
|
+
When all steps combined have not finished during the specified `timeout`, this method throws a `TimeoutError`. Passing
|
145
|
+
zero timeout disables this.
|
146
|
+
|
147
|
+
> NOTE: `elementHandle.dblclick()` dispatches two `click` events and a single `dblclick` event.
|
148
|
+
|
149
|
+
## dispatch_event
|
150
|
+
|
151
|
+
```
|
152
|
+
def dispatch_event(type, eventInit: nil)
|
153
|
+
```
|
154
|
+
|
155
|
+
The snippet below dispatches the `click` event on the element. Regardless of the visibility state of the element,
|
156
|
+
`click` is dispatched. This is equivalent to calling
|
157
|
+
[element.click()](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/click).
|
158
|
+
|
159
|
+
```python sync title=example_3b86add6ce355082cd43f4ac0ba9e69c15960bbd7ca601d0618355fe53aa8902.py
|
160
|
+
element_handle.dispatch_event("click")
|
161
|
+
|
162
|
+
```
|
163
|
+
|
164
|
+
Under the hood, it creates an instance of an event based on the given `type`, initializes it with `eventInit` properties
|
165
|
+
and dispatches it on the element. Events are `composed`, `cancelable` and bubble by default.
|
166
|
+
|
167
|
+
Since `eventInit` is event-specific, please refer to the events documentation for the lists of initial properties:
|
168
|
+
- [DragEvent](https://developer.mozilla.org/en-US/docs/Web/API/DragEvent/DragEvent)
|
169
|
+
- [FocusEvent](https://developer.mozilla.org/en-US/docs/Web/API/FocusEvent/FocusEvent)
|
170
|
+
- [KeyboardEvent](https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/KeyboardEvent)
|
171
|
+
- [MouseEvent](https://developer.mozilla.org/en-US/docs/Web/API/MouseEvent/MouseEvent)
|
172
|
+
- [PointerEvent](https://developer.mozilla.org/en-US/docs/Web/API/PointerEvent/PointerEvent)
|
173
|
+
- [TouchEvent](https://developer.mozilla.org/en-US/docs/Web/API/TouchEvent/TouchEvent)
|
174
|
+
- [Event](https://developer.mozilla.org/en-US/docs/Web/API/Event/Event)
|
175
|
+
|
176
|
+
You can also specify [JSHandle](./js_handle) as the property value if you want live objects to be passed into the event:
|
177
|
+
|
178
|
+
```python sync title=example_6b70ea4cf0c7ae9c82cf0ed22ab0dbbb563e2d1419b35d04aa513cf91f0856f9.py
|
179
|
+
# note you can only create data_transfer in chromium and firefox
|
180
|
+
data_transfer = page.evaluate_handle("new DataTransfer()")
|
181
|
+
element_handle.dispatch_event("#source", "dragstart", {"dataTransfer": data_transfer})
|
182
|
+
|
183
|
+
```
|
184
|
+
|
185
|
+
|
186
|
+
|
187
|
+
## eval_on_selector
|
188
|
+
|
189
|
+
```
|
190
|
+
def eval_on_selector(selector, expression, arg: nil)
|
191
|
+
```
|
192
|
+
|
193
|
+
Returns the return value of `expression`.
|
194
|
+
|
195
|
+
The method finds an element matching the specified selector in the [ElementHandle](./element_handle)s subtree and passes it as a first
|
196
|
+
argument to `expression`. See [Working with selectors](https://playwright.dev/python/docs/selectors) for more details. If no elements match the
|
197
|
+
selector, the method throws an error.
|
198
|
+
|
199
|
+
If `expression` returns a [Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise), then [ElementHandle#eval_on_selector](./element_handle#eval_on_selector) would wait for the promise to resolve
|
200
|
+
and return its value.
|
201
|
+
|
202
|
+
Examples:
|
203
|
+
|
204
|
+
```python sync title=example_f6a83ec555fcf23877c11cf55f02a8c89a7fc11d3324859feda42e592e129f4f.py
|
205
|
+
tweet_handle = page.query_selector(".tweet")
|
206
|
+
assert tweet_handle.eval_on_selector(".like", "node => node.innerText") == "100"
|
207
|
+
assert tweet_handle.eval_on_selector(".retweets", "node => node.innerText") = "10"
|
208
|
+
|
209
|
+
```
|
210
|
+
|
211
|
+
|
212
|
+
|
213
|
+
## eval_on_selector_all
|
214
|
+
|
215
|
+
```
|
216
|
+
def eval_on_selector_all(selector, expression, arg: nil)
|
217
|
+
```
|
218
|
+
|
219
|
+
Returns the return value of `expression`.
|
220
|
+
|
221
|
+
The method finds all elements matching the specified selector in the [ElementHandle](./element_handle)'s subtree and passes an array of
|
222
|
+
matched elements as a first argument to `expression`. See [Working with selectors](https://playwright.dev/python/docs/selectors) for more details.
|
223
|
+
|
224
|
+
If `expression` returns a [Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise), then [ElementHandle#eval_on_selector_all](./element_handle#eval_on_selector_all) would wait for the promise to
|
225
|
+
resolve and return its value.
|
226
|
+
|
227
|
+
Examples:
|
228
|
+
|
229
|
+
```html
|
230
|
+
<div class="feed">
|
231
|
+
<div class="tweet">Hello!</div>
|
232
|
+
<div class="tweet">Hi!</div>
|
233
|
+
</div>
|
234
|
+
```
|
235
|
+
|
236
|
+
```python sync title=example_11b54bf5ec18a0d0ceee0868651bb41ab5cd3afcc6b20d5c44f90d835c8d6f81.py
|
237
|
+
feed_handle = page.query_selector(".feed")
|
238
|
+
assert feed_handle.eval_on_selector_all(".tweet", "nodes => nodes.map(n => n.innerText)") == ["hello!", "hi!"]
|
239
|
+
|
240
|
+
```
|
241
|
+
|
242
|
+
|
243
|
+
|
244
|
+
## fill
|
245
|
+
|
246
|
+
```
|
247
|
+
def fill(value, noWaitAfter: nil, timeout: nil)
|
248
|
+
```
|
249
|
+
|
250
|
+
This method waits for [actionability](https://playwright.dev/python/docs/actionability) checks, focuses the element, fills it and triggers an `input`
|
251
|
+
event after filling. Note that you can pass an empty string to clear the input field.
|
252
|
+
|
253
|
+
If the target element is not an `<input>`, `<textarea>` or `[contenteditable]` element, this method throws an error.
|
254
|
+
However, if the element is inside the `<label>` element that has an associated
|
255
|
+
[control](https://developer.mozilla.org/en-US/docs/Web/API/HTMLLabelElement/control), the control will be filled
|
256
|
+
instead.
|
257
|
+
|
258
|
+
To send fine-grained keyboard events, use [ElementHandle#type](./element_handle#type).
|
259
|
+
|
260
|
+
## focus
|
261
|
+
|
262
|
+
```
|
263
|
+
def focus
|
264
|
+
```
|
265
|
+
|
266
|
+
Calls [focus](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/focus) on the element.
|
267
|
+
|
268
|
+
## get_attribute
|
269
|
+
|
270
|
+
```
|
271
|
+
def get_attribute(name)
|
272
|
+
```
|
273
|
+
alias: `[]`
|
274
|
+
|
275
|
+
Returns element attribute value.
|
276
|
+
|
277
|
+
## hover
|
278
|
+
|
279
|
+
```
|
280
|
+
def hover(
|
281
|
+
force: nil,
|
282
|
+
modifiers: nil,
|
283
|
+
position: nil,
|
284
|
+
timeout: nil,
|
285
|
+
trial: nil)
|
286
|
+
```
|
287
|
+
|
288
|
+
This method hovers over the element by performing the following steps:
|
289
|
+
1. Wait for [actionability](https://playwright.dev/python/docs/actionability) checks on the element, unless `force` option is set.
|
290
|
+
1. Scroll the element into view if needed.
|
291
|
+
1. Use [Page#mouse](./page#mouse) to hover over the center of the element, or the specified `position`.
|
292
|
+
1. Wait for initiated navigations to either succeed or fail, unless `noWaitAfter` option is set.
|
293
|
+
|
294
|
+
If the element is detached from the DOM at any moment during the action, this method throws.
|
295
|
+
|
296
|
+
When all steps combined have not finished during the specified `timeout`, this method throws a `TimeoutError`. Passing
|
297
|
+
zero timeout disables this.
|
298
|
+
|
299
|
+
## inner_html
|
300
|
+
|
301
|
+
```
|
302
|
+
def inner_html
|
303
|
+
```
|
304
|
+
|
305
|
+
Returns the `element.innerHTML`.
|
306
|
+
|
307
|
+
## inner_text
|
308
|
+
|
309
|
+
```
|
310
|
+
def inner_text
|
311
|
+
```
|
312
|
+
|
313
|
+
Returns the `element.innerText`.
|
314
|
+
|
315
|
+
## checked?
|
316
|
+
|
317
|
+
```
|
318
|
+
def checked?
|
319
|
+
```
|
320
|
+
|
321
|
+
Returns whether the element is checked. Throws if the element is not a checkbox or radio input.
|
322
|
+
|
323
|
+
## disabled?
|
324
|
+
|
325
|
+
```
|
326
|
+
def disabled?
|
327
|
+
```
|
328
|
+
|
329
|
+
Returns whether the element is disabled, the opposite of [enabled](https://playwright.dev/python/docs/actionability).
|
330
|
+
|
331
|
+
## editable?
|
332
|
+
|
333
|
+
```
|
334
|
+
def editable?
|
335
|
+
```
|
336
|
+
|
337
|
+
Returns whether the element is [editable](https://playwright.dev/python/docs/actionability).
|
338
|
+
|
339
|
+
## enabled?
|
340
|
+
|
341
|
+
```
|
342
|
+
def enabled?
|
343
|
+
```
|
344
|
+
|
345
|
+
Returns whether the element is [enabled](https://playwright.dev/python/docs/actionability).
|
346
|
+
|
347
|
+
## hidden?
|
348
|
+
|
349
|
+
```
|
350
|
+
def hidden?
|
351
|
+
```
|
352
|
+
|
353
|
+
Returns whether the element is hidden, the opposite of [visible](https://playwright.dev/python/docs/actionability).
|
354
|
+
|
355
|
+
## visible?
|
356
|
+
|
357
|
+
```
|
358
|
+
def visible?
|
359
|
+
```
|
360
|
+
|
361
|
+
Returns whether the element is [visible](https://playwright.dev/python/docs/actionability).
|
362
|
+
|
363
|
+
## owner_frame
|
364
|
+
|
365
|
+
```
|
366
|
+
def owner_frame
|
367
|
+
```
|
368
|
+
|
369
|
+
Returns the frame containing the given element.
|
370
|
+
|
371
|
+
## press
|
372
|
+
|
373
|
+
```
|
374
|
+
def press(key, delay: nil, noWaitAfter: nil, timeout: nil)
|
375
|
+
```
|
376
|
+
|
377
|
+
Focuses the element, and then uses [Keyboard#down](./keyboard#down) and [Keyboard#up](./keyboard#up).
|
378
|
+
|
379
|
+
`key` can specify the intended [keyboardEvent.key](https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/key)
|
380
|
+
value or a single character to generate the text for. A superset of the `key` values can be found
|
381
|
+
[here](https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/key/Key_Values). Examples of the keys are:
|
382
|
+
|
383
|
+
`F1` - `F12`, `Digit0`- `Digit9`, `KeyA`- `KeyZ`, `Backquote`, `Minus`, `Equal`, `Backslash`, `Backspace`, `Tab`,
|
384
|
+
`Delete`, `Escape`, `ArrowDown`, `End`, `Enter`, `Home`, `Insert`, `PageDown`, `PageUp`, `ArrowRight`, `ArrowUp`, etc.
|
385
|
+
|
386
|
+
Following modification shortcuts are also supported: `Shift`, `Control`, `Alt`, `Meta`, `ShiftLeft`.
|
387
|
+
|
388
|
+
Holding down `Shift` will type the text that corresponds to the `key` in the upper case.
|
389
|
+
|
390
|
+
If `key` is a single character, it is case-sensitive, so the values `a` and `A` will generate different respective
|
391
|
+
texts.
|
392
|
+
|
393
|
+
Shortcuts such as `key: "Control+o"` or `key: "Control+Shift+T"` are supported as well. When specified with the
|
394
|
+
modifier, modifier is pressed and being held while the subsequent key is being pressed.
|
395
|
+
|
396
|
+
## query_selector
|
397
|
+
|
398
|
+
```
|
399
|
+
def query_selector(selector)
|
400
|
+
```
|
401
|
+
|
402
|
+
The method finds an element matching the specified selector in the [ElementHandle](./element_handle)'s subtree. See
|
403
|
+
[Working with selectors](https://playwright.dev/python/docs/selectors) for more details. If no elements match the selector, returns `null`.
|
404
|
+
|
405
|
+
## query_selector_all
|
406
|
+
|
407
|
+
```
|
408
|
+
def query_selector_all(selector)
|
409
|
+
```
|
410
|
+
|
411
|
+
The method finds all elements matching the specified selector in the [ElementHandle](./element_handle)s subtree. See
|
412
|
+
[Working with selectors](https://playwright.dev/python/docs/selectors) for more details. If no elements match the selector, returns empty array.
|
413
|
+
|
414
|
+
## screenshot
|
415
|
+
|
416
|
+
```
|
417
|
+
def screenshot(
|
418
|
+
omitBackground: nil,
|
419
|
+
path: nil,
|
420
|
+
quality: nil,
|
421
|
+
timeout: nil,
|
422
|
+
type: nil)
|
423
|
+
```
|
424
|
+
|
425
|
+
Returns the buffer with the captured screenshot.
|
426
|
+
|
427
|
+
This method waits for the [actionability](https://playwright.dev/python/docs/actionability) checks, then scrolls element into view before taking a
|
428
|
+
screenshot. If the element is detached from DOM, the method throws an error.
|
429
|
+
|
430
|
+
## scroll_into_view_if_needed
|
431
|
+
|
432
|
+
```
|
433
|
+
def scroll_into_view_if_needed(timeout: nil)
|
434
|
+
```
|
435
|
+
|
436
|
+
This method waits for [actionability](https://playwright.dev/python/docs/actionability) checks, then tries to scroll element into view, unless it is
|
437
|
+
completely visible as defined by
|
438
|
+
[IntersectionObserver](https://developer.mozilla.org/en-US/docs/Web/API/Intersection_Observer_API)'s `ratio`.
|
439
|
+
|
440
|
+
Throws when `elementHandle` does not point to an element
|
441
|
+
[connected](https://developer.mozilla.org/en-US/docs/Web/API/Node/isConnected) to a Document or a ShadowRoot.
|
442
|
+
|
443
|
+
## select_option
|
444
|
+
|
445
|
+
```
|
446
|
+
def select_option(
|
447
|
+
element: nil,
|
448
|
+
index: nil,
|
449
|
+
value: nil,
|
450
|
+
label: nil,
|
451
|
+
noWaitAfter: nil,
|
452
|
+
timeout: nil)
|
453
|
+
```
|
454
|
+
|
455
|
+
This method waits for [actionability](https://playwright.dev/python/docs/actionability) checks, waits until all specified options are present in the
|
456
|
+
`<select>` element and selects these options.
|
457
|
+
|
458
|
+
If the target element is not a `<select>` element, this method throws an error. However, if the element is inside the
|
459
|
+
`<label>` element that has an associated
|
460
|
+
[control](https://developer.mozilla.org/en-US/docs/Web/API/HTMLLabelElement/control), the control will be used instead.
|
461
|
+
|
462
|
+
Returns the array of option values that have been successfully selected.
|
463
|
+
|
464
|
+
Triggers a `change` and `input` event once all the provided options have been selected.
|
465
|
+
|
466
|
+
```python sync title=example_dc2ce38846b91d234483ed8b915b785ffbd9403213279465acd6605f314fe736.py
|
467
|
+
# single selection matching the value
|
468
|
+
handle.select_option("blue")
|
469
|
+
# single selection matching both the label
|
470
|
+
handle.select_option(label="blue")
|
471
|
+
# multiple selection
|
472
|
+
handle.select_option(value=["red", "green", "blue"])
|
473
|
+
|
474
|
+
```
|
475
|
+
|
476
|
+
```python sync title=example_b4cdd4a1a4d0392c2d430e0fb5fc670df2d728b6907553650690a2d0377662e4.py
|
477
|
+
# single selection matching the value
|
478
|
+
handle.select_option("blue")
|
479
|
+
# single selection matching both the value and the label
|
480
|
+
handle.select_option(label="blue")
|
481
|
+
# multiple selection
|
482
|
+
handle.select_option("red", "green", "blue")
|
483
|
+
# multiple selection for blue, red and second option
|
484
|
+
handle.select_option(value="blue", { index: 2 }, "red")
|
485
|
+
|
486
|
+
```
|
487
|
+
|
488
|
+
|
489
|
+
|
490
|
+
## select_text
|
491
|
+
|
492
|
+
```
|
493
|
+
def select_text(timeout: nil)
|
494
|
+
```
|
495
|
+
|
496
|
+
This method waits for [actionability](https://playwright.dev/python/docs/actionability) checks, then focuses the element and selects all its text
|
497
|
+
content.
|
498
|
+
|
499
|
+
## set_input_files
|
500
|
+
|
501
|
+
```
|
502
|
+
def set_input_files(files, noWaitAfter: nil, timeout: nil)
|
503
|
+
```
|
504
|
+
alias: `input_files=`
|
505
|
+
|
506
|
+
This method expects `elementHandle` to point to an
|
507
|
+
[input element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input).
|
508
|
+
|
509
|
+
Sets the value of the file input to these file paths or files. If some of the `filePaths` are relative paths, then they
|
510
|
+
are resolved relative to the the current working directory. For empty array, clears the selected files.
|
511
|
+
|
512
|
+
## tap_point
|
513
|
+
|
514
|
+
```
|
515
|
+
def tap_point(
|
516
|
+
force: nil,
|
517
|
+
modifiers: nil,
|
518
|
+
noWaitAfter: nil,
|
519
|
+
position: nil,
|
520
|
+
timeout: nil,
|
521
|
+
trial: nil)
|
522
|
+
```
|
523
|
+
|
524
|
+
This method taps the element by performing the following steps:
|
525
|
+
1. Wait for [actionability](https://playwright.dev/python/docs/actionability) checks on the element, unless `force` option is set.
|
526
|
+
1. Scroll the element into view if needed.
|
527
|
+
1. Use [Page#touchscreen](./page#touchscreen) to tap the center of the element, or the specified `position`.
|
528
|
+
1. Wait for initiated navigations to either succeed or fail, unless `noWaitAfter` option is set.
|
529
|
+
|
530
|
+
If the element is detached from the DOM at any moment during the action, this method throws.
|
531
|
+
|
532
|
+
When all steps combined have not finished during the specified `timeout`, this method throws a `TimeoutError`. Passing
|
533
|
+
zero timeout disables this.
|
534
|
+
|
535
|
+
> NOTE: `elementHandle.tap()` requires that the `hasTouch` option of the browser context be set to true.
|
536
|
+
|
537
|
+
## text_content
|
538
|
+
|
539
|
+
```
|
540
|
+
def text_content
|
541
|
+
```
|
542
|
+
|
543
|
+
Returns the `node.textContent`.
|
544
|
+
|
545
|
+
## type
|
546
|
+
|
547
|
+
```
|
548
|
+
def type(text, delay: nil, noWaitAfter: nil, timeout: nil)
|
549
|
+
```
|
550
|
+
|
551
|
+
Focuses the element, and then sends a `keydown`, `keypress`/`input`, and `keyup` event for each character in the text.
|
552
|
+
|
553
|
+
To press a special key, like `Control` or `ArrowDown`, use [ElementHandle#press](./element_handle#press).
|
554
|
+
|
555
|
+
```python sync title=example_2dc9720467640fd8bc581ed65159742e51ff91b209cb176fef8b95f14eaad54e.py
|
556
|
+
element_handle.type("hello") # types instantly
|
557
|
+
element_handle.type("world", delay=100) # types slower, like a user
|
558
|
+
|
559
|
+
```
|
560
|
+
|
561
|
+
An example of typing into a text field and then submitting the form:
|
562
|
+
|
563
|
+
```python sync title=example_d13faaf53454653ce45371b5cf337082a82bf7bbb0aada7e97f47d14963bd6b0.py
|
564
|
+
element_handle = page.query_selector("input")
|
565
|
+
element_handle.type("some text")
|
566
|
+
element_handle.press("Enter")
|
567
|
+
|
568
|
+
```
|
569
|
+
|
570
|
+
|
571
|
+
|
572
|
+
## uncheck
|
573
|
+
|
574
|
+
```
|
575
|
+
def uncheck(
|
576
|
+
force: nil,
|
577
|
+
noWaitAfter: nil,
|
578
|
+
position: nil,
|
579
|
+
timeout: nil,
|
580
|
+
trial: nil)
|
581
|
+
```
|
582
|
+
|
583
|
+
This method checks the element by performing the following steps:
|
584
|
+
1. Ensure that element is a checkbox or a radio input. If not, this method throws. If the element is already
|
585
|
+
unchecked, this method returns immediately.
|
586
|
+
1. Wait for [actionability](https://playwright.dev/python/docs/actionability) checks on the element, unless `force` option is set.
|
587
|
+
1. Scroll the element into view if needed.
|
588
|
+
1. Use [Page#mouse](./page#mouse) to click in the center of the element.
|
589
|
+
1. Wait for initiated navigations to either succeed or fail, unless `noWaitAfter` option is set.
|
590
|
+
1. Ensure that the element is now unchecked. If not, this method throws.
|
591
|
+
|
592
|
+
If the element is detached from the DOM at any moment during the action, this method throws.
|
593
|
+
|
594
|
+
When all steps combined have not finished during the specified `timeout`, this method throws a `TimeoutError`. Passing
|
595
|
+
zero timeout disables this.
|
596
|
+
|
597
|
+
## wait_for_element_state
|
598
|
+
|
599
|
+
```
|
600
|
+
def wait_for_element_state(state, timeout: nil)
|
601
|
+
```
|
602
|
+
|
603
|
+
Returns when the element satisfies the `state`.
|
604
|
+
|
605
|
+
Depending on the `state` parameter, this method waits for one of the [actionability](https://playwright.dev/python/docs/actionability) checks to pass.
|
606
|
+
This method throws when the element is detached while waiting, unless waiting for the `"hidden"` state.
|
607
|
+
- `"visible"` Wait until the element is [visible](https://playwright.dev/python/docs/actionability).
|
608
|
+
- `"hidden"` Wait until the element is [not visible](https://playwright.dev/python/docs/actionability) or
|
609
|
+
[not attached](https://playwright.dev/python/docs/actionability). Note that waiting for hidden does not throw when the element detaches.
|
610
|
+
- `"stable"` Wait until the element is both [visible](https://playwright.dev/python/docs/actionability) and
|
611
|
+
[stable](https://playwright.dev/python/docs/actionability).
|
612
|
+
- `"enabled"` Wait until the element is [enabled](https://playwright.dev/python/docs/actionability).
|
613
|
+
- `"disabled"` Wait until the element is [not enabled](https://playwright.dev/python/docs/actionability).
|
614
|
+
- `"editable"` Wait until the element is [editable](https://playwright.dev/python/docs/actionability).
|
615
|
+
|
616
|
+
If the element does not satisfy the condition for the `timeout` milliseconds, this method will throw.
|
617
|
+
|
618
|
+
## wait_for_selector
|
619
|
+
|
620
|
+
```
|
621
|
+
def wait_for_selector(selector, state: nil, timeout: nil)
|
622
|
+
```
|
623
|
+
|
624
|
+
Returns element specified by selector when it satisfies `state` option. Returns `null` if waiting for `hidden` or
|
625
|
+
`detached`.
|
626
|
+
|
627
|
+
Wait for the `selector` relative to the element handle to satisfy `state` option (either appear/disappear from dom, or
|
628
|
+
become visible/hidden). If at the moment of calling the method `selector` already satisfies the condition, the method
|
629
|
+
will return immediately. If the selector doesn't satisfy the condition for the `timeout` milliseconds, the function will
|
630
|
+
throw.
|
631
|
+
|
632
|
+
```python sync title=example_3b0f6c6573db513b7b707a39d6c5bbf5ce5896b4785466d80f525968cfbd0be7.py
|
633
|
+
page.set_content("<div><span></span></div>")
|
634
|
+
div = page.query_selector("div")
|
635
|
+
# waiting for the "span" selector relative to the div.
|
636
|
+
span = div.wait_for_selector("span", state="attached")
|
637
|
+
|
638
|
+
```
|
639
|
+
|
640
|
+
> NOTE: This method does not work across navigations, use [Page#wait_for_selector](./page#wait_for_selector) instead.
|