playwright-ruby-client 1.16.beta1 → 1.17.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ac716fcd59a6c1b520004d0c5797dadaf77d8a5ec78dd60903cd424a2d9569ca
-  data.tar.gz: 6ec8fb266d6ce38229ee17e68dec62e5ba42edb09ddd59814242fe5dd757c157
+  metadata.gz: 35d4a4e4ac3aa460997a5a9cd44b5272142ba89b480908f0e429fb97d7968337
+  data.tar.gz: 2a577b8683a2eba60ed97b88b183bd351477cbde0874b8d06d287be0ec4664e8
 SHA512:
-  metadata.gz: 3c3fc4e0689b164b90791c9c288895966de3c42275df2c46f89fcd19999df2d830dd9fa081532d106a178ae17cd18807240ab3fe3c07f287f9906777b3bb0c72
-  data.tar.gz: cec2ee542633b9b7c803de01fc3b700a7b78eeac15e156dca97d99b62f9142c9f749e90a006b44bf9d7108ffeed63329b64003da53603fd02fcb75374f6a33e1
+  metadata.gz: 283b87141e9ab9090488684973741983506da16d9ea991945589a1177cd99a5cf2c3b65b35770cc95a6ed3645514c35c9925e75aaffb949d58cbe6a47380c334
+  data.tar.gz: 7a6071b83e537784b58e6b350c1654a7dfa90bc99576f8ae1780c2104b30242ddd2e9651f6eb9f880a3a777e9345a5706373fbd66b64cc32739ce10cb389b5fb

data/documentation/docs/api/{fetch_request.md → api_request_context.md}

@@ -2,9 +2,9 @@
 sidebar_position: 10
 ---
 
-# FetchRequest
+# APIRequestContext
 
-This API is used for Web API testing. You can use it to trigger API endpoints, configure micro-services, prepare
+This API is used for the Web API testing. You can use it to trigger API endpoints, configure micro-services, prepare
 environment or the service to your e2e test. When used on [Page](./page) or a [BrowserContext](./browser_context), this API will automatically use
 the cookies from the corresponding [BrowserContext](./browser_context). This means that if you log in using this API, your e2e test will be
 logged in and vice versa.

data/documentation/docs/api/browser_context.md

@@ -11,7 +11,7 @@ BrowserContexts provide a way to operate multiple independent browser sessions.
 If a page opens another page, e.g. with a `window.open` call, the popup will belong to the parent page's browser
 context.
 
-Playwright allows creation of "incognito" browser contexts with [Browser#new_context](./browser#new_context) method. "Incognito" browser
+Playwright allows creating "incognito" browser contexts with [Browser#new_context](./browser#new_context) method. "Incognito" browser
 contexts don't write any browsing data to disk.
 
 ```ruby

data/documentation/docs/api/element_handle.md

@@ -9,6 +9,8 @@ sidebar_position: 10
 ElementHandle represents an in-page DOM element. ElementHandles can be created with the [Page#query_selector](./page#query_selector)
 method.
 
+> NOTE: The use of ElementHandle is discouraged, use [Locator](./locator) objects and web-first assertions instead.
+
 ```ruby
 href_element = page.query_selector("a")
 href_element.click
@@ -20,9 +22,6 @@ ElementHandle prevents DOM element from garbage collection unless the handle is
 ElementHandle instances can be used as an argument in [Page#eval_on_selector](./page#eval_on_selector) and [Page#evaluate](./page#evaluate)
 methods.
 
-> NOTE: In most cases, you would want to use the [Locator](./locator) object instead. You should only use [ElementHandle](./element_handle) if you
-want to retain a handle to a particular DOM Node that you intend to pass into [Page#evaluate](./page#evaluate) as an argument.
-
 The difference between the [Locator](./locator) and ElementHandle is that the ElementHandle points to a particular element, while
 [Locator](./locator) captures the logic of how to retrieve an element.
 

data/documentation/docs/api/frame.md

@@ -218,6 +218,9 @@ def eval_on_selector(selector, expression, arg: nil, strict: nil)
 
 Returns the return value of `expression`.
 
+> NOTE: This method does not wait for the element to pass actionability checks and therefore can lead to the flaky
+tests. Use [Locator#evaluate](./locator#evaluate), other [Locator](./locator) helper methods or web-first assertions instead.
+
 The method finds an element matching the specified selector within the frame and passes it as a first argument to
 `expression`. See [Working with selectors](https://playwright.dev/python/docs/selectors) for more details. If no elements match the selector, the
 method throws an error.
@@ -243,6 +246,9 @@ def eval_on_selector_all(selector, expression, arg: nil)
 
 Returns the return value of `expression`.
 
+> NOTE: In most cases, [Locator#evaluate_all](./locator#evaluate_all), other [Locator](./locator) helper methods and web-first assertions do a
+better job.
+
 The method finds all elements matching the specified selector within the frame and passes an array of matched elements
 as a first argument to `expression`. See [Working with selectors](https://playwright.dev/python/docs/selectors) for more details.
 
@@ -384,6 +390,23 @@ puts frame == content_frame # => true
 
 
 
+## frame_locator
+
+```
+def frame_locator(selector)
+```
+
+When working with iframes, you can create a frame locator that will enter the iframe and allow selecting elements in
+that iframe. Following snippet locates element with text "Submit" in the iframe with id `my-frame`, like `<iframe
+id="my-frame">`:
+
+```ruby
+locator = frame.frame_locator("#my-iframe").locator("text=Submit")
+locator.click
+```
+
+
+
 ## get_attribute
 
 ```
@@ -598,6 +621,8 @@ def query_selector(selector, strict: nil)
 
 Returns the ElementHandle pointing to the frame element.
 
+> NOTE: The use of [ElementHandle](./element_handle) is discouraged, use [Locator](./locator) objects and web-first assertions instead.
+
 The method finds an element matching the specified selector within the frame. See
 [Working with selectors](https://playwright.dev/python/docs/selectors) for more details. If no elements match the selector, returns `null`.
 
@@ -609,6 +634,8 @@ def query_selector_all(selector)
 
 Returns the ElementHandles pointing to the frame elements.
 
+> NOTE: The use of [ElementHandle](./element_handle) is discouraged, use [Locator](./locator) objects instead.
+
 The method finds all elements matching the specified selector within the frame. See
 [Working with selectors](https://playwright.dev/python/docs/selectors) for more details. If no elements match the selector, returns empty array.
 
@@ -878,6 +905,9 @@ def wait_for_selector(selector, state: nil, strict: nil, timeout: nil)
 Returns when element specified by selector satisfies `state` option. Returns `null` if waiting for `hidden` or
 `detached`.
 
+> NOTE: Playwright automatically waits for element to be ready before performing an action. Using [Locator](./locator) objects and
+web-first assertions make the code wait-for-selector-free.
+
 Wait for the `selector` to satisfy `state` option (either appear/disappear from dom, or become visible/hidden). If at
 the moment of calling the method `selector` already satisfies the condition, the method will return immediately. If the
 selector doesn't satisfy the condition for the `timeout` milliseconds, the function will throw.

data/documentation/docs/api/frame_locator.md

@@ -0,0 +1,70 @@
+---
+sidebar_position: 10
+---
+
+# FrameLocator
+
+FrameLocator represents a view to the `iframe` on the page. It captures the logic sufficient to retrieve the `iframe`
+and locate elements in that iframe. FrameLocator can be created with either [Page#frame_locator](./page#frame_locator) or
+[Locator#frame_locator](./locator#frame_locator) method.
+
+```ruby
+locator = page.frame_locator("my-frame").locator("text=Submit")
+locator.click
+```
+
+**Strictness**
+
+Frame locators are strict. This means that all operations on frame locators will throw if more than one element matches
+given selector.
+
+```ruby
+# Throws if there are several frames in DOM:
+page.frame_locator('.result-frame').locator('button').click
+
+# Works because we explicitly tell locator to pick the first frame:
+page.frame_locator('.result-frame').first.locator('button').click
+```
+
+
+
+## first
+
+```
+def first
+```
+
+Returns locator to the first matching frame.
+
+## frame_locator
+
+```
+def frame_locator(selector)
+```
+
+When working with iframes, you can create a frame locator that will enter the iframe and allow selecting elements in
+that iframe.
+
+## last
+
+```
+def last
+```
+
+Returns locator to the last matching frame.
+
+## locator
+
+```
+def locator(selector)
+```
+
+The method finds an element matching the specified selector in the FrameLocator's subtree.
+
+## nth
+
+```
+def nth(index)
+```
+
+Returns locator to the n-th matching frame.

data/documentation/docs/api/locator.md

@@ -329,6 +329,22 @@ def focus(timeout: nil)
 
 Calls [focus](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/focus) on the element.
 
+## frame_locator
+
+```
+def frame_locator(selector)
+```
+
+When working with iframes, you can create a frame locator that will enter the iframe and allow selecting elements in
+that iframe:
+
+```ruby
+locator = page.frame_locator("text=Submit").locator("text=Submit")
+locator.click
+```
+
+
+
 ## get_attribute
 
 ```
@@ -445,8 +461,7 @@ Returns locator to the last matching element.
 def locator(selector)
 ```
 
-The method finds an element matching the specified selector in the [Locator](./locator)'s subtree. See
-[Working with selectors](https://playwright.dev/python/docs/selectors) for more details.
+The method finds an element matching the specified selector in the [Locator](./locator)'s subtree.
 
 ## nth
 

data/documentation/docs/api/page.md

@@ -315,6 +315,9 @@ page.evaluate("matchMedia('(prefers-color-scheme: no-preference)').matches") # =
 def eval_on_selector(selector, expression, arg: nil, strict: nil)
 ```
 
+> NOTE: This method does not wait for the element to pass actionability checks and therefore can lead to the flaky
+tests. Use [Locator#evaluate](./locator#evaluate), other [Locator](./locator) helper methods or web-first assertions instead.
+
 The method finds an element matching the specified selector within the page and passes it as a first argument to
 `expression`. If no elements match the selector, the method throws an error. Returns the value of `expression`.
 
@@ -337,6 +340,9 @@ Shortcut for main frame's [Frame#eval_on_selector](./frame#eval_on_selector).
 def eval_on_selector_all(selector, expression, arg: nil)
 ```
 
+> NOTE: In most cases, [Locator#evaluate_all](./locator#evaluate_all), other [Locator](./locator) helper methods and web-first assertions do a
+better job.
+
 The method finds all elements matching the specified selector within the page and passes an array of matched elements as
 a first argument to `expression`. Returns the result of `expression` invocation.
 
@@ -575,6 +581,23 @@ frame = page.frame(url: /.*domain.*/)
 
 
 
+## frame_locator
+
+```
+def frame_locator(selector)
+```
+
+When working with iframes, you can create a frame locator that will enter the iframe and allow selecting elements in
+that iframe. Following snippet locates element with text "Submit" in the iframe with id `my-frame`, like `<iframe
+id="my-frame">`:
+
+```ruby
+locator = page.frame_locator("#my-iframe").locator("text=Submit")
+locator.click
+```
+
+
+
 ## frames
 
 ```
@@ -905,8 +928,10 @@ page.screenshot(path: "o.png")
 def query_selector(selector, strict: nil)
 ```
 
+> NOTE: The use of [ElementHandle](./element_handle) is discouraged, use [Locator](./locator) objects and web-first assertions instead.
+
 The method finds an element matching the specified selector within the page. If no elements match the selector, the
-return value resolves to `null`. To wait for an element on the page, use [Page#wait_for_selector](./page#wait_for_selector).
+return value resolves to `null`. To wait for an element on the page, use [Locator#wait_for](./locator#wait_for).
 
 Shortcut for main frame's [Frame#query_selector](./frame#query_selector).
 
@@ -916,6 +941,8 @@ Shortcut for main frame's [Frame#query_selector](./frame#query_selector).
 def query_selector_all(selector)
 ```
 
+> NOTE: The use of [ElementHandle](./element_handle) is discouraged, use [Locator](./locator) objects and web-first assertions instead.
+
 The method finds all elements matching the specified selector within the page. If no elements match the selector, the
 return value resolves to `[]`.
 
@@ -927,8 +954,8 @@ Shortcut for main frame's [Frame#query_selector_all](./frame#query_selector_all)
 def reload(timeout: nil, waitUntil: nil)
 ```
 
-Returns the main resource response. In case of multiple redirects, the navigation will resolve with the response of the
-last redirect.
+This method reloads the current page, in the same way as if the user had triggered a browser refresh. Returns the main
+resource response. In case of multiple redirects, the navigation will resolve with the response of the last redirect.
 
 ## route
 
@@ -1141,7 +1168,8 @@ In the case of multiple pages in a single browser, each page can have its own vi
 [Browser#new_context](./browser#new_context) allows to set viewport size (and more) for all pages in the context at once.
 
 `page.setViewportSize` will resize the page. A lot of websites don't expect phones to change size, so you should set the
-viewport size before navigating to the page.
+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.
 
 ```ruby
 page.viewport_size = { width: 640, height: 480 }
@@ -1483,6 +1511,9 @@ def wait_for_selector(selector, state: nil, strict: nil, timeout: nil)
 Returns when element specified by selector satisfies `state` option. Returns `null` if waiting for `hidden` or
 `detached`.
 
+> NOTE: Playwright automatically waits for element to be ready before performing an action. Using [Locator](./locator) objects and
+web-first assertions make the code wait-for-selector-free.
+
 Wait for the `selector` to satisfy `state` option (either appear/disappear from dom, or become visible/hidden). If at
 the moment of calling the method `selector` already satisfies the condition, the method will return immediately. If the
 selector doesn't satisfy the condition for the `timeout` milliseconds, the function will throw.

data/documentation/docs/api/request.md

@@ -127,10 +127,10 @@ def redirected_from
 Request that was redirected by the server to this one, if any.
 
 When the server responds with a redirect, Playwright creates a new [Request](./request) object. The two requests are connected by
-`redirectedFrom()` and `redirectedTo()` methods. When multiple server redirects has happened, it is possible to
-construct the whole redirect chain by repeatedly calling `redirectedFrom()`.
+[redirected_from](./request#redirected_from) and [redirected_to](./request#redirected_to) methods. When multiple server redirects has happened, it is possible to
+construct the whole redirect chain by repeatedly calling [redirected_from](./request#redirected_from).
 
-For example, if the website `http://example.com` redirects to `https://example.com`:
+For example, if the website `http://github.com` redirects to `https://github.com`:
 
 ```ruby
 response = page.goto("http://github.com")

data/documentation/docs/api/selectors.md

@@ -41,7 +41,7 @@ playwright.chromium.launch do |browser|
   page.click('tag=div >> text="Click me"')
 
   # Can use it in any methods supporting selectors.
-  button_count = page.eval_on_selector_all('tag=button', 'buttons => buttons.length')
+  button_count = page.locator('tag=button').count
   button_count # => 1
 end
 ```

data/documentation/docs/api/tracing.md

@@ -23,7 +23,7 @@ end
 ## start
 
 ```
-def start(name: nil, screenshots: nil, snapshots: nil)
+def start(name: nil, screenshots: nil, snapshots: nil, title: nil)
 ```
 
 Start tracing.
@@ -40,7 +40,7 @@ context.tracing.stop(path: 'trace.zip')
 ## start_chunk
 
 ```
-def start_chunk
+def start_chunk(title: nil)
 ```
 
 Start a new trace chunk. If you'd like to record multiple traces on the same [BrowserContext](./browser_context), use

data/documentation/docs/include/api_coverage.md

@@ -1,5 +1,17 @@
 # API coverages
 
+## APIRequestContext
+
+* ~~delete~~
+* ~~dispose~~
+* ~~fetch~~
+* ~~get~~
+* ~~head~~
+* ~~patch~~
+* ~~post~~
+* ~~put~~
+* ~~storage_state~~
+
 ## Request
 
 * all_headers
@@ -48,13 +60,6 @@
 * fulfill
 * request
 
-## FetchRequest
-
-* ~~dispose~~
-* ~~fetch~~
-* ~~get~~
-* ~~post~~
-
 ## WebSocket
 
 * closed?
@@ -162,6 +167,7 @@
 * fill
 * focus
 * frame_element
+* frame_locator
 * get_attribute
 * goto
 * hover
@@ -259,6 +265,7 @@
 * fill
 * focus
 * frame
+* frame_locator
 * frames
 * get_attribute
 * go_back
@@ -354,6 +361,7 @@
 * expect_event
 * expect_page
 * ~~wait_for_event~~
+* ~~request~~
 * tracing
 
 ## CDPSession
@@ -388,6 +396,7 @@
 * chromium
 * devices
 * firefox
+* ~~request~~
 * selectors
 * webkit
 
@@ -416,6 +425,7 @@
 * fill
 * first
 * focus
+* frame_locator
 * get_attribute
 * hover
 * inner_html
@@ -443,6 +453,14 @@
 * uncheck
 * wait_for
 
+## FrameLocator
+
+* first
+* frame_locator
+* last
+* locator
+* nth
+
 ## Android
 
 * devices

data/lib/playwright/channel.rb

@@ -71,7 +71,7 @@ module Playwright
       {
         apiName: api_name,
         stack: stacks.map do |loc|
-          { file: loc.absolute_path, line: loc.lineno, function: loc.label }
+          { file: loc.absolute_path || '', line: loc.lineno, function: loc.label }
         end,
       }
     end

data/lib/playwright/channel_owners/api_request_context.rb

@@ -0,0 +1,4 @@
+module Playwright
+  define_channel_owner :APIRequestContext do
+  end
+end

data/lib/playwright/channel_owners/artifact.rb

@@ -1,14 +1,13 @@
 module Playwright
   define_channel_owner :Artifact do
     private def after_initialize
-      @remote = false
       @absolute_path = @initializer['absolutePath']
     end
 
     attr_reader :absolute_path
 
     def path_after_finished
-      if @remote
+      if @connection.remote?
         raise "Path is not available when using browser_type.connect(). Use save_as() to save a local copy."
       end
       @channel.send_message_to_server('pathAfterFinished')
@@ -30,9 +29,5 @@ module Playwright
     def cancel
       @channel.send_message_to_server('cancel')
     end
-
-    private def update_as_remote
-      @remote = true
-    end
   end
 end

data/lib/playwright/channel_owners/browser.rb

@@ -7,7 +7,7 @@ module Playwright
     private def after_initialize
       @connected = true
       @closed_or_closing = false
-      @remote = false
+      @should_close_connection_on_close = false
 
       @contexts = Set.new
       @channel.on('close', method(:on_close))
@@ -58,6 +58,9 @@ module Playwright
       return if @closed_or_closing
       @closed_or_closing = true
       @channel.send_message_to_server('close')
+      if @should_close_connection_on_close
+        @connection.stop
+      end
       nil
     rescue => err
       raise unless safe_close_error?(err)
@@ -99,13 +102,8 @@ module Playwright
       @contexts << context
     end
 
-    # called from BrowserType#connectOverCDP
-    private def update_as_remote
-      @remote = true
-    end
-
-    private def remote?
-      @remote
+    private def should_close_connection_on_close!
+      @should_close_connection_on_close = true
     end
 
     # called from BrowserContext#on_close with send(:remove_context), so keep private.

data/lib/playwright/channel_owners/browser_context.rb

@@ -72,6 +72,11 @@ module Playwright
 
       if @routes.none? { |handler_entry| handler_entry.handle(wrapped_route, wrapped_request) }
         route.continue
+      else
+        @routes.reject!(&:expired?)
+        if @routes.count == 0
+          @channel.async_send_message_to_server('setNetworkInterceptionEnabled', enabled: false)
+        end
       end
     end
 
@@ -271,9 +276,6 @@ module Playwright
     def close
       if @options && @options.key?(:recordHar)
         har = ChannelOwners::Artifact.from(@channel.send_message_to_server('harExport'))
-        if @browser.send(:remote?)
-          har.update_as_remote
-        end
         har.save_as(@options[:recordHar][:path])
         har.delete
       end

data/lib/playwright/channel_owners/browser_type.rb

@@ -54,7 +54,6 @@ module Playwright
 
       result = @channel.send_message_to_server_result('connectOverCDP', params)
       browser = ChannelOwners::Browser.from(result['browser'])
-      browser.send(:update_as_remote)
 
       if result['defaultContext']
         context = ChannelOwners::BrowserContext.from(result['defaultContext'])

data/lib/playwright/channel_owners/fetch_request.rb

@@ -1,4 +1,8 @@
+require_relative './api_request_context'
+
 module Playwright
-  define_channel_owner :FetchRequest do
+  module ChannelOwners
+    class FetchRequest < APIRequestContext
+    end
   end
 end

data/lib/playwright/channel_owners/frame.rb

@@ -110,8 +110,8 @@ module Playwright
     def wait_for_load_state(state: nil, timeout: nil)
       option_state = state || 'load'
       option_timeout = timeout || @page.send(:timeout_settings).navigation_timeout
-      unless %w(load domcontentloaded networkidle).include?(option_state)
-        raise ArgumentError.new('state: expected one of (load|domcontentloaded|networkidle)')
+      unless %w(load domcontentloaded networkidle commit).include?(option_state)
+        raise ArgumentError.new('state: expected one of (load|domcontentloaded|networkidle|commit)')
       end
       if @load_states.include?(option_state)
         return
@@ -191,10 +191,6 @@ module Playwright
       @channel.send_message_to_server('isVisible', params)
     end
 
-    def locator(selector)
-      LocatorImpl.new(frame: self, timeout_settings: @page.send(:timeout_settings), selector: selector)
-    end
-
     def dispatch_event(selector, type, eventInit: nil, strict: nil, timeout: nil)
       params = {
         selector: selector,
@@ -404,6 +400,14 @@ module Playwright
       nil
     end
 
+    def locator(selector)
+      LocatorImpl.new(frame: self, timeout_settings: @page.send(:timeout_settings), selector: selector)
+    end
+
+    def frame_locator(selector)
+      FrameLocatorImpl.new(frame: self, timeout_settings: @page.send(:timeout_settings), frame_selector: selector)
+    end
+
     def focus(selector, strict: nil, timeout: nil)
       params = { selector: selector, strict: strict, timeout: timeout }.compact
       @channel.send_message_to_server('focus', params)

data/lib/playwright/channel_owners/page.rb

@@ -100,6 +100,11 @@ module Playwright
 
       if @routes.none? { |handler_entry| handler_entry.handle(wrapped_route, wrapped_request) }
         @browser_context.send(:on_route, route, request)
+      else
+        @routes.reject!(&:expired?)
+        if @routes.count == 0
+          @channel.async_send_message_to_server('setNetworkInterceptionEnabled', enabled: false)
+        end
       end
     end
 
@@ -133,9 +138,6 @@ module Playwright
 
     private def on_download(params)
       artifact = ChannelOwners::Artifact.from(params['artifact'])
-      if @browser_context.browser.send(:remote?)
-        artifact.update_as_remote
-      end
       download = DownloadImpl.new(
         page: self,
         url: params['url'],
@@ -147,9 +149,6 @@ module Playwright
 
     private def on_video(params)
       artifact = ChannelOwners::Artifact.from(params['artifact'])
-      if @browser_context.browser.send(:remote?)
-        artifact.update_as_remote
-      end
       video.send(:set_artifact, artifact)
     end
 
@@ -256,10 +255,6 @@ module Playwright
       @main_frame.visible?(selector, strict: strict, timeout: timeout)
     end
 
-    def locator(selector)
-      @main_frame.locator(selector)
-    end
-
     def dispatch_event(selector, type, eventInit: nil, strict: nil, timeout: nil)
       @main_frame.dispatch_event(selector, type, eventInit: eventInit, strict: strict, timeout: timeout)
     end
@@ -563,6 +558,14 @@ module Playwright
         timeout: timeout)
     end
 
+    def locator(selector)
+      @main_frame.locator(selector)
+    end
+
+    def frame_locator(selector)
+      @main_frame.frame_locator(selector)
+    end
+
     def focus(selector, strict: nil, timeout: nil)
       @main_frame.focus(selector, strict: strict, timeout: timeout)
     end
@@ -920,6 +923,11 @@ module Playwright
       @workers.delete(worker)
     end
 
+    # called from Video
+    private def remote_connection?
+      @connection.remote?
+    end
+
     # Expose guid for library developers.
     # Not intended to be used by users.
     def guid