playwright-ruby-client 1.16.1 → 1.18.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 (52) hide show
  1. checksums.yaml +4 -4
  2. data/documentation/docs/api/api_request_context.md +49 -0
  3. data/documentation/docs/api/download.md +1 -3
  4. data/documentation/docs/api/element_handle.md +2 -3
  5. data/documentation/docs/api/frame.md +31 -1
  6. data/documentation/docs/api/frame_locator.md +79 -0
  7. data/documentation/docs/api/locator.md +36 -49
  8. data/documentation/docs/api/page.md +34 -4
  9. data/documentation/docs/api/selectors.md +1 -1
  10. data/documentation/docs/api/tracing.md +2 -2
  11. data/documentation/docs/include/api_coverage.md +18 -0
  12. data/lib/playwright/channel_owners/artifact.rb +1 -6
  13. data/lib/playwright/channel_owners/browser.rb +6 -8
  14. data/lib/playwright/channel_owners/browser_context.rb +5 -3
  15. data/lib/playwright/channel_owners/browser_type.rb +0 -1
  16. data/lib/playwright/channel_owners/frame.rb +10 -6
  17. data/lib/playwright/channel_owners/local_utils.rb +14 -0
  18. data/lib/playwright/channel_owners/page.rb +13 -10
  19. data/lib/playwright/connection.rb +9 -0
  20. data/lib/playwright/frame_locator_impl.rb +50 -0
  21. data/lib/playwright/locator_impl.rb +75 -8
  22. data/lib/playwright/tracing_impl.rb +25 -14
  23. data/lib/playwright/version.rb +2 -2
  24. data/lib/playwright/video.rb +3 -0
  25. data/lib/playwright.rb +2 -1
  26. data/lib/playwright_api/android.rb +6 -6
  27. data/lib/playwright_api/android_device.rb +8 -8
  28. data/lib/playwright_api/api_request_context.rb +56 -6
  29. data/lib/playwright_api/browser.rb +6 -6
  30. data/lib/playwright_api/browser_context.rb +15 -10
  31. data/lib/playwright_api/browser_type.rb +6 -6
  32. data/lib/playwright_api/cdp_session.rb +6 -6
  33. data/lib/playwright_api/console_message.rb +6 -6
  34. data/lib/playwright_api/dialog.rb +6 -6
  35. data/lib/playwright_api/download.rb +0 -4
  36. data/lib/playwright_api/element_handle.rb +8 -9
  37. data/lib/playwright_api/frame.rb +34 -9
  38. data/lib/playwright_api/frame_locator.rb +60 -0
  39. data/lib/playwright_api/js_handle.rb +6 -6
  40. data/lib/playwright_api/local_utils.rb +9 -0
  41. data/lib/playwright_api/locator.rb +28 -48
  42. data/lib/playwright_api/page.rb +42 -12
  43. data/lib/playwright_api/playwright.rb +11 -6
  44. data/lib/playwright_api/request.rb +6 -6
  45. data/lib/playwright_api/response.rb +6 -6
  46. data/lib/playwright_api/route.rb +6 -6
  47. data/lib/playwright_api/selectors.rb +8 -8
  48. data/lib/playwright_api/tracing.rb +4 -4
  49. data/lib/playwright_api/web_socket.rb +6 -6
  50. data/lib/playwright_api/worker.rb +6 -6
  51. data/playwright.gemspec +1 -1
  52. metadata +11 -6
@@ -33,12 +33,6 @@ module Playwright
33
33
  wrap_impl(@impl.send_message(unwrap_impl(method), params: unwrap_impl(params)))
34
34
  end
35
35
 
36
- # -- inherited from EventEmitter --
37
- # @nodoc
38
- def off(event, callback)
39
- event_emitter_proxy.off(event, callback)
40
- end
41
-
42
36
  # -- inherited from EventEmitter --
43
37
  # @nodoc
44
38
  def once(event, callback)
@@ -51,6 +45,12 @@ module Playwright
51
45
  event_emitter_proxy.on(event, callback)
52
46
  end
53
47
 
48
+ # -- inherited from EventEmitter --
49
+ # @nodoc
50
+ def off(event, callback)
51
+ event_emitter_proxy.off(event, callback)
52
+ end
53
+
54
54
  private def event_emitter_proxy
55
55
  @event_emitter_proxy ||= EventEmitterProxy.new(self, @impl)
56
56
  end
@@ -23,12 +23,6 @@ module Playwright
23
23
  wrap_impl(@impl.type)
24
24
  end
25
25
 
26
- # -- inherited from EventEmitter --
27
- # @nodoc
28
- def off(event, callback)
29
- event_emitter_proxy.off(event, callback)
30
- end
31
-
32
26
  # -- inherited from EventEmitter --
33
27
  # @nodoc
34
28
  def once(event, callback)
@@ -41,6 +35,12 @@ module Playwright
41
35
  event_emitter_proxy.on(event, callback)
42
36
  end
43
37
 
38
+ # -- inherited from EventEmitter --
39
+ # @nodoc
40
+ def off(event, callback)
41
+ event_emitter_proxy.off(event, callback)
42
+ end
43
+
44
44
  private def event_emitter_proxy
45
45
  @event_emitter_proxy ||= EventEmitterProxy.new(self, @impl)
46
46
  end
@@ -58,12 +58,6 @@ module Playwright
58
58
  wrap_impl(@impl.accept_async(promptText: unwrap_impl(promptText)))
59
59
  end
60
60
 
61
- # -- inherited from EventEmitter --
62
- # @nodoc
63
- def off(event, callback)
64
- event_emitter_proxy.off(event, callback)
65
- end
66
-
67
61
  # -- inherited from EventEmitter --
68
62
  # @nodoc
69
63
  def once(event, callback)
@@ -76,6 +70,12 @@ module Playwright
76
70
  event_emitter_proxy.on(event, callback)
77
71
  end
78
72
 
73
+ # -- inherited from EventEmitter --
74
+ # @nodoc
75
+ def off(event, callback)
76
+ event_emitter_proxy.off(event, callback)
77
+ end
78
+
79
79
  private def event_emitter_proxy
80
80
  @event_emitter_proxy ||= EventEmitterProxy.new(self, @impl)
81
81
  end
@@ -12,10 +12,6 @@ module Playwright
12
12
  # # wait for download to complete
13
13
  # path = download.path()
14
14
  # ```
15
- #
16
- # > NOTE: Browser context **must** be created with the `acceptDownloads` set to `true` when user needs access to the
17
- # downloaded content. If `acceptDownloads` is not set, download events are emitted, but the actual download is not
18
- # performed and user has no access to the downloaded files.
19
15
  class Download < PlaywrightApi
20
16
 
21
17
  # Cancels a download. Will not fail if the download is already finished or canceled. Upon successful cancellations,
@@ -6,6 +6,8 @@ module Playwright
6
6
  # ElementHandle represents an in-page DOM element. ElementHandles can be created with the [`method: Page.querySelector`]
7
7
  # method.
8
8
  #
9
+ # > NOTE: The use of ElementHandle is discouraged, use `Locator` objects and web-first assertions instead.
10
+ #
9
11
  # ```python sync
10
12
  # href_element = page.query_selector("a")
11
13
  # href_element.click()
@@ -17,9 +19,6 @@ module Playwright
17
19
  # ElementHandle instances can be used as an argument in [`method: Page.evalOnSelector`] and [`method: Page.evaluate`]
18
20
  # methods.
19
21
  #
20
- # > NOTE: In most cases, you would want to use the `Locator` object instead. You should only use `ElementHandle` if you
21
- # want to retain a handle to a particular DOM Node that you intend to pass into [`method: Page.evaluate`] as an argument.
22
- #
23
22
  # The difference between the `Locator` and ElementHandle is that the ElementHandle points to a particular element, while
24
23
  # `Locator` captures the logic of how to retrieve an element.
25
24
  #
@@ -552,12 +551,6 @@ module Playwright
552
551
  wrap_impl(@impl.wait_for_selector(unwrap_impl(selector), state: unwrap_impl(state), strict: unwrap_impl(strict), timeout: unwrap_impl(timeout)))
553
552
  end
554
553
 
555
- # -- inherited from EventEmitter --
556
- # @nodoc
557
- def off(event, callback)
558
- event_emitter_proxy.off(event, callback)
559
- end
560
-
561
554
  # -- inherited from EventEmitter --
562
555
  # @nodoc
563
556
  def once(event, callback)
@@ -570,6 +563,12 @@ module Playwright
570
563
  event_emitter_proxy.on(event, callback)
571
564
  end
572
565
 
566
+ # -- inherited from EventEmitter --
567
+ # @nodoc
568
+ def off(event, callback)
569
+ event_emitter_proxy.off(event, callback)
570
+ end
571
+
573
572
  private def event_emitter_proxy
574
573
  @event_emitter_proxy ||= EventEmitterProxy.new(self, @impl)
575
574
  end
@@ -183,6 +183,9 @@ module Playwright
183
183
 
184
184
  # Returns the return value of `expression`.
185
185
  #
186
+ # > NOTE: This method does not wait for the element to pass actionability checks and therefore can lead to the flaky
187
+ # tests. Use [`method: Locator.evaluate`], other `Locator` helper methods or web-first assertions instead.
188
+ #
186
189
  # The method finds an element matching the specified selector within the frame and passes it as a first argument to
187
190
  # `expression`. See [Working with selectors](./selectors.md) for more details. If no elements match the selector, the
188
191
  # method throws an error.
@@ -203,6 +206,9 @@ module Playwright
203
206
 
204
207
  # Returns the return value of `expression`.
205
208
  #
209
+ # > NOTE: In most cases, [`method: Locator.evaluateAll`], other `Locator` helper methods and web-first assertions do a
210
+ # better job.
211
+ #
206
212
  # The method finds all elements matching the specified selector within the frame and passes an array of matched elements
207
213
  # as a first argument to `expression`. See [Working with selectors](./selectors.md) for more details.
208
214
  #
@@ -243,7 +249,7 @@ module Playwright
243
249
  # `ElementHandle` instances can be passed as an argument to the [`method: Frame.evaluate`]:
244
250
  #
245
251
  # ```python sync
246
- # body_handle = frame.query_selector("body")
252
+ # body_handle = frame.evaluate("document.body")
247
253
  # html = frame.evaluate("([body, suffix]) => body.innerHTML + suffix", [body_handle, "hello"])
248
254
  # body_handle.dispose()
249
255
  # ```
@@ -324,6 +330,18 @@ module Playwright
324
330
  wrap_impl(@impl.frame_element)
325
331
  end
326
332
 
333
+ # When working with iframes, you can create a frame locator that will enter the iframe and allow selecting elements in
334
+ # that iframe. Following snippet locates element with text "Submit" in the iframe with id `my-frame`, like `<iframe
335
+ # id="my-frame">`:
336
+ #
337
+ # ```python sync
338
+ # locator = frame.frame_locator("#my-iframe").locator("text=Submit")
339
+ # locator.click()
340
+ # ```
341
+ def frame_locator(selector)
342
+ wrap_impl(@impl.frame_locator(unwrap_impl(selector)))
343
+ end
344
+
327
345
  # Returns element attribute value.
328
346
  def get_attribute(selector, name, strict: nil, timeout: nil)
329
347
  wrap_impl(@impl.get_attribute(unwrap_impl(selector), unwrap_impl(name), strict: unwrap_impl(strict), timeout: unwrap_impl(timeout)))
@@ -427,8 +445,8 @@ module Playwright
427
445
  # The method returns an element locator that can be used to perform actions in the frame. Locator is resolved to the
428
446
  # element immediately before performing an action, so a series of actions on the same locator can in fact be performed on
429
447
  # different DOM elements. That would happen if the DOM structure between those actions has changed.
430
- def locator(selector)
431
- wrap_impl(@impl.locator(unwrap_impl(selector)))
448
+ def locator(selector, hasText: nil)
449
+ wrap_impl(@impl.locator(unwrap_impl(selector), hasText: unwrap_impl(hasText)))
432
450
  end
433
451
 
434
452
  # Returns frame's name attribute as specified in the tag.
@@ -478,6 +496,8 @@ module Playwright
478
496
 
479
497
  # Returns the ElementHandle pointing to the frame element.
480
498
  #
499
+ # > NOTE: The use of `ElementHandle` is discouraged, use `Locator` objects and web-first assertions instead.
500
+ #
481
501
  # The method finds an element matching the specified selector within the frame. See
482
502
  # [Working with selectors](./selectors.md) for more details. If no elements match the selector, returns `null`.
483
503
  def query_selector(selector, strict: nil)
@@ -486,6 +506,8 @@ module Playwright
486
506
 
487
507
  # Returns the ElementHandles pointing to the frame elements.
488
508
  #
509
+ # > NOTE: The use of `ElementHandle` is discouraged, use `Locator` objects instead.
510
+ #
489
511
  # The method finds all elements matching the specified selector within the frame. See
490
512
  # [Working with selectors](./selectors.md) for more details. If no elements match the selector, returns empty array.
491
513
  def query_selector_all(selector)
@@ -714,6 +736,9 @@ module Playwright
714
736
  # Returns when element specified by selector satisfies `state` option. Returns `null` if waiting for `hidden` or
715
737
  # `detached`.
716
738
  #
739
+ # > NOTE: Playwright automatically waits for element to be ready before performing an action. Using `Locator` objects and
740
+ # web-first assertions make the code wait-for-selector-free.
741
+ #
717
742
  # Wait for the `selector` to satisfy `state` option (either appear/disappear from dom, or become visible/hidden). If at
718
743
  # the moment of calling the method `selector` already satisfies the condition, the method will return immediately. If the
719
744
  # selector doesn't satisfy the condition for the `timeout` milliseconds, the function will throw.
@@ -763,12 +788,6 @@ module Playwright
763
788
  wrap_impl(@impl.detached=(unwrap_impl(req)))
764
789
  end
765
790
 
766
- # -- inherited from EventEmitter --
767
- # @nodoc
768
- def off(event, callback)
769
- event_emitter_proxy.off(event, callback)
770
- end
771
-
772
791
  # -- inherited from EventEmitter --
773
792
  # @nodoc
774
793
  def once(event, callback)
@@ -781,6 +800,12 @@ module Playwright
781
800
  event_emitter_proxy.on(event, callback)
782
801
  end
783
802
 
803
+ # -- inherited from EventEmitter --
804
+ # @nodoc
805
+ def off(event, callback)
806
+ event_emitter_proxy.off(event, callback)
807
+ end
808
+
784
809
  private def event_emitter_proxy
785
810
  @event_emitter_proxy ||= EventEmitterProxy.new(self, @impl)
786
811
  end
@@ -0,0 +1,60 @@
1
+ module Playwright
2
+ # FrameLocator represents a view to the `iframe` on the page. It captures the logic sufficient to retrieve the `iframe`
3
+ # and locate elements in that iframe. FrameLocator can be created with either [`method: Page.frameLocator`] or
4
+ # [`method: Locator.frameLocator`] method.
5
+ #
6
+ # ```python sync
7
+ # locator = page.frame_locator("my-frame").locator("text=Submit")
8
+ # locator.click()
9
+ # ```
10
+ #
11
+ # **Strictness**
12
+ #
13
+ # Frame locators are strict. This means that all operations on frame locators will throw if more than one element matches
14
+ # given selector.
15
+ #
16
+ # ```python sync
17
+ # # Throws if there are several frames in DOM:
18
+ # page.frame_locator('.result-frame').locator('button').click()
19
+ #
20
+ # # Works because we explicitly tell locator to pick the first frame:
21
+ # page.frame_locator('.result-frame').first.locator('button').click()
22
+ # ```
23
+ #
24
+ # **Converting Locator to FrameLocator**
25
+ #
26
+ # If you have a `Locator` object pointing to an `iframe` it can be converted to `FrameLocator` using
27
+ # [`:scope`](https://developer.mozilla.org/en-US/docs/Web/CSS/:scope) CSS selector:
28
+ #
29
+ # ```python sync
30
+ # frameLocator = locator.frame_locator(":scope");
31
+ # ```
32
+ class FrameLocator < PlaywrightApi
33
+
34
+ # Returns locator to the first matching frame.
35
+ def first
36
+ wrap_impl(@impl.first)
37
+ end
38
+
39
+ # When working with iframes, you can create a frame locator that will enter the iframe and allow selecting elements in
40
+ # that iframe.
41
+ def frame_locator(selector)
42
+ wrap_impl(@impl.frame_locator(unwrap_impl(selector)))
43
+ end
44
+
45
+ # Returns locator to the last matching frame.
46
+ def last
47
+ wrap_impl(@impl.last)
48
+ end
49
+
50
+ # The method finds an element matching the specified selector in the FrameLocator's subtree.
51
+ def locator(selector, hasText: nil)
52
+ wrap_impl(@impl.locator(unwrap_impl(selector), hasText: unwrap_impl(hasText)))
53
+ end
54
+
55
+ # Returns locator to the n-th matching frame.
56
+ def nth(index)
57
+ wrap_impl(@impl.nth(unwrap_impl(index)))
58
+ end
59
+ end
60
+ end
@@ -88,12 +88,6 @@ module Playwright
88
88
  wrap_impl(@impl.to_s)
89
89
  end
90
90
 
91
- # -- inherited from EventEmitter --
92
- # @nodoc
93
- def off(event, callback)
94
- event_emitter_proxy.off(event, callback)
95
- end
96
-
97
91
  # -- inherited from EventEmitter --
98
92
  # @nodoc
99
93
  def once(event, callback)
@@ -106,6 +100,12 @@ module Playwright
106
100
  event_emitter_proxy.on(event, callback)
107
101
  end
108
102
 
103
+ # -- inherited from EventEmitter --
104
+ # @nodoc
105
+ def off(event, callback)
106
+ event_emitter_proxy.off(event, callback)
107
+ end
108
+
109
109
  private def event_emitter_proxy
110
110
  @event_emitter_proxy ||= EventEmitterProxy.new(self, @impl)
111
111
  end
@@ -0,0 +1,9 @@
1
+ module Playwright
2
+ class LocalUtils < PlaywrightApi
3
+
4
+ # @nodoc
5
+ def zip(zip_file, name_value_array)
6
+ wrap_impl(@impl.zip(unwrap_impl(zip_file), unwrap_impl(name_value_array)))
7
+ end
8
+ end
9
+ end
@@ -1,49 +1,8 @@
1
1
  module Playwright
2
- # Locator represents a view to the element(s) on the page. It captures the logic sufficient to retrieve the element at any
3
- # given moment. Locator can be created with the [`method: Page.locator`] method.
2
+ # Locators are the central piece of Playwright's auto-waiting and retry-ability. In a nutshell, locators represent a way
3
+ # to find element(s) on the page at any moment. Locator can be created with the [`method: Page.locator`] method.
4
4
  #
5
- # ```python sync
6
- # locator = page.locator("text=Submit")
7
- # locator.click()
8
- # ```
9
- #
10
- # The difference between the Locator and `ElementHandle` is that the latter points to a particular element, while Locator
11
- # captures the logic of how to retrieve that element.
12
- #
13
- # In the example below, handle points to a particular DOM element on page. If that element changes text or is used by
14
- # React to render an entirely different component, handle is still pointing to that very DOM element. This can lead to
15
- # unexpected behaviors.
16
- #
17
- # ```python sync
18
- # handle = page.query_selector("text=Submit")
19
- # handle.hover()
20
- # handle.click()
21
- # ```
22
- #
23
- # With the locator, every time the `element` is used, up-to-date DOM element is located in the page using the selector. So
24
- # in the snippet below, underlying DOM element is going to be located twice.
25
- #
26
- # ```python sync
27
- # locator = page.locator("text=Submit")
28
- # locator.hover()
29
- # locator.click()
30
- # ```
31
- #
32
- # **Strictness**
33
- #
34
- # Locators are strict. This means that all operations on locators that imply some target DOM element will throw if more
35
- # than one element matches given selector.
36
- #
37
- # ```python sync
38
- # # Throws if there are several buttons in DOM:
39
- # page.locator('button').click()
40
- #
41
- # # Works because we explicitly tell locator to pick the first element:
42
- # page.locator('button').first.click()
43
- #
44
- # # Works because count knows what to do with multiple matches:
45
- # page.locator('button').count()
46
- # ```
5
+ # [Learn more about locators](./locators.md).
47
6
  class Locator < PlaywrightApi
48
7
 
49
8
  # Returns an array of `node.innerText` values for all matching nodes.
@@ -183,6 +142,17 @@ module Playwright
183
142
  wrap_impl(@impl.dispatch_event(unwrap_impl(type), eventInit: unwrap_impl(eventInit), timeout: unwrap_impl(timeout)))
184
143
  end
185
144
 
145
+ def drag_to(
146
+ target,
147
+ force: nil,
148
+ noWaitAfter: nil,
149
+ sourcePosition: nil,
150
+ targetPosition: nil,
151
+ timeout: nil,
152
+ trial: nil)
153
+ wrap_impl(@impl.drag_to(unwrap_impl(target), force: unwrap_impl(force), noWaitAfter: unwrap_impl(noWaitAfter), sourcePosition: unwrap_impl(sourcePosition), targetPosition: unwrap_impl(targetPosition), timeout: unwrap_impl(timeout), trial: unwrap_impl(trial)))
154
+ end
155
+
186
156
  # Resolves given locator to the first matching DOM element. If no elements matching the query are visible, waits for them
187
157
  # up to a given timeout. If multiple elements match the selector, throws.
188
158
  def element_handle(timeout: nil)
@@ -264,6 +234,17 @@ module Playwright
264
234
  wrap_impl(@impl.focus(timeout: unwrap_impl(timeout)))
265
235
  end
266
236
 
237
+ # When working with iframes, you can create a frame locator that will enter the iframe and allow selecting elements in
238
+ # that iframe:
239
+ #
240
+ # ```python sync
241
+ # locator = page.frame_locator("text=Submit").locator("text=Submit")
242
+ # locator.click()
243
+ # ```
244
+ def frame_locator(selector)
245
+ wrap_impl(@impl.frame_locator(unwrap_impl(selector)))
246
+ end
247
+
267
248
  # Returns element attribute value.
268
249
  def get_attribute(name, timeout: nil)
269
250
  wrap_impl(@impl.get_attribute(unwrap_impl(name), timeout: unwrap_impl(timeout)))
@@ -338,10 +319,9 @@ module Playwright
338
319
  wrap_impl(@impl.last)
339
320
  end
340
321
 
341
- # The method finds an element matching the specified selector in the `Locator`'s subtree. See
342
- # [Working with selectors](./selectors.md) for more details.
343
- def locator(selector)
344
- wrap_impl(@impl.locator(unwrap_impl(selector)))
322
+ # The method finds an element matching the specified selector in the `Locator`'s subtree.
323
+ def locator(selector, hasText: nil)
324
+ wrap_impl(@impl.locator(unwrap_impl(selector), hasText: unwrap_impl(hasText)))
345
325
  end
346
326
 
347
327
  # Returns locator to the n-th matching element.
@@ -56,6 +56,11 @@ module Playwright
56
56
  wrap_impl(@impl.mouse)
57
57
  end
58
58
 
59
+ # API testing helper associated with this page. Requests made with this API will use page cookies.
60
+ def request # property
61
+ raise NotImplementedError.new('request is not implemented yet.')
62
+ end
63
+
59
64
  def touchscreen # property
60
65
  wrap_impl(@impl.touchscreen)
61
66
  end
@@ -288,6 +293,9 @@ module Playwright
288
293
  wrap_impl(@impl.emulate_media(colorScheme: unwrap_impl(colorScheme), forcedColors: unwrap_impl(forcedColors), media: unwrap_impl(media), reducedMotion: unwrap_impl(reducedMotion)))
289
294
  end
290
295
 
296
+ # > NOTE: This method does not wait for the element to pass actionability checks and therefore can lead to the flaky
297
+ # tests. Use [`method: Locator.evaluate`], other `Locator` helper methods or web-first assertions instead.
298
+ #
291
299
  # The method finds an element matching the specified selector within the page and passes it as a first argument to
292
300
  # `expression`. If no elements match the selector, the method throws an error. Returns the value of `expression`.
293
301
  #
@@ -307,6 +315,9 @@ module Playwright
307
315
  wrap_impl(@impl.eval_on_selector(unwrap_impl(selector), unwrap_impl(expression), arg: unwrap_impl(arg), strict: unwrap_impl(strict)))
308
316
  end
309
317
 
318
+ # > NOTE: In most cases, [`method: Locator.evaluateAll`], other `Locator` helper methods and web-first assertions do a
319
+ # better job.
320
+ #
310
321
  # The method finds all elements matching the specified selector within the page and passes an array of matched elements as
311
322
  # a first argument to `expression`. Returns the result of `expression` invocation.
312
323
  #
@@ -349,7 +360,7 @@ module Playwright
349
360
  # `ElementHandle` instances can be passed as an argument to the [`method: Page.evaluate`]:
350
361
  #
351
362
  # ```python sync
352
- # body_handle = page.query_selector("body")
363
+ # body_handle = page.evaluate("document.body")
353
364
  # html = page.evaluate("([body, suffix]) => body.innerHTML + suffix", [body_handle, "hello"])
354
365
  # body_handle.dispose()
355
366
  # ```
@@ -533,6 +544,18 @@ module Playwright
533
544
  wrap_impl(@impl.frame(name: unwrap_impl(name), url: unwrap_impl(url)))
534
545
  end
535
546
 
547
+ # When working with iframes, you can create a frame locator that will enter the iframe and allow selecting elements in
548
+ # that iframe. Following snippet locates element with text "Submit" in the iframe with id `my-frame`, like `<iframe
549
+ # id="my-frame">`:
550
+ #
551
+ # ```python sync
552
+ # locator = page.frame_locator("#my-iframe").locator("text=Submit")
553
+ # locator.click()
554
+ # ```
555
+ def frame_locator(selector)
556
+ wrap_impl(@impl.frame_locator(unwrap_impl(selector)))
557
+ end
558
+
536
559
  # An array of all frames attached to the page.
537
560
  def frames
538
561
  wrap_impl(@impl.frames)
@@ -663,8 +686,8 @@ module Playwright
663
686
  # different DOM elements. That would happen if the DOM structure between those actions has changed.
664
687
  #
665
688
  # Shortcut for main frame's [`method: Frame.locator`].
666
- def locator(selector)
667
- wrap_impl(@impl.locator(unwrap_impl(selector)))
689
+ def locator(selector, hasText: nil)
690
+ wrap_impl(@impl.locator(unwrap_impl(selector), hasText: unwrap_impl(hasText)))
668
691
  end
669
692
 
670
693
  # The page's main frame. Page is guaranteed to have a main frame which persists during navigations.
@@ -791,14 +814,18 @@ module Playwright
791
814
  wrap_impl(@impl.press(unwrap_impl(selector), unwrap_impl(key), delay: unwrap_impl(delay), noWaitAfter: unwrap_impl(noWaitAfter), strict: unwrap_impl(strict), timeout: unwrap_impl(timeout)))
792
815
  end
793
816
 
817
+ # > NOTE: The use of `ElementHandle` is discouraged, use `Locator` objects and web-first assertions instead.
818
+ #
794
819
  # The method finds an element matching the specified selector within the page. If no elements match the selector, the
795
- # return value resolves to `null`. To wait for an element on the page, use [`method: Page.waitForSelector`].
820
+ # return value resolves to `null`. To wait for an element on the page, use [`method: Locator.waitFor`].
796
821
  #
797
822
  # Shortcut for main frame's [`method: Frame.querySelector`].
798
823
  def query_selector(selector, strict: nil)
799
824
  wrap_impl(@impl.query_selector(unwrap_impl(selector), strict: unwrap_impl(strict)))
800
825
  end
801
826
 
827
+ # > NOTE: The use of `ElementHandle` is discouraged, use `Locator` objects and web-first assertions instead.
828
+ #
802
829
  # The method finds all elements matching the specified selector within the page. If no elements match the selector, the
803
830
  # return value resolves to `[]`.
804
831
  #
@@ -807,8 +834,8 @@ module Playwright
807
834
  wrap_impl(@impl.query_selector_all(unwrap_impl(selector)))
808
835
  end
809
836
 
810
- # Returns the main resource response. In case of multiple redirects, the navigation will resolve with the response of the
811
- # last redirect.
837
+ # This method reloads the current page, in the same way as if the user had triggered a browser refresh. Returns the main
838
+ # resource response. In case of multiple redirects, the navigation will resolve with the response of the last redirect.
812
839
  def reload(timeout: nil, waitUntil: nil)
813
840
  wrap_impl(@impl.reload(timeout: unwrap_impl(timeout), waitUntil: unwrap_impl(waitUntil)))
814
841
  end
@@ -1267,6 +1294,9 @@ module Playwright
1267
1294
  # Returns when element specified by selector satisfies `state` option. Returns `null` if waiting for `hidden` or
1268
1295
  # `detached`.
1269
1296
  #
1297
+ # > NOTE: Playwright automatically waits for element to be ready before performing an action. Using `Locator` objects and
1298
+ # web-first assertions make the code wait-for-selector-free.
1299
+ #
1270
1300
  # Wait for the `selector` to satisfy `state` option (either appear/disappear from dom, or become visible/hidden). If at
1271
1301
  # the moment of calling the method `selector` already satisfies the condition, the method will return immediately. If the
1272
1302
  # selector doesn't satisfy the condition for the `timeout` milliseconds, the function will throw.
@@ -1381,12 +1411,6 @@ module Playwright
1381
1411
  wrap_impl(@impl.guid)
1382
1412
  end
1383
1413
 
1384
- # -- inherited from EventEmitter --
1385
- # @nodoc
1386
- def off(event, callback)
1387
- event_emitter_proxy.off(event, callback)
1388
- end
1389
-
1390
1414
  # -- inherited from EventEmitter --
1391
1415
  # @nodoc
1392
1416
  def once(event, callback)
@@ -1399,6 +1423,12 @@ module Playwright
1399
1423
  event_emitter_proxy.on(event, callback)
1400
1424
  end
1401
1425
 
1426
+ # -- inherited from EventEmitter --
1427
+ # @nodoc
1428
+ def off(event, callback)
1429
+ event_emitter_proxy.off(event, callback)
1430
+ end
1431
+
1402
1432
  private def event_emitter_proxy
1403
1433
  @event_emitter_proxy ||= EventEmitterProxy.new(self, @impl)
1404
1434
  end
@@ -50,6 +50,11 @@ module Playwright
50
50
  wrap_impl(@impl.firefox)
51
51
  end
52
52
 
53
+ # Exposes API that can be used for the Web API testing.
54
+ def request # property
55
+ raise NotImplementedError.new('request is not implemented yet.')
56
+ end
57
+
53
58
  # Selectors can be used to install custom selector engines. See [Working with selectors](./selectors.md) for more
54
59
  # information.
55
60
  def selectors # property
@@ -91,12 +96,6 @@ module Playwright
91
96
  wrap_impl(@impl.electron)
92
97
  end
93
98
 
94
- # -- inherited from EventEmitter --
95
- # @nodoc
96
- def off(event, callback)
97
- event_emitter_proxy.off(event, callback)
98
- end
99
-
100
99
  # -- inherited from EventEmitter --
101
100
  # @nodoc
102
101
  def once(event, callback)
@@ -109,6 +108,12 @@ module Playwright
109
108
  event_emitter_proxy.on(event, callback)
110
109
  end
111
110
 
111
+ # -- inherited from EventEmitter --
112
+ # @nodoc
113
+ def off(event, callback)
114
+ event_emitter_proxy.off(event, callback)
115
+ end
116
+
112
117
  private def event_emitter_proxy
113
118
  @event_emitter_proxy ||= EventEmitterProxy.new(self, @impl)
114
119
  end
@@ -154,12 +154,6 @@ module Playwright
154
154
  wrap_impl(@impl.header_values(unwrap_impl(name)))
155
155
  end
156
156
 
157
- # -- inherited from EventEmitter --
158
- # @nodoc
159
- def off(event, callback)
160
- event_emitter_proxy.off(event, callback)
161
- end
162
-
163
157
  # -- inherited from EventEmitter --
164
158
  # @nodoc
165
159
  def once(event, callback)
@@ -172,6 +166,12 @@ module Playwright
172
166
  event_emitter_proxy.on(event, callback)
173
167
  end
174
168
 
169
+ # -- inherited from EventEmitter --
170
+ # @nodoc
171
+ def off(event, callback)
172
+ event_emitter_proxy.off(event, callback)
173
+ end
174
+
175
175
  private def event_emitter_proxy
176
176
  @event_emitter_proxy ||= EventEmitterProxy.new(self, @impl)
177
177
  end
@@ -97,12 +97,6 @@ module Playwright
97
97
  wrap_impl(@impl.ok?)
98
98
  end
99
99
 
100
- # -- inherited from EventEmitter --
101
- # @nodoc
102
- def off(event, callback)
103
- event_emitter_proxy.off(event, callback)
104
- end
105
-
106
100
  # -- inherited from EventEmitter --
107
101
  # @nodoc
108
102
  def once(event, callback)
@@ -115,6 +109,12 @@ module Playwright
115
109
  event_emitter_proxy.on(event, callback)
116
110
  end
117
111
 
112
+ # -- inherited from EventEmitter --
113
+ # @nodoc
114
+ def off(event, callback)
115
+ event_emitter_proxy.off(event, callback)
116
+ end
117
+
118
118
  private def event_emitter_proxy
119
119
  @event_emitter_proxy ||= EventEmitterProxy.new(self, @impl)
120
120
  end