playwright-ruby-client 1.58.1 → 1.59.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 22108b8b1e5e9488c99db9d754715fd700d29fac599ee605449701c93be11055
-  data.tar.gz: d9ce245e505e17085630c58c75721823f0c1019324066d79b43f707f711b9310
+  metadata.gz: 959a33f7494fd33763cd54ddcf1e1c17fa0d9d37c89643aef2198f0dd452bbc9
+  data.tar.gz: ce343d14b0541fdf0ba0892b2e79456eea0ea5340b9f651f77b50c4e9a835cf6
 SHA512:
-  metadata.gz: 10534107850650b883dac4b7b817bfe641ba91ae7414f828a0fbcf8941dacbf6015cbcb9b68a8de828eb2559c4feefab5a5cc539e1c07935ced1a668773c98c1
-  data.tar.gz: 8661b9a7991ae2e81fe5a43ac71f41fa7e405bdb1c9a04cf984bf02052f47615f86dfaac8a8deecf0a36f41ebd960bc3499493956087b9ba063315843ebf2bc7
+  metadata.gz: bab8717bee2ff89d4735682f4e4b68b545a9812b01143fe082028aded03dcac856e63db430de66ac87cbcbfd397c16ddd1f5a774d6c33e951272e8c701b0149c
+  data.tar.gz: bba6fa2ebc246f538ccd074630c59f57c206d2942e299514c3d42b4717ae859943e42e4e2c4bc9b8a84e3680b2559f94ec1d7a0c34e7c56c7740468483ebf93e

data/README.md

@@ -174,16 +174,16 @@ npx playwright install && npx playwright run-server --port 8080 --path /ws
 and we can connect to the server with the code like this:
 
 ```ruby
-Playwright.connect_to_playwright_server('ws://127.0.0.1:8080/ws?browser=chromium') do |playwright|
-  playwright.chromium.launch do |browser|
-    page = browser.new_page
-    page.goto('https://github.com/YusukeIwaki')
-    page.screenshot(path: './YusukeIwaki.png')
-  end
+require 'playwright'
+
+Playwright.connect_to_browser_server('wss://example.com:8888/ws') do |browser|
+  page = browser.new_page
+  page.goto('https://github.com/YusukeIwaki')
+  page.screenshot(path: './YusukeIwaki.png')
 end
 ```
 
-When `Playwright.connect_to_playwright_server` is used, playwright_cli_executable_path is not required.
+When `Playwright.connect_to_browser_server` is used, playwright_cli_executable_path is not required.
 
 For more detailed instraction, refer this article: https://playwright-ruby-client.vercel.app/docs/article/guides/playwright_on_alpine_linux
 

data/documentation/docs/api/browser_context.md

@@ -238,6 +238,15 @@ def grant_permissions(permissions, origin: nil)
 Grants specified permissions to the browser context. Only grants corresponding permissions to the given origin if
 specified.
 
+## closed?
+
+```
+def closed?
+```
+
+
+Indicates that the browser context is in the process of closing or has already been closed.
+
 ## new_cdp_session
 
 ```
@@ -431,6 +440,23 @@ def storage_state(indexedDB: nil, path: nil)
 
 Returns storage state for this browser context, contains current cookies, local storage snapshot and IndexedDB snapshot.
 
+## set_storage_state
+
+```
+def set_storage_state(storageState)
+```
+alias: `storage_state=`
+
+
+Clears the existing cookies, local storage and IndexedDB entries for all origins and sets the new storage state.
+
+**Usage**
+
+```ruby
+# Load storage state from a file and apply it to the context.
+context.set_storage_state("state.json")
+```
+
 ## unroute_all
 
 ```

data/documentation/docs/api/browser_type.md

@@ -62,6 +62,7 @@ A path where Playwright expects to find a bundled browser executable.
 ```
 def launch(
       args: nil,
+      artifactsDir: nil,
       channel: nil,
       chromiumSandbox: nil,
       downloadsPath: nil,
@@ -118,6 +119,7 @@ def launch_persistent_context(
       userDataDir,
       acceptDownloads: nil,
       args: nil,
+      artifactsDir: nil,
       baseURL: nil,
       bypassCSP: nil,
       channel: nil,

data/documentation/docs/api/console_message.md

@@ -67,6 +67,15 @@ def text
 
 The text of the console message.
 
+## timestamp
+
+```
+def timestamp
+```
+
+
+The timestamp of the console message in milliseconds since the Unix epoch.
+
 ## type
 
 ```

data/documentation/docs/api/frame.md

@@ -512,7 +512,7 @@ Consider the following DOM structure.
 <button>Submit</button>
 ```
 
-You can locate each element by it's implicit role:
+You can locate each element by its implicit role:
 
 ```ruby
 page.get_by_role("heading", name: "Sign up").visible? # => true
@@ -544,7 +544,7 @@ Consider the following DOM structure.
 <button data-testid="directions">Itinéraire</button>
 ```
 
-You can locate the element by it's test id:
+You can locate the element by its test id:
 
 ```ruby
 page.get_by_test_id("directions").click

data/documentation/docs/api/frame_locator.md

@@ -157,7 +157,7 @@ Consider the following DOM structure.
 <button>Submit</button>
 ```
 
-You can locate each element by it's implicit role:
+You can locate each element by its implicit role:
 
 ```ruby
 page.get_by_role("heading", name: "Sign up").visible? # => true
@@ -189,7 +189,7 @@ Consider the following DOM structure.
 <button data-testid="directions">Itinéraire</button>
 ```
 
-You can locate the element by it's test id:
+You can locate the element by its test id:
 
 ```ruby
 page.get_by_test_id("directions").click

data/documentation/docs/api/locator.md

@@ -87,7 +87,7 @@ button = page.get_by_role("button").and(page.get_by_title("Subscribe"))
 ## aria_snapshot
 
 ```
-def aria_snapshot(timeout: nil)
+def aria_snapshot(depth: nil, mode: nil, timeout: nil)
 ```
 
 
@@ -127,6 +127,9 @@ Below is the HTML markup and the respective ARIA snapshot:
     - link "About"
 ```
 
+An AI-optimized snapshot, controlled by `mode`, is different from a default snapshot:
+1. Includes element references `[ref=e2]`. 2. Does not wait for an element matching the locator, and throws when no elements match. 3. Includes snapshots of `<iframe>`s inside the target.
+
 ## blur
 
 ```
@@ -744,7 +747,7 @@ Consider the following DOM structure.
 <button>Submit</button>
 ```
 
-You can locate each element by it's implicit role:
+You can locate each element by its implicit role:
 
 ```ruby
 page.get_by_role("heading", name: "Sign up").visible? # => true
@@ -776,7 +779,7 @@ Consider the following DOM structure.
 <button data-testid="directions">Itinéraire</button>
 ```
 
-You can locate the element by it's test id:
+You can locate the element by its test id:
 
 ```ruby
 page.get_by_test_id("directions").click
@@ -1082,6 +1085,16 @@ The method finds an element matching the specified selector in the locator's sub
 
 [Learn more about locators](https://playwright.dev/python/docs/locators).
 
+## normalize
+
+```
+def normalize
+```
+
+
+Returns a new locator that uses best practices for referencing the matched element, prioritizing test ids,
+aria roles, and other user-facing attributes over CSS selectors. This is useful for converting implementation-detail selectors into more resilient, human-readable locators.
+
 ## nth
 
 ```

data/documentation/docs/api/page.md

@@ -94,6 +94,16 @@ def bring_to_front
 
 Brings page to front (activates tab).
 
+## cancel_pick_locator
+
+```
+def cancel_pick_locator
+```
+
+
+Cancels an ongoing [Page#pick_locator](./page#pick_locator) call by deactivating pick locator mode.
+If no pick locator mode is active, this method is a no-op.
+
 ## check
 
 ```
@@ -706,7 +716,7 @@ Consider the following DOM structure.
 <button>Submit</button>
 ```
 
-You can locate each element by it's implicit role:
+You can locate each element by its implicit role:
 
 ```ruby
 page.get_by_role("heading", name: "Sign up").visible? # => true
@@ -738,7 +748,7 @@ Consider the following DOM structure.
 <button data-testid="directions">Itinéraire</button>
 ```
 
-You can locate the element by it's test id:
+You can locate the element by its test id:
 
 ```ruby
 page.get_by_test_id("directions").click
@@ -995,10 +1005,28 @@ def visible?(selector, strict: nil, timeout: nil)
 
 Returns whether the element is [visible](https://playwright.dev/python/docs/actionability#visible). `selector` that does not match any elements is considered not visible.
 
+## clear_console_messages
+
+```
+def clear_console_messages
+```
+
+
+Clears all stored console messages from this page. Subsequent calls to [Page#console_messages](./page#console_messages) will only return messages logged after the clear.
+
+## clear_page_errors
+
+```
+def clear_page_errors
+```
+
+
+Clears all stored page errors from this page. Subsequent calls to [Page#page_errors](./page#page_errors) will only return errors thrown after the clear.
+
 ## console_messages
 
 ```
-def console_messages
+def console_messages(filter: nil)
 ```
 
 
@@ -1007,7 +1035,7 @@ Returns up to (currently) 200 last console messages from this page. See [`event:
 ## page_errors
 
 ```
-def page_errors
+def page_errors(filter: nil)
 ```
 
 
@@ -1132,6 +1160,23 @@ The `format` options are:
 **NOTE**: `headerTemplate` and `footerTemplate` markup have the following limitations: > 1. Script tags inside
 templates are not evaluated. > 2. Page styles are not visible inside templates.
 
+## pick_locator
+
+```
+def pick_locator
+```
+
+
+Enters pick locator mode where hovering over page elements highlights them and shows the corresponding locator.
+Once the user clicks an element, the mode is deactivated and the [Locator](./locator) for the picked element is returned.
+
+**Usage**
+
+```ruby
+locator = page.pick_locator
+puts locator
+```
+
 ## press
 
 ```
@@ -1269,6 +1314,8 @@ end
 page.route("/api/**", method(:handle_route))
 ```
 
+If a request matches multiple registered routes, the most recently registered route takes precedence.
+
 Page routes take precedence over browser context routes (set up with [BrowserContext#route](./browser_context#route)) when request
 matches both handlers.
 
@@ -1471,6 +1518,15 @@ page.viewport_size = { width: 640, height: 480 }
 page.goto("https://example.com")
 ```
 
+## aria_snapshot
+
+```
+def aria_snapshot(depth: nil, mode: nil, timeout: nil)
+```
+
+
+Captures the aria snapshot of the page. Read more about [aria snapshots](https://playwright.dev/python/docs/aria-snapshots).
+
 ## tap_point
 
 ```
@@ -1600,7 +1656,7 @@ def video
 ```
 
 
-Video object associated with this page.
+Video object associated with this page. Can be used to access the video file when using the `recordVideo` context option.
 
 ## viewport_size
 
@@ -1943,4 +1999,11 @@ Playwright has ability to mock clock and passage of time.
 API testing helper associated with this page. This method returns the same instance as
 [BrowserContext#request](./browser_context#request) on the page's context. See [BrowserContext#request](./browser_context#request) for more details.
 
+## screencast
+
+
+`Screencast` object associated with this page.
+
+**Usage**
+
 ## touchscreen

data/documentation/docs/api/request.md

@@ -216,6 +216,19 @@ def response
 
 Returns the matching [Response](./response) object, or `null` if the response was not received due to error.
 
+## existing_response
+
+```
+def existing_response
+```
+
+
+Returns the [Response](./response) object if the response has already been received, `null` otherwise.
+
+Unlike [Request#response](./request#response), this method does not wait for the response to arrive. It returns
+immediately with the response object if the response has been received, or `null` if the response
+has not been received yet.
+
 ## sizes
 
 ```

data/documentation/docs/api/response.md

@@ -92,6 +92,15 @@ def header_values(name)
 
 Returns all values of the headers matching the name, for example `set-cookie`. The name is case-insensitive.
 
+## http_version
+
+```
+def http_version
+```
+
+
+Returns the http version used by the response.
+
 ## json
 
 ```

data/documentation/docs/api/tracing.md

@@ -26,6 +26,7 @@ end
 
 ```
 def start(
+      live: nil,
       name: nil,
       screenshots: nil,
       snapshots: nil,

data/documentation/docs/article/guides/rails_integration_with_null_driver.md

@@ -85,6 +85,52 @@ describe 'example', driver: :null do
 end
 ```
 
+## Share one browser across all tests
+
+Launching a new browser for every test is slow. A better approach is to launch the browser once for the entire suite and give each test its own `BrowserContext` for isolation (fresh cookies, localStorage, and session state).
+
+The challenge is that `Playwright.create` and `playwright.chromium.launch` are block-scoped APIs — the browser shuts down when the block exits. RSpec has `before(:suite)` and `after(:suite)` but no `around(:suite)`. A `Fiber` bridges the gap: `start!` resumes the fiber until it yields the browser back, and `stop!` resumes it again so both blocks exit cleanly.
+
+```rb
+module PlaywrightBrowser
+  class << self
+    attr_reader :browser
+
+    def start!
+      @fiber = Fiber.new do
+        Playwright.create(playwright_cli_executable_path: './node_modules/.bin/playwright') do |playwright|
+          playwright.chromium.launch(headless: false) do |browser|
+            Fiber.yield(browser)
+          end
+        end
+      end
+      @browser = @fiber.resume
+    end
+
+    def stop!
+      @fiber.resume
+    end
+  end
+end
+
+RSpec.configure do |config|
+  config.before(:suite) { PlaywrightBrowser.start! }
+  config.after(:suite)  { PlaywrightBrowser.stop! }
+
+  config.around(driver: :null) do |example|
+    Capybara.current_driver = :null
+    base_url = Capybara.current_session.server.base_url
+
+    PlaywrightBrowser.browser.new_context(baseURL: base_url) do |browser_context|
+      @playwright_page = browser_context.new_page
+      example.run
+    end
+  end
+end
+```
+
+Each test gets a fresh `BrowserContext` (equivalent to a new incognito window), so cookies and storage never leak between tests. The block form of `new_context` ensures the context is always closed — even if the test raises an exception.
+
 ## Minitest Usage
 
 We can do something similar with the default Rails setup using Minitest. Here's the same example written with Minitest:

data/documentation/docs/include/api_coverage.md

@@ -17,6 +17,7 @@
 * redirected_to
 * resource_type
 * response
+* existing_response
 * ~~service_worker~~
 * sizes
 * timing
@@ -33,6 +34,7 @@
 * headers_array
 * header_value
 * header_values
+* http_version
 * json
 * ok
 * request
@@ -228,6 +230,7 @@
 * location
 * page
 * text
+* timestamp
 * type
 * worker
 
@@ -257,6 +260,7 @@
 * add_script_tag
 * add_style_tag
 * bring_to_front
+* cancel_pick_locator
 * check
 * click
 * close
@@ -300,6 +304,8 @@
 * enabled?
 * hidden?
 * visible?
+* clear_console_messages
+* clear_page_errors
 * console_messages
 * page_errors
 * locator
@@ -307,6 +313,7 @@
 * opener
 * pause
 * pdf
+* pick_locator
 * press
 * query_selector
 * query_selector_all
@@ -326,6 +333,7 @@
 * set_extra_http_headers
 * set_input_files
 * set_viewport_size
+* aria_snapshot
 * tap_point
 * text_content
 * title
@@ -358,6 +366,7 @@
 * keyboard
 * mouse
 * request
+* screencast
 * touchscreen
 
 ## BrowserContext
@@ -373,6 +382,7 @@
 * expose_binding
 * expose_function
 * grant_permissions
+* closed?
 * new_cdp_session
 * new_page
 * pages
@@ -386,6 +396,7 @@
 * set_geolocation
 * set_offline
 * storage_state
+* set_storage_state
 * unroute_all
 * unroute
 * expect_console_message
@@ -393,6 +404,7 @@
 * expect_page
 * ~~wait_for_event~~
 * clock
+* ~~debugger~~
 * request
 * tracing
 
@@ -410,8 +422,10 @@
 * new_browser_cdp_session
 * new_context
 * new_page
+* ~~bind~~
 * start_tracing
 * stop_tracing
+* ~~unbind~~
 * version
 
 ## BrowserType
@@ -492,6 +506,7 @@
 * visible?
 * last
 * locator
+* normalize
 * nth
 * or
 * page

data/lib/playwright/channel_owners/browser_context.rb

@@ -333,8 +333,8 @@ module Playwright
           raise ArgumentError.new('Either path or script parameter must be specified')
         end
 
-      @channel.send_message_to_server('addInitScript', source: source)
-      nil
+      result = @channel.send_message_to_server_result('addInitScript', source: source)
+      ChannelOwners::Disposable.from(result['disposable'])
     end
 
     def expose_binding(name, callback, handle: nil)
@@ -349,17 +349,19 @@ module Playwright
         needsHandle: handle,
       }.compact
       @bindings[name] = callback
-      @channel.send_message_to_server('exposeBinding', params)
+      result = @channel.send_message_to_server_result('exposeBinding', params)
+      ChannelOwners::Disposable.from(result['disposable'])
     end
 
     def expose_function(name, callback)
-      expose_binding(name, ->(_source, *args) { callback.call(*args) }, )
+      expose_binding(name, ->(_source, *args) { callback.call(*args) })
     end
 
     def route(url, handler, times: nil)
       entry = RouteHandler.new(url, base_url, handler, times)
       @routes.unshift(entry)
       update_interception_patterns
+      DisposableStub.new { unroute(url, handler: handler) }
     end
 
     def unroute_all(behavior: nil)
@@ -547,6 +549,24 @@ module Playwright
       @timeout_settings
     end
 
+    def set_storage_state(storageState)
+      payload = case storageState
+                when String
+                  begin
+                    JSON.parse(File.read(storageState))
+                  rescue => e
+                    raise ::Playwright::Error.new(message: "Failed to read storage state from '#{storageState}': #{e.message}")
+                  end
+                else
+                  storageState
+                end
+      @channel.send_message_to_server('setStorageState', storageState: payload)
+    end
+
+    def closed?
+      @close_was_called
+    end
+
     private def has_record_video_option?
       @options.key?(:recordVideo)
     end

data/lib/playwright/channel_owners/debugger.rb

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

data/lib/playwright/channel_owners/dialog.rb

@@ -26,7 +26,9 @@ module Playwright
     end
 
     def dismiss
-      @channel.async_send_message_to_server('dismiss')
+      @channel.send_message_to_server('dismiss')
+    rescue TargetClosedError
+      # Swallow target-closed errors for beforeunload dialogs.
     end
   end
 end

data/lib/playwright/channel_owners/disposable.rb

@@ -0,0 +1,9 @@
+module Playwright
+  define_channel_owner :Disposable do
+    def dispose
+      @channel.send_message_to_server('dispose')
+    rescue TargetClosedError
+      nil
+    end
+  end
+end

data/lib/playwright/channel_owners/overlay.rb

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