playwright-ruby-client 1.26.0 → 1.27.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (35) hide show
  1. checksums.yaml +4 -4
  2. data/documentation/docs/api/api_request_context.md +86 -0
  3. data/documentation/docs/api/browser_context.md +3 -3
  4. data/documentation/docs/api/download.md +1 -1
  5. data/documentation/docs/api/element_handle.md +1 -1
  6. data/documentation/docs/api/file_chooser.md +1 -1
  7. data/documentation/docs/api/frame.md +103 -4
  8. data/documentation/docs/api/frame_locator.md +104 -4
  9. data/documentation/docs/api/locator.md +121 -6
  10. data/documentation/docs/api/page.md +118 -9
  11. data/documentation/docs/api/tracing.md +1 -1
  12. data/documentation/docs/article/guides/rails_integration_with_null_driver.md +59 -0
  13. data/documentation/docs/include/api_coverage.md +29 -0
  14. data/lib/playwright/channel_owners/frame.rb +4 -0
  15. data/lib/playwright/channel_owners/page.rb +2 -0
  16. data/lib/playwright/channel_owners/selectors.rb +4 -0
  17. data/lib/playwright/frame_locator_impl.rb +6 -2
  18. data/lib/playwright/locator_impl.rb +7 -31
  19. data/lib/playwright/locator_utils.rb +142 -0
  20. data/lib/playwright/version.rb +2 -2
  21. data/lib/playwright_api/api_request_context.rb +80 -2
  22. data/lib/playwright_api/browser_context.rb +3 -3
  23. data/lib/playwright_api/download.rb +1 -1
  24. data/lib/playwright_api/element_handle.rb +1 -1
  25. data/lib/playwright_api/file_chooser.rb +1 -1
  26. data/lib/playwright_api/frame.rb +78 -4
  27. data/lib/playwright_api/frame_locator.rb +78 -3
  28. data/lib/playwright_api/locator.rb +94 -5
  29. data/lib/playwright_api/page.rb +92 -9
  30. data/lib/playwright_api/request.rb +4 -4
  31. data/lib/playwright_api/response.rb +4 -4
  32. data/lib/playwright_api/selectors.rb +11 -0
  33. data/lib/playwright_api/tracing.rb +1 -1
  34. data/lib/playwright_api/worker.rb +4 -4
  35. metadata +4 -3
@@ -91,6 +91,32 @@ module Playwright
91
91
 
92
92
  # Sends HTTP(S) request and returns its response. The method will populate request cookies from the context and update
93
93
  # context cookies from the response. The method will automatically follow redirects.
94
+ #
95
+ # JSON objects can be passed directly to the request:
96
+ #
97
+ # ```python
98
+ # data = {
99
+ # "title": "Book Title",
100
+ # "body": "John Doe",
101
+ # }
102
+ # api_request_context.fetch("https://example.com/api/createBook", method="post", data=data)
103
+ # ```
104
+ #
105
+ # The common way to send file(s) in the body of a request is to encode it as form fields with `multipart/form-data`
106
+ # encoding. You can achieve that with Playwright API like this:
107
+ #
108
+ # ```python
109
+ # api_request_context.fetch(
110
+ # "https://example.com/api/uploadScrip'",
111
+ # method="post",
112
+ # multipart={
113
+ # "fileField": {
114
+ # "name": "f.js",
115
+ # "mimeType": "text/javascript",
116
+ # "buffer": b"console.log(2022);",
117
+ # },
118
+ # })
119
+ # ```
94
120
  def fetch(
95
121
  urlOrRequest,
96
122
  data: nil,
@@ -109,15 +135,28 @@ module Playwright
109
135
  # Sends HTTP(S) [GET](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/GET) request and returns its response. The
110
136
  # method will populate request cookies from the context and update context cookies from the response. The method will
111
137
  # automatically follow redirects.
138
+ #
139
+ # Request parameters can be configured with `params` option, they will be serialized into the URL search parameters:
140
+ #
141
+ # ```python
142
+ # query_params = {
143
+ # "isbn": "1234",
144
+ # "page": "23"
145
+ # }
146
+ # api_request_context.get("https://example.com/api/getText", params=query_params)
147
+ # ```
112
148
  def get(
113
149
  url,
150
+ data: nil,
114
151
  failOnStatusCode: nil,
152
+ form: nil,
115
153
  headers: nil,
116
154
  ignoreHTTPSErrors: nil,
117
155
  maxRedirects: nil,
156
+ multipart: nil,
118
157
  params: nil,
119
158
  timeout: nil)
120
- wrap_impl(@impl.get(unwrap_impl(url), failOnStatusCode: unwrap_impl(failOnStatusCode), headers: unwrap_impl(headers), ignoreHTTPSErrors: unwrap_impl(ignoreHTTPSErrors), maxRedirects: unwrap_impl(maxRedirects), params: unwrap_impl(params), timeout: unwrap_impl(timeout)))
159
+ wrap_impl(@impl.get(unwrap_impl(url), data: unwrap_impl(data), failOnStatusCode: unwrap_impl(failOnStatusCode), form: unwrap_impl(form), headers: unwrap_impl(headers), ignoreHTTPSErrors: unwrap_impl(ignoreHTTPSErrors), maxRedirects: unwrap_impl(maxRedirects), multipart: unwrap_impl(multipart), params: unwrap_impl(params), timeout: unwrap_impl(timeout)))
121
160
  end
122
161
 
123
162
  # Sends HTTP(S) [HEAD](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/HEAD) request and returns its response.
@@ -125,13 +164,16 @@ module Playwright
125
164
  # automatically follow redirects.
126
165
  def head(
127
166
  url,
167
+ data: nil,
128
168
  failOnStatusCode: nil,
169
+ form: nil,
129
170
  headers: nil,
130
171
  ignoreHTTPSErrors: nil,
131
172
  maxRedirects: nil,
173
+ multipart: nil,
132
174
  params: nil,
133
175
  timeout: nil)
134
- wrap_impl(@impl.head(unwrap_impl(url), failOnStatusCode: unwrap_impl(failOnStatusCode), headers: unwrap_impl(headers), ignoreHTTPSErrors: unwrap_impl(ignoreHTTPSErrors), maxRedirects: unwrap_impl(maxRedirects), params: unwrap_impl(params), timeout: unwrap_impl(timeout)))
176
+ wrap_impl(@impl.head(unwrap_impl(url), data: unwrap_impl(data), failOnStatusCode: unwrap_impl(failOnStatusCode), form: unwrap_impl(form), headers: unwrap_impl(headers), ignoreHTTPSErrors: unwrap_impl(ignoreHTTPSErrors), maxRedirects: unwrap_impl(maxRedirects), multipart: unwrap_impl(multipart), params: unwrap_impl(params), timeout: unwrap_impl(timeout)))
135
177
  end
136
178
 
137
179
  # Sends HTTP(S) [PATCH](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/PATCH) request and returns its response.
@@ -154,6 +196,42 @@ module Playwright
154
196
  # Sends HTTP(S) [POST](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/POST) request and returns its response.
155
197
  # The method will populate request cookies from the context and update context cookies from the response. The method will
156
198
  # automatically follow redirects.
199
+ #
200
+ # JSON objects can be passed directly to the request:
201
+ #
202
+ # ```python
203
+ # data = {
204
+ # "title": "Book Title",
205
+ # "body": "John Doe",
206
+ # }
207
+ # api_request_context.post("https://example.com/api/createBook", data=data)
208
+ # ```
209
+ #
210
+ # To send form data to the server use `form` option. Its value will be encoded into the request body with
211
+ # `application/x-www-form-urlencoded` encoding (see below how to use `multipart/form-data` form encoding to send files):
212
+ #
213
+ # ```python
214
+ # formData = {
215
+ # "title": "Book Title",
216
+ # "body": "John Doe",
217
+ # }
218
+ # api_request_context.post("https://example.com/api/findBook", form=formData)
219
+ # ```
220
+ #
221
+ # The common way to send file(s) in the body of a request is to upload them as form fields with `multipart/form-data`
222
+ # encoding. You can achieve that with Playwright API like this:
223
+ #
224
+ # ```python
225
+ # api_request_context.post(
226
+ # "https://example.com/api/uploadScrip'",
227
+ # multipart={
228
+ # "fileField": {
229
+ # "name": "f.js",
230
+ # "mimeType": "text/javascript",
231
+ # "buffer": b"console.log(2022);",
232
+ # },
233
+ # })
234
+ # ```
157
235
  def post(
158
236
  url,
159
237
  data: nil,
@@ -131,7 +131,7 @@ module Playwright
131
131
  # <button onclick="onClick()">Click me</button>
132
132
  # <div></div>
133
133
  # """)
134
- # page.locator("button").click()
134
+ # page.get_by_role("button").click()
135
135
  #
136
136
  # with sync_playwright() as playwright:
137
137
  # run(playwright)
@@ -190,7 +190,7 @@ module Playwright
190
190
  # <button onclick="onClick()">Click me</button>
191
191
  # <div></div>
192
192
  # """)
193
- # page.locator("button").click()
193
+ # page.get_by_role("button").click()
194
194
  #
195
195
  # with sync_playwright() as playwright:
196
196
  # run(playwright)
@@ -358,7 +358,7 @@ module Playwright
358
358
  #
359
359
  # ```python sync
360
360
  # with context.expect_event("page") as event_info:
361
- # page.locator("button").click()
361
+ # page.get_by_role("button").click()
362
362
  # page = event_info.value
363
363
  # ```
364
364
  def expect_event(event, predicate: nil, timeout: nil, &block)
@@ -7,7 +7,7 @@ module Playwright
7
7
  #
8
8
  # ```python sync
9
9
  # with page.expect_download() as download_info:
10
- # page.locator("a").click()
10
+ # page.get_by_text("Download file").click()
11
11
  # download = download_info.value
12
12
  # # wait for download to complete
13
13
  # path = download.path()
@@ -36,7 +36,7 @@ module Playwright
36
36
  # in the snippet below, underlying DOM element is going to be located twice.
37
37
  #
38
38
  # ```python sync
39
- # locator = page.locator("text=Submit")
39
+ # locator = page.get_by_text("Submit")
40
40
  # locator.hover()
41
41
  # locator.click()
42
42
  # ```
@@ -3,7 +3,7 @@ module Playwright
3
3
  #
4
4
  # ```python sync
5
5
  # with page.expect_file_chooser() as fc_info:
6
- # page.locator("upload").click()
6
+ # page.get_by_text("Upload").click()
7
7
  # file_chooser = fc_info.value
8
8
  # file_chooser.set_files("myfile.pdf")
9
9
  # ```
@@ -335,7 +335,7 @@ module Playwright
335
335
  # id="my-frame">`:
336
336
  #
337
337
  # ```python sync
338
- # locator = frame.frame_locator("#my-iframe").locator("text=Submit")
338
+ # locator = frame.frame_locator("#my-iframe").get_by_text("Submit")
339
339
  # locator.click()
340
340
  # ```
341
341
  def frame_locator(selector)
@@ -347,6 +347,78 @@ module Playwright
347
347
  wrap_impl(@impl.get_attribute(unwrap_impl(selector), unwrap_impl(name), strict: unwrap_impl(strict), timeout: unwrap_impl(timeout)))
348
348
  end
349
349
 
350
+ # Allows locating elements by their alt text. For example, this method will find the image by alt text "Castle":
351
+ #
352
+ # ```html
353
+ # <img alt='Castle'>
354
+ # ```
355
+ def get_by_alt_text(text, exact: nil)
356
+ wrap_impl(@impl.get_by_alt_text(unwrap_impl(text), exact: unwrap_impl(exact)))
357
+ end
358
+
359
+ # Allows locating input elements by the text of the associated label. For example, this method will find the input by
360
+ # label text Password in the following DOM:
361
+ #
362
+ # ```html
363
+ # <label for="password-input">Password:</label>
364
+ # <input id="password-input">
365
+ # ```
366
+ def get_by_label(text, exact: nil)
367
+ wrap_impl(@impl.get_by_label(unwrap_impl(text), exact: unwrap_impl(exact)))
368
+ end
369
+
370
+ # Allows locating input elements by the placeholder text. For example, this method will find the input by placeholder
371
+ # "Country":
372
+ #
373
+ # ```html
374
+ # <input placeholder="Country">
375
+ # ```
376
+ def get_by_placeholder(text, exact: nil)
377
+ wrap_impl(@impl.get_by_placeholder(unwrap_impl(text), exact: unwrap_impl(exact)))
378
+ end
379
+
380
+ # Allows locating elements by their [ARIA role](https://www.w3.org/TR/wai-aria-1.2/#roles),
381
+ # [ARIA attributes](https://www.w3.org/TR/wai-aria-1.2/#aria-attributes) and
382
+ # [accessible name](https://w3c.github.io/accname/#dfn-accessible-name). Note that role selector **does not replace**
383
+ # accessibility audits and conformance tests, but rather gives early feedback about the ARIA guidelines.
384
+ #
385
+ # Note that many html elements have an implicitly
386
+ # [defined role](https://w3c.github.io/html-aam/#html-element-role-mappings) that is recognized by the role selector. You
387
+ # can find all the [supported roles here](https://www.w3.org/TR/wai-aria-1.2/#role_definitions). ARIA guidelines **do not
388
+ # recommend** duplicating implicit roles and attributes by setting `role` and/or `aria-*` attributes to default values.
389
+ def get_by_role(
390
+ role,
391
+ checked: nil,
392
+ disabled: nil,
393
+ expanded: nil,
394
+ includeHidden: nil,
395
+ level: nil,
396
+ name: nil,
397
+ pressed: nil,
398
+ selected: nil)
399
+ wrap_impl(@impl.get_by_role(unwrap_impl(role), checked: unwrap_impl(checked), disabled: unwrap_impl(disabled), expanded: unwrap_impl(expanded), includeHidden: unwrap_impl(includeHidden), level: unwrap_impl(level), name: unwrap_impl(name), pressed: unwrap_impl(pressed), selected: unwrap_impl(selected)))
400
+ end
401
+
402
+ # Locate element by the test id. By default, the `data-testid` attribute is used as a test id. Use
403
+ # [`method: Selectors.setTestIdAttribute`] to configure a different test id attribute if necessary.
404
+ def get_by_test_id(testId)
405
+ wrap_impl(@impl.get_by_test_id(unwrap_impl(testId)))
406
+ end
407
+
408
+ # Allows locating elements that contain given text.
409
+ def get_by_text(text, exact: nil)
410
+ wrap_impl(@impl.get_by_text(unwrap_impl(text), exact: unwrap_impl(exact)))
411
+ end
412
+
413
+ # Allows locating elements by their title. For example, this method will find the button by its title "Submit":
414
+ #
415
+ # ```html
416
+ # <button title='Place the order'>Order Now</button>
417
+ # ```
418
+ def get_by_title(text, exact: nil)
419
+ wrap_impl(@impl.get_by_title(unwrap_impl(text), exact: unwrap_impl(exact)))
420
+ end
421
+
350
422
  # Returns the main resource response. In case of multiple redirects, the navigation will resolve with the response of the
351
423
  # last redirect.
352
424
  #
@@ -445,9 +517,11 @@ module Playwright
445
517
  wrap_impl(@impl.visible?(unwrap_impl(selector), strict: unwrap_impl(strict), timeout: unwrap_impl(timeout)))
446
518
  end
447
519
 
448
- # The method returns an element locator that can be used to perform actions in the frame. Locator is resolved to the
449
- # element immediately before performing an action, so a series of actions on the same locator can in fact be performed on
450
- # different DOM elements. That would happen if the DOM structure between those actions has changed.
520
+ # The method returns an element locator that can be used to perform actions on this page / frame. Locator is resolved to
521
+ # the element immediately before performing an action, so a series of actions on the same locator can in fact be performed
522
+ # on different DOM elements. That would happen if the DOM structure between those actions has changed.
523
+ #
524
+ # [Learn more about locators](../locators.md).
451
525
  #
452
526
  # [Learn more about locators](../locators.md).
453
527
  def locator(selector, has: nil, hasText: nil)
@@ -15,10 +15,10 @@ module Playwright
15
15
  #
16
16
  # ```python sync
17
17
  # # Throws if there are several frames in DOM:
18
- # page.frame_locator('.result-frame').locator('button').click()
18
+ # page.frame_locator('.result-frame').get_by_role('button').click()
19
19
  #
20
20
  # # Works because we explicitly tell locator to pick the first frame:
21
- # page.frame_locator('.result-frame').first.locator('button').click()
21
+ # page.frame_locator('.result-frame').first.get_by_role('button').click()
22
22
  # ```
23
23
  #
24
24
  # **Converting Locator to FrameLocator**
@@ -42,12 +42,87 @@ module Playwright
42
42
  wrap_impl(@impl.frame_locator(unwrap_impl(selector)))
43
43
  end
44
44
 
45
+ # Allows locating elements by their alt text. For example, this method will find the image by alt text "Castle":
46
+ #
47
+ # ```html
48
+ # <img alt='Castle'>
49
+ # ```
50
+ def get_by_alt_text(text, exact: nil)
51
+ wrap_impl(@impl.get_by_alt_text(unwrap_impl(text), exact: unwrap_impl(exact)))
52
+ end
53
+
54
+ # Allows locating input elements by the text of the associated label. For example, this method will find the input by
55
+ # label text Password in the following DOM:
56
+ #
57
+ # ```html
58
+ # <label for="password-input">Password:</label>
59
+ # <input id="password-input">
60
+ # ```
61
+ def get_by_label(text, exact: nil)
62
+ wrap_impl(@impl.get_by_label(unwrap_impl(text), exact: unwrap_impl(exact)))
63
+ end
64
+
65
+ # Allows locating input elements by the placeholder text. For example, this method will find the input by placeholder
66
+ # "Country":
67
+ #
68
+ # ```html
69
+ # <input placeholder="Country">
70
+ # ```
71
+ def get_by_placeholder(text, exact: nil)
72
+ wrap_impl(@impl.get_by_placeholder(unwrap_impl(text), exact: unwrap_impl(exact)))
73
+ end
74
+
75
+ # Allows locating elements by their [ARIA role](https://www.w3.org/TR/wai-aria-1.2/#roles),
76
+ # [ARIA attributes](https://www.w3.org/TR/wai-aria-1.2/#aria-attributes) and
77
+ # [accessible name](https://w3c.github.io/accname/#dfn-accessible-name). Note that role selector **does not replace**
78
+ # accessibility audits and conformance tests, but rather gives early feedback about the ARIA guidelines.
79
+ #
80
+ # Note that many html elements have an implicitly
81
+ # [defined role](https://w3c.github.io/html-aam/#html-element-role-mappings) that is recognized by the role selector. You
82
+ # can find all the [supported roles here](https://www.w3.org/TR/wai-aria-1.2/#role_definitions). ARIA guidelines **do not
83
+ # recommend** duplicating implicit roles and attributes by setting `role` and/or `aria-*` attributes to default values.
84
+ def get_by_role(
85
+ role,
86
+ checked: nil,
87
+ disabled: nil,
88
+ expanded: nil,
89
+ includeHidden: nil,
90
+ level: nil,
91
+ name: nil,
92
+ pressed: nil,
93
+ selected: nil)
94
+ wrap_impl(@impl.get_by_role(unwrap_impl(role), checked: unwrap_impl(checked), disabled: unwrap_impl(disabled), expanded: unwrap_impl(expanded), includeHidden: unwrap_impl(includeHidden), level: unwrap_impl(level), name: unwrap_impl(name), pressed: unwrap_impl(pressed), selected: unwrap_impl(selected)))
95
+ end
96
+
97
+ # Locate element by the test id. By default, the `data-testid` attribute is used as a test id. Use
98
+ # [`method: Selectors.setTestIdAttribute`] to configure a different test id attribute if necessary.
99
+ def get_by_test_id(testId)
100
+ wrap_impl(@impl.get_by_test_id(unwrap_impl(testId)))
101
+ end
102
+
103
+ # Allows locating elements that contain given text.
104
+ def get_by_text(text, exact: nil)
105
+ wrap_impl(@impl.get_by_text(unwrap_impl(text), exact: unwrap_impl(exact)))
106
+ end
107
+
108
+ # Allows locating elements by their title. For example, this method will find the button by its title "Submit":
109
+ #
110
+ # ```html
111
+ # <button title='Place the order'>Order Now</button>
112
+ # ```
113
+ def get_by_title(text, exact: nil)
114
+ wrap_impl(@impl.get_by_title(unwrap_impl(text), exact: unwrap_impl(exact)))
115
+ end
116
+
45
117
  # Returns locator to the last matching frame.
46
118
  def last
47
119
  wrap_impl(@impl.last)
48
120
  end
49
121
 
50
- # The method finds an element matching the specified selector in the FrameLocator's subtree.
122
+ # The method finds an element matching the specified selector in the locator's subtree. It also accepts filter options,
123
+ # similar to [`method: Locator.filter`] method.
124
+ #
125
+ # [Learn more about locators](../locators.md).
51
126
  def locator(selector, has: nil, hasText: nil)
52
127
  wrap_impl(@impl.locator(unwrap_impl(selector), has: unwrap_impl(has), hasText: unwrap_impl(hasText)))
53
128
  end
@@ -142,6 +142,21 @@ module Playwright
142
142
  wrap_impl(@impl.dispatch_event(unwrap_impl(type), eventInit: unwrap_impl(eventInit), timeout: unwrap_impl(timeout)))
143
143
  end
144
144
 
145
+ # This method drags the locator to another target locator or target position. It will first move to the source element,
146
+ # perform a `mousedown`, then move to the target element or position and perform a `mouseup`.
147
+ #
148
+ # ```python sync
149
+ # source = page.locator("#source")
150
+ # target = page.locator("#target")
151
+ #
152
+ # source.drag_to(target)
153
+ # # or specify exact positions relative to the top-left corners of the elements:
154
+ # source.drag_to(
155
+ # target,
156
+ # source_position={"x": 34, "y": 7},
157
+ # target_position={"x": 10, "y": 20}
158
+ # )
159
+ # ```
145
160
  def drag_to(
146
161
  target,
147
162
  force: nil,
@@ -232,7 +247,7 @@ module Playwright
232
247
  # # ...
233
248
  # row_locator
234
249
  # .filter(has_text="text in column 1")
235
- # .filter(has=page.locator("tr", has_text="column 2 button"))
250
+ # .filter(has=page.get_by_role("button", name="column 2 button"))
236
251
  # .screenshot()
237
252
  # ```
238
253
  def filter(has: nil, hasText: nil)
@@ -253,7 +268,7 @@ module Playwright
253
268
  # that iframe:
254
269
  #
255
270
  # ```python sync
256
- # locator = page.frame_locator("iframe").locator("text=Submit")
271
+ # locator = page.frame_locator("iframe").get_by_text("Submit")
257
272
  # locator.click()
258
273
  # ```
259
274
  def frame_locator(selector)
@@ -266,6 +281,78 @@ module Playwright
266
281
  end
267
282
  alias_method :[], :get_attribute
268
283
 
284
+ # Allows locating elements by their alt text. For example, this method will find the image by alt text "Castle":
285
+ #
286
+ # ```html
287
+ # <img alt='Castle'>
288
+ # ```
289
+ def get_by_alt_text(text, exact: nil)
290
+ wrap_impl(@impl.get_by_alt_text(unwrap_impl(text), exact: unwrap_impl(exact)))
291
+ end
292
+
293
+ # Allows locating input elements by the text of the associated label. For example, this method will find the input by
294
+ # label text Password in the following DOM:
295
+ #
296
+ # ```html
297
+ # <label for="password-input">Password:</label>
298
+ # <input id="password-input">
299
+ # ```
300
+ def get_by_label(text, exact: nil)
301
+ wrap_impl(@impl.get_by_label(unwrap_impl(text), exact: unwrap_impl(exact)))
302
+ end
303
+
304
+ # Allows locating input elements by the placeholder text. For example, this method will find the input by placeholder
305
+ # "Country":
306
+ #
307
+ # ```html
308
+ # <input placeholder="Country">
309
+ # ```
310
+ def get_by_placeholder(text, exact: nil)
311
+ wrap_impl(@impl.get_by_placeholder(unwrap_impl(text), exact: unwrap_impl(exact)))
312
+ end
313
+
314
+ # Allows locating elements by their [ARIA role](https://www.w3.org/TR/wai-aria-1.2/#roles),
315
+ # [ARIA attributes](https://www.w3.org/TR/wai-aria-1.2/#aria-attributes) and
316
+ # [accessible name](https://w3c.github.io/accname/#dfn-accessible-name). Note that role selector **does not replace**
317
+ # accessibility audits and conformance tests, but rather gives early feedback about the ARIA guidelines.
318
+ #
319
+ # Note that many html elements have an implicitly
320
+ # [defined role](https://w3c.github.io/html-aam/#html-element-role-mappings) that is recognized by the role selector. You
321
+ # can find all the [supported roles here](https://www.w3.org/TR/wai-aria-1.2/#role_definitions). ARIA guidelines **do not
322
+ # recommend** duplicating implicit roles and attributes by setting `role` and/or `aria-*` attributes to default values.
323
+ def get_by_role(
324
+ role,
325
+ checked: nil,
326
+ disabled: nil,
327
+ expanded: nil,
328
+ includeHidden: nil,
329
+ level: nil,
330
+ name: nil,
331
+ pressed: nil,
332
+ selected: nil)
333
+ wrap_impl(@impl.get_by_role(unwrap_impl(role), checked: unwrap_impl(checked), disabled: unwrap_impl(disabled), expanded: unwrap_impl(expanded), includeHidden: unwrap_impl(includeHidden), level: unwrap_impl(level), name: unwrap_impl(name), pressed: unwrap_impl(pressed), selected: unwrap_impl(selected)))
334
+ end
335
+
336
+ # Locate element by the test id. By default, the `data-testid` attribute is used as a test id. Use
337
+ # [`method: Selectors.setTestIdAttribute`] to configure a different test id attribute if necessary.
338
+ def get_by_test_id(testId)
339
+ wrap_impl(@impl.get_by_test_id(unwrap_impl(testId)))
340
+ end
341
+
342
+ # Allows locating elements that contain given text.
343
+ def get_by_text(text, exact: nil)
344
+ wrap_impl(@impl.get_by_text(unwrap_impl(text), exact: unwrap_impl(exact)))
345
+ end
346
+
347
+ # Allows locating elements by their title. For example, this method will find the button by its title "Submit":
348
+ #
349
+ # ```html
350
+ # <button title='Place the order'>Order Now</button>
351
+ # ```
352
+ def get_by_title(text, exact: nil)
353
+ wrap_impl(@impl.get_by_title(unwrap_impl(text), exact: unwrap_impl(exact)))
354
+ end
355
+
269
356
  # Highlight the corresponding element(s) on the screen. Useful for debugging, don't commit the code that uses
270
357
  # [`method: Locator.highlight`].
271
358
  def highlight
@@ -344,8 +431,10 @@ module Playwright
344
431
  wrap_impl(@impl.last)
345
432
  end
346
433
 
347
- # The method finds an element matching the specified selector in the `Locator`'s subtree. It also accepts filter options,
434
+ # The method finds an element matching the specified selector in the locator's subtree. It also accepts filter options,
348
435
  # similar to [`method: Locator.filter`] method.
436
+ #
437
+ # [Learn more about locators](../locators.md).
349
438
  def locator(selector, has: nil, hasText: nil)
350
439
  wrap_impl(@impl.locator(unwrap_impl(selector), has: unwrap_impl(has), hasText: unwrap_impl(hasText)))
351
440
  end
@@ -524,8 +613,8 @@ module Playwright
524
613
  # An example of typing into a text field and then submitting the form:
525
614
  #
526
615
  # ```python sync
527
- # element = page.locator("input")
528
- # element.type("some text")
616
+ # element = page.get_by_label("Password")
617
+ # element.type("my password")
529
618
  # element.press("Enter")
530
619
  # ```
531
620
  def type(text, delay: nil, noWaitAfter: nil, timeout: nil)
@@ -250,6 +250,19 @@ module Playwright
250
250
  wrap_impl(@impl.dispatch_event(unwrap_impl(selector), unwrap_impl(type), eventInit: unwrap_impl(eventInit), strict: unwrap_impl(strict), timeout: unwrap_impl(timeout)))
251
251
  end
252
252
 
253
+ # This method drags the source element to the target element. It will first move to the source element, perform a
254
+ # `mousedown`, then move to the target element and perform a `mouseup`.
255
+ #
256
+ # ```python sync
257
+ # page.drag_and_drop("#source", "#target")
258
+ # # or specify exact positions relative to the top-left corners of the elements:
259
+ # page.drag_and_drop(
260
+ # "#source",
261
+ # "#target",
262
+ # source_position={"x": 34, "y": 7},
263
+ # target_position={"x": 10, "y": 20}
264
+ # )
265
+ # ```
253
266
  def drag_and_drop(
254
267
  source,
255
268
  target,
@@ -553,7 +566,7 @@ module Playwright
553
566
  # id="my-frame">`:
554
567
  #
555
568
  # ```python sync
556
- # locator = page.frame_locator("#my-iframe").locator("text=Submit")
569
+ # locator = page.frame_locator("#my-iframe").get_by_text("Submit")
557
570
  # locator.click()
558
571
  # ```
559
572
  def frame_locator(selector)
@@ -570,6 +583,78 @@ module Playwright
570
583
  wrap_impl(@impl.get_attribute(unwrap_impl(selector), unwrap_impl(name), strict: unwrap_impl(strict), timeout: unwrap_impl(timeout)))
571
584
  end
572
585
 
586
+ # Allows locating elements by their alt text. For example, this method will find the image by alt text "Castle":
587
+ #
588
+ # ```html
589
+ # <img alt='Castle'>
590
+ # ```
591
+ def get_by_alt_text(text, exact: nil)
592
+ wrap_impl(@impl.get_by_alt_text(unwrap_impl(text), exact: unwrap_impl(exact)))
593
+ end
594
+
595
+ # Allows locating input elements by the text of the associated label. For example, this method will find the input by
596
+ # label text Password in the following DOM:
597
+ #
598
+ # ```html
599
+ # <label for="password-input">Password:</label>
600
+ # <input id="password-input">
601
+ # ```
602
+ def get_by_label(text, exact: nil)
603
+ wrap_impl(@impl.get_by_label(unwrap_impl(text), exact: unwrap_impl(exact)))
604
+ end
605
+
606
+ # Allows locating input elements by the placeholder text. For example, this method will find the input by placeholder
607
+ # "Country":
608
+ #
609
+ # ```html
610
+ # <input placeholder="Country">
611
+ # ```
612
+ def get_by_placeholder(text, exact: nil)
613
+ wrap_impl(@impl.get_by_placeholder(unwrap_impl(text), exact: unwrap_impl(exact)))
614
+ end
615
+
616
+ # Allows locating elements by their [ARIA role](https://www.w3.org/TR/wai-aria-1.2/#roles),
617
+ # [ARIA attributes](https://www.w3.org/TR/wai-aria-1.2/#aria-attributes) and
618
+ # [accessible name](https://w3c.github.io/accname/#dfn-accessible-name). Note that role selector **does not replace**
619
+ # accessibility audits and conformance tests, but rather gives early feedback about the ARIA guidelines.
620
+ #
621
+ # Note that many html elements have an implicitly
622
+ # [defined role](https://w3c.github.io/html-aam/#html-element-role-mappings) that is recognized by the role selector. You
623
+ # can find all the [supported roles here](https://www.w3.org/TR/wai-aria-1.2/#role_definitions). ARIA guidelines **do not
624
+ # recommend** duplicating implicit roles and attributes by setting `role` and/or `aria-*` attributes to default values.
625
+ def get_by_role(
626
+ role,
627
+ checked: nil,
628
+ disabled: nil,
629
+ expanded: nil,
630
+ includeHidden: nil,
631
+ level: nil,
632
+ name: nil,
633
+ pressed: nil,
634
+ selected: nil)
635
+ wrap_impl(@impl.get_by_role(unwrap_impl(role), checked: unwrap_impl(checked), disabled: unwrap_impl(disabled), expanded: unwrap_impl(expanded), includeHidden: unwrap_impl(includeHidden), level: unwrap_impl(level), name: unwrap_impl(name), pressed: unwrap_impl(pressed), selected: unwrap_impl(selected)))
636
+ end
637
+
638
+ # Locate element by the test id. By default, the `data-testid` attribute is used as a test id. Use
639
+ # [`method: Selectors.setTestIdAttribute`] to configure a different test id attribute if necessary.
640
+ def get_by_test_id(testId)
641
+ wrap_impl(@impl.get_by_test_id(unwrap_impl(testId)))
642
+ end
643
+
644
+ # Allows locating elements that contain given text.
645
+ def get_by_text(text, exact: nil)
646
+ wrap_impl(@impl.get_by_text(unwrap_impl(text), exact: unwrap_impl(exact)))
647
+ end
648
+
649
+ # Allows locating elements by their title. For example, this method will find the button by its title "Submit":
650
+ #
651
+ # ```html
652
+ # <button title='Place the order'>Order Now</button>
653
+ # ```
654
+ def get_by_title(text, exact: nil)
655
+ wrap_impl(@impl.get_by_title(unwrap_impl(text), exact: unwrap_impl(exact)))
656
+ end
657
+
573
658
  # Returns the main resource response. In case of multiple redirects, the navigation will resolve with the response of the
574
659
  # last redirect. If can not go back, returns `null`.
575
660
  #
@@ -688,13 +773,11 @@ module Playwright
688
773
  wrap_impl(@impl.visible?(unwrap_impl(selector), strict: unwrap_impl(strict), timeout: unwrap_impl(timeout)))
689
774
  end
690
775
 
691
- # The method returns an element locator that can be used to perform actions on the page. Locator is resolved to the
692
- # element immediately before performing an action, so a series of actions on the same locator can in fact be performed on
693
- # different DOM elements. That would happen if the DOM structure between those actions has changed.
776
+ # The method returns an element locator that can be used to perform actions on this page / frame. Locator is resolved to
777
+ # the element immediately before performing an action, so a series of actions on the same locator can in fact be performed
778
+ # on different DOM elements. That would happen if the DOM structure between those actions has changed.
694
779
  #
695
780
  # [Learn more about locators](../locators.md).
696
- #
697
- # Shortcut for main frame's [`method: Frame.locator`].
698
781
  def locator(selector, has: nil, hasText: nil)
699
782
  wrap_impl(@impl.locator(unwrap_impl(selector), has: unwrap_impl(has), hasText: unwrap_impl(hasText)))
700
783
  end
@@ -1177,7 +1260,7 @@ module Playwright
1177
1260
  #
1178
1261
  # ```python sync
1179
1262
  # with page.expect_event("framenavigated") as event_info:
1180
- # page.click("button")
1263
+ # page.get_by_role("button")
1181
1264
  # frame = event_info.value
1182
1265
  # ```
1183
1266
  def expect_event(event, predicate: nil, timeout: nil, &block)
@@ -1228,13 +1311,13 @@ module Playwright
1228
1311
  # when this method is called. If current document has already reached the required state, resolves immediately.
1229
1312
  #
1230
1313
  # ```python sync
1231
- # page.click("button") # click triggers navigation.
1314
+ # page.get_by_role("button").click() # click triggers navigation.
1232
1315
  # page.wait_for_load_state() # the promise resolves after "load" event.
1233
1316
  # ```
1234
1317
  #
1235
1318
  # ```python sync
1236
1319
  # with page.expect_popup() as page_info:
1237
- # page.click("button") # click triggers a popup.
1320
+ # page.get_by_role("button").click() # click triggers a popup.
1238
1321
  # popup = page_info.value
1239
1322
  # # Following resolves after "domcontentloaded" event.
1240
1323
  # popup.wait_for_load_state("domcontentloaded")