playwright-ruby-client 1.28.1 → 1.29.0
Sign up to get free protection for your applications and to get access to all the features.
- checksums.yaml +4 -4
- data/documentation/docs/api/accessibility.md +9 -14
- data/documentation/docs/api/api_request_context.md +44 -41
- data/documentation/docs/api/api_response.md +13 -3
- data/documentation/docs/api/browser.md +24 -23
- data/documentation/docs/api/browser_context.md +71 -45
- data/documentation/docs/api/browser_type.md +21 -14
- data/documentation/docs/api/cdp_session.md +3 -5
- data/documentation/docs/api/console_message.md +7 -4
- data/documentation/docs/api/dialog.md +9 -5
- data/documentation/docs/api/download.md +19 -11
- data/documentation/docs/api/element_handle.md +125 -116
- data/documentation/docs/api/experimental/android.md +4 -5
- data/documentation/docs/api/experimental/android_device.md +11 -2
- data/documentation/docs/api/experimental/android_input.md +5 -0
- data/documentation/docs/api/file_chooser.md +6 -3
- data/documentation/docs/api/frame.md +182 -171
- data/documentation/docs/api/frame_locator.md +27 -38
- data/documentation/docs/api/js_handle.md +16 -10
- data/documentation/docs/api/keyboard.md +29 -16
- data/documentation/docs/api/locator.md +189 -140
- data/documentation/docs/api/mouse.md +9 -4
- data/documentation/docs/api/page.md +304 -289
- data/documentation/docs/api/playwright.md +8 -5
- data/documentation/docs/api/request.md +34 -15
- data/documentation/docs/api/response.md +27 -10
- data/documentation/docs/api/route.md +44 -12
- data/documentation/docs/api/selectors.md +5 -3
- data/documentation/docs/api/touchscreen.md +2 -0
- data/documentation/docs/api/tracing.md +11 -11
- data/documentation/docs/api/web_socket.md +9 -4
- data/documentation/docs/api/worker.md +12 -11
- data/documentation/docs/include/api_coverage.md +2 -0
- data/lib/playwright/channel_owners/api_request_context.rb +37 -2
- data/lib/playwright/channel_owners/browser_context.rb +22 -26
- data/lib/playwright/channel_owners/page.rb +35 -25
- data/lib/playwright/channel_owners/route.rb +28 -8
- data/lib/playwright/event_emitter.rb +6 -1
- data/lib/playwright/locator_impl.rb +8 -0
- data/lib/playwright/select_option_values.rb +2 -0
- data/lib/playwright/version.rb +2 -2
- data/lib/playwright_api/accessibility.rb +9 -13
- data/lib/playwright_api/android.rb +8 -6
- data/lib/playwright_api/android_device.rb +32 -7
- data/lib/playwright_api/android_input.rb +5 -0
- data/lib/playwright_api/android_socket.rb +4 -2
- data/lib/playwright_api/android_web_view.rb +5 -2
- data/lib/playwright_api/api_request.rb +6 -3
- data/lib/playwright_api/api_request_context.rb +46 -36
- data/lib/playwright_api/api_response.rb +13 -2
- data/lib/playwright_api/browser.rb +24 -16
- data/lib/playwright_api/browser_context.rb +76 -39
- data/lib/playwright_api/browser_type.rb +23 -13
- data/lib/playwright_api/cdp_session.rb +3 -4
- data/lib/playwright_api/console_message.rb +7 -2
- data/lib/playwright_api/dialog.rb +8 -4
- data/lib/playwright_api/download.rb +19 -9
- data/lib/playwright_api/element_handle.rb +116 -93
- data/lib/playwright_api/file_chooser.rb +6 -1
- data/lib/playwright_api/frame.rb +180 -135
- data/lib/playwright_api/frame_locator.rb +29 -32
- data/lib/playwright_api/js_handle.rb +16 -6
- data/lib/playwright_api/keyboard.rb +29 -14
- data/lib/playwright_api/locator.rb +183 -112
- data/lib/playwright_api/mouse.rb +9 -2
- data/lib/playwright_api/page.rb +301 -253
- data/lib/playwright_api/playwright.rb +11 -4
- data/lib/playwright_api/request.rb +34 -7
- data/lib/playwright_api/response.rb +27 -10
- data/lib/playwright_api/route.rb +44 -11
- data/lib/playwright_api/selectors.rb +6 -1
- data/lib/playwright_api/touchscreen.rb +2 -0
- data/lib/playwright_api/tracing.rb +11 -5
- data/lib/playwright_api/web_socket.rb +9 -4
- data/lib/playwright_api/worker.rb +16 -13
- data/playwright.gemspec +1 -1
- metadata +7 -7
@@ -6,10 +6,9 @@ sidebar_position: 10
|
|
6
6
|
|
7
7
|
- extends: [JSHandle](./js_handle)
|
8
8
|
|
9
|
-
ElementHandle represents an in-page DOM element. ElementHandles can be created with the [Page#query_selector](./page#query_selector)
|
10
|
-
method.
|
9
|
+
ElementHandle represents an in-page DOM element. ElementHandles can be created with the [Page#query_selector](./page#query_selector) method.
|
11
10
|
|
12
|
-
|
11
|
+
**NOTE**: The use of ElementHandle is discouraged, use [Locator](./locator) objects and web-first assertions instead.
|
13
12
|
|
14
13
|
```ruby
|
15
14
|
href_element = page.query_selector("a")
|
@@ -19,15 +18,11 @@ href_element.click
|
|
19
18
|
ElementHandle prevents DOM element from garbage collection unless the handle is disposed with
|
20
19
|
[JSHandle#dispose](./js_handle#dispose). ElementHandles are auto-disposed when their origin frame gets navigated.
|
21
20
|
|
22
|
-
ElementHandle instances can be used as an argument in [Page#eval_on_selector](./page#eval_on_selector) and [Page#evaluate](./page#evaluate)
|
23
|
-
methods.
|
21
|
+
ElementHandle instances can be used as an argument in [Page#eval_on_selector](./page#eval_on_selector) and [Page#evaluate](./page#evaluate) methods.
|
24
22
|
|
25
|
-
The difference between the [Locator](./locator) and ElementHandle is that the ElementHandle points to a particular element, while
|
26
|
-
[Locator](./locator) captures the logic of how to retrieve an element.
|
23
|
+
The difference between the [Locator](./locator) and ElementHandle is that the ElementHandle points to a particular element, while [Locator](./locator) captures the logic of how to retrieve an element.
|
27
24
|
|
28
|
-
In the example below, handle points to a particular DOM element on page. If that element changes text or is used by
|
29
|
-
React to render an entirely different component, handle is still pointing to that very DOM element. This can lead to
|
30
|
-
unexpected behaviors.
|
25
|
+
In the example below, handle points to a particular DOM element on page. If that element changes text or is used by React to render an entirely different component, handle is still pointing to that very DOM element. This can lead to unexpected behaviors.
|
31
26
|
|
32
27
|
```ruby
|
33
28
|
handle = page.query_selector("text=Submit")
|
@@ -35,8 +30,7 @@ handle.hover
|
|
35
30
|
handle.click
|
36
31
|
```
|
37
32
|
|
38
|
-
With the locator, every time the `element` is used, up-to-date DOM element is located in the page using the selector. So
|
39
|
-
in the snippet below, underlying DOM element is going to be located twice.
|
33
|
+
With the locator, every time the `element` is used, up-to-date DOM element is located in the page using the selector. So in the snippet below, underlying DOM element is going to be located twice.
|
40
34
|
|
41
35
|
```ruby
|
42
36
|
locator = page.get_by_text("Submit")
|
@@ -44,14 +38,13 @@ locator.hover
|
|
44
38
|
locator.click
|
45
39
|
```
|
46
40
|
|
47
|
-
|
48
|
-
|
49
41
|
## bounding_box
|
50
42
|
|
51
43
|
```
|
52
44
|
def bounding_box
|
53
45
|
```
|
54
46
|
|
47
|
+
|
55
48
|
This method returns the bounding box of the element, or `null` if the element is not visible. The bounding box is
|
56
49
|
calculated relative to the main frame viewport - which is usually the same as the browser window.
|
57
50
|
|
@@ -65,6 +58,8 @@ Elements from child frames return the bounding box relative to the main frame, u
|
|
65
58
|
Assuming the page is static, it is safe to use bounding box coordinates to perform input. For example, the following
|
66
59
|
snippet should click the center of the element.
|
67
60
|
|
61
|
+
**Usage**
|
62
|
+
|
68
63
|
```ruby
|
69
64
|
box = element_handle.bounding_box
|
70
65
|
page.mouse.click(
|
@@ -73,8 +68,6 @@ page.mouse.click(
|
|
73
68
|
)
|
74
69
|
```
|
75
70
|
|
76
|
-
|
77
|
-
|
78
71
|
## check
|
79
72
|
|
80
73
|
```
|
@@ -86,9 +79,9 @@ def check(
|
|
86
79
|
trial: nil)
|
87
80
|
```
|
88
81
|
|
82
|
+
|
89
83
|
This method checks the element by performing the following steps:
|
90
|
-
1. Ensure that element is a checkbox or a radio input. If not, this method throws. If the element is already checked,
|
91
|
-
this method returns immediately.
|
84
|
+
1. Ensure that element is a checkbox or a radio input. If not, this method throws. If the element is already checked, this method returns immediately.
|
92
85
|
1. Wait for [actionability](https://playwright.dev/python/docs/actionability) checks on the element, unless `force` option is set.
|
93
86
|
1. Scroll the element into view if needed.
|
94
87
|
1. Use [Page#mouse](./page#mouse) to click in the center of the element.
|
@@ -97,8 +90,8 @@ This method checks the element by performing the following steps:
|
|
97
90
|
|
98
91
|
If the element is detached from the DOM at any moment during the action, this method throws.
|
99
92
|
|
100
|
-
When all steps combined have not finished during the specified `timeout`, this method throws a
|
101
|
-
zero timeout disables this.
|
93
|
+
When all steps combined have not finished during the specified `timeout`, this method throws a
|
94
|
+
`TimeoutError`. Passing zero timeout disables this.
|
102
95
|
|
103
96
|
## click
|
104
97
|
|
@@ -115,6 +108,7 @@ def click(
|
|
115
108
|
trial: nil)
|
116
109
|
```
|
117
110
|
|
111
|
+
|
118
112
|
This method clicks the element by performing the following steps:
|
119
113
|
1. Wait for [actionability](https://playwright.dev/python/docs/actionability) checks on the element, unless `force` option is set.
|
120
114
|
1. Scroll the element into view if needed.
|
@@ -123,8 +117,8 @@ This method clicks the element by performing the following steps:
|
|
123
117
|
|
124
118
|
If the element is detached from the DOM at any moment during the action, this method throws.
|
125
119
|
|
126
|
-
When all steps combined have not finished during the specified `timeout`, this method throws a
|
127
|
-
zero timeout disables this.
|
120
|
+
When all steps combined have not finished during the specified `timeout`, this method throws a
|
121
|
+
`TimeoutError`. Passing zero timeout disables this.
|
128
122
|
|
129
123
|
## content_frame
|
130
124
|
|
@@ -132,6 +126,7 @@ zero timeout disables this.
|
|
132
126
|
def content_frame
|
133
127
|
```
|
134
128
|
|
129
|
+
|
135
130
|
Returns the content frame for element handles referencing iframe nodes, or `null` otherwise
|
136
131
|
|
137
132
|
## dblclick
|
@@ -148,19 +143,19 @@ def dblclick(
|
|
148
143
|
trial: nil)
|
149
144
|
```
|
150
145
|
|
146
|
+
|
151
147
|
This method double clicks the element by performing the following steps:
|
152
148
|
1. Wait for [actionability](https://playwright.dev/python/docs/actionability) checks on the element, unless `force` option is set.
|
153
149
|
1. Scroll the element into view if needed.
|
154
150
|
1. Use [Page#mouse](./page#mouse) to double click in the center of the element, or the specified `position`.
|
155
|
-
1. Wait for initiated navigations to either succeed or fail, unless `noWaitAfter` option is set. Note that if the
|
156
|
-
first click of the `dblclick()` triggers a navigation event, this method will throw.
|
151
|
+
1. Wait for initiated navigations to either succeed or fail, unless `noWaitAfter` option is set. Note that if the first click of the `dblclick()` triggers a navigation event, this method will throw.
|
157
152
|
|
158
153
|
If the element is detached from the DOM at any moment during the action, this method throws.
|
159
154
|
|
160
|
-
When all steps combined have not finished during the specified `timeout`, this method throws a
|
161
|
-
zero timeout disables this.
|
155
|
+
When all steps combined have not finished during the specified `timeout`, this method throws a
|
156
|
+
`TimeoutError`. Passing zero timeout disables this.
|
162
157
|
|
163
|
-
|
158
|
+
**NOTE**: `elementHandle.dblclick()` dispatches two `click` events and a single `dblclick` event.
|
164
159
|
|
165
160
|
## dispatch_event
|
166
161
|
|
@@ -168,18 +163,23 @@ zero timeout disables this.
|
|
168
163
|
def dispatch_event(type, eventInit: nil)
|
169
164
|
```
|
170
165
|
|
171
|
-
|
172
|
-
`click`
|
166
|
+
|
167
|
+
The snippet below dispatches the `click` event on the element. Regardless of the visibility state of the element, `click`
|
168
|
+
is dispatched. This is equivalent to calling
|
173
169
|
[element.click()](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/click).
|
174
170
|
|
171
|
+
**Usage**
|
172
|
+
|
175
173
|
```ruby
|
176
174
|
element_handle.dispatch_event("click")
|
177
175
|
```
|
178
176
|
|
179
|
-
Under the hood, it creates an instance of an event based on the given `type`, initializes it with
|
180
|
-
and dispatches it on the element. Events are `composed`, `cancelable` and bubble by
|
177
|
+
Under the hood, it creates an instance of an event based on the given `type`, initializes it with
|
178
|
+
`eventInit` properties and dispatches it on the element. Events are `composed`, `cancelable` and bubble by
|
179
|
+
default.
|
181
180
|
|
182
|
-
Since `eventInit` is event-specific, please refer to the events documentation for the lists of initial
|
181
|
+
Since `eventInit` is event-specific, please refer to the events documentation for the lists of initial
|
182
|
+
properties:
|
183
183
|
- [DragEvent](https://developer.mozilla.org/en-US/docs/Web/API/DragEvent/DragEvent)
|
184
184
|
- [FocusEvent](https://developer.mozilla.org/en-US/docs/Web/API/FocusEvent/FocusEvent)
|
185
185
|
- [KeyboardEvent](https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/KeyboardEvent)
|
@@ -196,24 +196,22 @@ data_transfer = page.evaluate_handle("new DataTransfer()")
|
|
196
196
|
element_handle.dispatch_event("dragstart", eventInit: { dataTransfer: data_transfer })
|
197
197
|
```
|
198
198
|
|
199
|
-
|
200
|
-
|
201
199
|
## eval_on_selector
|
202
200
|
|
203
201
|
```
|
204
202
|
def eval_on_selector(selector, expression, arg: nil)
|
205
203
|
```
|
206
204
|
|
205
|
+
|
207
206
|
Returns the return value of `expression`.
|
208
207
|
|
209
208
|
The method finds an element matching the specified selector in the [ElementHandle](./element_handle)s subtree and passes it as a first
|
210
|
-
argument to `expression`.
|
211
|
-
selector, the method throws an error.
|
209
|
+
argument to `expression`. If no elements match the selector, the method throws an error.
|
212
210
|
|
213
|
-
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
|
214
|
-
|
211
|
+
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 and return its
|
212
|
+
value.
|
215
213
|
|
216
|
-
|
214
|
+
**Usage**
|
217
215
|
|
218
216
|
```ruby
|
219
217
|
tweet_handle = page.query_selector(".tweet")
|
@@ -221,23 +219,22 @@ tweet_handle.eval_on_selector(".like", "node => node.innerText") # => "100"
|
|
221
219
|
tweet_handle.eval_on_selector(".retweets", "node => node.innerText") # => "10"
|
222
220
|
```
|
223
221
|
|
224
|
-
|
225
|
-
|
226
222
|
## eval_on_selector_all
|
227
223
|
|
228
224
|
```
|
229
225
|
def eval_on_selector_all(selector, expression, arg: nil)
|
230
226
|
```
|
231
227
|
|
228
|
+
|
232
229
|
Returns the return value of `expression`.
|
233
230
|
|
234
231
|
The method finds all elements matching the specified selector in the [ElementHandle](./element_handle)'s subtree and passes an array of
|
235
|
-
matched elements as a first argument to `expression`.
|
232
|
+
matched elements as a first argument to `expression`.
|
236
233
|
|
237
|
-
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
|
238
|
-
|
234
|
+
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 resolve and return its
|
235
|
+
value.
|
239
236
|
|
240
|
-
|
237
|
+
**Usage**
|
241
238
|
|
242
239
|
```html
|
243
240
|
<div class="feed">
|
@@ -251,21 +248,16 @@ feed_handle = page.query_selector(".feed")
|
|
251
248
|
feed_handle.eval_on_selector_all(".tweet", "nodes => nodes.map(n => n.innerText)") # => ["hello!", "hi!"]
|
252
249
|
```
|
253
250
|
|
254
|
-
|
255
|
-
|
256
251
|
## fill
|
257
252
|
|
258
253
|
```
|
259
254
|
def fill(value, force: nil, noWaitAfter: nil, timeout: nil)
|
260
255
|
```
|
261
256
|
|
262
|
-
This method waits for [actionability](https://playwright.dev/python/docs/actionability) checks, focuses the element, fills it and triggers an `input`
|
263
|
-
event after filling. Note that you can pass an empty string to clear the input field.
|
264
257
|
|
265
|
-
|
266
|
-
|
267
|
-
[control](https://developer.mozilla.org/en-US/docs/Web/API/HTMLLabelElement/control), the control will be filled
|
268
|
-
instead.
|
258
|
+
This method waits for [actionability](https://playwright.dev/python/docs/actionability) 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.
|
259
|
+
|
260
|
+
If the target element is not an `<input>`, `<textarea>` or `[contenteditable]` element, this method throws an error. However, if the element is inside the `<label>` element that has an associated [control](https://developer.mozilla.org/en-US/docs/Web/API/HTMLLabelElement/control), the control will be filled instead.
|
269
261
|
|
270
262
|
To send fine-grained keyboard events, use [ElementHandle#type](./element_handle#type).
|
271
263
|
|
@@ -275,6 +267,7 @@ To send fine-grained keyboard events, use [ElementHandle#type](./element_handle#
|
|
275
267
|
def focus
|
276
268
|
```
|
277
269
|
|
270
|
+
|
278
271
|
Calls [focus](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/focus) on the element.
|
279
272
|
|
280
273
|
## get_attribute
|
@@ -284,6 +277,7 @@ def get_attribute(name)
|
|
284
277
|
```
|
285
278
|
alias: `[]`
|
286
279
|
|
280
|
+
|
287
281
|
Returns element attribute value.
|
288
282
|
|
289
283
|
## hover
|
@@ -298,6 +292,7 @@ def hover(
|
|
298
292
|
trial: nil)
|
299
293
|
```
|
300
294
|
|
295
|
+
|
301
296
|
This method hovers over the element by performing the following steps:
|
302
297
|
1. Wait for [actionability](https://playwright.dev/python/docs/actionability) checks on the element, unless `force` option is set.
|
303
298
|
1. Scroll the element into view if needed.
|
@@ -306,8 +301,8 @@ This method hovers over the element by performing the following steps:
|
|
306
301
|
|
307
302
|
If the element is detached from the DOM at any moment during the action, this method throws.
|
308
303
|
|
309
|
-
When all steps combined have not finished during the specified `timeout`, this method throws a
|
310
|
-
zero timeout disables this.
|
304
|
+
When all steps combined have not finished during the specified `timeout`, this method throws a
|
305
|
+
`TimeoutError`. Passing zero timeout disables this.
|
311
306
|
|
312
307
|
## inner_html
|
313
308
|
|
@@ -315,6 +310,7 @@ zero timeout disables this.
|
|
315
310
|
def inner_html
|
316
311
|
```
|
317
312
|
|
313
|
+
|
318
314
|
Returns the `element.innerHTML`.
|
319
315
|
|
320
316
|
## inner_text
|
@@ -323,6 +319,7 @@ Returns the `element.innerHTML`.
|
|
323
319
|
def inner_text
|
324
320
|
```
|
325
321
|
|
322
|
+
|
326
323
|
Returns the `element.innerText`.
|
327
324
|
|
328
325
|
## input_value
|
@@ -331,10 +328,10 @@ Returns the `element.innerText`.
|
|
331
328
|
def input_value(timeout: nil)
|
332
329
|
```
|
333
330
|
|
331
|
+
|
334
332
|
Returns `input.value` for the selected `<input>` or `<textarea>` or `<select>` element.
|
335
333
|
|
336
|
-
Throws for non-input elements. However, if the element is inside the `<label>` element that has an associated
|
337
|
-
[control](https://developer.mozilla.org/en-US/docs/Web/API/HTMLLabelElement/control), returns the value of the control.
|
334
|
+
Throws for non-input elements. However, if the element is inside the `<label>` element that has an associated [control](https://developer.mozilla.org/en-US/docs/Web/API/HTMLLabelElement/control), returns the value of the control.
|
338
335
|
|
339
336
|
## checked?
|
340
337
|
|
@@ -342,6 +339,7 @@ Throws for non-input elements. However, if the element is inside the `<label>` e
|
|
342
339
|
def checked?
|
343
340
|
```
|
344
341
|
|
342
|
+
|
345
343
|
Returns whether the element is checked. Throws if the element is not a checkbox or radio input.
|
346
344
|
|
347
345
|
## disabled?
|
@@ -350,7 +348,8 @@ Returns whether the element is checked. Throws if the element is not a checkbox
|
|
350
348
|
def disabled?
|
351
349
|
```
|
352
350
|
|
353
|
-
|
351
|
+
|
352
|
+
Returns whether the element is disabled, the opposite of [enabled](https://playwright.dev/python/docs/actionability#enabled).
|
354
353
|
|
355
354
|
## editable?
|
356
355
|
|
@@ -358,7 +357,8 @@ Returns whether the element is disabled, the opposite of [enabled](https://playw
|
|
358
357
|
def editable?
|
359
358
|
```
|
360
359
|
|
361
|
-
|
360
|
+
|
361
|
+
Returns whether the element is [editable](https://playwright.dev/python/docs/actionability#editable).
|
362
362
|
|
363
363
|
## enabled?
|
364
364
|
|
@@ -366,7 +366,8 @@ Returns whether the element is [editable](https://playwright.dev/python/docs/act
|
|
366
366
|
def enabled?
|
367
367
|
```
|
368
368
|
|
369
|
-
|
369
|
+
|
370
|
+
Returns whether the element is [enabled](https://playwright.dev/python/docs/actionability#enabled).
|
370
371
|
|
371
372
|
## hidden?
|
372
373
|
|
@@ -374,7 +375,8 @@ Returns whether the element is [enabled](https://playwright.dev/python/docs/acti
|
|
374
375
|
def hidden?
|
375
376
|
```
|
376
377
|
|
377
|
-
|
378
|
+
|
379
|
+
Returns whether the element is hidden, the opposite of [visible](https://playwright.dev/python/docs/actionability#visible).
|
378
380
|
|
379
381
|
## visible?
|
380
382
|
|
@@ -382,7 +384,8 @@ Returns whether the element is hidden, the opposite of [visible](https://playwri
|
|
382
384
|
def visible?
|
383
385
|
```
|
384
386
|
|
385
|
-
|
387
|
+
|
388
|
+
Returns whether the element is [visible](https://playwright.dev/python/docs/actionability#visible).
|
386
389
|
|
387
390
|
## owner_frame
|
388
391
|
|
@@ -390,6 +393,7 @@ Returns whether the element is [visible](https://playwright.dev/python/docs/acti
|
|
390
393
|
def owner_frame
|
391
394
|
```
|
392
395
|
|
396
|
+
|
393
397
|
Returns the frame containing the given element.
|
394
398
|
|
395
399
|
## press
|
@@ -398,10 +402,12 @@ Returns the frame containing the given element.
|
|
398
402
|
def press(key, delay: nil, noWaitAfter: nil, timeout: nil)
|
399
403
|
```
|
400
404
|
|
405
|
+
|
401
406
|
Focuses the element, and then uses [Keyboard#down](./keyboard#down) and [Keyboard#up](./keyboard#up).
|
402
407
|
|
403
|
-
`key` can specify the intended
|
404
|
-
value or a single character to
|
408
|
+
`key` can specify the intended
|
409
|
+
[keyboardEvent.key](https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/key) value or a single character to
|
410
|
+
generate the text for. A superset of the `key` values can be found
|
405
411
|
[here](https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/key/Key_Values). Examples of the keys are:
|
406
412
|
|
407
413
|
`F1` - `F12`, `Digit0`- `Digit9`, `KeyA`- `KeyZ`, `Backquote`, `Minus`, `Equal`, `Backslash`, `Backspace`, `Tab`,
|
@@ -411,8 +417,8 @@ Following modification shortcuts are also supported: `Shift`, `Control`, `Alt`,
|
|
411
417
|
|
412
418
|
Holding down `Shift` will type the text that corresponds to the `key` in the upper case.
|
413
419
|
|
414
|
-
If `key` is a single character, it is case-sensitive, so the values `a` and `A` will generate different
|
415
|
-
texts.
|
420
|
+
If `key` is a single character, it is case-sensitive, so the values `a` and `A` will generate different
|
421
|
+
respective texts.
|
416
422
|
|
417
423
|
Shortcuts such as `key: "Control+o"` or `key: "Control+Shift+T"` are supported as well. When specified with the
|
418
424
|
modifier, modifier is pressed and being held while the subsequent key is being pressed.
|
@@ -423,8 +429,9 @@ modifier, modifier is pressed and being held while the subsequent key is being p
|
|
423
429
|
def query_selector(selector)
|
424
430
|
```
|
425
431
|
|
426
|
-
|
427
|
-
|
432
|
+
|
433
|
+
The method finds an element matching the specified selector in the [ElementHandle](./element_handle)'s subtree. If no elements match the selector,
|
434
|
+
returns `null`.
|
428
435
|
|
429
436
|
## query_selector_all
|
430
437
|
|
@@ -432,8 +439,9 @@ The method finds an element matching the specified selector in the [ElementHandl
|
|
432
439
|
def query_selector_all(selector)
|
433
440
|
```
|
434
441
|
|
435
|
-
|
436
|
-
|
442
|
+
|
443
|
+
The method finds all elements matching the specified selector in the [ElementHandle](./element_handle)s subtree. If no elements match the selector,
|
444
|
+
returns empty array.
|
437
445
|
|
438
446
|
## screenshot
|
439
447
|
|
@@ -450,9 +458,8 @@ def screenshot(
|
|
450
458
|
type: nil)
|
451
459
|
```
|
452
460
|
|
453
|
-
|
454
|
-
element is covered by other elements, it will not be actually visible on the screenshot. If the element is a scrollable
|
455
|
-
container, only the currently scrolled content will be visible on the screenshot.
|
461
|
+
|
462
|
+
This method captures a screenshot of the page, clipped to the size and position of this particular element. If the element is covered by other elements, it will not be actually visible on the screenshot. If the element is a scrollable container, only the currently scrolled content will be visible on the screenshot.
|
456
463
|
|
457
464
|
This method waits for the [actionability](https://playwright.dev/python/docs/actionability) checks, then scrolls element into view before taking a
|
458
465
|
screenshot. If the element is detached from DOM, the method throws an error.
|
@@ -465,6 +472,7 @@ Returns the buffer with the captured screenshot.
|
|
465
472
|
def scroll_into_view_if_needed(timeout: nil)
|
466
473
|
```
|
467
474
|
|
475
|
+
|
468
476
|
This method waits for [actionability](https://playwright.dev/python/docs/actionability) checks, then tries to scroll element into view, unless it is
|
469
477
|
completely visible as defined by
|
470
478
|
[IntersectionObserver](https://developer.mozilla.org/en-US/docs/Web/API/Intersection_Observer_API)'s `ratio`.
|
@@ -485,17 +493,17 @@ def select_option(
|
|
485
493
|
timeout: nil)
|
486
494
|
```
|
487
495
|
|
488
|
-
This method waits for [actionability](https://playwright.dev/python/docs/actionability) checks, waits until all specified options are present in the
|
489
|
-
`<select>` element and selects these options.
|
490
496
|
|
491
|
-
|
492
|
-
|
493
|
-
[control](https://developer.mozilla.org/en-US/docs/Web/API/HTMLLabelElement/control), the control will be used instead.
|
497
|
+
This method waits for [actionability](https://playwright.dev/python/docs/actionability) checks, waits until all specified options are present in the `<select>` element and selects these options.
|
498
|
+
|
499
|
+
If the target element is not a `<select>` element, this method throws an error. However, if the element is inside the `<label>` element that has an associated [control](https://developer.mozilla.org/en-US/docs/Web/API/HTMLLabelElement/control), the control will be used instead.
|
494
500
|
|
495
501
|
Returns the array of option values that have been successfully selected.
|
496
502
|
|
497
503
|
Triggers a `change` and `input` event once all the provided options have been selected.
|
498
504
|
|
505
|
+
**Usage**
|
506
|
+
|
499
507
|
```ruby
|
500
508
|
# single selection matching the value
|
501
509
|
element_handle.select_option(value: "blue")
|
@@ -505,20 +513,17 @@ element_handle.select_option(label: "blue")
|
|
505
513
|
element_handle.select_option(value: ["red", "green", "blue"])
|
506
514
|
```
|
507
515
|
|
508
|
-
|
509
|
-
|
510
516
|
## select_text
|
511
517
|
|
512
518
|
```
|
513
519
|
def select_text(force: nil, timeout: nil)
|
514
520
|
```
|
515
521
|
|
522
|
+
|
516
523
|
This method waits for [actionability](https://playwright.dev/python/docs/actionability) checks, then focuses the element and selects all its text
|
517
524
|
content.
|
518
525
|
|
519
|
-
If the element is inside the `<label>` element that has an associated
|
520
|
-
[control](https://developer.mozilla.org/en-US/docs/Web/API/HTMLLabelElement/control), focuses and selects text in the
|
521
|
-
control instead.
|
526
|
+
If the element is inside the `<label>` element that has an associated [control](https://developer.mozilla.org/en-US/docs/Web/API/HTMLLabelElement/control), focuses and selects text in the control instead.
|
522
527
|
|
523
528
|
## set_checked
|
524
529
|
|
@@ -533,18 +538,18 @@ def set_checked(
|
|
533
538
|
```
|
534
539
|
alias: `checked=`
|
535
540
|
|
541
|
+
|
536
542
|
This method checks or unchecks an element by performing the following steps:
|
537
543
|
1. Ensure that element is a checkbox or a radio input. If not, this method throws.
|
538
544
|
1. If the element already has the right checked state, this method returns immediately.
|
539
|
-
1. Wait for [actionability](https://playwright.dev/python/docs/actionability) checks on the matched element, unless `force` option is set. If the
|
540
|
-
element is detached during the checks, the whole action is retried.
|
545
|
+
1. Wait for [actionability](https://playwright.dev/python/docs/actionability) checks on the matched element, unless `force` option is set. If the element is detached during the checks, the whole action is retried.
|
541
546
|
1. Scroll the element into view if needed.
|
542
547
|
1. Use [Page#mouse](./page#mouse) to click in the center of the element.
|
543
548
|
1. Wait for initiated navigations to either succeed or fail, unless `noWaitAfter` option is set.
|
544
549
|
1. Ensure that the element is now checked or unchecked. If not, this method throws.
|
545
550
|
|
546
|
-
When all steps combined have not finished during the specified `timeout`, this method throws a
|
547
|
-
zero timeout disables this.
|
551
|
+
When all steps combined have not finished during the specified `timeout`, this method throws a
|
552
|
+
`TimeoutError`. Passing zero timeout disables this.
|
548
553
|
|
549
554
|
## set_input_files
|
550
555
|
|
@@ -553,13 +558,12 @@ def set_input_files(files, noWaitAfter: nil, timeout: nil)
|
|
553
558
|
```
|
554
559
|
alias: `input_files=`
|
555
560
|
|
561
|
+
|
556
562
|
Sets the value of the file input to these file paths or files. If some of the `filePaths` are relative paths, then they
|
557
563
|
are resolved relative to the current working directory. For empty array, clears the selected files.
|
558
564
|
|
559
565
|
This method expects [ElementHandle](./element_handle) to point to an
|
560
|
-
[input element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input). However, if the element is inside the
|
561
|
-
`<label>` element that has an associated
|
562
|
-
[control](https://developer.mozilla.org/en-US/docs/Web/API/HTMLLabelElement/control), targets the control instead.
|
566
|
+
[input element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input). However, if the element is inside the `<label>` element that has an associated [control](https://developer.mozilla.org/en-US/docs/Web/API/HTMLLabelElement/control), targets the control instead.
|
563
567
|
|
564
568
|
## tap_point
|
565
569
|
|
@@ -573,6 +577,7 @@ def tap_point(
|
|
573
577
|
trial: nil)
|
574
578
|
```
|
575
579
|
|
580
|
+
|
576
581
|
This method taps the element by performing the following steps:
|
577
582
|
1. Wait for [actionability](https://playwright.dev/python/docs/actionability) checks on the element, unless `force` option is set.
|
578
583
|
1. Scroll the element into view if needed.
|
@@ -581,10 +586,10 @@ This method taps the element by performing the following steps:
|
|
581
586
|
|
582
587
|
If the element is detached from the DOM at any moment during the action, this method throws.
|
583
588
|
|
584
|
-
When all steps combined have not finished during the specified `timeout`, this method throws a
|
585
|
-
zero timeout disables this.
|
589
|
+
When all steps combined have not finished during the specified `timeout`, this method throws a
|
590
|
+
`TimeoutError`. Passing zero timeout disables this.
|
586
591
|
|
587
|
-
|
592
|
+
**NOTE**: `elementHandle.tap()` requires that the `hasTouch` option of the browser context be set to true.
|
588
593
|
|
589
594
|
## text_content
|
590
595
|
|
@@ -592,6 +597,7 @@ zero timeout disables this.
|
|
592
597
|
def text_content
|
593
598
|
```
|
594
599
|
|
600
|
+
|
595
601
|
Returns the `node.textContent`.
|
596
602
|
|
597
603
|
## type
|
@@ -600,10 +606,13 @@ Returns the `node.textContent`.
|
|
600
606
|
def type(text, delay: nil, noWaitAfter: nil, timeout: nil)
|
601
607
|
```
|
602
608
|
|
609
|
+
|
603
610
|
Focuses the element, and then sends a `keydown`, `keypress`/`input`, and `keyup` event for each character in the text.
|
604
611
|
|
605
612
|
To press a special key, like `Control` or `ArrowDown`, use [ElementHandle#press](./element_handle#press).
|
606
613
|
|
614
|
+
**Usage**
|
615
|
+
|
607
616
|
```ruby
|
608
617
|
element_handle.type("hello") # types instantly
|
609
618
|
element_handle.type("world", delay: 100) # types slower, like a user
|
@@ -617,8 +626,6 @@ element_handle.type("some text")
|
|
617
626
|
element_handle.press("Enter")
|
618
627
|
```
|
619
628
|
|
620
|
-
|
621
|
-
|
622
629
|
## uncheck
|
623
630
|
|
624
631
|
```
|
@@ -630,9 +637,9 @@ def uncheck(
|
|
630
637
|
trial: nil)
|
631
638
|
```
|
632
639
|
|
640
|
+
|
633
641
|
This method checks the element by performing the following steps:
|
634
|
-
1. Ensure that element is a checkbox or a radio input. If not, this method throws. If the element is already
|
635
|
-
unchecked, this method returns immediately.
|
642
|
+
1. Ensure that element is a checkbox or a radio input. If not, this method throws. If the element is already unchecked, this method returns immediately.
|
636
643
|
1. Wait for [actionability](https://playwright.dev/python/docs/actionability) checks on the element, unless `force` option is set.
|
637
644
|
1. Scroll the element into view if needed.
|
638
645
|
1. Use [Page#mouse](./page#mouse) to click in the center of the element.
|
@@ -641,8 +648,8 @@ This method checks the element by performing the following steps:
|
|
641
648
|
|
642
649
|
If the element is detached from the DOM at any moment during the action, this method throws.
|
643
650
|
|
644
|
-
When all steps combined have not finished during the specified `timeout`, this method throws a
|
645
|
-
zero timeout disables this.
|
651
|
+
When all steps combined have not finished during the specified `timeout`, this method throws a
|
652
|
+
`TimeoutError`. Passing zero timeout disables this.
|
646
653
|
|
647
654
|
## wait_for_element_state
|
648
655
|
|
@@ -650,18 +657,17 @@ zero timeout disables this.
|
|
650
657
|
def wait_for_element_state(state, timeout: nil)
|
651
658
|
```
|
652
659
|
|
660
|
+
|
653
661
|
Returns when the element satisfies the `state`.
|
654
662
|
|
655
|
-
Depending on the `state` parameter, this method waits for one of the [actionability](https://playwright.dev/python/docs/actionability) checks
|
656
|
-
pass. This method throws when the element is detached while waiting, unless waiting for the `"hidden"` state.
|
657
|
-
- `"visible"` Wait until the element is [visible](https://playwright.dev/python/docs/actionability).
|
658
|
-
- `"hidden"` Wait until the element is [not visible](https://playwright.dev/python/docs/actionability) or
|
659
|
-
|
660
|
-
- `"
|
661
|
-
|
662
|
-
- `"
|
663
|
-
- `"disabled"` Wait until the element is [not enabled](https://playwright.dev/python/docs/actionability).
|
664
|
-
- `"editable"` Wait until the element is [editable](https://playwright.dev/python/docs/actionability).
|
663
|
+
Depending on the `state` parameter, this method waits for one of the [actionability](https://playwright.dev/python/docs/actionability) checks
|
664
|
+
to pass. This method throws when the element is detached while waiting, unless waiting for the `"hidden"` state.
|
665
|
+
- `"visible"` Wait until the element is [visible](https://playwright.dev/python/docs/actionability#visible).
|
666
|
+
- `"hidden"` Wait until the element is [not visible](https://playwright.dev/python/docs/actionability#visible) or [not attached](https://playwright.dev/python/docs/actionability#attached). Note that waiting for hidden does not throw when the element detaches.
|
667
|
+
- `"stable"` Wait until the element is both [visible](https://playwright.dev/python/docs/actionability#visible) and [stable](https://playwright.dev/python/docs/actionability#stable).
|
668
|
+
- `"enabled"` Wait until the element is [enabled](https://playwright.dev/python/docs/actionability#enabled).
|
669
|
+
- `"disabled"` Wait until the element is [not enabled](https://playwright.dev/python/docs/actionability#enabled).
|
670
|
+
- `"editable"` Wait until the element is [editable](https://playwright.dev/python/docs/actionability#editable).
|
665
671
|
|
666
672
|
If the element does not satisfy the condition for the `timeout` milliseconds, this method will throw.
|
667
673
|
|
@@ -671,13 +677,16 @@ If the element does not satisfy the condition for the `timeout` milliseconds, th
|
|
671
677
|
def wait_for_selector(selector, state: nil, strict: nil, timeout: nil)
|
672
678
|
```
|
673
679
|
|
674
|
-
Returns element specified by selector when it satisfies `state` option. Returns `null` if waiting for `hidden` or
|
675
|
-
`detached`.
|
676
680
|
|
677
|
-
|
678
|
-
|
679
|
-
|
680
|
-
|
681
|
+
Returns element specified by selector when it satisfies `state` option. Returns `null` if waiting for `hidden`
|
682
|
+
or `detached`.
|
683
|
+
|
684
|
+
Wait for the `selector` relative to the element handle to satisfy `state` option (either
|
685
|
+
appear/disappear from dom, or become visible/hidden). If at the moment of calling the method `selector` already
|
686
|
+
satisfies the condition, the method will return immediately. If the selector doesn't satisfy the condition for the
|
687
|
+
`timeout` milliseconds, the function will throw.
|
688
|
+
|
689
|
+
**Usage**
|
681
690
|
|
682
691
|
```ruby
|
683
692
|
page.content = "<div><span></span></div>"
|
@@ -686,4 +695,4 @@ div = page.query_selector("div")
|
|
686
695
|
span = div.wait_for_selector("span", state: "attached")
|
687
696
|
```
|
688
697
|
|
689
|
-
|
698
|
+
**NOTE**: This method does not work across navigations, use [Page#wait_for_selector](./page#wait_for_selector) instead.
|