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
@@ -4,15 +4,14 @@ sidebar_position: 10
|
|
4
4
|
|
5
5
|
# Frame
|
6
6
|
|
7
|
+
|
7
8
|
At every point of time, page exposes its current frame tree via the [Page#main_frame](./page#main_frame) and
|
8
9
|
[Frame#child_frames](./frame#child_frames) methods.
|
9
10
|
|
10
11
|
[Frame](./frame) object's lifecycle is controlled by three events, dispatched on the page object:
|
11
|
-
- [`event: Page.frameAttached`] - fired when the frame gets attached to the page. A Frame can be attached to the page
|
12
|
-
only once.
|
12
|
+
- [`event: Page.frameAttached`] - fired when the frame gets attached to the page. A Frame can be attached to the page only once.
|
13
13
|
- [`event: Page.frameNavigated`] - fired when the frame commits navigation to a different URL.
|
14
|
-
- [`event: Page.frameDetached`] - fired when the frame gets detached from the page. A Frame can be detached from the
|
15
|
-
page only once.
|
14
|
+
- [`event: Page.frameDetached`] - fired when the frame gets detached from the page. A Frame can be detached from the page only once.
|
16
15
|
|
17
16
|
An example of dumping frame tree:
|
18
17
|
|
@@ -28,14 +27,13 @@ page.goto("https://www.theverge.com")
|
|
28
27
|
dump_frame_tree(page.main_frame)
|
29
28
|
```
|
30
29
|
|
31
|
-
|
32
|
-
|
33
30
|
## add_script_tag
|
34
31
|
|
35
32
|
```
|
36
33
|
def add_script_tag(content: nil, path: nil, type: nil, url: nil)
|
37
34
|
```
|
38
35
|
|
36
|
+
|
39
37
|
Returns the added tag when the script's onload fires or when the script content was injected into frame.
|
40
38
|
|
41
39
|
Adds a `<script>` tag into the page with the desired url or content.
|
@@ -46,6 +44,7 @@ Adds a `<script>` tag into the page with the desired url or content.
|
|
46
44
|
def add_style_tag(content: nil, path: nil, url: nil)
|
47
45
|
```
|
48
46
|
|
47
|
+
|
49
48
|
Returns the added tag when the stylesheet's onload fires or when the CSS content was injected into frame.
|
50
49
|
|
51
50
|
Adds a `<link rel="stylesheet">` tag into the page with the desired url or a `<style type="text/css">` tag with the
|
@@ -64,19 +63,18 @@ def check(
|
|
64
63
|
trial: nil)
|
65
64
|
```
|
66
65
|
|
66
|
+
|
67
67
|
This method checks an element matching `selector` by performing the following steps:
|
68
68
|
1. Find an element matching `selector`. If there is none, wait until a matching element is attached to the DOM.
|
69
|
-
1. Ensure that matched element is a checkbox or a radio input. If not, this method throws. If the element is already
|
70
|
-
|
71
|
-
1. Wait for [actionability](https://playwright.dev/python/docs/actionability) checks on the matched element, unless `force` option is set. If the
|
72
|
-
element is detached during the checks, the whole action is retried.
|
69
|
+
1. Ensure that matched element is a checkbox or a radio input. If not, this method throws. If the element is already checked, this method returns immediately.
|
70
|
+
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.
|
73
71
|
1. Scroll the element into view if needed.
|
74
72
|
1. Use [Page#mouse](./page#mouse) to click in the center of the element.
|
75
73
|
1. Wait for initiated navigations to either succeed or fail, unless `noWaitAfter` option is set.
|
76
74
|
1. Ensure that the element is now checked. If not, this method throws.
|
77
75
|
|
78
|
-
When all steps combined have not finished during the specified `timeout`, this method throws a
|
79
|
-
zero timeout disables this.
|
76
|
+
When all steps combined have not finished during the specified `timeout`, this method throws a
|
77
|
+
`TimeoutError`. Passing zero timeout disables this.
|
80
78
|
|
81
79
|
## child_frames
|
82
80
|
|
@@ -103,16 +101,16 @@ def click(
|
|
103
101
|
trial: nil)
|
104
102
|
```
|
105
103
|
|
104
|
+
|
106
105
|
This method clicks an element matching `selector` by performing the following steps:
|
107
106
|
1. Find an element matching `selector`. If there is none, wait until a matching element is attached to the DOM.
|
108
|
-
1. Wait for [actionability](https://playwright.dev/python/docs/actionability) checks on the matched element, unless `force` option is set. If the
|
109
|
-
element is detached during the checks, the whole action is retried.
|
107
|
+
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.
|
110
108
|
1. Scroll the element into view if needed.
|
111
109
|
1. Use [Page#mouse](./page#mouse) to click in the center of the element, or the specified `position`.
|
112
110
|
1. Wait for initiated navigations to either succeed or fail, unless `noWaitAfter` option is set.
|
113
111
|
|
114
|
-
When all steps combined have not finished during the specified `timeout`, this method throws a
|
115
|
-
zero timeout disables this.
|
112
|
+
When all steps combined have not finished during the specified `timeout`, this method throws a
|
113
|
+
`TimeoutError`. Passing zero timeout disables this.
|
116
114
|
|
117
115
|
## content
|
118
116
|
|
@@ -120,6 +118,7 @@ zero timeout disables this.
|
|
120
118
|
def content
|
121
119
|
```
|
122
120
|
|
121
|
+
|
123
122
|
Gets the full HTML contents of the frame, including the doctype.
|
124
123
|
|
125
124
|
## dblclick
|
@@ -138,19 +137,18 @@ def dblclick(
|
|
138
137
|
trial: nil)
|
139
138
|
```
|
140
139
|
|
140
|
+
|
141
141
|
This method double clicks an element matching `selector` by performing the following steps:
|
142
142
|
1. Find an element matching `selector`. If there is none, wait until a matching element is attached to the DOM.
|
143
|
-
1. Wait for [actionability](https://playwright.dev/python/docs/actionability) checks on the matched element, unless `force` option is set. If the
|
144
|
-
element is detached during the checks, the whole action is retried.
|
143
|
+
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.
|
145
144
|
1. Scroll the element into view if needed.
|
146
145
|
1. Use [Page#mouse](./page#mouse) to double click in the center of the element, or the specified `position`.
|
147
|
-
1. Wait for initiated navigations to either succeed or fail, unless `noWaitAfter` option is set. Note that if the
|
148
|
-
first click of the `dblclick()` triggers a navigation event, this method will throw.
|
146
|
+
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.
|
149
147
|
|
150
|
-
When all steps combined have not finished during the specified `timeout`, this method throws a
|
151
|
-
zero timeout disables this.
|
148
|
+
When all steps combined have not finished during the specified `timeout`, this method throws a
|
149
|
+
`TimeoutError`. Passing zero timeout disables this.
|
152
150
|
|
153
|
-
|
151
|
+
**NOTE**: `frame.dblclick()` dispatches two `click` events and a single `dblclick` event.
|
154
152
|
|
155
153
|
## dispatch_event
|
156
154
|
|
@@ -163,18 +161,23 @@ def dispatch_event(
|
|
163
161
|
timeout: nil)
|
164
162
|
```
|
165
163
|
|
166
|
-
|
167
|
-
`click`
|
164
|
+
|
165
|
+
The snippet below dispatches the `click` event on the element. Regardless of the visibility state of the element, `click`
|
166
|
+
is dispatched. This is equivalent to calling
|
168
167
|
[element.click()](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/click).
|
169
168
|
|
169
|
+
**Usage**
|
170
|
+
|
170
171
|
```ruby
|
171
172
|
frame.dispatch_event("button#submit", "click")
|
172
173
|
```
|
173
174
|
|
174
|
-
Under the hood, it creates an instance of an event based on the given `type`, initializes it with
|
175
|
-
and dispatches it on the element. Events are `composed`, `cancelable` and bubble by
|
175
|
+
Under the hood, it creates an instance of an event based on the given `type`, initializes it with
|
176
|
+
`eventInit` properties and dispatches it on the element. Events are `composed`, `cancelable` and bubble by
|
177
|
+
default.
|
176
178
|
|
177
|
-
Since `eventInit` is event-specific, please refer to the events documentation for the lists of initial
|
179
|
+
Since `eventInit` is event-specific, please refer to the events documentation for the lists of initial
|
180
|
+
properties:
|
178
181
|
- [DragEvent](https://developer.mozilla.org/en-US/docs/Web/API/DragEvent/DragEvent)
|
179
182
|
- [FocusEvent](https://developer.mozilla.org/en-US/docs/Web/API/FocusEvent/FocusEvent)
|
180
183
|
- [KeyboardEvent](https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/KeyboardEvent)
|
@@ -191,8 +194,6 @@ data_transfer = frame.evaluate_handle("new DataTransfer()")
|
|
191
194
|
frame.dispatch_event("#source", "dragstart", eventInit: { dataTransfer: data_transfer })
|
192
195
|
```
|
193
196
|
|
194
|
-
|
195
|
-
|
196
197
|
## drag_and_drop
|
197
198
|
|
198
199
|
```
|
@@ -216,19 +217,17 @@ def drag_and_drop(
|
|
216
217
|
def eval_on_selector(selector, expression, arg: nil, strict: nil)
|
217
218
|
```
|
218
219
|
|
219
|
-
Returns the return value of `expression`.
|
220
220
|
|
221
|
-
|
222
|
-
tests. Use [Locator#evaluate](./locator#evaluate), other [Locator](./locator) helper methods or web-first assertions instead.
|
221
|
+
Returns the return value of `expression`.
|
223
222
|
|
224
223
|
The method finds an element matching the specified selector within the frame and passes it as a first argument to
|
225
|
-
`expression`.
|
226
|
-
method throws an error.
|
224
|
+
`expression`. If no
|
225
|
+
elements match the selector, the method throws an error.
|
227
226
|
|
228
|
-
If `expression` returns a [Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise), then [Frame#eval_on_selector](./frame#eval_on_selector) would wait for the promise to resolve and
|
229
|
-
|
227
|
+
If `expression` returns a [Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise), then [Frame#eval_on_selector](./frame#eval_on_selector) would wait for the promise to resolve and return its
|
228
|
+
value.
|
230
229
|
|
231
|
-
|
230
|
+
**Usage**
|
232
231
|
|
233
232
|
```ruby
|
234
233
|
search_value = frame.eval_on_selector("#search", "el => el.value")
|
@@ -236,47 +235,44 @@ preload_href = frame.eval_on_selector("link[rel=preload]", "el => el.href")
|
|
236
235
|
html = frame.eval_on_selector(".main-container", "(e, suffix) => e.outerHTML + suffix", arg: "hello")
|
237
236
|
```
|
238
237
|
|
239
|
-
|
240
|
-
|
241
238
|
## eval_on_selector_all
|
242
239
|
|
243
240
|
```
|
244
241
|
def eval_on_selector_all(selector, expression, arg: nil)
|
245
242
|
```
|
246
243
|
|
247
|
-
Returns the return value of `expression`.
|
248
244
|
|
249
|
-
|
250
|
-
better job.
|
245
|
+
Returns the return value of `expression`.
|
251
246
|
|
252
247
|
The method finds all elements matching the specified selector within the frame and passes an array of matched elements
|
253
|
-
as a first argument to `expression`.
|
248
|
+
as a first argument to `expression`.
|
254
249
|
|
255
|
-
If `expression` returns a [Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise), then [Frame#eval_on_selector_all](./frame#eval_on_selector_all) would wait for the promise to resolve and
|
256
|
-
|
250
|
+
If `expression` returns a [Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise), then [Frame#eval_on_selector_all](./frame#eval_on_selector_all) would wait for the promise to resolve and return its
|
251
|
+
value.
|
257
252
|
|
258
|
-
|
253
|
+
**Usage**
|
259
254
|
|
260
255
|
```ruby
|
261
256
|
divs_counts = frame.eval_on_selector_all("div", "(divs, min) => divs.length >= min", arg: 10)
|
262
257
|
```
|
263
258
|
|
264
|
-
|
265
|
-
|
266
259
|
## evaluate
|
267
260
|
|
268
261
|
```
|
269
262
|
def evaluate(expression, arg: nil)
|
270
263
|
```
|
271
264
|
|
265
|
+
|
272
266
|
Returns the return value of `expression`.
|
273
267
|
|
274
|
-
If the function passed to the [Frame#evaluate](./frame#evaluate) returns a [Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise), then [Frame#evaluate](./frame#evaluate) would wait
|
275
|
-
|
268
|
+
If the function passed to the [Frame#evaluate](./frame#evaluate) returns a [Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise), then [Frame#evaluate](./frame#evaluate) would wait for the promise to
|
269
|
+
resolve and return its value.
|
276
270
|
|
277
271
|
If the function passed to the [Frame#evaluate](./frame#evaluate) returns a non-[Serializable](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify#description) value, then
|
278
|
-
[Frame#evaluate](./frame#evaluate) returns `undefined`. Playwright also supports transferring some
|
279
|
-
not serializable by `JSON`: `-0`, `NaN`, `Infinity`, `-Infinity`.
|
272
|
+
[Frame#evaluate](./frame#evaluate) returns `undefined`. Playwright also supports transferring some
|
273
|
+
additional values that are not serializable by `JSON`: `-0`, `NaN`, `Infinity`, `-Infinity`.
|
274
|
+
|
275
|
+
**Usage**
|
280
276
|
|
281
277
|
```ruby
|
282
278
|
result = frame.evaluate("([x, y]) => Promise.resolve(x * y)", arg: [7, 8])
|
@@ -299,14 +295,13 @@ html = frame.evaluate("([body, suffix]) => body.innerHTML + suffix", arg: [body_
|
|
299
295
|
body_handle.dispose
|
300
296
|
```
|
301
297
|
|
302
|
-
|
303
|
-
|
304
298
|
## evaluate_handle
|
305
299
|
|
306
300
|
```
|
307
301
|
def evaluate_handle(expression, arg: nil)
|
308
302
|
```
|
309
303
|
|
304
|
+
|
310
305
|
Returns the return value of `expression` as a [JSHandle](./js_handle).
|
311
306
|
|
312
307
|
The only difference between [Frame#evaluate](./frame#evaluate) and [Frame#evaluate_handle](./frame#evaluate_handle) is that
|
@@ -315,6 +310,8 @@ The only difference between [Frame#evaluate](./frame#evaluate) and [Frame#evalua
|
|
315
310
|
If the function, passed to the [Frame#evaluate_handle](./frame#evaluate_handle), returns a [Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise), then
|
316
311
|
[Frame#evaluate_handle](./frame#evaluate_handle) would wait for the promise to resolve and return its value.
|
317
312
|
|
313
|
+
**Usage**
|
314
|
+
|
318
315
|
```ruby
|
319
316
|
a_window_handle = frame.evaluate_handle("Promise.resolve(window)")
|
320
317
|
a_window_handle # handle for the window object.
|
@@ -335,8 +332,6 @@ puts result_handle.json_value
|
|
335
332
|
result_handle.dispose
|
336
333
|
```
|
337
334
|
|
338
|
-
|
339
|
-
|
340
335
|
## fill
|
341
336
|
|
342
337
|
```
|
@@ -349,14 +344,10 @@ def fill(
|
|
349
344
|
timeout: nil)
|
350
345
|
```
|
351
346
|
|
352
|
-
This method waits for an element matching `selector`, waits for [actionability](https://playwright.dev/python/docs/actionability) checks, focuses the
|
353
|
-
element, fills it and triggers an `input` event after filling. Note that you can pass an empty string to clear the input
|
354
|
-
field.
|
355
347
|
|
356
|
-
|
357
|
-
|
358
|
-
[control](https://developer.mozilla.org/en-US/docs/Web/API/HTMLLabelElement/control), the control will be filled
|
359
|
-
instead.
|
348
|
+
This method waits for an element matching `selector`, 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.
|
349
|
+
|
350
|
+
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.
|
360
351
|
|
361
352
|
To send fine-grained keyboard events, use [Frame#type](./frame#type).
|
362
353
|
|
@@ -366,8 +357,9 @@ To send fine-grained keyboard events, use [Frame#type](./frame#type).
|
|
366
357
|
def focus(selector, strict: nil, timeout: nil)
|
367
358
|
```
|
368
359
|
|
369
|
-
|
370
|
-
|
360
|
+
|
361
|
+
This method fetches an element with `selector` and focuses it. If there's no element matching
|
362
|
+
`selector`, the method waits until a matching element appears in the DOM.
|
371
363
|
|
372
364
|
## frame_element
|
373
365
|
|
@@ -375,6 +367,7 @@ waits until a matching element appears in the DOM.
|
|
375
367
|
def frame_element
|
376
368
|
```
|
377
369
|
|
370
|
+
|
378
371
|
Returns the `frame` or `iframe` element handle which corresponds to this frame.
|
379
372
|
|
380
373
|
This is an inverse of [ElementHandle#content_frame](./element_handle#content_frame). Note that returned handle actually belongs to the parent
|
@@ -382,37 +375,40 @@ frame.
|
|
382
375
|
|
383
376
|
This method throws an error if the frame has been detached before `frameElement()` returns.
|
384
377
|
|
378
|
+
**Usage**
|
379
|
+
|
385
380
|
```ruby
|
386
381
|
frame_element = frame.frame_element
|
387
382
|
content_frame = frame_element.content_frame
|
388
383
|
puts frame == content_frame # => true
|
389
384
|
```
|
390
385
|
|
391
|
-
|
392
|
-
|
393
386
|
## frame_locator
|
394
387
|
|
395
388
|
```
|
396
389
|
def frame_locator(selector)
|
397
390
|
```
|
398
391
|
|
399
|
-
|
400
|
-
|
401
|
-
|
392
|
+
|
393
|
+
When working with iframes, you can create a frame locator that will enter the iframe and allow selecting elements
|
394
|
+
in that iframe.
|
395
|
+
|
396
|
+
**Usage**
|
397
|
+
|
398
|
+
Following snippet locates element with text "Submit" in the iframe with id `my-frame`, like `<iframe id="my-frame">`:
|
402
399
|
|
403
400
|
```ruby
|
404
401
|
locator = frame.frame_locator("#my-iframe").get_by_text("Submit")
|
405
402
|
locator.click
|
406
403
|
```
|
407
404
|
|
408
|
-
|
409
|
-
|
410
405
|
## get_attribute
|
411
406
|
|
412
407
|
```
|
413
408
|
def get_attribute(selector, name, strict: nil, timeout: nil)
|
414
409
|
```
|
415
410
|
|
411
|
+
|
416
412
|
Returns element attribute value.
|
417
413
|
|
418
414
|
## get_by_alt_text
|
@@ -421,42 +417,40 @@ Returns element attribute value.
|
|
421
417
|
def get_by_alt_text(text, exact: nil)
|
422
418
|
```
|
423
419
|
|
420
|
+
|
424
421
|
Allows locating elements by their alt text. For example, this method will find the image by alt text "Castle":
|
425
422
|
|
426
423
|
```html
|
427
424
|
<img alt='Castle'>
|
428
425
|
```
|
429
426
|
|
430
|
-
|
431
427
|
## get_by_label
|
432
428
|
|
433
429
|
```
|
434
430
|
def get_by_label(text, exact: nil)
|
435
431
|
```
|
436
432
|
|
437
|
-
|
438
|
-
label text "Password" in the following DOM:
|
433
|
+
|
434
|
+
Allows locating input elements by the text of the associated label. For example, this method will find the input by label text "Password" in the following DOM:
|
439
435
|
|
440
436
|
```html
|
441
437
|
<label for="password-input">Password:</label>
|
442
438
|
<input id="password-input">
|
443
439
|
```
|
444
440
|
|
445
|
-
|
446
441
|
## get_by_placeholder
|
447
442
|
|
448
443
|
```
|
449
444
|
def get_by_placeholder(text, exact: nil)
|
450
445
|
```
|
451
446
|
|
452
|
-
|
453
|
-
"Country":
|
447
|
+
|
448
|
+
Allows locating input elements by the placeholder text. For example, this method will find the input by placeholder "Country":
|
454
449
|
|
455
450
|
```html
|
456
451
|
<input placeholder="Country">
|
457
452
|
```
|
458
453
|
|
459
|
-
|
460
454
|
## get_by_role
|
461
455
|
|
462
456
|
```
|
@@ -473,15 +467,10 @@ def get_by_role(
|
|
473
467
|
selected: nil)
|
474
468
|
```
|
475
469
|
|
476
|
-
Allows locating elements by their [ARIA role](https://www.w3.org/TR/wai-aria-1.2/#roles),
|
477
|
-
[ARIA attributes](https://www.w3.org/TR/wai-aria-1.2/#aria-attributes) and
|
478
|
-
[accessible name](https://w3c.github.io/accname/#dfn-accessible-name). Note that role selector **does not replace**
|
479
|
-
accessibility audits and conformance tests, but rather gives early feedback about the ARIA guidelines.
|
480
470
|
|
481
|
-
Note that
|
482
|
-
|
483
|
-
can find all the [supported roles here](https://www.w3.org/TR/wai-aria-1.2/#role_definitions). ARIA guidelines **do not
|
484
|
-
recommend** duplicating implicit roles and attributes by setting `role` and/or `aria-*` attributes to default values.
|
471
|
+
Allows locating elements by their [ARIA role](https://www.w3.org/TR/wai-aria-1.2/#roles), [ARIA attributes](https://www.w3.org/TR/wai-aria-1.2/#aria-attributes) and [accessible name](https://w3c.github.io/accname/#dfn-accessible-name). Note that role selector **does not replace** accessibility audits and conformance tests, but rather gives early feedback about the ARIA guidelines.
|
472
|
+
|
473
|
+
Note that many html elements have an implicitly [defined role](https://w3c.github.io/html-aam/#html-element-role-mappings) that is recognized by the role selector. You can find all the [supported roles here](https://www.w3.org/TR/wai-aria-1.2/#role_definitions). ARIA guidelines **do not recommend** duplicating implicit roles and attributes by setting `role` and/or `aria-*` attributes to default values.
|
485
474
|
|
486
475
|
## get_by_test_id
|
487
476
|
|
@@ -489,10 +478,8 @@ recommend** duplicating implicit roles and attributes by setting `role` and/or `
|
|
489
478
|
def get_by_test_id(testId)
|
490
479
|
```
|
491
480
|
|
492
|
-
Locate element by the test id. By default, the `data-testid` attribute is used as a test id. Use
|
493
|
-
[Selectors#set_test_id_attribute](./selectors#set_test_id_attribute) to configure a different test id attribute if necessary.
|
494
|
-
|
495
481
|
|
482
|
+
Locate element by the test id. By default, the `data-testid` attribute is used as a test id. Use [Selectors#set_test_id_attribute](./selectors#set_test_id_attribute) to configure a different test id attribute if necessary.
|
496
483
|
|
497
484
|
## get_by_text
|
498
485
|
|
@@ -500,6 +487,7 @@ Locate element by the test id. By default, the `data-testid` attribute is used a
|
|
500
487
|
def get_by_text(text, exact: nil)
|
501
488
|
```
|
502
489
|
|
490
|
+
|
503
491
|
Allows locating elements that contain given text. Consider the following DOM structure:
|
504
492
|
|
505
493
|
```html
|
@@ -538,13 +526,11 @@ locator = page.get_by_text(/^hello$/i)
|
|
538
526
|
expect(locator.evaluate('e => e.outerHTML')).to eq('<div>Hello</div>')
|
539
527
|
```
|
540
528
|
|
541
|
-
See also [Locator#filter](./locator#filter) that allows to match by another criteria, like an accessible role, and then filter
|
542
|
-
|
529
|
+
See also [Locator#filter](./locator#filter) that allows to match by another criteria, like an accessible role, and then filter by the text content.
|
530
|
+
|
531
|
+
**NOTE**: Matching by text always normalizes whitespace, even with exact match. For example, it turns multiple spaces into one, turns line breaks into spaces and ignores leading and trailing whitespace.
|
543
532
|
|
544
|
-
|
545
|
-
one, turns line breaks into spaces and ignores leading and trailing whitespace.
|
546
|
-
> NOTE: Input elements of the type `button` and `submit` are matched by their `value` instead of the text content. For
|
547
|
-
example, locating by text `"Log in"` matches `<input type=button value="Log in">`.
|
533
|
+
**NOTE**: Input elements of the type `button` and `submit` are matched by their `value` instead of the text content. For example, locating by text `"Log in"` matches `<input type=button value="Log in">`.
|
548
534
|
|
549
535
|
## get_by_title
|
550
536
|
|
@@ -552,19 +538,20 @@ example, locating by text `"Log in"` matches `<input type=button value="Log in">
|
|
552
538
|
def get_by_title(text, exact: nil)
|
553
539
|
```
|
554
540
|
|
541
|
+
|
555
542
|
Allows locating elements by their title. For example, this method will find the button by its title "Place the order":
|
556
543
|
|
557
544
|
```html
|
558
545
|
<button title='Place the order'>Order Now</button>
|
559
546
|
```
|
560
547
|
|
561
|
-
|
562
548
|
## goto
|
563
549
|
|
564
550
|
```
|
565
551
|
def goto(url, referer: nil, timeout: nil, waitUntil: nil)
|
566
552
|
```
|
567
553
|
|
554
|
+
|
568
555
|
Returns the main resource response. In case of multiple redirects, the navigation will resolve with the response of the
|
569
556
|
last redirect.
|
570
557
|
|
@@ -575,13 +562,14 @@ The method will throw an error if:
|
|
575
562
|
- the remote server does not respond or is unreachable.
|
576
563
|
- the main resource failed to load.
|
577
564
|
|
578
|
-
The method will not throw an error when any valid HTTP status code is returned by the remote server, including 404
|
579
|
-
Found" and 500 "Internal Server Error". The status code for such responses can be retrieved by calling
|
565
|
+
The method will not throw an error when any valid HTTP status code is returned by the remote server, including 404
|
566
|
+
"Not Found" and 500 "Internal Server Error". The status code for such responses can be retrieved by calling
|
580
567
|
[Response#status](./response#status).
|
581
568
|
|
582
|
-
|
569
|
+
**NOTE**: The method either throws an error or returns a main resource response. The only exceptions are navigation to
|
583
570
|
`about:blank` or navigation to the same URL with a different hash, which would succeed and return `null`.
|
584
|
-
|
571
|
+
|
572
|
+
**NOTE**: Headless mode doesn't support navigation to a PDF document. See the
|
585
573
|
[upstream issue](https://bugs.chromium.org/p/chromium/issues/detail?id=761295).
|
586
574
|
|
587
575
|
## hover
|
@@ -598,16 +586,16 @@ def hover(
|
|
598
586
|
trial: nil)
|
599
587
|
```
|
600
588
|
|
589
|
+
|
601
590
|
This method hovers over an element matching `selector` by performing the following steps:
|
602
591
|
1. Find an element matching `selector`. If there is none, wait until a matching element is attached to the DOM.
|
603
|
-
1. Wait for [actionability](https://playwright.dev/python/docs/actionability) checks on the matched element, unless `force` option is set. If the
|
604
|
-
element is detached during the checks, the whole action is retried.
|
592
|
+
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.
|
605
593
|
1. Scroll the element into view if needed.
|
606
594
|
1. Use [Page#mouse](./page#mouse) to hover over the center of the element, or the specified `position`.
|
607
595
|
1. Wait for initiated navigations to either succeed or fail, unless `noWaitAfter` option is set.
|
608
596
|
|
609
|
-
When all steps combined have not finished during the specified `timeout`, this method throws a
|
610
|
-
zero timeout disables this.
|
597
|
+
When all steps combined have not finished during the specified `timeout`, this method throws a
|
598
|
+
`TimeoutError`. Passing zero timeout disables this.
|
611
599
|
|
612
600
|
## inner_html
|
613
601
|
|
@@ -615,6 +603,7 @@ zero timeout disables this.
|
|
615
603
|
def inner_html(selector, strict: nil, timeout: nil)
|
616
604
|
```
|
617
605
|
|
606
|
+
|
618
607
|
Returns `element.innerHTML`.
|
619
608
|
|
620
609
|
## inner_text
|
@@ -623,6 +612,7 @@ Returns `element.innerHTML`.
|
|
623
612
|
def inner_text(selector, strict: nil, timeout: nil)
|
624
613
|
```
|
625
614
|
|
615
|
+
|
626
616
|
Returns `element.innerText`.
|
627
617
|
|
628
618
|
## input_value
|
@@ -631,10 +621,10 @@ Returns `element.innerText`.
|
|
631
621
|
def input_value(selector, strict: nil, timeout: nil)
|
632
622
|
```
|
633
623
|
|
624
|
+
|
634
625
|
Returns `input.value` for the selected `<input>` or `<textarea>` or `<select>` element.
|
635
626
|
|
636
|
-
Throws for non-input elements. However, if the element is inside the `<label>` element that has an associated
|
637
|
-
[control](https://developer.mozilla.org/en-US/docs/Web/API/HTMLLabelElement/control), returns the value of the control.
|
627
|
+
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.
|
638
628
|
|
639
629
|
## checked?
|
640
630
|
|
@@ -642,6 +632,7 @@ Throws for non-input elements. However, if the element is inside the `<label>` e
|
|
642
632
|
def checked?(selector, strict: nil, timeout: nil)
|
643
633
|
```
|
644
634
|
|
635
|
+
|
645
636
|
Returns whether the element is checked. Throws if the element is not a checkbox or radio input.
|
646
637
|
|
647
638
|
## detached?
|
@@ -650,6 +641,7 @@ Returns whether the element is checked. Throws if the element is not a checkbox
|
|
650
641
|
def detached?
|
651
642
|
```
|
652
643
|
|
644
|
+
|
653
645
|
Returns `true` if the frame has been detached, or `false` otherwise.
|
654
646
|
|
655
647
|
## disabled?
|
@@ -658,7 +650,8 @@ Returns `true` if the frame has been detached, or `false` otherwise.
|
|
658
650
|
def disabled?(selector, strict: nil, timeout: nil)
|
659
651
|
```
|
660
652
|
|
661
|
-
|
653
|
+
|
654
|
+
Returns whether the element is disabled, the opposite of [enabled](https://playwright.dev/python/docs/actionability#enabled).
|
662
655
|
|
663
656
|
## editable?
|
664
657
|
|
@@ -666,7 +659,8 @@ Returns whether the element is disabled, the opposite of [enabled](https://playw
|
|
666
659
|
def editable?(selector, strict: nil, timeout: nil)
|
667
660
|
```
|
668
661
|
|
669
|
-
|
662
|
+
|
663
|
+
Returns whether the element is [editable](https://playwright.dev/python/docs/actionability#editable).
|
670
664
|
|
671
665
|
## enabled?
|
672
666
|
|
@@ -674,7 +668,8 @@ Returns whether the element is [editable](https://playwright.dev/python/docs/act
|
|
674
668
|
def enabled?(selector, strict: nil, timeout: nil)
|
675
669
|
```
|
676
670
|
|
677
|
-
|
671
|
+
|
672
|
+
Returns whether the element is [enabled](https://playwright.dev/python/docs/actionability#enabled).
|
678
673
|
|
679
674
|
## hidden?
|
680
675
|
|
@@ -682,8 +677,8 @@ Returns whether the element is [enabled](https://playwright.dev/python/docs/acti
|
|
682
677
|
def hidden?(selector, strict: nil, timeout: nil)
|
683
678
|
```
|
684
679
|
|
685
|
-
|
686
|
-
match any elements is considered hidden.
|
680
|
+
|
681
|
+
Returns whether the element is hidden, the opposite of [visible](https://playwright.dev/python/docs/actionability#visible). `selector` that does not match any elements is considered hidden.
|
687
682
|
|
688
683
|
## visible?
|
689
684
|
|
@@ -691,8 +686,8 @@ match any elements is considered hidden.
|
|
691
686
|
def visible?(selector, strict: nil, timeout: nil)
|
692
687
|
```
|
693
688
|
|
694
|
-
|
695
|
-
considered not visible.
|
689
|
+
|
690
|
+
Returns whether the element is [visible](https://playwright.dev/python/docs/actionability#visible). `selector` that does not match any elements is considered not visible.
|
696
691
|
|
697
692
|
## locator
|
698
693
|
|
@@ -700,9 +695,9 @@ considered not visible.
|
|
700
695
|
def locator(selector, has: nil, hasText: nil)
|
701
696
|
```
|
702
697
|
|
703
|
-
|
704
|
-
|
705
|
-
on different DOM elements. That would happen if the DOM structure between those actions has changed.
|
698
|
+
|
699
|
+
The method returns an element locator that can be used to perform actions on this page / frame.
|
700
|
+
Locator is resolved to the element immediately before performing an action, so a series of actions on the same locator can in fact be performed on different DOM elements. That would happen if the DOM structure between those actions has changed.
|
706
701
|
|
707
702
|
[Learn more about locators](https://playwright.dev/python/docs/locators).
|
708
703
|
|
@@ -714,11 +709,12 @@ on different DOM elements. That would happen if the DOM structure between those
|
|
714
709
|
def name
|
715
710
|
```
|
716
711
|
|
712
|
+
|
717
713
|
Returns frame's name attribute as specified in the tag.
|
718
714
|
|
719
715
|
If the name is empty, returns the id attribute instead.
|
720
716
|
|
721
|
-
|
717
|
+
**NOTE**: This value is calculated once when the frame is created, and will not update if the attribute is changed later.
|
722
718
|
|
723
719
|
## page
|
724
720
|
|
@@ -726,6 +722,7 @@ If the name is empty, returns the id attribute instead.
|
|
726
722
|
def page
|
727
723
|
```
|
728
724
|
|
725
|
+
|
729
726
|
Returns the page containing this frame.
|
730
727
|
|
731
728
|
## parent_frame
|
@@ -734,6 +731,7 @@ Returns the page containing this frame.
|
|
734
731
|
def parent_frame
|
735
732
|
```
|
736
733
|
|
734
|
+
|
737
735
|
Parent frame, if any. Detached frames and main frames return `null`.
|
738
736
|
|
739
737
|
## press
|
@@ -748,8 +746,10 @@ def press(
|
|
748
746
|
timeout: nil)
|
749
747
|
```
|
750
748
|
|
751
|
-
|
752
|
-
|
749
|
+
|
750
|
+
`key` can specify the intended
|
751
|
+
[keyboardEvent.key](https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/key) value or a single character to
|
752
|
+
generate the text for. A superset of the `key` values can be found
|
753
753
|
[here](https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/key/Key_Values). Examples of the keys are:
|
754
754
|
|
755
755
|
`F1` - `F12`, `Digit0`- `Digit9`, `KeyA`- `KeyZ`, `Backquote`, `Minus`, `Equal`, `Backslash`, `Backspace`, `Tab`,
|
@@ -759,8 +759,8 @@ Following modification shortcuts are also supported: `Shift`, `Control`, `Alt`,
|
|
759
759
|
|
760
760
|
Holding down `Shift` will type the text that corresponds to the `key` in the upper case.
|
761
761
|
|
762
|
-
If `key` is a single character, it is case-sensitive, so the values `a` and `A` will generate different
|
763
|
-
texts.
|
762
|
+
If `key` is a single character, it is case-sensitive, so the values `a` and `A` will generate different
|
763
|
+
respective texts.
|
764
764
|
|
765
765
|
Shortcuts such as `key: "Control+o"` or `key: "Control+Shift+T"` are supported as well. When specified with the
|
766
766
|
modifier, modifier is pressed and being held while the subsequent key is being pressed.
|
@@ -771,12 +771,13 @@ modifier, modifier is pressed and being held while the subsequent key is being p
|
|
771
771
|
def query_selector(selector, strict: nil)
|
772
772
|
```
|
773
773
|
|
774
|
+
|
774
775
|
Returns the ElementHandle pointing to the frame element.
|
775
776
|
|
776
|
-
|
777
|
+
**NOTE**: The use of [ElementHandle](./element_handle) is discouraged, use [Locator](./locator) objects and web-first assertions instead.
|
777
778
|
|
778
|
-
The method finds an element matching the specified selector within the frame.
|
779
|
-
|
779
|
+
The method finds an element matching the specified selector within the frame. If no elements match the selector,
|
780
|
+
returns `null`.
|
780
781
|
|
781
782
|
## query_selector_all
|
782
783
|
|
@@ -784,12 +785,13 @@ The method finds an element matching the specified selector within the frame. Se
|
|
784
785
|
def query_selector_all(selector)
|
785
786
|
```
|
786
787
|
|
788
|
+
|
787
789
|
Returns the ElementHandles pointing to the frame elements.
|
788
790
|
|
789
|
-
|
791
|
+
**NOTE**: The use of [ElementHandle](./element_handle) is discouraged, use [Locator](./locator) objects instead.
|
790
792
|
|
791
|
-
The method finds all elements matching the specified selector within the frame.
|
792
|
-
|
793
|
+
The method finds all elements matching the specified selector within the frame. If no elements match the selector,
|
794
|
+
returns empty array.
|
793
795
|
|
794
796
|
## select_option
|
795
797
|
|
@@ -806,17 +808,17 @@ def select_option(
|
|
806
808
|
timeout: nil)
|
807
809
|
```
|
808
810
|
|
809
|
-
This method waits for an element matching `selector`, waits for [actionability](https://playwright.dev/python/docs/actionability) checks, waits until
|
810
|
-
all specified options are present in the `<select>` element and selects these options.
|
811
811
|
|
812
|
-
|
813
|
-
|
814
|
-
[control](https://developer.mozilla.org/en-US/docs/Web/API/HTMLLabelElement/control), the control will be used instead.
|
812
|
+
This method waits for an element matching `selector`, 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.
|
813
|
+
|
814
|
+
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.
|
815
815
|
|
816
816
|
Returns the array of option values that have been successfully selected.
|
817
817
|
|
818
818
|
Triggers a `change` and `input` event once all the provided options have been selected.
|
819
819
|
|
820
|
+
**Usage**
|
821
|
+
|
820
822
|
```ruby
|
821
823
|
# single selection matching the value
|
822
824
|
frame.select_option("select#colors", value: "blue")
|
@@ -826,8 +828,6 @@ frame.select_option("select#colors", label: "blue")
|
|
826
828
|
frame.select_option("select#colors", value: ["red", "green", "blue"])
|
827
829
|
```
|
828
830
|
|
829
|
-
|
830
|
-
|
831
831
|
## set_checked
|
832
832
|
|
833
833
|
```
|
@@ -842,19 +842,19 @@ def set_checked(
|
|
842
842
|
trial: nil)
|
843
843
|
```
|
844
844
|
|
845
|
+
|
845
846
|
This method checks or unchecks an element matching `selector` by performing the following steps:
|
846
847
|
1. Find an element matching `selector`. If there is none, wait until a matching element is attached to the DOM.
|
847
848
|
1. Ensure that matched element is a checkbox or a radio input. If not, this method throws.
|
848
849
|
1. If the element already has the right checked state, this method returns immediately.
|
849
|
-
1. Wait for [actionability](https://playwright.dev/python/docs/actionability) checks on the matched element, unless `force` option is set. If the
|
850
|
-
element is detached during the checks, the whole action is retried.
|
850
|
+
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.
|
851
851
|
1. Scroll the element into view if needed.
|
852
852
|
1. Use [Page#mouse](./page#mouse) to click in the center of the element.
|
853
853
|
1. Wait for initiated navigations to either succeed or fail, unless `noWaitAfter` option is set.
|
854
854
|
1. Ensure that the element is now checked or unchecked. If not, this method throws.
|
855
855
|
|
856
|
-
When all steps combined have not finished during the specified `timeout`, this method throws a
|
857
|
-
zero timeout disables this.
|
856
|
+
When all steps combined have not finished during the specified `timeout`, this method throws a
|
857
|
+
`TimeoutError`. Passing zero timeout disables this.
|
858
858
|
|
859
859
|
## set_content
|
860
860
|
|
@@ -876,13 +876,12 @@ def set_input_files(
|
|
876
876
|
timeout: nil)
|
877
877
|
```
|
878
878
|
|
879
|
+
|
879
880
|
Sets the value of the file input to these file paths or files. If some of the `filePaths` are relative paths, then they
|
880
881
|
are resolved relative to the current working directory. For empty array, clears the selected files.
|
881
882
|
|
882
883
|
This method expects `selector` to point to an
|
883
|
-
[input element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input). However, if the element is inside the
|
884
|
-
`<label>` element that has an associated
|
885
|
-
[control](https://developer.mozilla.org/en-US/docs/Web/API/HTMLLabelElement/control), targets the control instead.
|
884
|
+
[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.
|
886
885
|
|
887
886
|
## tap_point
|
888
887
|
|
@@ -898,18 +897,18 @@ def tap_point(
|
|
898
897
|
trial: nil)
|
899
898
|
```
|
900
899
|
|
900
|
+
|
901
901
|
This method taps an element matching `selector` by performing the following steps:
|
902
902
|
1. Find an element matching `selector`. If there is none, wait until a matching element is attached to the DOM.
|
903
|
-
1. Wait for [actionability](https://playwright.dev/python/docs/actionability) checks on the matched element, unless `force` option is set. If the
|
904
|
-
element is detached during the checks, the whole action is retried.
|
903
|
+
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.
|
905
904
|
1. Scroll the element into view if needed.
|
906
905
|
1. Use [Page#touchscreen](./page#touchscreen) to tap the center of the element, or the specified `position`.
|
907
906
|
1. Wait for initiated navigations to either succeed or fail, unless `noWaitAfter` option is set.
|
908
907
|
|
909
|
-
When all steps combined have not finished during the specified `timeout`, this method throws a
|
910
|
-
zero timeout disables this.
|
908
|
+
When all steps combined have not finished during the specified `timeout`, this method throws a
|
909
|
+
`TimeoutError`. Passing zero timeout disables this.
|
911
910
|
|
912
|
-
|
911
|
+
**NOTE**: `frame.tap()` requires that the `hasTouch` option of the browser context be set to true.
|
913
912
|
|
914
913
|
## text_content
|
915
914
|
|
@@ -917,6 +916,7 @@ zero timeout disables this.
|
|
917
916
|
def text_content(selector, strict: nil, timeout: nil)
|
918
917
|
```
|
919
918
|
|
919
|
+
|
920
920
|
Returns `element.textContent`.
|
921
921
|
|
922
922
|
## title
|
@@ -925,6 +925,7 @@ Returns `element.textContent`.
|
|
925
925
|
def title
|
926
926
|
```
|
927
927
|
|
928
|
+
|
928
929
|
Returns the page title.
|
929
930
|
|
930
931
|
## type
|
@@ -939,18 +940,19 @@ def type(
|
|
939
940
|
timeout: nil)
|
940
941
|
```
|
941
942
|
|
943
|
+
|
942
944
|
Sends a `keydown`, `keypress`/`input`, and `keyup` event for each character in the text. `frame.type` can be used to
|
943
945
|
send fine-grained keyboard events. To fill values in form fields, use [Frame#fill](./frame#fill).
|
944
946
|
|
945
947
|
To press a special key, like `Control` or `ArrowDown`, use [Keyboard#press](./keyboard#press).
|
946
948
|
|
949
|
+
**Usage**
|
950
|
+
|
947
951
|
```ruby
|
948
952
|
frame.type("#mytextarea", "hello") # types instantly
|
949
953
|
frame.type("#mytextarea", "world", delay: 100) # types slower, like a user
|
950
954
|
```
|
951
955
|
|
952
|
-
|
953
|
-
|
954
956
|
## uncheck
|
955
957
|
|
956
958
|
```
|
@@ -964,19 +966,18 @@ def uncheck(
|
|
964
966
|
trial: nil)
|
965
967
|
```
|
966
968
|
|
969
|
+
|
967
970
|
This method checks an element matching `selector` by performing the following steps:
|
968
971
|
1. Find an element matching `selector`. If there is none, wait until a matching element is attached to the DOM.
|
969
|
-
1. Ensure that matched element is a checkbox or a radio input. If not, this method throws. If the element is already
|
970
|
-
|
971
|
-
1. Wait for [actionability](https://playwright.dev/python/docs/actionability) checks on the matched element, unless `force` option is set. If the
|
972
|
-
element is detached during the checks, the whole action is retried.
|
972
|
+
1. Ensure that matched element is a checkbox or a radio input. If not, this method throws. If the element is already unchecked, this method returns immediately.
|
973
|
+
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.
|
973
974
|
1. Scroll the element into view if needed.
|
974
975
|
1. Use [Page#mouse](./page#mouse) to click in the center of the element.
|
975
976
|
1. Wait for initiated navigations to either succeed or fail, unless `noWaitAfter` option is set.
|
976
977
|
1. Ensure that the element is now unchecked. If not, this method throws.
|
977
978
|
|
978
|
-
When all steps combined have not finished during the specified `timeout`, this method throws a
|
979
|
-
zero timeout disables this.
|
979
|
+
When all steps combined have not finished during the specified `timeout`, this method throws a
|
980
|
+
`TimeoutError`. Passing zero timeout disables this.
|
980
981
|
|
981
982
|
## url
|
982
983
|
|
@@ -984,6 +985,7 @@ zero timeout disables this.
|
|
984
985
|
def url
|
985
986
|
```
|
986
987
|
|
988
|
+
|
987
989
|
Returns frame's url.
|
988
990
|
|
989
991
|
## wait_for_function
|
@@ -992,8 +994,11 @@ Returns frame's url.
|
|
992
994
|
def wait_for_function(expression, arg: nil, polling: nil, timeout: nil)
|
993
995
|
```
|
994
996
|
|
997
|
+
|
995
998
|
Returns when the `expression` returns a truthy value, returns that value.
|
996
999
|
|
1000
|
+
**Usage**
|
1001
|
+
|
997
1002
|
The [Frame#wait_for_function](./frame#wait_for_function) can be used to observe viewport size change:
|
998
1003
|
|
999
1004
|
```ruby
|
@@ -1008,36 +1013,38 @@ selector = ".foo"
|
|
1008
1013
|
frame.wait_for_function("selector => !!document.querySelector(selector)", arg: selector)
|
1009
1014
|
```
|
1010
1015
|
|
1011
|
-
|
1012
|
-
|
1013
1016
|
## wait_for_load_state
|
1014
1017
|
|
1015
1018
|
```
|
1016
1019
|
def wait_for_load_state(state: nil, timeout: nil)
|
1017
1020
|
```
|
1018
1021
|
|
1022
|
+
|
1019
1023
|
Waits for the required load state to be reached.
|
1020
1024
|
|
1021
1025
|
This returns when the frame reaches a required load state, `load` by default. The navigation must have been committed
|
1022
1026
|
when this method is called. If current document has already reached the required state, resolves immediately.
|
1023
1027
|
|
1028
|
+
**Usage**
|
1029
|
+
|
1024
1030
|
```ruby
|
1025
1031
|
frame.click("button") # click triggers navigation.
|
1026
1032
|
frame.wait_for_load_state # the promise resolves after "load" event.
|
1027
1033
|
```
|
1028
1034
|
|
1029
|
-
|
1030
|
-
|
1031
1035
|
## expect_navigation
|
1032
1036
|
|
1033
1037
|
```
|
1034
1038
|
def expect_navigation(timeout: nil, url: nil, waitUntil: nil, &block)
|
1035
1039
|
```
|
1036
1040
|
|
1041
|
+
|
1037
1042
|
Waits for the frame navigation and returns the main resource response. In case of multiple redirects, the navigation
|
1038
1043
|
will resolve with the response of the last redirect. In case of navigation to a different anchor or navigation due to
|
1039
1044
|
History API usage, the navigation will resolve with `null`.
|
1040
1045
|
|
1046
|
+
**Usage**
|
1047
|
+
|
1041
1048
|
This method waits for the frame to navigate to a new URL. It is useful for when you run code which will indirectly cause
|
1042
1049
|
the frame to navigate. Consider this example:
|
1043
1050
|
|
@@ -1047,8 +1054,8 @@ frame.expect_navigation do
|
|
1047
1054
|
end # Resolves after navigation has finished
|
1048
1055
|
```
|
1049
1056
|
|
1050
|
-
|
1051
|
-
|
1057
|
+
**NOTE**: Usage of the [History API](https://developer.mozilla.org/en-US/docs/Web/API/History_API) to change the URL is considered
|
1058
|
+
a navigation.
|
1052
1059
|
|
1053
1060
|
## wait_for_selector
|
1054
1061
|
|
@@ -1056,15 +1063,19 @@ considered a navigation.
|
|
1056
1063
|
def wait_for_selector(selector, state: nil, strict: nil, timeout: nil)
|
1057
1064
|
```
|
1058
1065
|
|
1066
|
+
|
1059
1067
|
Returns when element specified by selector satisfies `state` option. Returns `null` if waiting for `hidden` or
|
1060
1068
|
`detached`.
|
1061
1069
|
|
1062
|
-
|
1063
|
-
web-first assertions make the code wait-for-selector-free.
|
1070
|
+
**NOTE**: Playwright automatically waits for element to be ready before performing an action. Using
|
1071
|
+
[Locator](./locator) objects and web-first assertions make the code wait-for-selector-free.
|
1072
|
+
|
1073
|
+
Wait for the `selector` to satisfy `state` option (either appear/disappear from dom, or become
|
1074
|
+
visible/hidden). If at the moment of calling the method `selector` already satisfies the condition, the method
|
1075
|
+
will return immediately. If the selector doesn't satisfy the condition for the `timeout` milliseconds, the
|
1076
|
+
function will throw.
|
1064
1077
|
|
1065
|
-
|
1066
|
-
the moment of calling the method `selector` already satisfies the condition, the method will return immediately. If the
|
1067
|
-
selector doesn't satisfy the condition for the `timeout` milliseconds, the function will throw.
|
1078
|
+
**Usage**
|
1068
1079
|
|
1069
1080
|
This method works across navigations:
|
1070
1081
|
|
@@ -1077,14 +1088,13 @@ This method works across navigations:
|
|
1077
1088
|
end
|
1078
1089
|
```
|
1079
1090
|
|
1080
|
-
|
1081
|
-
|
1082
1091
|
## wait_for_timeout
|
1083
1092
|
|
1084
1093
|
```
|
1085
1094
|
def wait_for_timeout(timeout)
|
1086
1095
|
```
|
1087
1096
|
|
1097
|
+
|
1088
1098
|
Waits for the given `timeout` in milliseconds.
|
1089
1099
|
|
1090
1100
|
Note that `frame.waitForTimeout()` should only be used for debugging. Tests using the timer in production are going to
|
@@ -1096,11 +1106,12 @@ be flaky. Use signals such as network events, selectors becoming visible and oth
|
|
1096
1106
|
def wait_for_url(url, timeout: nil, waitUntil: nil)
|
1097
1107
|
```
|
1098
1108
|
|
1109
|
+
|
1099
1110
|
Waits for the frame to navigate to the given URL.
|
1100
1111
|
|
1112
|
+
**Usage**
|
1113
|
+
|
1101
1114
|
```ruby
|
1102
1115
|
frame.click("a.delayed-navigation") # clicking the link will indirectly cause a navigation
|
1103
1116
|
frame.wait_for_url("**/target.html")
|
1104
1117
|
```
|
1105
|
-
|
1106
|
-
|