playwright-ruby-client 1.15.1 → 1.17.beta1

data/lib/playwright_api/browser_context.rb

@@ -6,7 +6,7 @@ module Playwright
   # 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.newContext()` method. "Incognito" browser
+  # Playwright allows creating "incognito" browser contexts with [`method: Browser.newContext`] method. "Incognito" browser
   # contexts don't write any browsing data to disk.
   #
   # ```python sync
@@ -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
@@ -540,6 +550,19 @@ module Playwright
       wrap_impl(@impl.uncheck(force: unwrap_impl(force), noWaitAfter: unwrap_impl(noWaitAfter), position: unwrap_impl(position), timeout: unwrap_impl(timeout), trial: unwrap_impl(trial)))
     end
 
+    # Returns when element specified by locator satisfies the `state` option.
+    #
+    # If target element already satisfies the condition, the method returns immediately. Otherwise, waits for up to `timeout`
+    # milliseconds until the condition is met.
+    #
+    # ```python sync
+    # order_sent = page.locator("#order-sent")
+    # order_sent.wait_for()
+    # ```
+    def wait_for(state: nil, timeout: nil)
+      wrap_impl(@impl.wait_for(state: unwrap_impl(state), timeout: unwrap_impl(timeout)))
+    end
+
     # @nodoc
     def to_s
       wrap_impl(@impl.to_s)

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
@@ -990,7 +1012,8 @@ module Playwright
     # [`method: Browser.newContext`] 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. [`method: Page.setViewportSize`] will also reset `screen` size, use
+    # [`method: Browser.newContext`] with `screen` and `viewport` parameters if you need better control of these properties.
     #
     # ```python sync
     # page = browser.new_page()
@@ -1266,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.
@@ -1366,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.15.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
@@ -210,6 +210,7 @@ files:
 - documentation/README.md
 - documentation/babel.config.js
 - documentation/docs/api/accessibility.md
+- documentation/docs/api/api_request_context.md
 - documentation/docs/api/browser.md
 - documentation/docs/api/browser_context.md
 - documentation/docs/api/browser_type.md
@@ -224,9 +225,9 @@ files:
 - documentation/docs/api/experimental/android_input.md
 - documentation/docs/api/experimental/android_socket.md
 - documentation/docs/api/experimental/android_web_view.md
-- documentation/docs/api/fetch_request.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
@@ -278,6 +279,7 @@ files:
 - lib/playwright/channel_owner.rb
 - lib/playwright/channel_owners/android.rb
 - lib/playwright/channel_owners/android_device.rb
+- lib/playwright/channel_owners/api_request_context.rb
 - lib/playwright/channel_owners/artifact.rb
 - lib/playwright/channel_owners/binding_call.rb
 - lib/playwright/channel_owners/browser.rb
@@ -307,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
@@ -337,6 +340,7 @@ files:
 - lib/playwright_api/android_input.rb
 - lib/playwright_api/android_socket.rb
 - lib/playwright_api/android_web_view.rb
+- lib/playwright_api/api_request_context.rb
 - lib/playwright_api/browser.rb
 - lib/playwright_api/browser_context.rb
 - lib/playwright_api/browser_type.rb
@@ -345,9 +349,9 @@ files:
 - lib/playwright_api/dialog.rb
 - lib/playwright_api/download.rb
 - lib/playwright_api/element_handle.rb
-- lib/playwright_api/fetch_request.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
@@ -378,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.15.2
+summary: The Ruby binding of playwright driver 1.17.0
 test_files: []

data/lib/playwright_api/fetch_request.rb

@@ -1,74 +0,0 @@
-module Playwright
-  # This API is used for 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` or a `BrowserContext`, this API will automatically use
-  # the cookies from the corresponding `BrowserContext`. This means that if you log in using this API, your e2e test will be
-  # logged in and vice versa.
-  class FetchRequest < PlaywrightApi
-
-    # All responses received through [`method: FetchRequest.fetch`], [`method: FetchRequest.get`],
-    # [`method: FetchRequest.post`] and other methods are stored in the memory, so that you can later call
-    # [`method: FetchResponse.body`]. This method discards all stored responses, and makes [`method: FetchResponse.body`]
-    # throw "Response disposed" error.
-    def dispose
-      raise NotImplementedError.new('dispose is not implemented yet.')
-    end
-
-    # Sends HTTP(S) fetch and returns its response. The method will populate fetch cookies from the context and update context
-    # cookies from the response. The method will automatically follow redirects.
-    def fetch(
-          urlOrRequest,
-          data: nil,
-          failOnStatusCode: nil,
-          headers: nil,
-          method: nil,
-          params: nil,
-          timeout: nil)
-      raise NotImplementedError.new('fetch is not implemented yet.')
-    end
-
-    # Sends HTTP(S) GET request and returns its response. The method will populate fetch cookies from the context and update
-    # context cookies from the response. The method will automatically follow redirects.
-    def get(
-          urlOrRequest,
-          failOnStatusCode: nil,
-          headers: nil,
-          params: nil,
-          timeout: nil)
-      raise NotImplementedError.new('get is not implemented yet.')
-    end
-
-    # Sends HTTP(S) fetch and returns its response. The method will populate fetch cookies from the context and update context
-    # cookies from the response. The method will automatically follow redirects.
-    def post(
-          urlOrRequest,
-          data: nil,
-          failOnStatusCode: nil,
-          headers: nil,
-          params: nil,
-          timeout: nil)
-      raise NotImplementedError.new('post is not implemented yet.')
-    end
-
-    # -- inherited from EventEmitter --
-    # @nodoc
-    def off(event, callback)
-      event_emitter_proxy.off(event, callback)
-    end
-
-    # -- inherited from EventEmitter --
-    # @nodoc
-    def once(event, callback)
-      event_emitter_proxy.once(event, callback)
-    end
-
-    # -- inherited from EventEmitter --
-    # @nodoc
-    def on(event, callback)
-      event_emitter_proxy.on(event, callback)
-    end
-
-    private def event_emitter_proxy
-      @event_emitter_proxy ||= EventEmitterProxy.new(self, @impl)
-    end
-  end
-end