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
@@ -40,22 +40,22 @@ page.off('request', listener)
|
|
40
40
|
page.goto('https://example.com/') # => no print
|
41
41
|
```
|
42
42
|
|
43
|
-
|
44
|
-
|
45
43
|
## add_init_script
|
46
44
|
|
47
45
|
```
|
48
46
|
def add_init_script(path: nil, script: nil)
|
49
47
|
```
|
50
48
|
|
49
|
+
|
51
50
|
Adds a script which would be evaluated in one of the following scenarios:
|
52
51
|
- Whenever the page is navigated.
|
53
|
-
- Whenever the child frame is attached or navigated. In this case, the script is evaluated in the context of the newly
|
54
|
-
attached frame.
|
52
|
+
- Whenever the child frame is attached or navigated. In this case, the script is evaluated in the context of the newly attached frame.
|
55
53
|
|
56
54
|
The script is evaluated after the document was created but before any of its scripts were run. This is useful to amend
|
57
55
|
the JavaScript environment, e.g. to seed `Math.random`.
|
58
56
|
|
57
|
+
**Usage**
|
58
|
+
|
59
59
|
An example of overriding `Math.random` before the page loads:
|
60
60
|
|
61
61
|
```ruby
|
@@ -63,7 +63,7 @@ An example of overriding `Math.random` before the page loads:
|
|
63
63
|
page.add_init_script(path: "./preload.js")
|
64
64
|
```
|
65
65
|
|
66
|
-
|
66
|
+
**NOTE**: The order of evaluation of multiple scripts installed via [BrowserContext#add_init_script](./browser_context#add_init_script) and
|
67
67
|
[Page#add_init_script](./page#add_init_script) is not defined.
|
68
68
|
|
69
69
|
## add_script_tag
|
@@ -72,28 +72,27 @@ page.add_init_script(path: "./preload.js")
|
|
72
72
|
def add_script_tag(content: nil, path: nil, type: nil, url: nil)
|
73
73
|
```
|
74
74
|
|
75
|
+
|
75
76
|
Adds a `<script>` tag into the page with the desired url or content. Returns the added tag when the script's onload
|
76
77
|
fires or when the script content was injected into frame.
|
77
78
|
|
78
|
-
Shortcut for main frame's [Frame#add_script_tag](./frame#add_script_tag).
|
79
|
-
|
80
79
|
## add_style_tag
|
81
80
|
|
82
81
|
```
|
83
82
|
def add_style_tag(content: nil, path: nil, url: nil)
|
84
83
|
```
|
85
84
|
|
85
|
+
|
86
86
|
Adds a `<link rel="stylesheet">` tag into the page with the desired url or a `<style type="text/css">` tag with the
|
87
87
|
content. Returns the added tag when the stylesheet's onload fires or when the CSS content was injected into frame.
|
88
88
|
|
89
|
-
Shortcut for main frame's [Frame#add_style_tag](./frame#add_style_tag).
|
90
|
-
|
91
89
|
## bring_to_front
|
92
90
|
|
93
91
|
```
|
94
92
|
def bring_to_front
|
95
93
|
```
|
96
94
|
|
95
|
+
|
97
96
|
Brings page to front (activates tab).
|
98
97
|
|
99
98
|
## check
|
@@ -109,21 +108,18 @@ def check(
|
|
109
108
|
trial: nil)
|
110
109
|
```
|
111
110
|
|
111
|
+
|
112
112
|
This method checks an element matching `selector` by performing the following steps:
|
113
113
|
1. Find an element matching `selector`. If there is none, wait until a matching element is attached to the DOM.
|
114
|
-
1. Ensure that matched element is a checkbox or a radio input. If not, this method throws. If the element is already
|
115
|
-
|
116
|
-
1. Wait for [actionability](https://playwright.dev/python/docs/actionability) checks on the matched element, unless `force` option is set. If the
|
117
|
-
element is detached during the checks, the whole action is retried.
|
114
|
+
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.
|
115
|
+
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.
|
118
116
|
1. Scroll the element into view if needed.
|
119
117
|
1. Use [Page#mouse](./page#mouse) to click in the center of the element.
|
120
118
|
1. Wait for initiated navigations to either succeed or fail, unless `noWaitAfter` option is set.
|
121
119
|
1. Ensure that the element is now checked. If not, this method throws.
|
122
120
|
|
123
|
-
When all steps combined have not finished during the specified `timeout`, this method throws a
|
124
|
-
zero timeout disables this.
|
125
|
-
|
126
|
-
Shortcut for main frame's [Frame#check](./frame#check).
|
121
|
+
When all steps combined have not finished during the specified `timeout`, this method throws a
|
122
|
+
`TimeoutError`. Passing zero timeout disables this.
|
127
123
|
|
128
124
|
## click
|
129
125
|
|
@@ -142,18 +138,16 @@ def click(
|
|
142
138
|
trial: nil)
|
143
139
|
```
|
144
140
|
|
141
|
+
|
145
142
|
This method clicks an element matching `selector` by performing the following steps:
|
146
143
|
1. Find an element matching `selector`. If there is none, wait until a matching element is attached to the DOM.
|
147
|
-
1. Wait for [actionability](https://playwright.dev/python/docs/actionability) checks on the matched element, unless `force` option is set. If the
|
148
|
-
element is detached during the checks, the whole action is retried.
|
144
|
+
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.
|
149
145
|
1. Scroll the element into view if needed.
|
150
146
|
1. Use [Page#mouse](./page#mouse) to click in the center of the element, or the specified `position`.
|
151
147
|
1. Wait for initiated navigations to either succeed or fail, unless `noWaitAfter` option is set.
|
152
148
|
|
153
|
-
When all steps combined have not finished during the specified `timeout`, this method throws a
|
154
|
-
zero timeout disables this.
|
155
|
-
|
156
|
-
Shortcut for main frame's [Frame#click](./frame#click).
|
149
|
+
When all steps combined have not finished during the specified `timeout`, this method throws a
|
150
|
+
`TimeoutError`. Passing zero timeout disables this.
|
157
151
|
|
158
152
|
## close
|
159
153
|
|
@@ -161,13 +155,14 @@ Shortcut for main frame's [Frame#click](./frame#click).
|
|
161
155
|
def close(runBeforeUnload: nil)
|
162
156
|
```
|
163
157
|
|
158
|
+
|
164
159
|
If `runBeforeUnload` is `false`, does not run any unload handlers and waits for the page to be closed. If
|
165
160
|
`runBeforeUnload` is `true` the method will run unload handlers, but will **not** wait for the page to close.
|
166
161
|
|
167
162
|
By default, `page.close()` **does not** run `beforeunload` handlers.
|
168
163
|
|
169
|
-
|
170
|
-
via [`event: Page.dialog`] event.
|
164
|
+
**NOTE**: if `runBeforeUnload` is passed as true, a `beforeunload` dialog might be summoned and should be handled
|
165
|
+
manually via [`event: Page.dialog`] event.
|
171
166
|
|
172
167
|
## content
|
173
168
|
|
@@ -175,6 +170,7 @@ via [`event: Page.dialog`] event.
|
|
175
170
|
def content
|
176
171
|
```
|
177
172
|
|
173
|
+
|
178
174
|
Gets the full HTML contents of the page, including the doctype.
|
179
175
|
|
180
176
|
## context
|
@@ -183,6 +179,7 @@ Gets the full HTML contents of the page, including the doctype.
|
|
183
179
|
def context
|
184
180
|
```
|
185
181
|
|
182
|
+
|
186
183
|
Get the browser context that the page belongs to.
|
187
184
|
|
188
185
|
## dblclick
|
@@ -201,21 +198,18 @@ def dblclick(
|
|
201
198
|
trial: nil)
|
202
199
|
```
|
203
200
|
|
201
|
+
|
204
202
|
This method double clicks an element matching `selector` by performing the following steps:
|
205
203
|
1. Find an element matching `selector`. If there is none, wait until a matching element is attached to the DOM.
|
206
|
-
1. Wait for [actionability](https://playwright.dev/python/docs/actionability) checks on the matched element, unless `force` option is set. If the
|
207
|
-
element is detached during the checks, the whole action is retried.
|
204
|
+
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.
|
208
205
|
1. Scroll the element into view if needed.
|
209
206
|
1. Use [Page#mouse](./page#mouse) to double click in the center of the element, or the specified `position`.
|
210
|
-
1. Wait for initiated navigations to either succeed or fail, unless `noWaitAfter` option is set. Note that if the
|
211
|
-
first click of the `dblclick()` triggers a navigation event, this method will throw.
|
207
|
+
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.
|
212
208
|
|
213
|
-
When all steps combined have not finished during the specified `timeout`, this method throws a
|
214
|
-
zero timeout disables this.
|
209
|
+
When all steps combined have not finished during the specified `timeout`, this method throws a
|
210
|
+
`TimeoutError`. Passing zero timeout disables this.
|
215
211
|
|
216
|
-
|
217
|
-
|
218
|
-
Shortcut for main frame's [Frame#dblclick](./frame#dblclick).
|
212
|
+
**NOTE**: `page.dblclick()` dispatches two `click` events and a single `dblclick` event.
|
219
213
|
|
220
214
|
## dispatch_event
|
221
215
|
|
@@ -228,19 +222,24 @@ def dispatch_event(
|
|
228
222
|
timeout: nil)
|
229
223
|
```
|
230
224
|
|
231
|
-
|
232
|
-
`click`
|
225
|
+
|
226
|
+
The snippet below dispatches the `click` event on the element. Regardless of the visibility state of the element, `click`
|
227
|
+
is dispatched. This is equivalent to calling
|
233
228
|
[element.click()](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/click).
|
234
229
|
|
230
|
+
**Usage**
|
231
|
+
|
235
232
|
```ruby
|
236
233
|
page.content = '<button id="submit">Send</button>'
|
237
234
|
page.dispatch_event("button#submit", "click")
|
238
235
|
```
|
239
236
|
|
240
|
-
Under the hood, it creates an instance of an event based on the given `type`, initializes it with
|
241
|
-
and dispatches it on the element. Events are `composed`, `cancelable` and bubble by
|
237
|
+
Under the hood, it creates an instance of an event based on the given `type`, initializes it with
|
238
|
+
`eventInit` properties and dispatches it on the element. Events are `composed`, `cancelable` and bubble by
|
239
|
+
default.
|
242
240
|
|
243
|
-
Since `eventInit` is event-specific, please refer to the events documentation for the lists of initial
|
241
|
+
Since `eventInit` is event-specific, please refer to the events documentation for the lists of initial
|
242
|
+
properties:
|
244
243
|
- [DragEvent](https://developer.mozilla.org/en-US/docs/Web/API/DragEvent/DragEvent)
|
245
244
|
- [FocusEvent](https://developer.mozilla.org/en-US/docs/Web/API/FocusEvent/FocusEvent)
|
246
245
|
- [KeyboardEvent](https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/KeyboardEvent)
|
@@ -259,8 +258,6 @@ data_transfer = page.evaluate_handle("new DataTransfer()")
|
|
259
258
|
page.dispatch_event("#source", "dragstart", eventInit: { dataTransfer: data_transfer })
|
260
259
|
```
|
261
260
|
|
262
|
-
|
263
|
-
|
264
261
|
## drag_and_drop
|
265
262
|
|
266
263
|
```
|
@@ -276,8 +273,12 @@ def drag_and_drop(
|
|
276
273
|
trial: nil)
|
277
274
|
```
|
278
275
|
|
279
|
-
|
280
|
-
|
276
|
+
|
277
|
+
This method drags the source element to the target element.
|
278
|
+
It will first move to the source element, perform a `mousedown`,
|
279
|
+
then move to the target element and perform a `mouseup`.
|
280
|
+
|
281
|
+
**Usage**
|
281
282
|
|
282
283
|
```ruby
|
283
284
|
page.drag_and_drop("#source", "#target")
|
@@ -290,16 +291,16 @@ page.drag_and_drop(
|
|
290
291
|
)
|
291
292
|
```
|
292
293
|
|
293
|
-
|
294
|
-
|
295
294
|
## emulate_media
|
296
295
|
|
297
296
|
```
|
298
297
|
def emulate_media(colorScheme: nil, forcedColors: nil, media: nil, reducedMotion: nil)
|
299
298
|
```
|
300
299
|
|
301
|
-
|
302
|
-
feature, using the `colorScheme` argument.
|
300
|
+
|
301
|
+
This method changes the `CSS media type` through the `media` argument, and/or the `'prefers-colors-scheme'` media feature, using the `colorScheme` argument.
|
302
|
+
|
303
|
+
**Usage**
|
303
304
|
|
304
305
|
```ruby
|
305
306
|
page.evaluate("matchMedia('screen').matches") # => true
|
@@ -321,24 +322,21 @@ page.evaluate("matchMedia('(prefers-color-scheme: light)').matches") # => false
|
|
321
322
|
page.evaluate("matchMedia('(prefers-color-scheme: no-preference)').matches") # => false
|
322
323
|
```
|
323
324
|
|
324
|
-
|
325
|
-
|
326
325
|
## eval_on_selector
|
327
326
|
|
328
327
|
```
|
329
328
|
def eval_on_selector(selector, expression, arg: nil, strict: nil)
|
330
329
|
```
|
331
330
|
|
332
|
-
> NOTE: This method does not wait for the element to pass actionability checks and therefore can lead to the flaky
|
333
|
-
tests. Use [Locator#evaluate](./locator#evaluate), other [Locator](./locator) helper methods or web-first assertions instead.
|
334
331
|
|
335
332
|
The method finds an element matching the specified selector within the page and passes it as a first argument to
|
336
|
-
`expression`. If no elements match the selector, the method throws an error. Returns the value of
|
333
|
+
`expression`. If no elements match the selector, the method throws an error. Returns the value of
|
334
|
+
`expression`.
|
337
335
|
|
338
336
|
If `expression` returns a [Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise), then [Page#eval_on_selector](./page#eval_on_selector) would wait for the promise to resolve and
|
339
337
|
return its value.
|
340
338
|
|
341
|
-
|
339
|
+
**Usage**
|
342
340
|
|
343
341
|
```ruby
|
344
342
|
search_value = page.eval_on_selector("#search", "el => el.value")
|
@@ -346,16 +344,12 @@ preload_href = page.eval_on_selector("link[rel=preload]", "el => el.href")
|
|
346
344
|
html = page.eval_on_selector(".main-container", "(e, suffix) => e.outer_html + suffix", arg: "hello")
|
347
345
|
```
|
348
346
|
|
349
|
-
Shortcut for main frame's [Frame#eval_on_selector](./frame#eval_on_selector).
|
350
|
-
|
351
347
|
## eval_on_selector_all
|
352
348
|
|
353
349
|
```
|
354
350
|
def eval_on_selector_all(selector, expression, arg: nil)
|
355
351
|
```
|
356
352
|
|
357
|
-
> NOTE: In most cases, [Locator#evaluate_all](./locator#evaluate_all), other [Locator](./locator) helper methods and web-first assertions do a
|
358
|
-
better job.
|
359
353
|
|
360
354
|
The method finds all elements matching the specified selector within the page and passes an array of matched elements as
|
361
355
|
a first argument to `expression`. Returns the result of `expression` invocation.
|
@@ -363,28 +357,29 @@ a first argument to `expression`. Returns the result of `expression` invocation.
|
|
363
357
|
If `expression` returns a [Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise), then [Page#eval_on_selector_all](./page#eval_on_selector_all) would wait for the promise to resolve and
|
364
358
|
return its value.
|
365
359
|
|
366
|
-
|
360
|
+
**Usage**
|
367
361
|
|
368
362
|
```ruby
|
369
363
|
div_counts = page.eval_on_selector_all("div", "(divs, min) => divs.length >= min", arg: 10)
|
370
364
|
```
|
371
365
|
|
372
|
-
|
373
|
-
|
374
366
|
## evaluate
|
375
367
|
|
376
368
|
```
|
377
369
|
def evaluate(expression, arg: nil)
|
378
370
|
```
|
379
371
|
|
372
|
+
|
380
373
|
Returns the value of the `expression` invocation.
|
381
374
|
|
382
375
|
If the function passed to the [Page#evaluate](./page#evaluate) returns a [Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise), then [Page#evaluate](./page#evaluate) would wait
|
383
376
|
for the promise to resolve and return its value.
|
384
377
|
|
385
378
|
If the function passed to the [Page#evaluate](./page#evaluate) returns a non-[Serializable](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify#description) value, then
|
386
|
-
[Page#evaluate](./page#evaluate) resolves to `undefined`. Playwright also supports transferring some
|
387
|
-
not serializable by `JSON`: `-0`, `NaN`, `Infinity`, `-Infinity`.
|
379
|
+
[Page#evaluate](./page#evaluate) resolves to `undefined`. Playwright also supports transferring some
|
380
|
+
additional values that are not serializable by `JSON`: `-0`, `NaN`, `Infinity`, `-Infinity`.
|
381
|
+
|
382
|
+
**Usage**
|
388
383
|
|
389
384
|
Passing argument to `expression`:
|
390
385
|
|
@@ -409,21 +404,21 @@ html = page.evaluate("([body, suffix]) => body.innerHTML + suffix", arg: [body_h
|
|
409
404
|
body_handle.dispose
|
410
405
|
```
|
411
406
|
|
412
|
-
Shortcut for main frame's [Frame#evaluate](./frame#evaluate).
|
413
|
-
|
414
407
|
## evaluate_handle
|
415
408
|
|
416
409
|
```
|
417
410
|
def evaluate_handle(expression, arg: nil)
|
418
411
|
```
|
419
412
|
|
413
|
+
|
420
414
|
Returns the value of the `expression` invocation as a [JSHandle](./js_handle).
|
421
415
|
|
422
|
-
The only difference between [Page#evaluate](./page#evaluate) and [Page#evaluate_handle](./page#evaluate_handle) is that
|
423
|
-
|
416
|
+
The only difference between [Page#evaluate](./page#evaluate) and [Page#evaluate_handle](./page#evaluate_handle) is that [Page#evaluate_handle](./page#evaluate_handle) returns [JSHandle](./js_handle).
|
417
|
+
|
418
|
+
If the function passed to the [Page#evaluate_handle](./page#evaluate_handle) returns a [Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise), then [Page#evaluate_handle](./page#evaluate_handle) would wait for the
|
419
|
+
promise to resolve and return its value.
|
424
420
|
|
425
|
-
|
426
|
-
would wait for the promise to resolve and return its value.
|
421
|
+
**Usage**
|
427
422
|
|
428
423
|
```ruby
|
429
424
|
a_window_handle = page.evaluate_handle("Promise.resolve(window)")
|
@@ -445,23 +440,25 @@ puts result_handle.json_value
|
|
445
440
|
result_handle.dispose
|
446
441
|
```
|
447
442
|
|
448
|
-
|
449
|
-
|
450
443
|
## expose_binding
|
451
444
|
|
452
445
|
```
|
453
446
|
def expose_binding(name, callback, handle: nil)
|
454
447
|
```
|
455
448
|
|
456
|
-
The method adds a function called `name` on the `window` object of every frame in this page. When called, the function
|
457
|
-
executes `callback` and returns a [Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) which resolves to the return value of `callback`. If the `callback` returns
|
458
|
-
a [Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise), it will be awaited.
|
459
449
|
|
460
|
-
The
|
450
|
+
The method adds a function called `name` on the `window` object of every frame in this page. When called, the
|
451
|
+
function executes `callback` and returns a [Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) which resolves to the return value of `callback`.
|
452
|
+
If the `callback` returns a [Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise), it will be awaited.
|
453
|
+
|
454
|
+
The first argument of the `callback` function contains information about the caller: `{ browserContext:
|
455
|
+
BrowserContext, page: Page, frame: Frame }`.
|
461
456
|
|
462
457
|
See [BrowserContext#expose_binding](./browser_context#expose_binding) for the context-wide version.
|
463
458
|
|
464
|
-
|
459
|
+
**NOTE**: Functions installed via [Page#expose_binding](./page#expose_binding) survive navigations.
|
460
|
+
|
461
|
+
**Usage**
|
465
462
|
|
466
463
|
An example of exposing page URL to all frames in a page:
|
467
464
|
|
@@ -500,22 +497,23 @@ HTML
|
|
500
497
|
page.locator('div').first.click
|
501
498
|
```
|
502
499
|
|
503
|
-
|
504
|
-
|
505
500
|
## expose_function
|
506
501
|
|
507
502
|
```
|
508
503
|
def expose_function(name, callback)
|
509
504
|
```
|
510
505
|
|
511
|
-
|
512
|
-
|
506
|
+
|
507
|
+
The method adds a function called `name` on the `window` object of every frame in the page. When called, the
|
508
|
+
function executes `callback` and returns a [Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) which resolves to the return value of `callback`.
|
513
509
|
|
514
510
|
If the `callback` returns a [Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise), it will be awaited.
|
515
511
|
|
516
512
|
See [BrowserContext#expose_function](./browser_context#expose_function) for context-wide exposed function.
|
517
513
|
|
518
|
-
|
514
|
+
**NOTE**: Functions installed via [Page#expose_function](./page#expose_function) survive navigations.
|
515
|
+
|
516
|
+
**Usage**
|
519
517
|
|
520
518
|
An example of adding a `sha256` function to the page:
|
521
519
|
|
@@ -539,8 +537,6 @@ HTML
|
|
539
537
|
page.locator("button").click
|
540
538
|
```
|
541
539
|
|
542
|
-
|
543
|
-
|
544
540
|
## fill
|
545
541
|
|
546
542
|
```
|
@@ -553,18 +549,12 @@ def fill(
|
|
553
549
|
timeout: nil)
|
554
550
|
```
|
555
551
|
|
556
|
-
This method waits for an element matching `selector`, waits for [actionability](https://playwright.dev/python/docs/actionability) checks, focuses the
|
557
|
-
element, fills it and triggers an `input` event after filling. Note that you can pass an empty string to clear the input
|
558
|
-
field.
|
559
552
|
|
560
|
-
|
561
|
-
However, if the element is inside the `<label>` element that has an associated
|
562
|
-
[control](https://developer.mozilla.org/en-US/docs/Web/API/HTMLLabelElement/control), the control will be filled
|
563
|
-
instead.
|
553
|
+
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.
|
564
554
|
|
565
|
-
|
555
|
+
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.
|
566
556
|
|
567
|
-
|
557
|
+
To send fine-grained keyboard events, use [Page#type](./page#type).
|
568
558
|
|
569
559
|
## focus
|
570
560
|
|
@@ -572,10 +562,9 @@ Shortcut for main frame's [Frame#fill](./frame#fill).
|
|
572
562
|
def focus(selector, strict: nil, timeout: nil)
|
573
563
|
```
|
574
564
|
|
575
|
-
This method fetches an element with `selector` and focuses it. If there's no element matching `selector`, the method
|
576
|
-
waits until a matching element appears in the DOM.
|
577
565
|
|
578
|
-
|
566
|
+
This method fetches an element with `selector` and focuses it. If there's no element matching
|
567
|
+
`selector`, the method waits until a matching element appears in the DOM.
|
579
568
|
|
580
569
|
## frame
|
581
570
|
|
@@ -583,8 +572,11 @@ Shortcut for main frame's [Frame#focus](./frame#focus).
|
|
583
572
|
def frame(name: nil, url: nil)
|
584
573
|
```
|
585
574
|
|
575
|
+
|
586
576
|
Returns frame matching the specified criteria. Either `name` or `url` must be specified.
|
587
577
|
|
578
|
+
**Usage**
|
579
|
+
|
588
580
|
```ruby
|
589
581
|
frame = page.frame(name: "frame-name")
|
590
582
|
```
|
@@ -593,31 +585,33 @@ frame = page.frame(name: "frame-name")
|
|
593
585
|
frame = page.frame(url: /.*domain.*/)
|
594
586
|
```
|
595
587
|
|
596
|
-
|
597
|
-
|
598
588
|
## frame_locator
|
599
589
|
|
600
590
|
```
|
601
591
|
def frame_locator(selector)
|
602
592
|
```
|
603
593
|
|
604
|
-
|
605
|
-
|
606
|
-
|
594
|
+
|
595
|
+
When working with iframes, you can create a frame locator that will enter the iframe and allow selecting elements
|
596
|
+
in that iframe.
|
597
|
+
|
598
|
+
**Usage**
|
599
|
+
|
600
|
+
Following snippet locates element with text "Submit" in the iframe with id `my-frame`,
|
601
|
+
like `<iframe id="my-frame">`:
|
607
602
|
|
608
603
|
```ruby
|
609
604
|
locator = page.frame_locator("#my-iframe").get_by_text("Submit")
|
610
605
|
locator.click
|
611
606
|
```
|
612
607
|
|
613
|
-
|
614
|
-
|
615
608
|
## frames
|
616
609
|
|
617
610
|
```
|
618
611
|
def frames
|
619
612
|
```
|
620
613
|
|
614
|
+
|
621
615
|
An array of all frames attached to the page.
|
622
616
|
|
623
617
|
## get_attribute
|
@@ -626,6 +620,7 @@ An array of all frames attached to the page.
|
|
626
620
|
def get_attribute(selector, name, strict: nil, timeout: nil)
|
627
621
|
```
|
628
622
|
|
623
|
+
|
629
624
|
Returns element attribute value.
|
630
625
|
|
631
626
|
## get_by_alt_text
|
@@ -634,42 +629,40 @@ Returns element attribute value.
|
|
634
629
|
def get_by_alt_text(text, exact: nil)
|
635
630
|
```
|
636
631
|
|
632
|
+
|
637
633
|
Allows locating elements by their alt text. For example, this method will find the image by alt text "Castle":
|
638
634
|
|
639
635
|
```html
|
640
636
|
<img alt='Castle'>
|
641
637
|
```
|
642
638
|
|
643
|
-
|
644
639
|
## get_by_label
|
645
640
|
|
646
641
|
```
|
647
642
|
def get_by_label(text, exact: nil)
|
648
643
|
```
|
649
644
|
|
650
|
-
|
651
|
-
label text "Password" in the following DOM:
|
645
|
+
|
646
|
+
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:
|
652
647
|
|
653
648
|
```html
|
654
649
|
<label for="password-input">Password:</label>
|
655
650
|
<input id="password-input">
|
656
651
|
```
|
657
652
|
|
658
|
-
|
659
653
|
## get_by_placeholder
|
660
654
|
|
661
655
|
```
|
662
656
|
def get_by_placeholder(text, exact: nil)
|
663
657
|
```
|
664
658
|
|
665
|
-
|
666
|
-
"Country":
|
659
|
+
|
660
|
+
Allows locating input elements by the placeholder text. For example, this method will find the input by placeholder "Country":
|
667
661
|
|
668
662
|
```html
|
669
663
|
<input placeholder="Country">
|
670
664
|
```
|
671
665
|
|
672
|
-
|
673
666
|
## get_by_role
|
674
667
|
|
675
668
|
```
|
@@ -686,15 +679,10 @@ def get_by_role(
|
|
686
679
|
selected: nil)
|
687
680
|
```
|
688
681
|
|
689
|
-
Allows locating elements by their [ARIA role](https://www.w3.org/TR/wai-aria-1.2/#roles),
|
690
|
-
[ARIA attributes](https://www.w3.org/TR/wai-aria-1.2/#aria-attributes) and
|
691
|
-
[accessible name](https://w3c.github.io/accname/#dfn-accessible-name). Note that role selector **does not replace**
|
692
|
-
accessibility audits and conformance tests, but rather gives early feedback about the ARIA guidelines.
|
693
682
|
|
694
|
-
Note that
|
695
|
-
|
696
|
-
can find all the [supported roles here](https://www.w3.org/TR/wai-aria-1.2/#role_definitions). ARIA guidelines **do not
|
697
|
-
recommend** duplicating implicit roles and attributes by setting `role` and/or `aria-*` attributes to default values.
|
683
|
+
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.
|
684
|
+
|
685
|
+
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.
|
698
686
|
|
699
687
|
## get_by_test_id
|
700
688
|
|
@@ -702,10 +690,8 @@ recommend** duplicating implicit roles and attributes by setting `role` and/or `
|
|
702
690
|
def get_by_test_id(testId)
|
703
691
|
```
|
704
692
|
|
705
|
-
Locate element by the test id. By default, the `data-testid` attribute is used as a test id. Use
|
706
|
-
[Selectors#set_test_id_attribute](./selectors#set_test_id_attribute) to configure a different test id attribute if necessary.
|
707
|
-
|
708
693
|
|
694
|
+
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.
|
709
695
|
|
710
696
|
## get_by_text
|
711
697
|
|
@@ -713,6 +699,7 @@ Locate element by the test id. By default, the `data-testid` attribute is used a
|
|
713
699
|
def get_by_text(text, exact: nil)
|
714
700
|
```
|
715
701
|
|
702
|
+
|
716
703
|
Allows locating elements that contain given text. Consider the following DOM structure:
|
717
704
|
|
718
705
|
```html
|
@@ -751,13 +738,11 @@ locator = page.get_by_text(/^hello$/i)
|
|
751
738
|
expect(locator.evaluate('e => e.outerHTML')).to eq('<div>Hello</div>')
|
752
739
|
```
|
753
740
|
|
754
|
-
See also [Locator#filter](./locator#filter) that allows to match by another criteria, like an accessible role, and then filter
|
755
|
-
|
741
|
+
See also [Locator#filter](./locator#filter) that allows to match by another criteria, like an accessible role, and then filter by the text content.
|
742
|
+
|
743
|
+
**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.
|
756
744
|
|
757
|
-
|
758
|
-
one, turns line breaks into spaces and ignores leading and trailing whitespace.
|
759
|
-
> NOTE: Input elements of the type `button` and `submit` are matched by their `value` instead of the text content. For
|
760
|
-
example, locating by text `"Log in"` matches `<input type=button value="Log in">`.
|
745
|
+
**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">`.
|
761
746
|
|
762
747
|
## get_by_title
|
763
748
|
|
@@ -765,19 +750,20 @@ example, locating by text `"Log in"` matches `<input type=button value="Log in">
|
|
765
750
|
def get_by_title(text, exact: nil)
|
766
751
|
```
|
767
752
|
|
753
|
+
|
768
754
|
Allows locating elements by their title. For example, this method will find the button by its title "Place the order":
|
769
755
|
|
770
756
|
```html
|
771
757
|
<button title='Place the order'>Order Now</button>
|
772
758
|
```
|
773
759
|
|
774
|
-
|
775
760
|
## go_back
|
776
761
|
|
777
762
|
```
|
778
763
|
def go_back(timeout: nil, waitUntil: nil)
|
779
764
|
```
|
780
765
|
|
766
|
+
|
781
767
|
Returns the main resource response. In case of multiple redirects, the navigation will resolve with the response of the
|
782
768
|
last redirect. If can not go back, returns `null`.
|
783
769
|
|
@@ -789,6 +775,7 @@ Navigate to the previous page in history.
|
|
789
775
|
def go_forward(timeout: nil, waitUntil: nil)
|
790
776
|
```
|
791
777
|
|
778
|
+
|
792
779
|
Returns the main resource response. In case of multiple redirects, the navigation will resolve with the response of the
|
793
780
|
last redirect. If can not go forward, returns `null`.
|
794
781
|
|
@@ -800,6 +787,7 @@ Navigate to the next page in history.
|
|
800
787
|
def goto(url, referer: nil, timeout: nil, waitUntil: nil)
|
801
788
|
```
|
802
789
|
|
790
|
+
|
803
791
|
Returns the main resource response. In case of multiple redirects, the navigation will resolve with the first
|
804
792
|
non-redirect response.
|
805
793
|
|
@@ -814,12 +802,11 @@ The method will not throw an error when any valid HTTP status code is returned b
|
|
814
802
|
Found" and 500 "Internal Server Error". The status code for such responses can be retrieved by calling
|
815
803
|
[Response#status](./response#status).
|
816
804
|
|
817
|
-
|
805
|
+
**NOTE**: The method either throws an error or returns a main resource response. The only exceptions are navigation to
|
818
806
|
`about:blank` or navigation to the same URL with a different hash, which would succeed and return `null`.
|
819
|
-
> NOTE: Headless mode doesn't support navigation to a PDF document. See the
|
820
|
-
[upstream issue](https://bugs.chromium.org/p/chromium/issues/detail?id=761295).
|
821
807
|
|
822
|
-
|
808
|
+
**NOTE**: Headless mode doesn't support navigation to a PDF document. See the
|
809
|
+
[upstream issue](https://bugs.chromium.org/p/chromium/issues/detail?id=761295).
|
823
810
|
|
824
811
|
## hover
|
825
812
|
|
@@ -835,18 +822,16 @@ def hover(
|
|
835
822
|
trial: nil)
|
836
823
|
```
|
837
824
|
|
825
|
+
|
838
826
|
This method hovers over an element matching `selector` by performing the following steps:
|
839
827
|
1. Find an element matching `selector`. If there is none, wait until a matching element is attached to the DOM.
|
840
|
-
1. Wait for [actionability](https://playwright.dev/python/docs/actionability) checks on the matched element, unless `force` option is set. If the
|
841
|
-
element is detached during the checks, the whole action is retried.
|
828
|
+
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.
|
842
829
|
1. Scroll the element into view if needed.
|
843
830
|
1. Use [Page#mouse](./page#mouse) to hover over the center of the element, or the specified `position`.
|
844
831
|
1. Wait for initiated navigations to either succeed or fail, unless `noWaitAfter` option is set.
|
845
832
|
|
846
|
-
When all steps combined have not finished during the specified `timeout`, this method throws a
|
847
|
-
zero timeout disables this.
|
848
|
-
|
849
|
-
Shortcut for main frame's [Frame#hover](./frame#hover).
|
833
|
+
When all steps combined have not finished during the specified `timeout`, this method throws a
|
834
|
+
`TimeoutError`. Passing zero timeout disables this.
|
850
835
|
|
851
836
|
## inner_html
|
852
837
|
|
@@ -854,6 +839,7 @@ Shortcut for main frame's [Frame#hover](./frame#hover).
|
|
854
839
|
def inner_html(selector, strict: nil, timeout: nil)
|
855
840
|
```
|
856
841
|
|
842
|
+
|
857
843
|
Returns `element.innerHTML`.
|
858
844
|
|
859
845
|
## inner_text
|
@@ -862,6 +848,7 @@ Returns `element.innerHTML`.
|
|
862
848
|
def inner_text(selector, strict: nil, timeout: nil)
|
863
849
|
```
|
864
850
|
|
851
|
+
|
865
852
|
Returns `element.innerText`.
|
866
853
|
|
867
854
|
## input_value
|
@@ -870,10 +857,10 @@ Returns `element.innerText`.
|
|
870
857
|
def input_value(selector, strict: nil, timeout: nil)
|
871
858
|
```
|
872
859
|
|
860
|
+
|
873
861
|
Returns `input.value` for the selected `<input>` or `<textarea>` or `<select>` element.
|
874
862
|
|
875
|
-
Throws for non-input elements. However, if the element is inside the `<label>` element that has an associated
|
876
|
-
[control](https://developer.mozilla.org/en-US/docs/Web/API/HTMLLabelElement/control), returns the value of the control.
|
863
|
+
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.
|
877
864
|
|
878
865
|
## checked?
|
879
866
|
|
@@ -881,6 +868,7 @@ Throws for non-input elements. However, if the element is inside the `<label>` e
|
|
881
868
|
def checked?(selector, strict: nil, timeout: nil)
|
882
869
|
```
|
883
870
|
|
871
|
+
|
884
872
|
Returns whether the element is checked. Throws if the element is not a checkbox or radio input.
|
885
873
|
|
886
874
|
## closed?
|
@@ -889,6 +877,7 @@ Returns whether the element is checked. Throws if the element is not a checkbox
|
|
889
877
|
def closed?
|
890
878
|
```
|
891
879
|
|
880
|
+
|
892
881
|
Indicates that the page has been closed.
|
893
882
|
|
894
883
|
## disabled?
|
@@ -897,7 +886,8 @@ Indicates that the page has been closed.
|
|
897
886
|
def disabled?(selector, strict: nil, timeout: nil)
|
898
887
|
```
|
899
888
|
|
900
|
-
|
889
|
+
|
890
|
+
Returns whether the element is disabled, the opposite of [enabled](https://playwright.dev/python/docs/actionability#enabled).
|
901
891
|
|
902
892
|
## editable?
|
903
893
|
|
@@ -905,7 +895,8 @@ Returns whether the element is disabled, the opposite of [enabled](https://playw
|
|
905
895
|
def editable?(selector, strict: nil, timeout: nil)
|
906
896
|
```
|
907
897
|
|
908
|
-
|
898
|
+
|
899
|
+
Returns whether the element is [editable](https://playwright.dev/python/docs/actionability#editable).
|
909
900
|
|
910
901
|
## enabled?
|
911
902
|
|
@@ -913,7 +904,8 @@ Returns whether the element is [editable](https://playwright.dev/python/docs/act
|
|
913
904
|
def enabled?(selector, strict: nil, timeout: nil)
|
914
905
|
```
|
915
906
|
|
916
|
-
|
907
|
+
|
908
|
+
Returns whether the element is [enabled](https://playwright.dev/python/docs/actionability#enabled).
|
917
909
|
|
918
910
|
## hidden?
|
919
911
|
|
@@ -921,8 +913,8 @@ Returns whether the element is [enabled](https://playwright.dev/python/docs/acti
|
|
921
913
|
def hidden?(selector, strict: nil, timeout: nil)
|
922
914
|
```
|
923
915
|
|
924
|
-
|
925
|
-
match any elements is considered hidden.
|
916
|
+
|
917
|
+
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.
|
926
918
|
|
927
919
|
## visible?
|
928
920
|
|
@@ -930,8 +922,8 @@ match any elements is considered hidden.
|
|
930
922
|
def visible?(selector, strict: nil, timeout: nil)
|
931
923
|
```
|
932
924
|
|
933
|
-
|
934
|
-
considered not visible.
|
925
|
+
|
926
|
+
Returns whether the element is [visible](https://playwright.dev/python/docs/actionability#visible). `selector` that does not match any elements is considered not visible.
|
935
927
|
|
936
928
|
## locator
|
937
929
|
|
@@ -939,9 +931,9 @@ considered not visible.
|
|
939
931
|
def locator(selector, has: nil, hasText: nil)
|
940
932
|
```
|
941
933
|
|
942
|
-
|
943
|
-
|
944
|
-
on different DOM elements. That would happen if the DOM structure between those actions has changed.
|
934
|
+
|
935
|
+
The method returns an element locator that can be used to perform actions on this page / frame.
|
936
|
+
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.
|
945
937
|
|
946
938
|
[Learn more about locators](https://playwright.dev/python/docs/locators).
|
947
939
|
|
@@ -951,6 +943,7 @@ on different DOM elements. That would happen if the DOM structure between those
|
|
951
943
|
def main_frame
|
952
944
|
```
|
953
945
|
|
946
|
+
|
954
947
|
The page's main frame. Page is guaranteed to have a main frame which persists during navigations.
|
955
948
|
|
956
949
|
## opener
|
@@ -959,6 +952,7 @@ The page's main frame. Page is guaranteed to have a main frame which persists du
|
|
959
952
|
def opener
|
960
953
|
```
|
961
954
|
|
955
|
+
|
962
956
|
Returns the opener for popup pages and `null` for others. If the opener has been closed already the returns `null`.
|
963
957
|
|
964
958
|
## pause
|
@@ -967,14 +961,15 @@ Returns the opener for popup pages and `null` for others. If the opener has been
|
|
967
961
|
def pause
|
968
962
|
```
|
969
963
|
|
970
|
-
|
971
|
-
|
964
|
+
|
965
|
+
Pauses script execution. Playwright will stop executing the script and wait for the user to either press 'Resume'
|
966
|
+
button in the page overlay or to call `playwright.resume()` in the DevTools console.
|
972
967
|
|
973
968
|
User can inspect selectors or perform manual steps while paused. Resume will continue running the original script from
|
974
969
|
the place it was paused.
|
975
970
|
|
976
|
-
|
977
|
-
[BrowserType#launch](./browser_type#launch).
|
971
|
+
**NOTE**: This method requires Playwright to be started in a headed mode, with a falsy `headless` value in
|
972
|
+
the [BrowserType#launch](./browser_type#launch).
|
978
973
|
|
979
974
|
## pdf
|
980
975
|
|
@@ -995,24 +990,28 @@ def pdf(
|
|
995
990
|
width: nil)
|
996
991
|
```
|
997
992
|
|
993
|
+
|
998
994
|
Returns the PDF buffer.
|
999
995
|
|
1000
|
-
|
996
|
+
**NOTE**: Generating a pdf is currently only supported in Chromium headless.
|
1001
997
|
|
1002
998
|
`page.pdf()` generates a pdf of the page with `print` css media. To generate a pdf with `screen` media, call
|
1003
999
|
[Page#emulate_media](./page#emulate_media) before calling `page.pdf()`:
|
1004
1000
|
|
1005
|
-
|
1001
|
+
**NOTE**: By default, `page.pdf()` generates a pdf with modified colors for printing. Use the
|
1006
1002
|
[`-webkit-print-color-adjust`](https://developer.mozilla.org/en-US/docs/Web/CSS/-webkit-print-color-adjust) property to
|
1007
1003
|
force rendering of exact colors.
|
1008
1004
|
|
1005
|
+
**Usage**
|
1006
|
+
|
1009
1007
|
```ruby
|
1010
1008
|
# generates a pdf with "screen" media type.
|
1011
1009
|
page.emulate_media(media: "screen")
|
1012
1010
|
page.pdf(path: "page.pdf")
|
1013
1011
|
```
|
1014
1012
|
|
1015
|
-
The `width`, `height`, and `margin` options accept values labeled with units. Unlabeled
|
1013
|
+
The `width`, `height`, and `margin` options accept values labeled with units. Unlabeled
|
1014
|
+
values are treated as pixels.
|
1016
1015
|
|
1017
1016
|
A few examples:
|
1018
1017
|
- `page.pdf({width: 100})` - prints with width set to 100 pixels
|
@@ -1038,8 +1037,8 @@ The `format` options are:
|
|
1038
1037
|
- `A5`: 5.83in x 8.27in
|
1039
1038
|
- `A6`: 4.13in x 5.83in
|
1040
1039
|
|
1041
|
-
|
1042
|
-
are not evaluated. > 2. Page styles are not visible inside templates.
|
1040
|
+
**NOTE**: `headerTemplate` and `footerTemplate` markup have the following limitations: > 1. Script tags inside
|
1041
|
+
templates are not evaluated. > 2. Page styles are not visible inside templates.
|
1043
1042
|
|
1044
1043
|
## press
|
1045
1044
|
|
@@ -1053,10 +1052,12 @@ def press(
|
|
1053
1052
|
timeout: nil)
|
1054
1053
|
```
|
1055
1054
|
|
1055
|
+
|
1056
1056
|
Focuses the element, and then uses [Keyboard#down](./keyboard#down) and [Keyboard#up](./keyboard#up).
|
1057
1057
|
|
1058
|
-
`key` can specify the intended
|
1059
|
-
value or a single character to
|
1058
|
+
`key` can specify the intended
|
1059
|
+
[keyboardEvent.key](https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/key) value or a single character to
|
1060
|
+
generate the text for. A superset of the `key` values can be found
|
1060
1061
|
[here](https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/key/Key_Values). Examples of the keys are:
|
1061
1062
|
|
1062
1063
|
`F1` - `F12`, `Digit0`- `Digit9`, `KeyA`- `KeyZ`, `Backquote`, `Minus`, `Equal`, `Backslash`, `Backspace`, `Tab`,
|
@@ -1066,12 +1067,14 @@ Following modification shortcuts are also supported: `Shift`, `Control`, `Alt`,
|
|
1066
1067
|
|
1067
1068
|
Holding down `Shift` will type the text that corresponds to the `key` in the upper case.
|
1068
1069
|
|
1069
|
-
If `key` is a single character, it is case-sensitive, so the values `a` and `A` will generate different
|
1070
|
-
texts.
|
1070
|
+
If `key` is a single character, it is case-sensitive, so the values `a` and `A` will generate different
|
1071
|
+
respective texts.
|
1071
1072
|
|
1072
1073
|
Shortcuts such as `key: "Control+o"` or `key: "Control+Shift+T"` are supported as well. When specified with the
|
1073
1074
|
modifier, modifier is pressed and being held while the subsequent key is being pressed.
|
1074
1075
|
|
1076
|
+
**Usage**
|
1077
|
+
|
1075
1078
|
```ruby
|
1076
1079
|
page.goto("https://keycode.info")
|
1077
1080
|
page.press("body", "A")
|
@@ -1082,42 +1085,36 @@ page.press("body", "Shift+O")
|
|
1082
1085
|
page.screenshot(path: "o.png")
|
1083
1086
|
```
|
1084
1087
|
|
1085
|
-
|
1086
|
-
|
1087
1088
|
## query_selector
|
1088
1089
|
|
1089
1090
|
```
|
1090
1091
|
def query_selector(selector, strict: nil)
|
1091
1092
|
```
|
1092
1093
|
|
1093
|
-
> NOTE: The use of [ElementHandle](./element_handle) is discouraged, use [Locator](./locator) objects and web-first assertions instead.
|
1094
1094
|
|
1095
1095
|
The method finds an element matching the specified selector within the page. If no elements match the selector, the
|
1096
1096
|
return value resolves to `null`. To wait for an element on the page, use [Locator#wait_for](./locator#wait_for).
|
1097
1097
|
|
1098
|
-
Shortcut for main frame's [Frame#query_selector](./frame#query_selector).
|
1099
|
-
|
1100
1098
|
## query_selector_all
|
1101
1099
|
|
1102
1100
|
```
|
1103
1101
|
def query_selector_all(selector)
|
1104
1102
|
```
|
1105
1103
|
|
1106
|
-
> NOTE: The use of [ElementHandle](./element_handle) is discouraged, use [Locator](./locator) objects and web-first assertions instead.
|
1107
1104
|
|
1108
1105
|
The method finds all elements matching the specified selector within the page. If no elements match the selector, the
|
1109
1106
|
return value resolves to `[]`.
|
1110
1107
|
|
1111
|
-
Shortcut for main frame's [Frame#query_selector_all](./frame#query_selector_all).
|
1112
|
-
|
1113
1108
|
## reload
|
1114
1109
|
|
1115
1110
|
```
|
1116
1111
|
def reload(timeout: nil, waitUntil: nil)
|
1117
1112
|
```
|
1118
1113
|
|
1119
|
-
|
1120
|
-
|
1114
|
+
|
1115
|
+
This method reloads the current page, in the same way as if the user had triggered a browser refresh.
|
1116
|
+
Returns the main resource response. In case of multiple redirects, the navigation will resolve with the response of the
|
1117
|
+
last redirect.
|
1121
1118
|
|
1122
1119
|
## route
|
1123
1120
|
|
@@ -1125,14 +1122,16 @@ resource response. In case of multiple redirects, the navigation will resolve wi
|
|
1125
1122
|
def route(url, handler, times: nil)
|
1126
1123
|
```
|
1127
1124
|
|
1125
|
+
|
1128
1126
|
Routing provides the capability to modify network requests that are made by a page.
|
1129
1127
|
|
1130
1128
|
Once routing is enabled, every request matching the url pattern will stall unless it's continued, fulfilled or aborted.
|
1131
1129
|
|
1132
|
-
|
1133
|
-
|
1134
|
-
[this](https://github.com/microsoft/playwright/issues/1090) issue. We recommend disabling Service Workers when using
|
1135
|
-
|
1130
|
+
**NOTE**: The handler will only be called for the first url if the response is a redirect.
|
1131
|
+
|
1132
|
+
**NOTE**: [Page#route](./page#route) will not intercept requests intercepted by Service Worker. See [this](https://github.com/microsoft/playwright/issues/1090) issue. We recommend disabling Service Workers when using request interception by setting `Browser.newContext.serviceWorkers` to `'block'`.
|
1133
|
+
|
1134
|
+
**Usage**
|
1136
1135
|
|
1137
1136
|
An example of a naive handler that aborts all image requests:
|
1138
1137
|
|
@@ -1148,8 +1147,7 @@ page.route(/\.(png|jpg)$/, ->(route, request) { route.abort })
|
|
1148
1147
|
page.goto("https://example.com")
|
1149
1148
|
```
|
1150
1149
|
|
1151
|
-
It is possible to examine the request to decide the route action. For example, mocking all requests that contain some
|
1152
|
-
post data, and leaving all other requests as is:
|
1150
|
+
It is possible to examine the request to decide the route action. For example, mocking all requests that contain some post data, and leaving all other requests as is:
|
1153
1151
|
|
1154
1152
|
```ruby
|
1155
1153
|
def handle_route(route, request)
|
@@ -1168,7 +1166,7 @@ matches both handlers.
|
|
1168
1166
|
|
1169
1167
|
To remove a route with its handler you can use [Page#unroute](./page#unroute).
|
1170
1168
|
|
1171
|
-
|
1169
|
+
**NOTE**: Enabling routing disables http cache.
|
1172
1170
|
|
1173
1171
|
## route_from_har
|
1174
1172
|
|
@@ -1176,12 +1174,10 @@ To remove a route with its handler you can use [Page#unroute](./page#unroute).
|
|
1176
1174
|
def route_from_har(har, notFound: nil, update: nil, url: nil)
|
1177
1175
|
```
|
1178
1176
|
|
1179
|
-
If specified the network requests that are made in the page will be served from the HAR file. Read more about
|
1180
|
-
[Replaying from HAR](https://playwright.dev/python/docs/network).
|
1181
1177
|
|
1182
|
-
|
1183
|
-
|
1184
|
-
request interception by setting `Browser.newContext.serviceWorkers` to `'block'`.
|
1178
|
+
If specified the network requests that are made in the page will be served from the HAR file. Read more about [Replaying from HAR](https://playwright.dev/python/docs/network#replaying-from-har).
|
1179
|
+
|
1180
|
+
Playwright will not serve requests intercepted by Service Worker from the HAR file. See [this](https://github.com/microsoft/playwright/issues/1090) issue. We recommend disabling Service Workers when using request interception by setting `Browser.newContext.serviceWorkers` to `'block'`.
|
1185
1181
|
|
1186
1182
|
## screenshot
|
1187
1183
|
|
@@ -1200,6 +1196,7 @@ def screenshot(
|
|
1200
1196
|
type: nil)
|
1201
1197
|
```
|
1202
1198
|
|
1199
|
+
|
1203
1200
|
Returns the buffer with the captured screenshot.
|
1204
1201
|
|
1205
1202
|
## select_option
|
@@ -1217,17 +1214,17 @@ def select_option(
|
|
1217
1214
|
timeout: nil)
|
1218
1215
|
```
|
1219
1216
|
|
1220
|
-
This method waits for an element matching `selector`, waits for [actionability](https://playwright.dev/python/docs/actionability) checks, waits until
|
1221
|
-
all specified options are present in the `<select>` element and selects these options.
|
1222
1217
|
|
1223
|
-
|
1224
|
-
|
1225
|
-
[control](https://developer.mozilla.org/en-US/docs/Web/API/HTMLLabelElement/control), the control will be used instead.
|
1218
|
+
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.
|
1219
|
+
|
1220
|
+
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.
|
1226
1221
|
|
1227
1222
|
Returns the array of option values that have been successfully selected.
|
1228
1223
|
|
1229
1224
|
Triggers a `change` and `input` event once all the provided options have been selected.
|
1230
1225
|
|
1226
|
+
**Usage**
|
1227
|
+
|
1231
1228
|
```ruby
|
1232
1229
|
# single selection matching the value
|
1233
1230
|
page.select_option("select#colors", value: "blue")
|
@@ -1237,8 +1234,6 @@ page.select_option("select#colors", label: "blue")
|
|
1237
1234
|
page.select_option("select#colors", value: ["red", "green", "blue"])
|
1238
1235
|
```
|
1239
1236
|
|
1240
|
-
Shortcut for main frame's [Frame#select_option](./frame#select_option).
|
1241
|
-
|
1242
1237
|
## set_checked
|
1243
1238
|
|
1244
1239
|
```
|
@@ -1253,21 +1248,19 @@ def set_checked(
|
|
1253
1248
|
trial: nil)
|
1254
1249
|
```
|
1255
1250
|
|
1251
|
+
|
1256
1252
|
This method checks or unchecks an element matching `selector` by performing the following steps:
|
1257
1253
|
1. Find an element matching `selector`. If there is none, wait until a matching element is attached to the DOM.
|
1258
1254
|
1. Ensure that matched element is a checkbox or a radio input. If not, this method throws.
|
1259
1255
|
1. If the element already has the right checked state, this method returns immediately.
|
1260
|
-
1. Wait for [actionability](https://playwright.dev/python/docs/actionability) checks on the matched element, unless `force` option is set. If the
|
1261
|
-
element is detached during the checks, the whole action is retried.
|
1256
|
+
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.
|
1262
1257
|
1. Scroll the element into view if needed.
|
1263
1258
|
1. Use [Page#mouse](./page#mouse) to click in the center of the element.
|
1264
1259
|
1. Wait for initiated navigations to either succeed or fail, unless `noWaitAfter` option is set.
|
1265
1260
|
1. Ensure that the element is now checked or unchecked. If not, this method throws.
|
1266
1261
|
|
1267
|
-
When all steps combined have not finished during the specified `timeout`, this method throws a
|
1268
|
-
zero timeout disables this.
|
1269
|
-
|
1270
|
-
Shortcut for main frame's [Frame#set_checked](./frame#set_checked).
|
1262
|
+
When all steps combined have not finished during the specified `timeout`, this method throws a
|
1263
|
+
`TimeoutError`. Passing zero timeout disables this.
|
1271
1264
|
|
1272
1265
|
## set_content
|
1273
1266
|
|
@@ -1285,6 +1278,7 @@ def set_default_navigation_timeout(timeout)
|
|
1285
1278
|
```
|
1286
1279
|
alias: `default_navigation_timeout=`
|
1287
1280
|
|
1281
|
+
|
1288
1282
|
This setting will change the default maximum navigation time for the following methods and related shortcuts:
|
1289
1283
|
- [Page#go_back](./page#go_back)
|
1290
1284
|
- [Page#go_forward](./page#go_forward)
|
@@ -1294,7 +1288,7 @@ This setting will change the default maximum navigation time for the following m
|
|
1294
1288
|
- [Page#expect_navigation](./page#expect_navigation)
|
1295
1289
|
- [Page#wait_for_url](./page#wait_for_url)
|
1296
1290
|
|
1297
|
-
|
1291
|
+
**NOTE**: [Page#set_default_navigation_timeout](./page#set_default_navigation_timeout) takes priority over [Page#set_default_timeout](./page#set_default_timeout),
|
1298
1292
|
[BrowserContext#set_default_timeout](./browser_context#set_default_timeout) and [BrowserContext#set_default_navigation_timeout](./browser_context#set_default_navigation_timeout).
|
1299
1293
|
|
1300
1294
|
## set_default_timeout
|
@@ -1304,9 +1298,10 @@ def set_default_timeout(timeout)
|
|
1304
1298
|
```
|
1305
1299
|
alias: `default_timeout=`
|
1306
1300
|
|
1301
|
+
|
1307
1302
|
This setting will change the default maximum time for all the methods accepting `timeout` option.
|
1308
1303
|
|
1309
|
-
|
1304
|
+
**NOTE**: [Page#set_default_navigation_timeout](./page#set_default_navigation_timeout) takes priority over [Page#set_default_timeout](./page#set_default_timeout).
|
1310
1305
|
|
1311
1306
|
## set_extra_http_headers
|
1312
1307
|
|
@@ -1315,9 +1310,10 @@ def set_extra_http_headers(headers)
|
|
1315
1310
|
```
|
1316
1311
|
alias: `extra_http_headers=`
|
1317
1312
|
|
1313
|
+
|
1318
1314
|
The extra HTTP headers will be sent with every request the page initiates.
|
1319
1315
|
|
1320
|
-
|
1316
|
+
**NOTE**: [Page#set_extra_http_headers](./page#set_extra_http_headers) does not guarantee the order of headers in the outgoing requests.
|
1321
1317
|
|
1322
1318
|
## set_input_files
|
1323
1319
|
|
@@ -1330,13 +1326,12 @@ def set_input_files(
|
|
1330
1326
|
timeout: nil)
|
1331
1327
|
```
|
1332
1328
|
|
1329
|
+
|
1333
1330
|
Sets the value of the file input to these file paths or files. If some of the `filePaths` are relative paths, then they
|
1334
1331
|
are resolved relative to the current working directory. For empty array, clears the selected files.
|
1335
1332
|
|
1336
1333
|
This method expects `selector` to point to an
|
1337
|
-
[input element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input). However, if the element is inside the
|
1338
|
-
`<label>` element that has an associated
|
1339
|
-
[control](https://developer.mozilla.org/en-US/docs/Web/API/HTMLLabelElement/control), targets the control instead.
|
1334
|
+
[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.
|
1340
1335
|
|
1341
1336
|
## set_viewport_size
|
1342
1337
|
|
@@ -1345,21 +1340,20 @@ def set_viewport_size(viewportSize)
|
|
1345
1340
|
```
|
1346
1341
|
alias: `viewport_size=`
|
1347
1342
|
|
1343
|
+
|
1348
1344
|
In the case of multiple pages in a single browser, each page can have its own viewport size. However,
|
1349
1345
|
[Browser#new_context](./browser#new_context) allows to set viewport size (and more) for all pages in the context at once.
|
1350
1346
|
|
1351
|
-
[Page#set_viewport_size](./page#set_viewport_size) will resize the page. A lot of websites don't expect phones to change size, so you
|
1352
|
-
|
1353
|
-
|
1354
|
-
|
1347
|
+
[Page#set_viewport_size](./page#set_viewport_size) will resize the page. A lot of websites don't expect phones to change size, so you should set the
|
1348
|
+
viewport size before navigating to the page. [Page#set_viewport_size](./page#set_viewport_size) will also reset `screen` size, use [Browser#new_context](./browser#new_context) with `screen` and `viewport` parameters if you need better control of these properties.
|
1349
|
+
|
1350
|
+
**Usage**
|
1355
1351
|
|
1356
1352
|
```ruby
|
1357
1353
|
page.viewport_size = { width: 640, height: 480 }
|
1358
1354
|
page.goto("https://example.com")
|
1359
1355
|
```
|
1360
1356
|
|
1361
|
-
|
1362
|
-
|
1363
1357
|
## tap_point
|
1364
1358
|
|
1365
1359
|
```
|
@@ -1374,20 +1368,18 @@ def tap_point(
|
|
1374
1368
|
trial: nil)
|
1375
1369
|
```
|
1376
1370
|
|
1371
|
+
|
1377
1372
|
This method taps an element matching `selector` by performing the following steps:
|
1378
1373
|
1. Find an element matching `selector`. If there is none, wait until a matching element is attached to the DOM.
|
1379
|
-
1. Wait for [actionability](https://playwright.dev/python/docs/actionability) checks on the matched element, unless `force` option is set. If the
|
1380
|
-
element is detached during the checks, the whole action is retried.
|
1374
|
+
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.
|
1381
1375
|
1. Scroll the element into view if needed.
|
1382
1376
|
1. Use [Page#touchscreen](./page#touchscreen) to tap the center of the element, or the specified `position`.
|
1383
1377
|
1. Wait for initiated navigations to either succeed or fail, unless `noWaitAfter` option is set.
|
1384
1378
|
|
1385
|
-
When all steps combined have not finished during the specified `timeout`, this method throws a
|
1386
|
-
zero timeout disables this.
|
1379
|
+
When all steps combined have not finished during the specified `timeout`, this method throws a
|
1380
|
+
`TimeoutError`. Passing zero timeout disables this.
|
1387
1381
|
|
1388
|
-
|
1389
|
-
|
1390
|
-
Shortcut for main frame's [Frame#tap_point](./frame#tap_point).
|
1382
|
+
**NOTE**: [Page#tap_point](./page#tap_point) requires that the `hasTouch` option of the browser context be set to true.
|
1391
1383
|
|
1392
1384
|
## text_content
|
1393
1385
|
|
@@ -1395,6 +1387,7 @@ Shortcut for main frame's [Frame#tap_point](./frame#tap_point).
|
|
1395
1387
|
def text_content(selector, strict: nil, timeout: nil)
|
1396
1388
|
```
|
1397
1389
|
|
1390
|
+
|
1398
1391
|
Returns `element.textContent`.
|
1399
1392
|
|
1400
1393
|
## title
|
@@ -1403,7 +1396,8 @@ Returns `element.textContent`.
|
|
1403
1396
|
def title
|
1404
1397
|
```
|
1405
1398
|
|
1406
|
-
|
1399
|
+
|
1400
|
+
Returns the page's title.
|
1407
1401
|
|
1408
1402
|
## type
|
1409
1403
|
|
@@ -1417,18 +1411,19 @@ def type(
|
|
1417
1411
|
timeout: nil)
|
1418
1412
|
```
|
1419
1413
|
|
1414
|
+
|
1420
1415
|
Sends a `keydown`, `keypress`/`input`, and `keyup` event for each character in the text. `page.type` can be used to send
|
1421
1416
|
fine-grained keyboard events. To fill values in form fields, use [Page#fill](./page#fill).
|
1422
1417
|
|
1423
1418
|
To press a special key, like `Control` or `ArrowDown`, use [Keyboard#press](./keyboard#press).
|
1424
1419
|
|
1420
|
+
**Usage**
|
1421
|
+
|
1425
1422
|
```ruby
|
1426
1423
|
page.type("#mytextarea", "hello") # types instantly
|
1427
1424
|
page.type("#mytextarea", "world", delay: 100) # types slower, like a user
|
1428
1425
|
```
|
1429
1426
|
|
1430
|
-
Shortcut for main frame's [Frame#type](./frame#type).
|
1431
|
-
|
1432
1427
|
## uncheck
|
1433
1428
|
|
1434
1429
|
```
|
@@ -1442,21 +1437,18 @@ def uncheck(
|
|
1442
1437
|
trial: nil)
|
1443
1438
|
```
|
1444
1439
|
|
1440
|
+
|
1445
1441
|
This method unchecks an element matching `selector` by performing the following steps:
|
1446
1442
|
1. Find an element matching `selector`. If there is none, wait until a matching element is attached to the DOM.
|
1447
|
-
1. Ensure that matched element is a checkbox or a radio input. If not, this method throws. If the element is already
|
1448
|
-
|
1449
|
-
1. Wait for [actionability](https://playwright.dev/python/docs/actionability) checks on the matched element, unless `force` option is set. If the
|
1450
|
-
element is detached during the checks, the whole action is retried.
|
1443
|
+
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.
|
1444
|
+
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.
|
1451
1445
|
1. Scroll the element into view if needed.
|
1452
1446
|
1. Use [Page#mouse](./page#mouse) to click in the center of the element.
|
1453
1447
|
1. Wait for initiated navigations to either succeed or fail, unless `noWaitAfter` option is set.
|
1454
1448
|
1. Ensure that the element is now unchecked. If not, this method throws.
|
1455
1449
|
|
1456
|
-
When all steps combined have not finished during the specified `timeout`, this method throws a
|
1457
|
-
zero timeout disables this.
|
1458
|
-
|
1459
|
-
Shortcut for main frame's [Frame#uncheck](./frame#uncheck).
|
1450
|
+
When all steps combined have not finished during the specified `timeout`, this method throws a
|
1451
|
+
`TimeoutError`. Passing zero timeout disables this.
|
1460
1452
|
|
1461
1453
|
## unroute
|
1462
1454
|
|
@@ -1464,7 +1456,9 @@ Shortcut for main frame's [Frame#uncheck](./frame#uncheck).
|
|
1464
1456
|
def unroute(url, handler: nil)
|
1465
1457
|
```
|
1466
1458
|
|
1467
|
-
|
1459
|
+
|
1460
|
+
Removes a route created with [Page#route](./page#route). When `handler` is not specified, removes all routes for
|
1461
|
+
the `url`.
|
1468
1462
|
|
1469
1463
|
## url
|
1470
1464
|
|
@@ -1472,7 +1466,7 @@ Removes a route created with [Page#route](./page#route). When `handler` is not s
|
|
1472
1466
|
def url
|
1473
1467
|
```
|
1474
1468
|
|
1475
|
-
|
1469
|
+
|
1476
1470
|
|
1477
1471
|
## video
|
1478
1472
|
|
@@ -1480,6 +1474,7 @@ Shortcut for main frame's [Frame#url](./frame#url).
|
|
1480
1474
|
def video
|
1481
1475
|
```
|
1482
1476
|
|
1477
|
+
|
1483
1478
|
Video object associated with this page.
|
1484
1479
|
|
1485
1480
|
## viewport_size
|
@@ -1496,9 +1491,10 @@ def viewport_size
|
|
1496
1491
|
def expect_console_message(predicate: nil, timeout: nil, &block)
|
1497
1492
|
```
|
1498
1493
|
|
1494
|
+
|
1499
1495
|
Performs action and waits for a [ConsoleMessage](./console_message) to be logged by in the page. If predicate is provided, it passes
|
1500
|
-
[ConsoleMessage](./console_message) value into the `predicate` function and waits for `predicate(message)` to return a truthy value.
|
1501
|
-
throw an error if the page is closed before the [`event: Page.console`] event is fired.
|
1496
|
+
[ConsoleMessage](./console_message) value into the `predicate` function and waits for `predicate(message)` to return a truthy value.
|
1497
|
+
Will throw an error if the page is closed before the [`event: Page.console`] event is fired.
|
1502
1498
|
|
1503
1499
|
## expect_download
|
1504
1500
|
|
@@ -1506,9 +1502,10 @@ throw an error if the page is closed before the [`event: Page.console`] event is
|
|
1506
1502
|
def expect_download(predicate: nil, timeout: nil, &block)
|
1507
1503
|
```
|
1508
1504
|
|
1509
|
-
|
1510
|
-
|
1511
|
-
|
1505
|
+
|
1506
|
+
Performs action and waits for a new [Download](./download). If predicate is provided, it passes
|
1507
|
+
[Download](./download) value into the `predicate` function and waits for `predicate(download)` to return a truthy value.
|
1508
|
+
Will throw an error if the page is closed before the download event is fired.
|
1512
1509
|
|
1513
1510
|
## expect_event
|
1514
1511
|
|
@@ -1516,25 +1513,28 @@ closed before the download event is fired.
|
|
1516
1513
|
def expect_event(event, predicate: nil, timeout: nil, &block)
|
1517
1514
|
```
|
1518
1515
|
|
1516
|
+
|
1519
1517
|
Waits for event to fire and passes its value into the predicate function. Returns when the predicate returns truthy
|
1520
1518
|
value. Will throw an error if the page is closed before the event is fired. Returns the event data value.
|
1521
1519
|
|
1520
|
+
**Usage**
|
1521
|
+
|
1522
1522
|
```ruby
|
1523
1523
|
frame = page.expect_event("framenavigated") do
|
1524
1524
|
page.get_by_role("button")
|
1525
1525
|
end
|
1526
1526
|
```
|
1527
1527
|
|
1528
|
-
|
1529
1528
|
## expect_file_chooser
|
1530
1529
|
|
1531
1530
|
```
|
1532
1531
|
def expect_file_chooser(predicate: nil, timeout: nil, &block)
|
1533
1532
|
```
|
1534
1533
|
|
1535
|
-
|
1536
|
-
|
1537
|
-
the
|
1534
|
+
|
1535
|
+
Performs action and waits for a new [FileChooser](./file_chooser) to be created. If predicate is provided, it passes
|
1536
|
+
[FileChooser](./file_chooser) value into the `predicate` function and waits for `predicate.call(fileChooser)` to return a truthy value.
|
1537
|
+
Will throw an error if the page is closed before the file chooser is opened.
|
1538
1538
|
|
1539
1539
|
## wait_for_function
|
1540
1540
|
|
@@ -1542,8 +1542,11 @@ the page is closed before the file chooser is opened.
|
|
1542
1542
|
def wait_for_function(expression, arg: nil, polling: nil, timeout: nil)
|
1543
1543
|
```
|
1544
1544
|
|
1545
|
+
|
1545
1546
|
Returns when the `expression` returns a truthy value. It resolves to a JSHandle of the truthy value.
|
1546
1547
|
|
1548
|
+
**Usage**
|
1549
|
+
|
1547
1550
|
The [Page#wait_for_function](./page#wait_for_function) can be used to observe viewport size change:
|
1548
1551
|
|
1549
1552
|
```ruby
|
@@ -1558,19 +1561,20 @@ selector = ".foo"
|
|
1558
1561
|
page.wait_for_function("selector => !!document.querySelector(selector)", arg: selector)
|
1559
1562
|
```
|
1560
1563
|
|
1561
|
-
Shortcut for main frame's [Frame#wait_for_function](./frame#wait_for_function).
|
1562
|
-
|
1563
1564
|
## wait_for_load_state
|
1564
1565
|
|
1565
1566
|
```
|
1566
1567
|
def wait_for_load_state(state: nil, timeout: nil)
|
1567
1568
|
```
|
1568
1569
|
|
1570
|
+
|
1569
1571
|
Returns when the required load state has been reached.
|
1570
1572
|
|
1571
1573
|
This resolves when the page reaches a required load state, `load` by default. The navigation must have been committed
|
1572
1574
|
when this method is called. If current document has already reached the required state, resolves immediately.
|
1573
1575
|
|
1576
|
+
**Usage**
|
1577
|
+
|
1574
1578
|
```ruby
|
1575
1579
|
page.get_by_role("button").click # click triggers navigation.
|
1576
1580
|
page.wait_for_load_state # the promise resolves after "load" event.
|
@@ -1581,22 +1585,23 @@ popup = page.expect_popup do
|
|
1581
1585
|
page.get_by_role("button").click # click triggers a popup.
|
1582
1586
|
end
|
1583
1587
|
|
1584
|
-
#
|
1588
|
+
# Wait for the "DOMContentLoaded" event.
|
1585
1589
|
popup.wait_for_load_state("domcontentloaded")
|
1586
1590
|
puts popup.title # popup is ready to use.
|
1587
1591
|
```
|
1588
1592
|
|
1589
|
-
Shortcut for main frame's [Frame#wait_for_load_state](./frame#wait_for_load_state).
|
1590
|
-
|
1591
1593
|
## expect_navigation
|
1592
1594
|
|
1593
1595
|
```
|
1594
1596
|
def expect_navigation(timeout: nil, url: nil, waitUntil: nil, &block)
|
1595
1597
|
```
|
1596
1598
|
|
1597
|
-
|
1598
|
-
|
1599
|
-
|
1599
|
+
|
1600
|
+
Waits for the main frame navigation and returns the main resource response. In case of multiple redirects, the navigation
|
1601
|
+
will resolve with the response of the last redirect. In case of navigation to a different anchor or navigation due to
|
1602
|
+
History API usage, the navigation will resolve with `null`.
|
1603
|
+
|
1604
|
+
**Usage**
|
1600
1605
|
|
1601
1606
|
This resolves when the page navigates to a new URL or reloads. It is useful for when you run code which will indirectly
|
1602
1607
|
cause the page to navigate. e.g. The click target has an `onclick` handler that triggers navigation from a `setTimeout`.
|
@@ -1604,14 +1609,13 @@ Consider this example:
|
|
1604
1609
|
|
1605
1610
|
```ruby
|
1606
1611
|
page.expect_navigation do
|
1607
|
-
|
1612
|
+
# This action triggers the navigation after a timeout.
|
1613
|
+
page.get_by_text("Navigate after timeout").click
|
1608
1614
|
end # Resolves after navigation has finished
|
1609
1615
|
```
|
1610
1616
|
|
1611
|
-
|
1612
|
-
|
1613
|
-
|
1614
|
-
Shortcut for main frame's [Frame#expect_navigation](./frame#expect_navigation).
|
1617
|
+
**NOTE**: Usage of the [History API](https://developer.mozilla.org/en-US/docs/Web/API/History_API) to change the URL is considered
|
1618
|
+
a navigation.
|
1615
1619
|
|
1616
1620
|
## expect_popup
|
1617
1621
|
|
@@ -1619,7 +1623,10 @@ Shortcut for main frame's [Frame#expect_navigation](./frame#expect_navigation).
|
|
1619
1623
|
def expect_popup(predicate: nil, timeout: nil, &block)
|
1620
1624
|
```
|
1621
1625
|
|
1622
|
-
|
1626
|
+
|
1627
|
+
Performs action and waits for a popup [Page](./page). If predicate is provided, it passes
|
1628
|
+
[Popup] value into the `predicate` function and waits for `predicate(page)` to return a truthy value.
|
1629
|
+
Will throw an error if the page is closed before the popup event is fired.
|
1623
1630
|
|
1624
1631
|
## expect_request
|
1625
1632
|
|
@@ -1627,37 +1634,38 @@ Performs action and waits for a popup [Page](./page). If predicate is provided,
|
|
1627
1634
|
def expect_request(urlOrPredicate, timeout: nil, &block)
|
1628
1635
|
```
|
1629
1636
|
|
1630
|
-
|
1631
|
-
about events.
|
1637
|
+
|
1638
|
+
Waits for the matching request and returns it. See [waiting for event](https://playwright.dev/python/docs/events#waiting-for-event) for more details about events.
|
1639
|
+
|
1640
|
+
**Usage**
|
1632
1641
|
|
1633
1642
|
```ruby
|
1634
|
-
page.content = '<form action="https://example.com/resource"><input type="submit" /></form>'
|
1643
|
+
page.content = '<form action="https://example.com/resource"><input type="submit" value="trigger request" /></form>'
|
1635
1644
|
request = page.expect_request(/example.com\/resource/) do
|
1636
|
-
page.
|
1645
|
+
page.get_by_text("trigger request").click()
|
1637
1646
|
end
|
1638
1647
|
puts request.headers
|
1639
1648
|
|
1640
1649
|
page.wait_for_load_state # wait for request finished.
|
1641
1650
|
|
1642
1651
|
# or with a predicate
|
1643
|
-
page.content = '<form action="https://example.com/resource"><input type="submit" /></form>'
|
1652
|
+
page.content = '<form action="https://example.com/resource"><input type="submit" value="trigger request" /></form>'
|
1644
1653
|
request = page.expect_request(->(req) { req.url.start_with? 'https://example.com/resource' }) do
|
1645
|
-
page.
|
1654
|
+
page.get_by_text("trigger request").click()
|
1646
1655
|
end
|
1647
1656
|
puts request.headers
|
1648
1657
|
```
|
1649
1658
|
|
1650
|
-
|
1651
|
-
|
1652
1659
|
## expect_request_finished
|
1653
1660
|
|
1654
1661
|
```
|
1655
1662
|
def expect_request_finished(predicate: nil, timeout: nil, &block)
|
1656
1663
|
```
|
1657
1664
|
|
1658
|
-
|
1659
|
-
|
1660
|
-
|
1665
|
+
|
1666
|
+
Performs action and waits for a [Request](./request) to finish loading. If predicate is provided, it passes
|
1667
|
+
[Request](./request) value into the `predicate` function and waits for `predicate(request)` to return a truthy value.
|
1668
|
+
Will throw an error if the page is closed before the [`event: Page.requestFinished`] event is fired.
|
1661
1669
|
|
1662
1670
|
## expect_response
|
1663
1671
|
|
@@ -1665,12 +1673,15 @@ closed before the [`event: Page.requestFinished`] event is fired.
|
|
1665
1673
|
def expect_response(urlOrPredicate, timeout: nil, &block)
|
1666
1674
|
```
|
1667
1675
|
|
1668
|
-
|
1676
|
+
|
1677
|
+
Returns the matched response. See [waiting for event](https://playwright.dev/python/docs/events#waiting-for-event) for more details about events.
|
1678
|
+
|
1679
|
+
**Usage**
|
1669
1680
|
|
1670
1681
|
```ruby
|
1671
|
-
page.content = '<form action="https://example.com/resource"><input type="submit" /></form>'
|
1682
|
+
page.content = '<form action="https://example.com/resource"><input type="submit" value="trigger response" /></form>'
|
1672
1683
|
response = page.expect_response(/example.com\/resource/) do
|
1673
|
-
page.
|
1684
|
+
page.get_by_text("trigger response").click()
|
1674
1685
|
end
|
1675
1686
|
puts response.body
|
1676
1687
|
puts response.ok?
|
@@ -1678,31 +1689,33 @@ puts response.ok?
|
|
1678
1689
|
page.wait_for_load_state # wait for request finished.
|
1679
1690
|
|
1680
1691
|
# or with a predicate
|
1681
|
-
page.content = '<form action="https://example.com/resource"><input type="submit" /></form>'
|
1692
|
+
page.content = '<form action="https://example.com/resource"><input type="submit" value="trigger response" /></form>'
|
1682
1693
|
response = page.expect_response(->(res) { res.url.start_with? 'https://example.com/resource' }) do
|
1683
|
-
page.
|
1694
|
+
page.get_by_text("trigger response").click()
|
1684
1695
|
end
|
1685
1696
|
puts response.body
|
1686
1697
|
puts response.ok?
|
1687
1698
|
```
|
1688
1699
|
|
1689
|
-
|
1690
|
-
|
1691
1700
|
## wait_for_selector
|
1692
1701
|
|
1693
1702
|
```
|
1694
1703
|
def wait_for_selector(selector, state: nil, strict: nil, timeout: nil)
|
1695
1704
|
```
|
1696
1705
|
|
1706
|
+
|
1697
1707
|
Returns when element specified by selector satisfies `state` option. Returns `null` if waiting for `hidden` or
|
1698
1708
|
`detached`.
|
1699
1709
|
|
1700
|
-
|
1701
|
-
web-first assertions makes the code wait-for-selector-free.
|
1710
|
+
**NOTE**: Playwright automatically waits for element to be ready before performing an action. Using
|
1711
|
+
[Locator](./locator) objects and web-first assertions makes the code wait-for-selector-free.
|
1712
|
+
|
1713
|
+
Wait for the `selector` to satisfy `state` option (either appear/disappear from dom, or become
|
1714
|
+
visible/hidden). If at the moment of calling the method `selector` already satisfies the condition, the method
|
1715
|
+
will return immediately. If the selector doesn't satisfy the condition for the `timeout` milliseconds, the
|
1716
|
+
function will throw.
|
1702
1717
|
|
1703
|
-
|
1704
|
-
the moment of calling the method `selector` already satisfies the condition, the method will return immediately. If the
|
1705
|
-
selector doesn't satisfy the condition for the `timeout` milliseconds, the function will throw.
|
1718
|
+
**Usage**
|
1706
1719
|
|
1707
1720
|
This method works across navigations:
|
1708
1721
|
|
@@ -1714,47 +1727,50 @@ This method works across navigations:
|
|
1714
1727
|
end
|
1715
1728
|
```
|
1716
1729
|
|
1717
|
-
|
1718
|
-
|
1719
1730
|
## wait_for_timeout
|
1720
1731
|
|
1721
1732
|
```
|
1722
1733
|
def wait_for_timeout(timeout)
|
1723
1734
|
```
|
1724
1735
|
|
1736
|
+
|
1725
1737
|
Waits for the given `timeout` in milliseconds.
|
1726
1738
|
|
1727
1739
|
Note that `page.waitForTimeout()` should only be used for debugging. Tests using the timer in production are going to be
|
1728
1740
|
flaky. Use signals such as network events, selectors becoming visible and others instead.
|
1729
1741
|
|
1742
|
+
**Usage**
|
1743
|
+
|
1730
1744
|
```ruby
|
1731
1745
|
page.wait_for_timeout(1000)
|
1732
1746
|
```
|
1733
1747
|
|
1734
|
-
Shortcut for main frame's [Frame#wait_for_timeout](./frame#wait_for_timeout).
|
1735
|
-
|
1736
1748
|
## wait_for_url
|
1737
1749
|
|
1738
1750
|
```
|
1739
1751
|
def wait_for_url(url, timeout: nil, waitUntil: nil)
|
1740
1752
|
```
|
1741
1753
|
|
1754
|
+
|
1742
1755
|
Waits for the main frame to navigate to the given URL.
|
1743
1756
|
|
1757
|
+
**Usage**
|
1758
|
+
|
1744
1759
|
```ruby
|
1745
1760
|
page.click("a.delayed-navigation") # clicking the link will indirectly cause a navigation
|
1746
1761
|
page.wait_for_url("**/target.html")
|
1747
1762
|
```
|
1748
1763
|
|
1749
|
-
Shortcut for main frame's [Frame#wait_for_url](./frame#wait_for_url).
|
1750
|
-
|
1751
1764
|
## expect_websocket
|
1752
1765
|
|
1753
1766
|
```
|
1754
1767
|
def expect_websocket(predicate: nil, timeout: nil, &block)
|
1755
1768
|
```
|
1756
1769
|
|
1757
|
-
|
1770
|
+
|
1771
|
+
Performs action and waits for a new [WebSocket](./web_socket). If predicate is provided, it passes
|
1772
|
+
[WebSocket](./web_socket) value into the `predicate` function and waits for `predicate(webSocket)` to return a truthy value.
|
1773
|
+
Will throw an error if the page is closed before the WebSocket event is fired.
|
1758
1774
|
|
1759
1775
|
## expect_worker
|
1760
1776
|
|
@@ -1762,9 +1778,10 @@ Performs action and waits for a new [WebSocket](./web_socket). If predicate is p
|
|
1762
1778
|
def expect_worker(predicate: nil, timeout: nil, &block)
|
1763
1779
|
```
|
1764
1780
|
|
1765
|
-
|
1766
|
-
|
1767
|
-
the worker
|
1781
|
+
|
1782
|
+
Performs action and waits for a new [Worker](./worker). If predicate is provided, it passes
|
1783
|
+
[Worker](./worker) value into the `predicate` function and waits for `predicate(worker)` to return a truthy value.
|
1784
|
+
Will throw an error if the page is closed before the worker event is fired.
|
1768
1785
|
|
1769
1786
|
## workers
|
1770
1787
|
|
@@ -1772,23 +1789,21 @@ the worker event is fired.
|
|
1772
1789
|
def workers
|
1773
1790
|
```
|
1774
1791
|
|
1792
|
+
|
1775
1793
|
This method returns all of the dedicated [WebWorkers](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API)
|
1776
1794
|
associated with the page.
|
1777
1795
|
|
1778
|
-
|
1796
|
+
**NOTE**: This does not contain ServiceWorkers
|
1779
1797
|
|
1780
1798
|
## accessibility
|
1781
1799
|
|
1782
|
-
**DEPRECATED** This property is deprecated. Please use other libraries such as [Axe](https://www.deque.com/axe/) if you
|
1783
|
-
need to test page accessibility. See our Node.js [guide](https://playwright.dev/docs/accessibility-testing) for
|
1784
|
-
integration with Axe.
|
1785
|
-
|
1786
1800
|
## keyboard
|
1787
1801
|
|
1788
1802
|
## mouse
|
1789
1803
|
|
1790
1804
|
## request
|
1791
1805
|
|
1806
|
+
|
1792
1807
|
API testing helper associated with this page. This method returns the same instance as
|
1793
1808
|
[BrowserContext#request](./browser_context#request) on the page's context. See [BrowserContext#request](./browser_context#request) for more details.
|
1794
1809
|
|