playwright-ruby-client 1.16.1 → 1.17.beta1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1e3d50fa44b6ed68d4c5edbcf0b96f802908beb8d0f988f13069d85e96771e11
-  data.tar.gz: a25808094dd8a763da76c8e36ebf40041f41fa076c1231d664cdc159793a1366
+  metadata.gz: c2fe4b12d358a45b087eee4cdfc8aecb03b9e6df7d012158e4a04a042d290d13
+  data.tar.gz: ed57849806349f58419ead4e64164cafb94de892fa5d4be7cbf9f6e67867eb5d
 SHA512:
-  metadata.gz: ba3f3f15fb496b90c1179b3ec39543d202c708098edb664dd5e43291241b435877a5004d1054f15142aba97c38ef9b6a4ed11851afe4ebe2535b6e799ba001ee
-  data.tar.gz: '0927a665bc87db2296d8e479d8420786b12cbda7886c364bd3cb4eceeefb2d11c0ed7c2b9b6fa3779821f6440c5270ef9723062cb8b814c4fb29e02f47bc981f'
+  metadata.gz: b4245e2cc937bf4dd85ab98848b4a56149d796d814407598e17258f64154d85f252a3f993e13c8a81bda0f0112ffc5c1fa93e699c7fb691e3bf7592f27cd6133
+  data.tar.gz: 5680b2040b8ff3927b952e9f5321355137c298c697b0ba5ecde686eb89545f8b3444e191da3fe8ba22315df6fc982e452bdff73d71774419ee32a08e9a0281ef

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
 
@@ -1484,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/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

@@ -167,6 +167,7 @@
 * fill
 * focus
 * frame_element
+* frame_locator
 * get_attribute
 * goto
 * hover
@@ -264,6 +265,7 @@
 * fill
 * focus
 * frame
+* frame_locator
 * frames
 * get_attribute
 * go_back
@@ -359,6 +361,7 @@
 * expect_event
 * expect_page
 * ~~wait_for_event~~
+* ~~request~~
 * tracing
 
 ## CDPSession
@@ -393,6 +396,7 @@
 * chromium
 * devices
 * firefox
+* ~~request~~
 * selectors
 * webkit
 
@@ -421,6 +425,7 @@
 * fill
 * first
 * focus
+* frame_locator
 * get_attribute
 * hover
 * inner_html
@@ -448,6 +453,14 @@
 * uncheck
 * wait_for
 
+## FrameLocator
+
+* first
+* frame_locator
+* last
+* locator
+* nth
+
 ## Android
 
 * devices

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

@@ -276,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/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

@@ -138,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'],
@@ -152,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
 
@@ -261,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
@@ -568,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
@@ -925,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

data/lib/playwright/connection.rb

@@ -21,6 +21,15 @@ module Playwright
       @waiting_for_object = {} # Hash[ guid => Promise<ChannelOwner> ]
       @callbacks = {} # Hash [ guid => Promise<ChannelOwner> ]
       @root_object = RootChannelOwner.new(self)
+      @remote = false
+    end
+
+    def mark_as_remote
+      @remote = true
+    end
+
+    def remote?
+      @remote
     end
 
     def async_run

data/lib/playwright/frame_locator_impl.rb

@@ -0,0 +1,49 @@
+module Playwright
+  define_api_implementation :FrameLocatorImpl do
+    def initialize(frame:, timeout_settings:, frame_selector:)
+      @frame = frame
+      @timeout_settings = timeout_settings
+      @frame_selector = frame_selector
+    end
+
+    def locator(selector)
+      LocatorImpl.new(
+        frame: @frame,
+        timeout_settings: @timeout_settings,
+        selector: "#{@frame_selector} >> control=enter-frame >> #{selector}",
+      )
+    end
+
+    def frame_locator(selector)
+      FrameLocatorImpl.new(
+        frame: @frame,
+        timeout_settings: @timeout_settings,
+        frame_selector: "#{@frame_selector} >> control=enter-frame >> #{selector}",
+      )
+    end
+
+    def first
+      FrameLocatorImpl.new(
+        frame: @frame,
+        timeout_settings: @timeout_settings,
+        frame_selector: "#{@frame_selector} >> nth=0",
+      )
+    end
+
+    def last
+      FrameLocatorImpl.new(
+        frame: @frame,
+        timeout_settings: @timeout_settings,
+        frame_selector: "#{@frame_selector} >> nth=-1",
+      )
+    end
+
+    def nth(index)
+      FrameLocatorImpl.new(
+        frame: @frame,
+        timeout_settings: @timeout_settings,
+        frame_selector: "#{@frame_selector} >> nth=#{index}",
+      )
+    end
+  end
+end

data/lib/playwright/locator_impl.rb

@@ -11,17 +11,17 @@ module Playwright
     end
 
     private def with_element(timeout: nil, &block)
+      timeout_or_default = @timeout_settings.timeout(timeout)
       start_time = Time.now
 
-      handle = @frame.wait_for_selector(@selector, strict: true, state: 'attached', timeout: timeout)
+      handle = @frame.wait_for_selector(@selector, strict: true, state: 'attached', timeout: timeout_or_default)
       unless handle
         raise "Could not resolve #{@selector} to DOM Element"
       end
 
-      call_options = {}
-      if timeout
-        call_options[:timeout] = (timeout - (Time.now - start_time) * 1000).to_i
-      end
+      call_options = {
+        timeout: (timeout_or_default - (Time.now - start_time) * 1000).to_i,
+      }
 
       begin
         block.call(handle, call_options)
@@ -130,6 +130,14 @@ module Playwright
       )
     end
 
+    def frame_locator(selector)
+      FrameLocatorImpl.new(
+        frame: @frame,
+        timeout_settings: @timeout_settings,
+        frame_selector: "#{@selector} >> #{selector}",
+      )
+    end
+
     def element_handle(timeout: nil)
       @frame.wait_for_selector(@selector, strict: true, state: 'attached', timeout: timeout)
     end

data/lib/playwright/tracing_impl.rb

@@ -5,18 +5,18 @@ module Playwright
       @context = context
     end
 
-    def start(name: nil, screenshots: nil, snapshots: nil)
+    def start(name: nil, title: nil, screenshots: nil, snapshots: nil)
       params = {
         name: name,
         screenshots: screenshots,
         snapshots: snapshots,
       }.compact
       @channel.send_message_to_server('tracingStart', params)
-      @channel.send_message_to_server('tracingStartChunk')
+      @channel.send_message_to_server('tracingStartChunk', { title: title }.compact)
     end
 
-    def start_chunk
-      @channel.send_message_to_server('tracingStartChunk')
+    def start_chunk(title: nil)
+      @channel.send_message_to_server('tracingStartChunk', { title: title }.compact)
     end
 
     def stop_chunk(path: nil)
@@ -29,13 +29,10 @@ module Playwright
     end
 
     private def do_stop_chunk(path:)
-      resp = @channel.send_message_to_server('tracingStopChunk', save: !path.nil?)
-      artifact = ChannelOwners::Artifact.from_nullable(resp)
+      result = @channel.send_message_to_server_result('tracingStopChunk', save: !path.nil?, skipCompress: false)
+      artifact = ChannelOwners::Artifact.from_nullable(result['artifact'])
       return unless artifact
 
-      if @context.browser.send(:remote?)
-        artifact.update_as_remote
-      end
       artifact.save_as(path)
       artifact.delete
     end

data/lib/playwright/version.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
 module Playwright
-  VERSION = '1.16.1'
-  COMPATIBLE_PLAYWRIGHT_VERSION = '1.16.3'
+  VERSION = '1.17.beta1'
+  COMPATIBLE_PLAYWRIGHT_VERSION = '1.17.0'
 end

data/lib/playwright/video.rb

@@ -22,6 +22,9 @@ module Playwright
     end
 
     def path
+      if @page.send(:remote_connection?)
+        raise 'Path is not available when using browserType.connect(). Use save_as() to save a local copy.'
+      end
       wait_for_artifact_and do |artifact|
         artifact.absolute_path
       end

data/lib/playwright.rb

@@ -135,13 +135,14 @@ module Playwright
 
     transport = WebSocketTransport.new(ws_endpoint: ws_endpoint)
     connection = Connection.new(transport)
+    connection.mark_as_remote
     connection.async_run
 
     execution =
       begin
         playwright = connection.initialize_playwright
         browser = playwright.send(:pre_launched_browser)
-        browser.send(:update_as_remote)
+        browser.should_close_connection_on_close!
         Execution.new(connection, PlaywrightApi.wrap(playwright), PlaywrightApi.wrap(browser))
       rescue
         connection.stop

data/lib/playwright_api/api_request_context.rb

@@ -10,9 +10,12 @@ module Playwright
     # method will automatically follow redirects.
     def delete(
           url,
+          data: nil,
           failOnStatusCode: nil,
+          form: nil,
           headers: nil,
           ignoreHTTPSErrors: nil,
+          multipart: nil,
           params: nil,
           timeout: nil)
       raise NotImplementedError.new('delete is not implemented yet.')

data/lib/playwright_api/browser_context.rb

@@ -20,6 +20,11 @@ module Playwright
   # ```
   class BrowserContext < PlaywrightApi
 
+    # API testing helper associated with this context. Requests made with this API will use context cookies.
+    def request # property
+      raise NotImplementedError.new('request is not implemented yet.')
+    end
+
     def tracing # property
       wrap_impl(@impl.tracing)
     end

data/lib/playwright_api/element_handle.rb

@@ -6,6 +6,8 @@ module Playwright
   # ElementHandle represents an in-page DOM element. ElementHandles can be created with the [`method: Page.querySelector`]
   # method.
   #
+  # > NOTE: The use of ElementHandle is discouraged, use `Locator` objects and web-first assertions instead.
+  #
   # ```python sync
   # href_element = page.query_selector("a")
   # href_element.click()
@@ -17,9 +19,6 @@ module Playwright
   # ElementHandle instances can be used as an argument in [`method: Page.evalOnSelector`] and [`method: Page.evaluate`]
   # methods.
   #
-  # > NOTE: In most cases, you would want to use the `Locator` object instead. You should only use `ElementHandle` if you
-  # want to retain a handle to a particular DOM Node that you intend to pass into [`method: Page.evaluate`] as an argument.
-  #
   # The difference between the `Locator` and ElementHandle is that the ElementHandle points to a particular element, while
   # `Locator` captures the logic of how to retrieve an element.
   #

data/lib/playwright_api/frame.rb

@@ -183,6 +183,9 @@ module Playwright
 
     # 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 [`method: Locator.evaluate`], other `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](./selectors.md) for more details. If no elements match the selector, the
     # method throws an error.
@@ -203,6 +206,9 @@ module Playwright
 
     # Returns the return value of `expression`.
     #
+    # > NOTE: In most cases, [`method: Locator.evaluateAll`], other `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](./selectors.md) for more details.
     #
@@ -243,7 +249,7 @@ module Playwright
     # `ElementHandle` instances can be passed as an argument to the [`method: Frame.evaluate`]:
     #
     # ```python sync
-    # body_handle = frame.query_selector("body")
+    # body_handle = frame.evaluate("document.body")
     # html = frame.evaluate("([body, suffix]) => body.innerHTML + suffix", [body_handle, "hello"])
     # body_handle.dispose()
     # ```
@@ -324,6 +330,18 @@ module Playwright
       wrap_impl(@impl.frame_element)
     end
 
+    # 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">`:
+    #
+    # ```python sync
+    # locator = frame.frame_locator("#my-iframe").locator("text=Submit")
+    # locator.click()
+    # ```
+    def frame_locator(selector)
+      wrap_impl(@impl.frame_locator(unwrap_impl(selector)))
+    end
+
     # Returns element attribute value.
     def get_attribute(selector, name, strict: nil, timeout: nil)
       wrap_impl(@impl.get_attribute(unwrap_impl(selector), unwrap_impl(name), strict: unwrap_impl(strict), timeout: unwrap_impl(timeout)))
@@ -478,6 +496,8 @@ module Playwright
 
     # Returns the ElementHandle pointing to the frame element.
     #
+    # > NOTE: The use of `ElementHandle` is discouraged, use `Locator` objects and web-first assertions instead.
+    #
     # The method finds an element matching the specified selector within the frame. See
     # [Working with selectors](./selectors.md) for more details. If no elements match the selector, returns `null`.
     def query_selector(selector, strict: nil)
@@ -486,6 +506,8 @@ module Playwright
 
     # Returns the ElementHandles pointing to the frame elements.
     #
+    # > NOTE: The use of `ElementHandle` is discouraged, use `Locator` objects instead.
+    #
     # The method finds all elements matching the specified selector within the frame. See
     # [Working with selectors](./selectors.md) for more details. If no elements match the selector, returns empty array.
     def query_selector_all(selector)
@@ -714,6 +736,9 @@ module Playwright
     # 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` 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/lib/playwright_api/frame_locator.rb

@@ -0,0 +1,51 @@
+module Playwright
+  # 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 [`method: Page.frameLocator`] or
+  # [`method: Locator.frameLocator`] method.
+  #
+  # ```python sync
+  # 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.
+  #
+  # ```python sync
+  # # 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()
+  # ```
+  class FrameLocator < PlaywrightApi
+
+    # Returns locator to the first matching frame.
+    def first
+      wrap_impl(@impl.first)
+    end
+
+    # When working with iframes, you can create a frame locator that will enter the iframe and allow selecting elements in
+    # that iframe.
+    def frame_locator(selector)
+      wrap_impl(@impl.frame_locator(unwrap_impl(selector)))
+    end
+
+    # Returns locator to the last matching frame.
+    def last
+      wrap_impl(@impl.last)
+    end
+
+    # The method finds an element matching the specified selector in the FrameLocator's subtree.
+    def locator(selector)
+      wrap_impl(@impl.locator(unwrap_impl(selector)))
+    end
+
+    # Returns locator to the n-th matching frame.
+    def nth(index)
+      wrap_impl(@impl.nth(unwrap_impl(index)))
+    end
+  end
+end

data/lib/playwright_api/locator.rb

@@ -264,6 +264,17 @@ module Playwright
       wrap_impl(@impl.focus(timeout: unwrap_impl(timeout)))
     end
 
+    # When working with iframes, you can create a frame locator that will enter the iframe and allow selecting elements in
+    # that iframe:
+    #
+    # ```python sync
+    # locator = page.frame_locator("text=Submit").locator("text=Submit")
+    # locator.click()
+    # ```
+    def frame_locator(selector)
+      wrap_impl(@impl.frame_locator(unwrap_impl(selector)))
+    end
+
     # Returns element attribute value.
     def get_attribute(name, timeout: nil)
       wrap_impl(@impl.get_attribute(unwrap_impl(name), timeout: unwrap_impl(timeout)))
@@ -338,8 +349,7 @@ module Playwright
       wrap_impl(@impl.last)
     end
 
-    # The method finds an element matching the specified selector in the `Locator`'s subtree. See
-    # [Working with selectors](./selectors.md) for more details.
+    # The method finds an element matching the specified selector in the `Locator`'s subtree.
     def locator(selector)
       wrap_impl(@impl.locator(unwrap_impl(selector)))
     end

data/lib/playwright_api/page.rb

@@ -288,6 +288,9 @@ module Playwright
       wrap_impl(@impl.emulate_media(colorScheme: unwrap_impl(colorScheme), forcedColors: unwrap_impl(forcedColors), media: unwrap_impl(media), reducedMotion: unwrap_impl(reducedMotion)))
     end
 
+    # > NOTE: This method does not wait for the element to pass actionability checks and therefore can lead to the flaky
+    # tests. Use [`method: Locator.evaluate`], other `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`.
     #
@@ -307,6 +310,9 @@ module Playwright
       wrap_impl(@impl.eval_on_selector(unwrap_impl(selector), unwrap_impl(expression), arg: unwrap_impl(arg), strict: unwrap_impl(strict)))
     end
 
+    # > NOTE: In most cases, [`method: Locator.evaluateAll`], other `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.
     #
@@ -349,7 +355,7 @@ module Playwright
     # `ElementHandle` instances can be passed as an argument to the [`method: Page.evaluate`]:
     #
     # ```python sync
-    # body_handle = page.query_selector("body")
+    # body_handle = page.evaluate("document.body")
     # html = page.evaluate("([body, suffix]) => body.innerHTML + suffix", [body_handle, "hello"])
     # body_handle.dispose()
     # ```
@@ -533,6 +539,18 @@ module Playwright
       wrap_impl(@impl.frame(name: unwrap_impl(name), url: unwrap_impl(url)))
     end
 
+    # 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">`:
+    #
+    # ```python sync
+    # locator = page.frame_locator("#my-iframe").locator("text=Submit")
+    # locator.click()
+    # ```
+    def frame_locator(selector)
+      wrap_impl(@impl.frame_locator(unwrap_impl(selector)))
+    end
+
     # An array of all frames attached to the page.
     def frames
       wrap_impl(@impl.frames)
@@ -791,14 +809,18 @@ module Playwright
       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)))
     end
 
+    # > NOTE: The use of `ElementHandle` is discouraged, use `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 [`method: Page.waitForSelector`].
+    # return value resolves to `null`. To wait for an element on the page, use [`method: Locator.waitFor`].
     #
     # Shortcut for main frame's [`method: Frame.querySelector`].
     def query_selector(selector, strict: nil)
       wrap_impl(@impl.query_selector(unwrap_impl(selector), strict: unwrap_impl(strict)))
     end
 
+    # > NOTE: The use of `ElementHandle` is discouraged, use `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 `[]`.
     #
@@ -807,8 +829,8 @@ module Playwright
       wrap_impl(@impl.query_selector_all(unwrap_impl(selector)))
     end
 
-    # 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.
     def reload(timeout: nil, waitUntil: nil)
       wrap_impl(@impl.reload(timeout: unwrap_impl(timeout), waitUntil: unwrap_impl(waitUntil)))
     end
@@ -1267,6 +1289,9 @@ module Playwright
     # 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` 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.
@@ -1367,13 +1392,13 @@ module Playwright
     end
 
     # @nodoc
-    def start_css_coverage(resetOnNavigation: nil, reportAnonymousScripts: nil)
-      wrap_impl(@impl.start_css_coverage(resetOnNavigation: unwrap_impl(resetOnNavigation), reportAnonymousScripts: unwrap_impl(reportAnonymousScripts)))
+    def stop_css_coverage
+      wrap_impl(@impl.stop_css_coverage)
     end
 
     # @nodoc
-    def stop_css_coverage
-      wrap_impl(@impl.stop_css_coverage)
+    def start_css_coverage(resetOnNavigation: nil, reportAnonymousScripts: nil)
+      wrap_impl(@impl.start_css_coverage(resetOnNavigation: unwrap_impl(resetOnNavigation), reportAnonymousScripts: unwrap_impl(reportAnonymousScripts)))
     end
 
     # @nodoc

data/lib/playwright_api/playwright.rb

@@ -50,6 +50,11 @@ module Playwright
       wrap_impl(@impl.firefox)
     end
 
+    # Exposes API that can be used for the Web API testing.
+    def request # property
+      raise NotImplementedError.new('request is not implemented yet.')
+    end
+
     # Selectors can be used to install custom selector engines. See [Working with selectors](./selectors.md) for more
     # information.
     def selectors # property

data/lib/playwright_api/selectors.rb

@@ -28,11 +28,11 @@ module Playwright
     #     page.set_content('<div><button>Click me</button></div>')
     #
     #     # Use the selector prefixed with its name.
-    #     button = page.query_selector('tag=button')
+    #     button = page.locator('tag=button')
     #     # Combine it with other selector engines.
     #     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()
     #     print(button_count)
     #     browser.close()
     #

data/lib/playwright_api/tracing.rb

@@ -22,8 +22,8 @@ module Playwright
     # page.goto("https://playwright.dev")
     # context.tracing.stop(path = "trace.zip")
     # ```
-    def start(name: nil, screenshots: nil, snapshots: nil)
-      wrap_impl(@impl.start(name: unwrap_impl(name), screenshots: unwrap_impl(screenshots), snapshots: unwrap_impl(snapshots)))
+    def start(name: nil, screenshots: nil, snapshots: nil, title: nil)
+      wrap_impl(@impl.start(name: unwrap_impl(name), screenshots: unwrap_impl(screenshots), snapshots: unwrap_impl(snapshots), title: unwrap_impl(title)))
     end
 
     # Start a new trace chunk. If you'd like to record multiple traces on the same `BrowserContext`, use
@@ -45,8 +45,8 @@ module Playwright
     # # Save a second trace file with different actions.
     # context.tracing.stop_chunk(path = "trace2.zip")
     # ```
-    def start_chunk
-      wrap_impl(@impl.start_chunk)
+    def start_chunk(title: nil)
+      wrap_impl(@impl.start_chunk(title: unwrap_impl(title)))
     end
 
     # Stop tracing.

data/lib/playwright_api/worker.rb

@@ -44,13 +44,13 @@ module Playwright
     end
 
     # @nodoc
-    def context=(req)
-      wrap_impl(@impl.context=(unwrap_impl(req)))
+    def page=(req)
+      wrap_impl(@impl.page=(unwrap_impl(req)))
     end
 
     # @nodoc
-    def page=(req)
-      wrap_impl(@impl.page=(unwrap_impl(req)))
+    def context=(req)
+      wrap_impl(@impl.context=(unwrap_impl(req)))
     end
 
     # -- inherited from EventEmitter --

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: playwright-ruby-client
 version: !ruby/object:Gem::Version
-  version: 1.16.1
+  version: 1.17.beta1
 platform: ruby
 authors:
 - YusukeIwaki
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2021-11-07 00:00:00.000000000 Z
+date: 2021-11-22 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: concurrent-ruby
@@ -227,6 +227,7 @@ files:
 - documentation/docs/api/experimental/android_web_view.md
 - documentation/docs/api/file_chooser.md
 - documentation/docs/api/frame.md
+- documentation/docs/api/frame_locator.md
 - documentation/docs/api/js_handle.md
 - documentation/docs/api/keyboard.md
 - documentation/docs/api/locator.md
@@ -308,6 +309,7 @@ files:
 - lib/playwright/event_emitter_proxy.rb
 - lib/playwright/events.rb
 - lib/playwright/file_chooser_impl.rb
+- lib/playwright/frame_locator_impl.rb
 - lib/playwright/http_headers.rb
 - lib/playwright/input_files.rb
 - lib/playwright/javascript.rb
@@ -349,6 +351,7 @@ files:
 - lib/playwright_api/element_handle.rb
 - lib/playwright_api/file_chooser.rb
 - lib/playwright_api/frame.rb
+- lib/playwright_api/frame_locator.rb
 - lib/playwright_api/js_handle.rb
 - lib/playwright_api/keyboard.rb
 - lib/playwright_api/locator.rb
@@ -379,12 +382,12 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '2.4'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
-  - - ">="
+  - - ">"
     - !ruby/object:Gem::Version
-      version: '0'
+      version: 1.3.1
 requirements: []
 rubygems_version: 3.2.22
 signing_key: 
 specification_version: 4
-summary: The Ruby binding of playwright driver 1.16.3
+summary: The Ruby binding of playwright driver 1.17.0
 test_files: []