playwright-ruby-client 1.62.0 → 1.64.0

data/lib/playwright_api/locator.rb

@@ -961,6 +961,26 @@ module Playwright
     #
     # 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.
+    #
+    # **Usage**
+    #
+    # An agent can pick an element by its ref from an [`method: Page.ariaSnapshot`] taken in the `"ai"` mode. Refs only
+    # work for the latest snapshot. Normalize the ref locator and convert it to a string to get resilient locator code
+    # in your language, the same way `codegen` does.
+    #
+    # Consider the following aria snapshot.
+    #
+    # ```yaml
+    # - button "Submit" [ref=e2]
+    # ```
+    #
+    # You can turn the ref into locator code:
+    #
+    # ```python sync
+    # normalized = page.get_by_ref("e2").normalize()
+    # print(str(normalized))
+    # # get_by_role("button", name="Submit")
+    # ```
     def normalize
       wrap_impl(@impl.normalize)
     end
@@ -1317,6 +1337,31 @@ module Playwright
       wrap_impl(@impl.uncheck(force: unwrap_impl(force), noWaitAfter: unwrap_impl(noWaitAfter), position: unwrap_impl(position), scroll: unwrap_impl(scroll), timeout: unwrap_impl(timeout), trial: unwrap_impl(trial)))
     end
 
+    #
+    # Returns a locator that matches only [visible](../actionability.md#visible) elements, ignoring the invisible ones. This is the recommended way to distinguish elements by visibility, as opposed to the `:visible` CSS pseudo-class.
+    #
+    # Note that visibility is checked every time the locator is used, and not at the moment of the [`method: Locator.visible`] call.
+    #
+    # **Usage**
+    #
+    # Consider a page with two buttons, the first invisible and the second visible.
+    #
+    # ```html
+    # <button style='display: none'>Invisible</button>
+    # <button>Visible</button>
+    # ```
+    #
+    # This will only find the second button, because it is visible, and then click it.
+    #
+    # ```python sync
+    # page.locator("button").visible.click()
+    # ```
+    #
+    # To match invisible elements instead, use [`method: Locator.filter`] with the `visible` option set to `false`.
+    def visible
+      wrap_impl(@impl.visible)
+    end
+
     #
     # Returns when element specified by locator satisfies the `state` option.
     #
@@ -1351,9 +1396,19 @@ module Playwright
       wrap_impl(@impl.wait_for_function(unwrap_impl(expression), arg: unwrap_impl(arg), timeout: unwrap_impl(timeout)))
     end
 
-    # @nodoc
-    def expect(expression, options, title)
-      wrap_impl(@impl.expect(unwrap_impl(expression), unwrap_impl(options), unwrap_impl(title)))
+    #
+    # Returns a locator that matches this locator's elements inside each element matched by `locator`.
+    #
+    # Note that relative locators, such as [`method: Locator.nth`] or [`method: Locator.first`], are resolved separately inside each matched parent. In the example below, `page.getByRole('cell').nth(2)` picks the third cell of every row, not the third cell in the whole table.
+    #
+    # **Usage**
+    #
+    # ```python sync
+    # third_column = page.get_by_role("cell").nth(2).within(page.get_by_role("row"))
+    # expect(third_column).to_have_text(["Apple", "Banana", "Cherry"])
+    # ```
+    def within(locator)
+      wrap_impl(@impl.within(unwrap_impl(locator)))
     end
 
     # @nodoc
@@ -1366,6 +1421,11 @@ module Playwright
       wrap_impl(@impl.resolve_selector)
     end
 
+    # @nodoc
+    def expect(expression, options, title)
+      wrap_impl(@impl.expect(unwrap_impl(expression), unwrap_impl(options), unwrap_impl(title)))
+    end
+
     # @nodoc
     def to_s
       wrap_impl(@impl.to_s)

data/lib/playwright_api/page.rb

@@ -88,6 +88,14 @@ module Playwright
       wrap_impl(@impl.touchscreen)
     end
 
+    #
+    # Tools that the main frame registers through the experimental `WebMCP` browser API. Shortcut for [`property: Frame.webmcp`] of [`method: Page.mainFrame`], see `WebMCP` for details.
+    #
+    # **Usage**
+    def webmcp # property
+      wrap_impl(@impl.webmcp)
+    end
+
     #
     # Adds a script which would be evaluated in one of the following scenarios:
     # - Whenever the page is navigated.
@@ -201,8 +209,8 @@ module Playwright
 
     #
     # Gets the full HTML contents of the page, including the doctype.
-    def content
-      wrap_impl(@impl.content)
+    def content(includeShadow: nil)
+      wrap_impl(@impl.content(includeShadow: unwrap_impl(includeShadow)))
     end
 
     #
@@ -592,6 +600,10 @@ module Playwright
     # When working with iframes, you can create a frame locator that will enter the iframe and allow selecting elements
     # in that iframe.
     #
+    # When called without `selector`, the search starts in any frame on the page - the main frame or any of
+    # the iframes - so that you don't need to locate each iframe first. Note that the rest of the locator is resolved
+    # inside a single frame, just like any other locator. If it matches elements inside multiple frames, an error is thrown.
+    #
     # **Usage**
     #
     # Following snippet locates element with text "Submit" in the iframe with id `my-frame`,
@@ -601,7 +613,14 @@ module Playwright
     # locator = page.frame_locator("#my-iframe").get_by_text("Submit")
     # locator.click()
     # ```
-    def frame_locator(selector)
+    #
+    # Following snippet locates a button, either in the main frame or in one of the iframes:
+    #
+    # ```python sync
+    # locator = page.frame_locator().get_by_role("button")
+    # locator.click()
+    # ```
+    def frame_locator(selector = nil)
       wrap_impl(@impl.frame_locator(unwrap_impl(selector)))
     end
 
@@ -676,6 +695,27 @@ module Playwright
       wrap_impl(@impl.get_by_placeholder(unwrap_impl(text), exact: unwrap_impl(exact)))
     end
 
+    #
+    # Locate element by its aria ref. Refs like `[ref=e2]` are reported by [`method: Page.ariaSnapshot`] when called with
+    # the `"ai"` mode, and resolve against the latest snapshot taken in the element's frame.
+    #
+    # **Usage**
+    #
+    # Consider the following aria snapshot.
+    #
+    # ```yaml
+    # - button "Submit" [ref=e2]
+    # ```
+    #
+    # You can locate the button by its ref:
+    #
+    # ```python sync
+    # page.get_by_ref("e2").click()
+    # ```
+    def get_by_ref(ref)
+      wrap_impl(@impl.get_by_ref(unwrap_impl(ref)))
+    end
+
     #
     # Allows locating elements by their [ARIA role](https://www.w3.org/TR/wai-aria-1.2/#roles), [ARIA attributes](https://www.w3.org/TR/wai-aria-1.2/#aria-attributes) and [accessible name](https://w3c.github.io/accname/#dfn-accessible-name).
     #
@@ -1900,13 +1940,13 @@ module Playwright
     end
 
     # @nodoc
-    def _assertions(timeout, is_not, message)
-      wrap_impl(@impl._assertions(unwrap_impl(timeout), unwrap_impl(is_not), unwrap_impl(message)))
+    def start_js_coverage(resetOnNavigation: nil, reportAnonymousScripts: nil)
+      wrap_impl(@impl.start_js_coverage(resetOnNavigation: unwrap_impl(resetOnNavigation), reportAnonymousScripts: unwrap_impl(reportAnonymousScripts)))
     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_js_coverage
+      wrap_impl(@impl.stop_js_coverage)
     end
 
     # @nodoc
@@ -1915,13 +1955,13 @@ module Playwright
     end
 
     # @nodoc
-    def start_js_coverage(resetOnNavigation: nil, reportAnonymousScripts: nil)
-      wrap_impl(@impl.start_js_coverage(resetOnNavigation: unwrap_impl(resetOnNavigation), reportAnonymousScripts: unwrap_impl(reportAnonymousScripts)))
+    def _assertions(timeout, is_not, message)
+      wrap_impl(@impl._assertions(unwrap_impl(timeout), unwrap_impl(is_not), unwrap_impl(message)))
     end
 
     # @nodoc
-    def stop_js_coverage
-      wrap_impl(@impl.stop_js_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
@@ -1936,20 +1976,20 @@ module Playwright
 
     # -- inherited from EventEmitter --
     # @nodoc
-    def once(event, callback)
-      event_emitter_proxy.once(event, callback)
+    def off(event, callback)
+      event_emitter_proxy.off(event, callback)
     end
 
     # -- inherited from EventEmitter --
     # @nodoc
-    def on(event, callback)
-      event_emitter_proxy.on(event, callback)
+    def once(event, callback)
+      event_emitter_proxy.once(event, callback)
     end
 
     # -- inherited from EventEmitter --
     # @nodoc
-    def off(event, callback)
-      event_emitter_proxy.off(event, callback)
+    def on(event, callback)
+      event_emitter_proxy.on(event, callback)
     end
 
     private def event_emitter_proxy

data/lib/playwright_api/playwright.rb

@@ -105,20 +105,20 @@ module Playwright
 
     # -- inherited from EventEmitter --
     # @nodoc
-    def once(event, callback)
-      event_emitter_proxy.once(event, callback)
+    def off(event, callback)
+      event_emitter_proxy.off(event, callback)
     end
 
     # -- inherited from EventEmitter --
     # @nodoc
-    def on(event, callback)
-      event_emitter_proxy.on(event, callback)
+    def once(event, callback)
+      event_emitter_proxy.once(event, callback)
     end
 
     # -- inherited from EventEmitter --
     # @nodoc
-    def off(event, callback)
-      event_emitter_proxy.off(event, callback)
+    def on(event, callback)
+      event_emitter_proxy.on(event, callback)
     end
 
     private def event_emitter_proxy

data/lib/playwright_api/request.rb

@@ -155,7 +155,7 @@ module Playwright
     #
     # Contains the request's resource type as it was perceived by the rendering engine. ResourceType will be one of the
     # following: `document`, `stylesheet`, `image`, `media`, `font`, `script`, `texttrack`, `xhr`, `fetch`, `eventsource`,
-    # `websocket`, `manifest`, `other`.
+    # `websocket`, `manifest`, `beacon`, `ping`, `cspreport`, `other`.
     def resource_type
       wrap_impl(@impl.resource_type)
     end
@@ -229,20 +229,20 @@ module Playwright
 
     # -- inherited from EventEmitter --
     # @nodoc
-    def once(event, callback)
-      event_emitter_proxy.once(event, callback)
+    def off(event, callback)
+      event_emitter_proxy.off(event, callback)
     end
 
     # -- inherited from EventEmitter --
     # @nodoc
-    def on(event, callback)
-      event_emitter_proxy.on(event, callback)
+    def once(event, callback)
+      event_emitter_proxy.once(event, callback)
     end
 
     # -- inherited from EventEmitter --
     # @nodoc
-    def off(event, callback)
-      event_emitter_proxy.off(event, callback)
+    def on(event, callback)
+      event_emitter_proxy.on(event, callback)
     end
 
     private def event_emitter_proxy

data/lib/playwright_api/response.rb

@@ -42,8 +42,9 @@ module Playwright
     end
 
     #
-    # An array with all the request HTTP headers associated with this response. Unlike [`method: Response.allHeaders`], header names are NOT lower-cased.
+    # An array with all the response HTTP headers associated with this response. Unlike [`method: Response.allHeaders`], header names are NOT lower-cased.
     # Headers with multiple entries, such as `Set-Cookie`, appear in the array multiple times.
+    # Some browser network stacks combine multiple field values before reporting them, so separate entries are not always available.
     def headers_array
       wrap_impl(@impl.headers_array)
     end
@@ -135,20 +136,20 @@ module Playwright
 
     # -- inherited from EventEmitter --
     # @nodoc
-    def once(event, callback)
-      event_emitter_proxy.once(event, callback)
+    def off(event, callback)
+      event_emitter_proxy.off(event, callback)
     end
 
     # -- inherited from EventEmitter --
     # @nodoc
-    def on(event, callback)
-      event_emitter_proxy.on(event, callback)
+    def once(event, callback)
+      event_emitter_proxy.once(event, callback)
     end
 
     # -- inherited from EventEmitter --
     # @nodoc
-    def off(event, callback)
-      event_emitter_proxy.off(event, callback)
+    def on(event, callback)
+      event_emitter_proxy.on(event, callback)
     end
 
     private def event_emitter_proxy

data/lib/playwright_api/route.rb

@@ -179,20 +179,20 @@ module Playwright
 
     # -- inherited from EventEmitter --
     # @nodoc
-    def once(event, callback)
-      event_emitter_proxy.once(event, callback)
+    def off(event, callback)
+      event_emitter_proxy.off(event, callback)
     end
 
     # -- inherited from EventEmitter --
     # @nodoc
-    def on(event, callback)
-      event_emitter_proxy.on(event, callback)
+    def once(event, callback)
+      event_emitter_proxy.once(event, callback)
     end
 
     # -- inherited from EventEmitter --
     # @nodoc
-    def off(event, callback)
-      event_emitter_proxy.off(event, callback)
+    def on(event, callback)
+      event_emitter_proxy.on(event, callback)
     end
 
     private def event_emitter_proxy

data/lib/playwright_api/tracing.rb

@@ -19,7 +19,7 @@ module Playwright
   class Tracing < PlaywrightApi
 
     #
-    # Start tracing.
+    # Start tracing. Disposing the returned `Disposable` stops tracing without saving the trace, similarly to calling [`method: Tracing.stop`] without a path.
     #
     # **NOTE**: You probably want to [enable tracing in your config file](https://playwright.dev/docs/api/class-testoptions#test-options-trace) instead of using `Tracing.start`.
     #
@@ -34,17 +34,19 @@ module Playwright
     # context.tracing.stop(path = "trace.zip")
     # ```
     def start(
+          ariaSnapshots: nil,
           live: nil,
           name: nil,
           screenshots: nil,
+          screenSnapshots: nil,
           snapshots: nil,
           sources: nil,
           title: nil)
-      wrap_impl(@impl.start(live: unwrap_impl(live), name: unwrap_impl(name), screenshots: unwrap_impl(screenshots), snapshots: unwrap_impl(snapshots), sources: unwrap_impl(sources), title: unwrap_impl(title)))
+      wrap_impl(@impl.start(ariaSnapshots: unwrap_impl(ariaSnapshots), live: unwrap_impl(live), name: unwrap_impl(name), screenshots: unwrap_impl(screenshots), screenSnapshots: unwrap_impl(screenSnapshots), snapshots: unwrap_impl(snapshots), sources: unwrap_impl(sources), title: unwrap_impl(title)))
     end
 
     #
-    # Start a new trace chunk. If you'd like to record multiple traces on the same `BrowserContext`, use [`method: Tracing.start`] once, and then create multiple trace chunks with [`method: Tracing.startChunk`] and [`method: Tracing.stopChunk`].
+    # Start a new trace chunk. Disposing the returned `Disposable` stops the chunk without saving it, similarly to calling [`method: Tracing.stopChunk`] without a path. If you'd like to record multiple traces on the same `BrowserContext`, use [`method: Tracing.start`] once, and then create multiple trace chunks with [`method: Tracing.startChunk`] and [`method: Tracing.stopChunk`].
     #
     # **Usage**
     #
@@ -70,7 +72,7 @@ module Playwright
     #
     # Start recording a HAR (HTTP Archive) of network activity in this context. The HAR file is written to disk when [`method: Tracing.stopHar`] is called, or when the returned `Disposable` is disposed.
     #
-    # Only one HAR recording can be active at a time per `BrowserContext`.
+    # Only one HAR recording can be active at a time per `Tracing` instance.
     #
     # **Usage**
     #
@@ -129,20 +131,20 @@ module Playwright
 
     # -- inherited from EventEmitter --
     # @nodoc
-    def once(event, callback)
-      event_emitter_proxy.once(event, callback)
+    def off(event, callback)
+      event_emitter_proxy.off(event, callback)
     end
 
     # -- inherited from EventEmitter --
     # @nodoc
-    def on(event, callback)
-      event_emitter_proxy.on(event, callback)
+    def once(event, callback)
+      event_emitter_proxy.once(event, callback)
     end
 
     # -- inherited from EventEmitter --
     # @nodoc
-    def off(event, callback)
-      event_emitter_proxy.off(event, callback)
+    def on(event, callback)
+      event_emitter_proxy.on(event, callback)
     end
 
     private def event_emitter_proxy

data/lib/playwright_api/web_mcp.rb

@@ -0,0 +1,26 @@
+module Playwright
+  #
+  # `WebMCP` exposes the tools that a frame registers through the experimental `WebMCP` browser API, `navigator.modelContext`. It lists the tools and calls them.
+  #
+  # Instances are accessed through [`property: Frame.webmcp`]. [`property: Page.webmcp`] is the instance of the main frame.
+  #
+  # **NOTE**: WebMCP is an experimental browser feature. Chromium enables it with the `--enable-features=WebMCP` launch argument, Firefox with the `dom.modelcontext.enabled` and `dom.modelcontext.testing.enabled` preferences. WebKit does not implement it.
+  #
+  # Tool names, descriptions, input schemas and results are provided by the page, so treat them as untrusted input.
+  class WebMCP < PlaywrightApi
+
+    #
+    # Calls a tool registered by the frame and returns its result. The result is whatever the tool's `execute` function resolved to, typically an object with a `content` array. A result with `isError: true` is returned as is. The method throws when the tool is not registered or its `execute` function throws.
+    def call_tool(name, input: nil, timeout: nil)
+      wrap_impl(@impl.call_tool(unwrap_impl(name), input: unwrap_impl(input), timeout: unwrap_impl(timeout)))
+    end
+
+    #
+    # Returns the tools currently registered by the frame. Throws if the browser was launched without WebMCP support, see the note above for the launch options that enable it.
+    #
+    # [`property: Page.webmcp`] covers the main frame only, child frames list their tools through their own [`property: Frame.webmcp`].
+    def tools(timeout: nil)
+      wrap_impl(@impl.tools(timeout: unwrap_impl(timeout)))
+    end
+  end
+end

data/lib/playwright_api/web_socket.rb

@@ -36,20 +36,20 @@ module Playwright
 
     # -- inherited from EventEmitter --
     # @nodoc
-    def once(event, callback)
-      event_emitter_proxy.once(event, callback)
+    def off(event, callback)
+      event_emitter_proxy.off(event, callback)
     end
 
     # -- inherited from EventEmitter --
     # @nodoc
-    def on(event, callback)
-      event_emitter_proxy.on(event, callback)
+    def once(event, callback)
+      event_emitter_proxy.once(event, callback)
     end
 
     # -- inherited from EventEmitter --
     # @nodoc
-    def off(event, callback)
-      event_emitter_proxy.off(event, callback)
+    def on(event, callback)
+      event_emitter_proxy.on(event, callback)
     end
 
     private def event_emitter_proxy

data/lib/playwright_api/worker.rb

@@ -75,20 +75,20 @@ module Playwright
 
     # -- inherited from EventEmitter --
     # @nodoc
-    def once(event, callback)
-      event_emitter_proxy.once(event, callback)
+    def off(event, callback)
+      event_emitter_proxy.off(event, callback)
     end
 
     # -- inherited from EventEmitter --
     # @nodoc
-    def on(event, callback)
-      event_emitter_proxy.on(event, callback)
+    def once(event, callback)
+      event_emitter_proxy.once(event, callback)
     end
 
     # -- inherited from EventEmitter --
     # @nodoc
-    def off(event, callback)
-      event_emitter_proxy.off(event, callback)
+    def on(event, callback)
+      event_emitter_proxy.on(event, callback)
     end
 
     private def event_emitter_proxy