playwright-ruby-client 1.16.0 → 1.18.beta1

data/lib/playwright_api/frame_locator.rb

@@ -0,0 +1,60 @@
+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()
+  # ```
+  #
+  # **Converting Locator to FrameLocator**
+  #
+  # If you have a `Locator` object pointing to an `iframe` it can be converted to `FrameLocator` using
+  # [`:scope`](https://developer.mozilla.org/en-US/docs/Web/CSS/:scope) CSS selector:
+  #
+  # ```python sync
+  # frameLocator = locator.frame_locator(":scope");
+  # ```
+  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, hasText: nil)
+      wrap_impl(@impl.locator(unwrap_impl(selector), hasText: unwrap_impl(hasText)))
+    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/local_utils.rb

@@ -0,0 +1,9 @@
+module Playwright
+  class LocalUtils < PlaywrightApi
+
+    # @nodoc
+    def zip(zip_file, name_value_array)
+      wrap_impl(@impl.zip(unwrap_impl(zip_file), unwrap_impl(name_value_array)))
+    end
+  end
+end

data/lib/playwright_api/locator.rb

@@ -1,49 +1,8 @@
 module Playwright
-  # Locator represents a view to the element(s) on the page. It captures the logic sufficient to retrieve the element at any
-  # given moment. Locator can be created with the [`method: Page.locator`] method.
+  # Locators are the central piece of Playwright's auto-waiting and retry-ability. In a nutshell, locators represent a way
+  # to find element(s) on the page at any moment. Locator can be created with the [`method: Page.locator`] method.
   #
-  # ```python sync
-  # locator = page.locator("text=Submit")
-  # locator.click()
-  # ```
-  #
-  # The difference between the Locator and `ElementHandle` is that the latter points to a particular element, while Locator
-  # captures the logic of how to retrieve that element.
-  #
-  # In the example below, handle points to a particular DOM element on page. If that element changes text or is used by
-  # React to render an entirely different component, handle is still pointing to that very DOM element. This can lead to
-  # unexpected behaviors.
-  #
-  # ```python sync
-  # handle = page.query_selector("text=Submit")
-  # handle.hover()
-  # handle.click()
-  # ```
-  #
-  # With the locator, every time the `element` is used, up-to-date DOM element is located in the page using the selector. So
-  # in the snippet below, underlying DOM element is going to be located twice.
-  #
-  # ```python sync
-  # locator = page.locator("text=Submit")
-  # locator.hover()
-  # locator.click()
-  # ```
-  #
-  # **Strictness**
-  #
-  # Locators are strict. This means that all operations on locators that imply some target DOM element will throw if more
-  # than one element matches given selector.
-  #
-  # ```python sync
-  # # Throws if there are several buttons in DOM:
-  # page.locator('button').click()
-  #
-  # # Works because we explicitly tell locator to pick the first element:
-  # page.locator('button').first.click()
-  #
-  # # Works because count knows what to do with multiple matches:
-  # page.locator('button').count()
-  # ```
+  # [Learn more about locators](./locators.md).
   class Locator < PlaywrightApi
 
     # Returns an array of `node.innerText` values for all matching nodes.
@@ -183,6 +142,17 @@ module Playwright
       wrap_impl(@impl.dispatch_event(unwrap_impl(type), eventInit: unwrap_impl(eventInit), timeout: unwrap_impl(timeout)))
     end
 
+    def drag_to(
+          target,
+          force: nil,
+          noWaitAfter: nil,
+          sourcePosition: nil,
+          targetPosition: nil,
+          timeout: nil,
+          trial: nil)
+      wrap_impl(@impl.drag_to(unwrap_impl(target), force: unwrap_impl(force), noWaitAfter: unwrap_impl(noWaitAfter), sourcePosition: unwrap_impl(sourcePosition), targetPosition: unwrap_impl(targetPosition), timeout: unwrap_impl(timeout), trial: unwrap_impl(trial)))
+    end
+
     # Resolves given locator to the first matching DOM element. If no elements matching the query are visible, waits for them
     # up to a given timeout. If multiple elements match the selector, throws.
     def element_handle(timeout: nil)
@@ -264,6 +234,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,10 +319,9 @@ 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.
-    def locator(selector)
-      wrap_impl(@impl.locator(unwrap_impl(selector)))
+    # The method finds an element matching the specified selector in the `Locator`'s subtree.
+    def locator(selector, hasText: nil)
+      wrap_impl(@impl.locator(unwrap_impl(selector), hasText: unwrap_impl(hasText)))
     end
 
     # Returns locator to the n-th matching element.

data/lib/playwright_api/page.rb

@@ -56,6 +56,11 @@ module Playwright
       wrap_impl(@impl.mouse)
     end
 
+    # API testing helper associated with this page. Requests made with this API will use page cookies.
+    def request # property
+      raise NotImplementedError.new('request is not implemented yet.')
+    end
+
     def touchscreen # property
       wrap_impl(@impl.touchscreen)
     end
@@ -288,6 +293,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 +315,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 +360,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 +544,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)
@@ -663,8 +686,8 @@ module Playwright
     # different DOM elements. That would happen if the DOM structure between those actions has changed.
     #
     # Shortcut for main frame's [`method: Frame.locator`].
-    def locator(selector)
-      wrap_impl(@impl.locator(unwrap_impl(selector)))
+    def locator(selector, hasText: nil)
+      wrap_impl(@impl.locator(unwrap_impl(selector), hasText: unwrap_impl(hasText)))
     end
 
     # The page's main frame. Page is guaranteed to have a main frame which persists during navigations.
@@ -791,14 +814,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 +834,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 +1294,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/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
@@ -82,13 +87,13 @@ module Playwright
     end
 
     # @nodoc
-    def electron
-      wrap_impl(@impl.electron)
+    def android
+      wrap_impl(@impl.android)
     end
 
     # @nodoc
-    def android
-      wrap_impl(@impl.android)
+    def electron
+      wrap_impl(@impl.electron)
     end
 
     # -- inherited from EventEmitter --

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/playwright.gemspec

@@ -27,7 +27,7 @@ Gem::Specification.new do |spec|
   spec.required_ruby_version = '>= 2.4'
   spec.add_dependency 'concurrent-ruby', '>= 1.1.6'
   spec.add_dependency 'mime-types', '>= 3.0'
-  spec.add_development_dependency 'bundler', '~> 2.2.3'
+  spec.add_development_dependency 'bundler', '~> 2.3.0'
   spec.add_development_dependency 'chunky_png'
   spec.add_development_dependency 'dry-inflector'
   spec.add_development_dependency 'faye-websocket'

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: playwright-ruby-client
 version: !ruby/object:Gem::Version
-  version: 1.16.0
+  version: 1.18.beta1
 platform: ruby
 authors:
 - YusukeIwaki
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2021-10-24 00:00:00.000000000 Z
+date: 2022-01-18 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: concurrent-ruby
@@ -44,14 +44,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 2.2.3
+        version: 2.3.0
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 2.2.3
+        version: 2.3.0
 - !ruby/object:Gem::Dependency
   name: chunky_png
   requirement: !ruby/object:Gem::Requirement
@@ -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
@@ -292,6 +293,7 @@ files:
 - lib/playwright/channel_owners/fetch_request.rb
 - lib/playwright/channel_owners/frame.rb
 - lib/playwright/channel_owners/js_handle.rb
+- lib/playwright/channel_owners/local_utils.rb
 - lib/playwright/channel_owners/page.rb
 - lib/playwright/channel_owners/playwright.rb
 - lib/playwright/channel_owners/request.rb
@@ -308,6 +310,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,8 +352,10 @@ 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/local_utils.rb
 - lib/playwright_api/locator.rb
 - lib/playwright_api/mouse.rb
 - lib/playwright_api/page.rb
@@ -379,12 +384,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
+rubygems_version: 3.3.3
 signing_key: 
 specification_version: 4
-summary: The Ruby binding of playwright driver 1.16.0
+summary: The Ruby binding of playwright driver 1.18.0
 test_files: []