playwright-ruby-client 1.62.0 → 1.64.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7c78e6a1f2ee45aadb2b8a027d08a0264560172b843419e23376c80f74095ccd
-  data.tar.gz: b31e8c1c972865e68312f65ee23a821535f14592affadcc65580b10169819b81
+  metadata.gz: 3d790738449c6398b19249ce438000db7f00a06a46b8db59307f2595d849781b
+  data.tar.gz: 7010d04e7614128ad40443dae1f3745b0588915c5af4e1d8c81c21f962b9d4c5
 SHA512:
-  metadata.gz: de6ea998c746c0fa3107850695144b7204105c01daa6209f646c2a172bd59eb906e169b4b7ed7dca436e8084611496def05fc81bb23134d8475bedbc480d6fd5
-  data.tar.gz: 907612d4a87117af9d0c57ada0ec4144f7451f7a75176b2b93d3cf896ff6ce8492f7e72ff8a2c04ce1d5d2871fdf9af2f967de9e5175010574d09c276b160300
+  metadata.gz: c1ff297b16ee61f37ece9c223280dc7ea31c1ecbe5aab4ec130348e6c0c74ca5ab86769328c2810daee6166bb4153a7a703d3bcac99472cdc43920089a60a37c
+  data.tar.gz: 9a899659118c9b797a368c956538496fad57df2bb6b33d282af420095eecea459a323d2f046ba61d67e6c7d0bed9cb181fdcc4d2b7e57ac1d7bd8a05f0215e71

data/documentation/docs/api/api_request_context.md

@@ -57,6 +57,53 @@ playwright.chromium.launch do |browser|
 end
 ```
 
+## add_cookies
+
+```
+def add_cookies(cookies)
+```
+
+
+Adds cookies into this request context. They will be sent with matching subsequent requests. For [BrowserContext#request](./browser_context#request)
+and [Page#request](./page#request), this is equivalent to calling [BrowserContext#add_cookies](./browser_context#add_cookies) on the corresponding browser context.
+
+**Usage**
+
+```ruby
+request.add_cookies([cookie_object1, cookie_object2])
+```
+
+## clear_cookies
+
+```
+def clear_cookies(domain: nil, name: nil, path: nil)
+```
+
+
+Removes cookies from this request context. Accepts optional filter. For [BrowserContext#request](./browser_context#request)
+and [Page#request](./page#request), this is equivalent to calling [BrowserContext#clear_cookies](./browser_context#clear_cookies) on the corresponding browser context.
+
+**Usage**
+
+```ruby
+request.clear_cookies
+request.clear_cookies(name: "session-id")
+request.clear_cookies(domain: "my-origin.com")
+request.clear_cookies(path: "/api/v1")
+request.clear_cookies(name: "session-id", domain: "my-origin.com")
+```
+
+## cookies
+
+```
+def cookies(urls: nil)
+```
+
+
+If no URLs are specified, this method returns all cookies. If URLs are specified, only cookies that affect those URLs
+are returned. For [BrowserContext#request](./browser_context#request) and [Page#request](./page#request), this is equivalent to calling
+[BrowserContext#cookies](./browser_context#cookies) on the corresponding browser context.
+
 ## delete
 
 ```
@@ -298,3 +345,6 @@ The method will populate request cookies from the context and update
 context cookies from the response. The method will automatically follow redirects.
 
 ## tracing
+
+
+Tracing recorder for requests made through this API request context.

data/documentation/docs/api/browser.md

@@ -113,6 +113,7 @@ def new_context(
       record_har_path: nil,
       record_har_url_filter: nil,
       record_video_dir: nil,
+      record_video_fps: nil,
       record_video_size: nil,
       reducedMotion: nil,
       screen: nil,
@@ -174,6 +175,7 @@ def new_page(
       record_har_path: nil,
       record_har_url_filter: nil,
       record_video_dir: nil,
+      record_video_fps: nil,
       record_video_size: nil,
       reducedMotion: nil,
       screen: nil,

data/documentation/docs/api/browser_context.md

@@ -434,11 +434,11 @@ alias: `offline=`
 ## storage_state
 
 ```
-def storage_state(credentials: nil, indexedDB: nil, path: nil)
+def storage_state(credentials: nil, indexedDB: nil, opfs: nil, path: nil)
 ```
 
 
-Returns storage state for this browser context, contains current cookies, local storage snapshot, IndexedDB snapshot and virtual WebAuthn credentials.
+Returns storage state for this browser context, contains current cookies, local storage snapshot, IndexedDB snapshot, origin private file system snapshot and virtual WebAuthn credentials.
 
 ## set_storage_state
 
@@ -448,7 +448,7 @@ def set_storage_state(storageState)
 alias: `storage_state=`
 
 
-Clears the existing cookies, local storage, IndexedDB entries and virtual WebAuthn credentials, and sets the new storage
+Clears the existing cookies, local storage, IndexedDB entries, origin private file system entries and virtual WebAuthn credentials, and sets the new storage
 state. When the storage state contains credentials, the virtual WebAuthn authenticator is installed (equivalent to
 [Credentials#install](./credentials#install)), preventing all real authenticators from working in this context.
 

data/documentation/docs/api/browser_type.md

@@ -177,6 +177,7 @@ def launch_persistent_context(
       record_har_path: nil,
       record_har_url_filter: nil,
       record_video_dir: nil,
+      record_video_fps: nil,
       record_video_size: nil,
       reducedMotion: nil,
       screen: nil,

data/documentation/docs/api/clock.md

@@ -36,6 +36,7 @@ def install(time: nil)
 
 Install fake implementations for the following time-related functions:
 - `Date`
+- `Temporal.Now`
 - `setTimeout`
 - `clearTimeout`
 - `setInterval`

data/documentation/docs/api/credentials.md

@@ -57,6 +57,7 @@ context.credentials.create(
   userHandle: credential["userHandle"],
   privateKey: credential["privateKey"],
   publicKey: credential["publicKey"],
+  signCount: credential["signCount"],
 )
 context.credentials.install
 
@@ -67,7 +68,7 @@ page.goto("https://example.com/login")
 
 **Usage: save credentials in the storage state, restore later**
 
-See [authentication guide](https://playwright.dev/python/docs/auth) for examples of using saving and resotring the storage state.
+See [authentication guide](https://playwright.dev/python/docs/auth) for examples of using saving and restoring the storage state.
 
 **Defaults**
 
@@ -95,6 +96,7 @@ def create(
       id: nil,
       privateKey: nil,
       publicKey: nil,
+      signCount: nil,
       userHandle: nil)
 ```
 
@@ -106,7 +108,8 @@ seeded credential is discoverable (resident), so the page can resolve it from bo
 username-then-passkey and usernameless passkey flows. The returned object carries the private and public keys, so it can be persisted to disk and re-seeded in a later test.
 
 To **import a known credential**, supply all four of `id`, `userHandle`, `privateKey` and
-`publicKey` together.
+`publicKey` together. Pass `signCount` as well to continue from the
+signature counter the relying party has already seen.
 
 Call [Credentials#install](./credentials#install) before navigating to a page that uses WebAuthn.
 
@@ -132,5 +135,5 @@ Returns every credential currently held by the authenticator, optionally filtere
 `id`. This includes both credentials seeded with [Credentials#create](./credentials#create) and credentials
 the page registered itself by calling `navigator.credentials.create()`.
 
-Each returned credential includes its private and public keys, so a passkey the app just
+Each returned credential includes its private and public keys and the current signature counter, so a passkey the app just
 registered can be saved and re-seeded into a later test with [Credentials#create](./credentials#create) — see the second example in the class overview.

data/documentation/docs/api/frame.md

@@ -116,7 +116,7 @@ When all steps combined have not finished during the specified `timeout`, this m
 ## content
 
 ```
-def content
+def content(includeShadow: nil)
 ```
 
 
@@ -391,13 +391,17 @@ puts frame == content_frame # => true
 ## frame_locator
 
 ```
-def frame_locator(selector)
+def frame_locator(selector = nil)
 ```
 
 
 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 this frame or in any of the iframes inside it,
+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`, like `<iframe id="my-frame">`:
@@ -407,6 +411,13 @@ locator = frame.frame_locator("#my-iframe").get_by_text("Submit")
 locator.click
 ```
 
+Following snippet locates a button, either in the frame or in one of the iframes inside it:
+
+```ruby
+locator = frame.frame_locator.get_by_role('button')
+locator.click
+```
+
 ## get_attribute
 
 ```
@@ -1225,3 +1236,8 @@ Waits for the frame to navigate to the given URL.
 frame.click("a.delayed-navigation") # clicking the link will indirectly cause a navigation
 frame.wait_for_url("**/target.html")
 ```
+
+## webmcp
+
+
+Tools that the frame registers through the experimental [WebMCP](./web_mcp) browser API. See [WebMCP](./web_mcp) for details.

data/documentation/docs/api/frame_locator.md

@@ -24,6 +24,26 @@ page.locator('.result-frame').content_frame.get_by_role('button').click
 page.locator('.result-frame').first.content_frame.get_by_role('button').click
 ```
 
+**Any frame**
+
+Calling [Page#frame_locator](./page#frame_locator) or [Frame#frame_locator](./frame#frame_locator) without a selector creates a frame locator that
+starts the search in any frame of the subtree - so that you don't
+need to locate the iframe first.
+
+```ruby
+# Finds the button in any frame on the page:
+page.frame_locator.get_by_role('button').click
+
+# Finds the iframe anywhere on the page and clicks the button inside it:
+page.frame_locator.locator('#my-frame').content_frame.get_by_role('button').click
+```
+
+Only the start of the search is affected - the rest of the locator is resolved inside a single frame, just like any
+other locator. Following the strictness rules above, an error is thrown when elements are matched in multiple frames.
+
+Such a frame locator does not point to a particular `iframe`, so [FrameLocator#owner](./frame_locator#owner),
+[FrameLocator#first](./frame_locator#first), [FrameLocator#last](./frame_locator#last) and [FrameLocator#nth](./frame_locator#nth) are not supported on it.
+
 **Converting Locator to FrameLocator**
 
 If you have a [Locator](./locator) object pointing to an `iframe` it can be converted to [FrameLocator](./frame_locator) using [Locator#content_frame](./locator#content_frame).

data/documentation/docs/api/locator.md

@@ -1135,6 +1135,26 @@ 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.
 
+**Usage**
+
+An agent can pick an element by its ref from an [Page#aria_snapshot](./page#aria_snapshot) 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:
+
+```ruby
+normalized = page.get_by_ref("e2").normalize
+puts normalized.to_s
+# get_by_role("button", name="Submit")
+```
+
 ## nth
 
 ```
@@ -1531,6 +1551,34 @@ If the element is detached from the DOM at any moment during the action, this me
 When all steps combined have not finished during the specified `timeout`, this method throws a
 `TimeoutError`. Passing zero timeout disables this.
 
+## visible
+
+```
+def visible
+```
+
+
+Returns a locator that matches only [visible](https://playwright.dev/python/docs/actionability#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 [Locator#visible](./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.
+
+```ruby
+page.locator('button').visible.click
+```
+
+To match invisible elements instead, use [Locator#filter](./locator#filter) with the `visible` option set to `false`.
+
 ## wait_for
 
 ```
@@ -1570,3 +1618,21 @@ If `expression` throws or rejects, this method throws.
 Wait for an attribute to appear:
 
 Passing argument to `expression`:
+
+## within
+
+```
+def within(locator)
+```
+
+
+Returns a locator that matches this locator's elements inside each element matched by `locator`.
+
+Note that relative locators, such as [Locator#nth](./locator#nth) or [Locator#first](./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**
+
+```ruby
+third_column = page.get_by_role("cell").nth(2).within(page.get_by_role("row"))
+expect(third_column).to have_text(["Apple", "Banana", "Cherry"])
+```

data/documentation/docs/api/page.md

@@ -177,7 +177,7 @@ manually via [`event: Page.dialog`] event.
 ## content
 
 ```
-def content
+def content(includeShadow: nil)
 ```
 
 
@@ -585,13 +585,17 @@ frame = page.frame(url: /.*domain.*/)
 ## frame_locator
 
 ```
-def frame_locator(selector)
+def frame_locator(selector = nil)
 ```
 
 
 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`,
@@ -602,6 +606,13 @@ locator = page.frame_locator("#my-iframe").get_by_text("Submit")
 locator.click
 ```
 
+Following snippet locates a button, either in the main frame or in one of the iframes:
+
+```ruby
+locator = page.frame_locator.get_by_role('button')
+locator.click
+```
+
 ## frames
 
 ```
@@ -688,6 +699,30 @@ You can fill the input after locating it by the placeholder text:
 page.get_by_placeholder("name@example.com").fill("playwright@microsoft.com")
 ```
 
+## get_by_ref
+
+```
+def get_by_ref(ref)
+```
+
+
+Locate element by its aria ref. Refs like `[ref=e2]` are reported by [Page#aria_snapshot](./page#aria_snapshot) 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:
+
+```ruby
+page.get_by_ref("e2").click
+```
+
 ## get_by_role
 
 ```
@@ -2041,3 +2076,10 @@ API testing helper associated with this page. This method returns the same insta
 **Usage**
 
 ## touchscreen
+
+## webmcp
+
+
+Tools that the main frame registers through the experimental [WebMCP](./web_mcp) browser API. Shortcut for [Frame#webmcp](./frame#webmcp) of [Page#main_frame](./page#main_frame), see [WebMCP](./web_mcp) for details.
+
+**Usage**

data/documentation/docs/api/request.md

@@ -205,7 +205,7 @@ def resource_type
 
 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`.
 
 ## response
 

data/documentation/docs/api/response.md

@@ -70,8 +70,9 @@ def headers_array
 ```
 
 
-An array with all the request HTTP headers associated with this response. Unlike [Response#all_headers](./response#all_headers), header names are NOT lower-cased.
+An array with all the response HTTP headers associated with this response. Unlike [Response#all_headers](./response#all_headers), 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.
 
 ## header_value
 

data/documentation/docs/api/tracing.md

@@ -26,16 +26,18 @@ end
 
 ```
 def start(
+      ariaSnapshots: nil,
       live: nil,
       name: nil,
       screenshots: nil,
+      screenSnapshots: nil,
       snapshots: nil,
       sources: nil,
       title: nil)
 ```
 
 
-Start tracing.
+Start tracing. Disposing the returned `Disposable` stops tracing without saving the trace, similarly to calling [Tracing#stop](./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`.
 
@@ -57,7 +59,7 @@ def start_chunk(name: nil, title: nil)
 ```
 
 
-Start a new trace chunk. If you'd like to record multiple traces on the same [BrowserContext](./browser_context), use [Tracing#start](./tracing#start) once, and then create multiple trace chunks with [Tracing#start_chunk](./tracing#start_chunk) and [Tracing#stop_chunk](./tracing#stop_chunk).
+Start a new trace chunk. Disposing the returned `Disposable` stops the chunk without saving it, similarly to calling [Tracing#stop_chunk](./tracing#stop_chunk) without a path. If you'd like to record multiple traces on the same [BrowserContext](./browser_context), use [Tracing#start](./tracing#start) once, and then create multiple trace chunks with [Tracing#start_chunk](./tracing#start_chunk) and [Tracing#stop_chunk](./tracing#stop_chunk).
 
 **Usage**
 
@@ -86,7 +88,7 @@ def start_har(path, content: nil, mode: nil, urlFilter: nil)
 
 Start recording a HAR (HTTP Archive) of network activity in this context. The HAR file is written to disk when [Tracing#stop_har](./tracing#stop_har) is called, or when the returned `Disposable` is disposed.
 
-Only one HAR recording can be active at a time per [BrowserContext](./browser_context).
+Only one HAR recording can be active at a time per [Tracing](./tracing) instance.
 
 **Usage**
 

data/documentation/docs/api/web_mcp.md

@@ -0,0 +1,34 @@
+---
+sidebar_position: 10
+---
+
+# WebMCP
+
+
+[WebMCP](./web_mcp) exposes the tools that a frame registers through the experimental [WebMCP](./web_mcp) browser API, `navigator.modelContext`. It lists the tools and calls them.
+
+Instances are accessed through [Frame#webmcp](./frame#webmcp). [Page#webmcp](./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.
+
+## call_tool
+
+```
+def call_tool(name, input: nil, timeout: nil)
+```
+
+
+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.
+
+## tools
+
+```
+def tools(timeout: nil)
+```
+
+
+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.
+
+[Page#webmcp](./page#webmcp) covers the main frame only, child frames list their tools through their own [Frame#webmcp](./frame#webmcp).

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

@@ -83,7 +83,7 @@ If custom Docker image is preferred, build it as follows:
 FROM mcr.microsoft.com/playwright
 
 WORKDIR /root
-ARG PLAYWRIGHT_CORE_VERSION=1.62.1
+ARG PLAYWRIGHT_CORE_VERSION=1.64.0
 RUN npm install "playwright-core@$PLAYWRIGHT_CORE_VERSION" && ./node_modules/.bin/playwright-core install
 
 ENV PORT 8888

data/documentation/docs/include/api_coverage.md

@@ -201,6 +201,7 @@
 * wait_for_selector
 * wait_for_timeout
 * wait_for_url
+* webmcp
 
 ## Worker
 
@@ -285,6 +286,7 @@
 * get_by_alt_text
 * get_by_label
 * get_by_placeholder
+* get_by_ref
 * get_by_role
 * get_by_test_id
 * get_by_text
@@ -371,6 +373,7 @@
 * request
 * screencast
 * touchscreen
+* webmcp
 
 ## BrowserContext
 
@@ -530,8 +533,10 @@
 * text_content
 * type
 * uncheck
+* visible
 * wait_for
 * wait_for_function
+* within
 
 ## FrameLocator
 
@@ -567,6 +572,9 @@
 
 ## APIRequestContext
 
+* add_cookies
+* clear_cookies
+* cookies
 * delete
 * dispose
 * fetch
@@ -660,3 +668,8 @@
 * create
 * delete
 * get
+
+## WebMCP
+
+* call_tool
+* tools

data/lib/playwright/api_request_impl.rb

@@ -3,6 +3,8 @@ require 'json'
 
 module Playwright
   define_api_implementation :APIRequestImpl do
+    include Utils::PrepareHttpCredentials
+
     def initialize(playwright)
       @playwright = playwright
     end
@@ -24,7 +26,7 @@ module Playwright
         clientCertificates: prepare_client_certificates(clientCertificates),
         extraHTTPHeaders: extraHTTPHeaders ? HttpHeaders.new(extraHTTPHeaders).as_serialized : nil,
         failOnStatusCode: failOnStatusCode,
-        httpCredentials: httpCredentials,
+        httpCredentials: prepare_http_credentials(httpCredentials),
         ignoreHTTPSErrors: ignoreHTTPSErrors,
         maxRedirects: maxRedirects,
         proxy: proxy,

data/lib/playwright/channel.rb

@@ -75,7 +75,8 @@ module Playwright
         wallTime: (Time.now.to_f * 1000).to_i,
         apiName: api_name,
         stack: stacks.map do |loc|
-          { file: loc.absolute_path || '', line: loc.lineno, function: loc.label }
+          # Ruby backtraces do not provide a column, but the trace protocol requires one.
+          { file: loc.absolute_path || '', line: loc.lineno, column: 0, function: loc.label }
         end,
       }
     end

data/lib/playwright/channel_owners/api_request_context.rb

@@ -3,6 +3,8 @@ require 'cgi/escape'
 
 module Playwright
   define_channel_owner :APIRequestContext do
+    include Utils::ClearCookiesParameters
+
     private def after_initialize
       @tracing = ChannelOwners::Tracing.from(@initializer['tracing'])
       @timeout_settings = TimeoutSettings.new
@@ -10,6 +12,20 @@ module Playwright
 
     attr_reader :tracing
 
+    def cookies(urls: nil)
+      @channel.send_message_to_server('cookies', urls: urls.nil? ? [] : Array(urls))
+    end
+
+    def add_cookies(cookies)
+      @channel.send_message_to_server('addCookies', cookies: cookies)
+      nil
+    end
+
+    def clear_cookies(domain: nil, name: nil, path: nil)
+      @channel.send_message_to_server('clearCookies', clear_cookies_params(domain: domain, name: name, path: path))
+      nil
+    end
+
     private def _update_timeout_settings(timeout_settings)
       @timeout_settings = timeout_settings
     end

data/lib/playwright/channel_owners/browser.rb

@@ -156,6 +156,7 @@ module Playwright
 
     private def setup_browser_context(context)
       context.tracing.send(:update_traces_dir, @traces_dir)
+      context.request.tracing.send(:update_traces_dir, @traces_dir)
       @browser_type.send(:playwright_selectors_browser_contexts) << context
     end