playwright-ruby-client 1.38.0 → 1.39.0

data/documentation/docs/api/playwright.md

@@ -8,19 +8,20 @@ sidebar_position: 10
 Playwright module provides a method to launch a browser instance. The following is a typical example of using Playwright
 to drive automation:
 
-```ruby
-require 'playwright'
+```python sync title=example_6647e5a44b0440884026a6142606dfddad75ba1e643919b015457df4ed2e198f.py
+from playwright.sync_api import sync_playwright, Playwright
 
-Playwright.create(playwright_cli_executable_path: 'npx playwright') do |playwright|
-  chromium = playwright.chromium # or "firefox" or "webkit".
-  chromium.launch do |browser|
-    page = browser.new_page
-    page.goto('https://example.com/')
+def run(playwright: Playwright):
+    chromium = playwright.chromium # or "firefox" or "webkit".
+    browser = chromium.launch()
+    page = browser.new_page()
+    page.goto("http://example.com")
+    # other actions...
+    browser.close()
 
-    # other actions
+with sync_playwright() as playwright:
+    run(playwright)
 
-  end
-end
 ```
 
 ## chromium
@@ -33,20 +34,22 @@ This object can be used to launch or connect to Chromium, returning instances of
 
 Returns a dictionary of devices to be used with [Browser#new_context](./browser#new_context) or [Browser#new_page](./browser#new_page).
 
-```ruby
-require 'playwright'
+```python sync title=example_14d627977a4ad16a605ec5472d768a3324812fa8e7c57685561408fa6601e352.py
+from playwright.sync_api import sync_playwright, Playwright
 
-Playwright.create(playwright_cli_executable_path: 'npx playwright') do |playwright|
-  iphone = playwright.devices["iPhone 6"]
-  playwright.webkit.launch do |browser|
+def run(playwright: Playwright):
+    webkit = playwright.webkit
+    iphone = playwright.devices["iPhone 6"]
+    browser = webkit.launch()
     context = browser.new_context(**iphone)
-    page = context.new_page
-    page.goto('https://example.com/')
+    page = context.new_page()
+    page.goto("http://example.com")
+    # other actions...
+    browser.close()
 
-    # other actions
+with sync_playwright() as playwright:
+    run(playwright)
 
-  end
-end
 ```
 
 ## firefox

data/documentation/docs/api/selectors.md

@@ -21,33 +21,38 @@ Selectors must be registered before creating the page.
 
 An example of registering selector engine that queries elements based on a tag name:
 
-```ruby
-tag_selector = <<~JAVASCRIPT
-{
-    // Returns the first element matching given selector in the root's subtree.
-    query(root, selector) {
-        return root.querySelector(selector);
-    },
-    // Returns all elements matching given selector in the root's subtree.
-    queryAll(root, selector) {
-        return Array.from(root.querySelectorAll(selector));
-    }
-}
-JAVASCRIPT
-
-# Register the engine. Selectors will be prefixed with "tag=".
-playwright.selectors.register("tag", script: tag_selector)
-playwright.chromium.launch do |browser|
-  page = browser.new_page
-  page.content = '<div><button>Click me</button></div>'
-
-  # Use the selector prefixed with its name.
-  button = page.locator('tag=button')
-  # Combine it with other selector engines.
-  page.locator('tag=div').get_by_text('Click me').click
-
-  # Can use it in any methods supporting selectors.
-  button_count = page.locator('tag=button').count
-  button_count # => 1
-end
+```python sync title=example_3e739d4f0e30e20a6a698e0e17605a841c35e65e75aa3c2642f8bfc368b33f9e.py
+from playwright.sync_api import sync_playwright, Playwright
+
+def run(playwright: Playwright):
+    tag_selector = """
+      {
+          // Returns the first element matching given selector in the root's subtree.
+          query(root, selector) {
+              return root.querySelector(selector);
+          },
+          // Returns all elements matching given selector in the root's subtree.
+          queryAll(root, selector) {
+              return Array.from(root.querySelectorAll(selector));
+          }
+      }"""
+
+    # Register the engine. Selectors will be prefixed with "tag=".
+    playwright.selectors.register("tag", tag_selector)
+    browser = playwright.chromium.launch()
+    page = browser.new_page()
+    page.set_content('<div><button>Click me</button></div>')
+
+    # Use the selector prefixed with its name.
+    button = page.locator('tag=button')
+    # Combine it with built-in locators.
+    page.locator('tag=div').get_by_text('Click me').click()
+    # Can use it in any methods supporting selectors.
+    button_count = page.locator('tag=button').count()
+    print(button_count)
+    browser.close()
+
+with sync_playwright() as playwright:
+    run(playwright)
+
 ```

data/lib/playwright/channel.rb

@@ -30,6 +30,7 @@ module Playwright
     # @param params [Hash]
     # @return [Hash]
     def send_message_to_server_result(method, params)
+      check_not_collected
       with_logging do |metadata|
         @connection.send_message_to_server(@guid, method, params, metadata: metadata)
       end
@@ -39,6 +40,7 @@ module Playwright
     # @param params [Hash]
     # @returns [Concurrent::Promises::Future]
     def async_send_message_to_server(method, params = {})
+      check_not_collected
       with_logging do |metadata|
         @connection.async_send_message_to_server(@guid, method, params, metadata: metadata)
       end
@@ -74,5 +76,11 @@ module Playwright
         end,
       }
     end
+
+    private def check_not_collected
+      if @object.was_collected?
+        raise "The object has been collected to prevent unbounded heap growth."
+      end
+    end
   end
 end

data/lib/playwright/channel_owner.rb

@@ -50,13 +50,18 @@ module Playwright
       child.send(:update_parent, self)
     end
 
+    def was_collected?
+      @was_collected
+    end
+
     # used only from Connection. Not intended for public use. So keep private.
-    private def dispose!
+    private def dispose!(reason: nil)
       # Clean up from parent and connection.
       @connection.send(:delete_object_from_channel_owner, @guid)
+      @was_collected = reason == 'gc'
 
       # Dispose all children.
-      @objects.each_value { |object| object.send(:dispose!) }
+      @objects.each_value { |object| object.send(:dispose!, reason: reason) }
       @objects.clear
     end
 

data/lib/playwright/channel_owners/browser_context.rb

@@ -36,7 +36,7 @@ module Playwright
         on_service_worker(ChannelOwners::Worker.from(params['worker']))
       })
       @channel.on('console', ->(params) {
-        on_console_message(ChannelOwners::ConsoleMessage.from(params['message']))
+        on_console_message(ConsoleMessageImpl.new(params))
       })
       @channel.on('pageError', ->(params) {
         on_page_error(

data/lib/playwright/channel_owners/local_utils.rb

@@ -1,5 +1,11 @@
 module Playwright
   define_channel_owner :LocalUtils do
+    def devices
+      @devices ||= @initializer['deviceDescriptors'].map do |device|
+        [device['name'], parse_device_descriptor(device['descriptor'])]
+      end.to_h
+    end
+
     # @param zip_file [String]
     def zip(params)
       @channel.send_message_to_server('zip', params)
@@ -51,5 +57,26 @@ module Playwright
       @channel.async_send_message_to_server('addStackToTracingNoReply', callData: { id: id, stack: stack })
       nil
     end
+
+    private def parse_device_descriptor(descriptor)
+      # This return value can be passed into Browser#new_context as it is.
+      # ex:
+      # ```
+      #   iPhone = playwright.devices['iPhone 6']
+      #   context = browser.new_context(**iPhone)
+      #   page = context.new_page
+      #
+      # ```
+      {
+        userAgent: descriptor['userAgent'],
+        viewport: {
+          width: descriptor['viewport']['width'],
+          height: descriptor['viewport']['height'],
+        },
+        deviceScaleFactor: descriptor['deviceScaleFactor'],
+        isMobile: descriptor['isMobile'],
+        hasTouch: descriptor['hasTouch'],
+      }
+    end
   end
 end

data/lib/playwright/channel_owners/playwright.rb

@@ -25,9 +25,7 @@ module Playwright
     end
 
     def devices
-      @devices ||= @initializer['deviceDescriptors'].map do |item|
-        [item['name'], parse_device_descriptor(item['descriptor'])]
-      end.to_h
+      @connection.local_utils.devices
     end
 
     # used only from Playwright#connect_to_browser_server
@@ -44,26 +42,5 @@ module Playwright
       end
       ::Playwright::ChannelOwners::AndroidDevice.from(@initializer['preConnectedAndroidDevice'])
     end
-
-    private def parse_device_descriptor(descriptor)
-      # This return value can be passed into Browser#new_context as it is.
-      # ex:
-      # ```
-      #   iPhone = playwright.devices['iPhone 6']
-      #   context = browser.new_context(**iPhone)
-      #   page = context.new_page
-      #
-      # ```
-      {
-        userAgent: descriptor['userAgent'],
-        viewport: {
-          width: descriptor['viewport']['width'],
-          height: descriptor['viewport']['height'],
-        },
-        deviceScaleFactor: descriptor['deviceScaleFactor'],
-        isMobile: descriptor['isMobile'],
-        hasTouch: descriptor['hasTouch'],
-      }
-    end
   end
 end

data/lib/playwright/connection.rb

@@ -181,7 +181,7 @@ module Playwright
       end
 
       if method == "__dispose__"
-        object.send(:dispose!)
+        object.send(:dispose!, reason: params["reason"])
         return
       end
 

data/lib/playwright/console_message_impl.rb

@@ -0,0 +1,29 @@
+module Playwright
+  define_api_implementation :ConsoleMessageImpl do
+    def initialize(event)
+      @event = event
+    end
+
+    def page
+      @page ||= ChannelOwners::Page.from_nullable(@event['page'])
+    end
+
+    def type
+      @event['type']
+    end
+
+    def text
+      @event['text']
+    end
+
+    def args
+      @event['args']&.map do |arg|
+        ChannelOwner.from(arg)
+      end
+    end
+
+    def location
+      @event['location']
+    end
+  end
+end

data/lib/playwright/version.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
 module Playwright
-  VERSION = '1.38.0'
-  COMPATIBLE_PLAYWRIGHT_VERSION = '1.38.0'
+  VERSION = '1.39.0'
+  COMPATIBLE_PLAYWRIGHT_VERSION = '1.39.0'
 end

data/lib/playwright_api/browser.rb

@@ -4,9 +4,9 @@ module Playwright
   # A Browser is created via [`method: BrowserType.launch`]. An example of using a `Browser` to create a `Page`:
   #
   # ```python sync
-  # from playwright.sync_api import sync_playwright
+  # from playwright.sync_api import sync_playwright, Playwright
   #
-  # def run(playwright):
+  # def run(playwright: Playwright):
   #     firefox = playwright.firefox
   #     browser = firefox.launch()
   #     page = browser.new_page()

data/lib/playwright_api/browser_context.rb

@@ -131,9 +131,9 @@ module Playwright
     # An example of exposing page URL to all frames in all pages in the context:
     #
     # ```python sync
-    # from playwright.sync_api import sync_playwright
+    # from playwright.sync_api import sync_playwright, Playwright
     #
-    # def run(playwright):
+    # def run(playwright: Playwright):
     #     webkit = playwright.webkit
     #     browser = webkit.launch(headless=false)
     #     context = browser.new_context()
@@ -190,13 +190,13 @@ module Playwright
     # import hashlib
     # from playwright.sync_api import sync_playwright
     #
-    # def sha256(text):
+    # def sha256(text: str) -> str:
     #     m = hashlib.sha256()
     #     m.update(bytes(text, "utf8"))
     #     return m.hexdigest()
     #
     #
-    # def run(playwright):
+    # def run(playwright: Playwright):
     #     webkit = playwright.webkit
     #     browser = webkit.launch(headless=False)
     #     context = browser.new_context()

data/lib/playwright_api/browser_type.rb

@@ -4,9 +4,9 @@ module Playwright
   # typical example of using Playwright to drive automation:
   #
   # ```python sync
-  # from playwright.sync_api import sync_playwright
+  # from playwright.sync_api import sync_playwright, Playwright
   #
-  # def run(playwright):
+  # def run(playwright: Playwright):
   #     chromium = playwright.chromium
   #     browser = chromium.launch()
   #     page = browser.new_page()

data/lib/playwright_api/console_message.rb

@@ -52,27 +52,5 @@ module Playwright
     def type
       wrap_impl(@impl.type)
     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

data/lib/playwright_api/dialog.rb

@@ -5,13 +5,13 @@ module Playwright
   # An example of using `Dialog` class:
   #
   # ```python sync
-  # from playwright.sync_api import sync_playwright
+  # from playwright.sync_api import sync_playwright, Playwright
   #
   # def handle_dialog(dialog):
   #     print(dialog.message)
   #     dialog.dismiss()
   #
-  # def run(playwright):
+  # def run(playwright: Playwright):
   #     chromium = playwright.chromium
   #     browser = chromium.launch()
   #     page = browser.new_page()

data/lib/playwright_api/element_handle.rb

@@ -407,7 +407,7 @@ module Playwright
     # **Usage**
     #
     # ```python sync
-    # # single selection matching the value
+    # # Single selection matching the value or label
     # handle.select_option("blue")
     # # single selection matching both the label
     # handle.select_option(label="blue")

data/lib/playwright_api/frame.rb

@@ -11,9 +11,9 @@ module Playwright
   # An example of dumping frame tree:
   #
   # ```python sync
-  # from playwright.sync_api import sync_playwright
+  # from playwright.sync_api import sync_playwright, Playwright
   #
-  # def run(playwright):
+  # def run(playwright: Playwright):
   #     firefox = playwright.firefox
   #     browser = firefox.launch()
   #     page = browser.new_page()
@@ -757,7 +757,7 @@ module Playwright
     # **Usage**
     #
     # ```python sync
-    # # single selection matching the value
+    # # Single selection matching the value or label
     # frame.select_option("select#colors", "blue")
     # # single selection matching both the label
     # frame.select_option("select#colors", label="blue")
@@ -914,9 +914,9 @@ module Playwright
     # The [`method: Frame.waitForFunction`] can be used to observe viewport size change:
     #
     # ```python sync
-    # from playwright.sync_api import sync_playwright
+    # from playwright.sync_api import sync_playwright, Playwright
     #
-    # def run(playwright):
+    # def run(playwright: Playwright):
     #     webkit = playwright.webkit
     #     browser = webkit.launch()
     #     page = browser.new_page()
@@ -993,9 +993,9 @@ module Playwright
     # This method works across navigations:
     #
     # ```python sync
-    # from playwright.sync_api import sync_playwright
+    # from playwright.sync_api import sync_playwright, Playwright
     #
-    # def run(playwright):
+    # def run(playwright: Playwright):
     #     chromium = playwright.chromium
     #     browser = chromium.launch()
     #     page = browser.new_page()

data/lib/playwright_api/locator.rb

@@ -28,6 +28,8 @@ module Playwright
     #
     # Returns an array of `node.innerText` values for all matching nodes.
     #
+    # **NOTE**: If you need to assert text on the page, prefer [`method: LocatorAssertions.toHaveText`] with `useInnerText` option to avoid flakiness. See [assertions guide](../test-assertions.md) for more details.
+    #
     # **Usage**
     #
     # ```python sync
@@ -40,6 +42,8 @@ module Playwright
     #
     # Returns an array of `node.textContent` values for all matching nodes.
     #
+    # **NOTE**: If you need to assert text on the page, prefer [`method: LocatorAssertions.toHaveText`] to avoid flakiness. See [assertions guide](../test-assertions.md) for more details.
+    #
     # **Usage**
     #
     # ```python sync
@@ -192,6 +196,8 @@ module Playwright
     #
     # Returns the number of elements matching the locator.
     #
+    # **NOTE**: If you need to assert the number of elements on the page, prefer [`method: LocatorAssertions.toHaveCount`] to avoid flakiness. See [assertions guide](../test-assertions.md) for more details.
+    #
     # **Usage**
     #
     # ```python sync
@@ -441,6 +447,8 @@ module Playwright
 
     #
     # Returns the matching element's attribute value.
+    #
+    # **NOTE**: If you need to assert an element's attribute, prefer [`method: LocatorAssertions.toHaveAttribute`] to avoid flakiness. See [assertions guide](../test-assertions.md) for more details.
     def get_attribute(name, timeout: nil)
       wrap_impl(@impl.get_attribute(unwrap_impl(name), timeout: unwrap_impl(timeout)))
     end
@@ -681,6 +689,8 @@ module Playwright
 
     #
     # Returns the [`element.innerText`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/innerText).
+    #
+    # **NOTE**: If you need to assert text on the page, prefer [`method: LocatorAssertions.toHaveText`] with `useInnerText` option to avoid flakiness. See [assertions guide](../test-assertions.md) for more details.
     def inner_text(timeout: nil)
       wrap_impl(@impl.inner_text(timeout: unwrap_impl(timeout)))
     end
@@ -688,6 +698,8 @@ module Playwright
     #
     # Returns the value for the matching `<input>` or `<textarea>` or `<select>` element.
     #
+    # **NOTE**: If you need to assert input value, prefer [`method: LocatorAssertions.toHaveValue`] to avoid flakiness. See [assertions guide](../test-assertions.md) for more details.
+    #
     # **Usage**
     #
     # ```python sync
@@ -704,6 +716,8 @@ module Playwright
     #
     # Returns whether the element is checked. Throws if the element is not a checkbox or radio input.
     #
+    # **NOTE**: If you need to assert that checkbox is checked, prefer [`method: LocatorAssertions.toBeChecked`] to avoid flakiness. See [assertions guide](../test-assertions.md) for more details.
+    #
     # **Usage**
     #
     # ```python sync
@@ -716,6 +730,8 @@ module Playwright
     #
     # Returns whether the element is disabled, the opposite of [enabled](../actionability.md#enabled).
     #
+    # **NOTE**: If you need to assert that an element is disabled, prefer [`method: LocatorAssertions.toBeDisabled`] to avoid flakiness. See [assertions guide](../test-assertions.md) for more details.
+    #
     # **Usage**
     #
     # ```python sync
@@ -728,6 +744,8 @@ module Playwright
     #
     # Returns whether the element is [editable](../actionability.md#editable).
     #
+    # **NOTE**: If you need to assert that an element is editable, prefer [`method: LocatorAssertions.toBeEditable`] to avoid flakiness. See [assertions guide](../test-assertions.md) for more details.
+    #
     # **Usage**
     #
     # ```python sync
@@ -740,6 +758,8 @@ module Playwright
     #
     # Returns whether the element is [enabled](../actionability.md#enabled).
     #
+    # **NOTE**: If you need to assert that an element is enabled, prefer [`method: LocatorAssertions.toBeEnabled`] to avoid flakiness. See [assertions guide](../test-assertions.md) for more details.
+    #
     # **Usage**
     #
     # ```python sync
@@ -752,6 +772,8 @@ module Playwright
     #
     # Returns whether the element is hidden, the opposite of [visible](../actionability.md#visible).
     #
+    # **NOTE**: If you need to assert that element is hidden, prefer [`method: LocatorAssertions.toBeHidden`] to avoid flakiness. See [assertions guide](../test-assertions.md) for more details.
+    #
     # **Usage**
     #
     # ```python sync
@@ -764,6 +786,8 @@ module Playwright
     #
     # Returns whether the element is [visible](../actionability.md#visible).
     #
+    # **NOTE**: If you need to assert that element is visible, prefer [`method: LocatorAssertions.toBeVisible`] to avoid flakiness. See [assertions guide](../test-assertions.md) for more details.
+    #
     # **Usage**
     #
     # ```python sync
@@ -1087,6 +1111,8 @@ module Playwright
 
     #
     # Returns the [`node.textContent`](https://developer.mozilla.org/en-US/docs/Web/API/Node/textContent).
+    #
+    # **NOTE**: If you need to assert text on the page, prefer [`method: LocatorAssertions.toHaveText`] to avoid flakiness. See [assertions guide](../test-assertions.md) for more details.
     def text_content(timeout: nil)
       wrap_impl(@impl.text_content(timeout: unwrap_impl(timeout)))
     end