playwright-ruby-client 1.21.0 → 1.24.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5e2dee736be02c56e75b6a89e2eab014c4d205ca23688b30084ea3854f50dfda
-  data.tar.gz: a213f955daad15c58bc1edd1b123cb6768cbc6df5ec6be0b09e537a8b6ea22ec
+  metadata.gz: 4e87b002bd3cd1dfaf592f6be37902b0a0604553d419b8b7516e0e887584125a
+  data.tar.gz: 5b956c57000f12dc8399df4382dd301a7ef1d47551782afff0fae0871892c630
 SHA512:
-  metadata.gz: eba2fed3585b9ef5aa1b068cfc3294acc0f134e1ecccec6fae465bfd8df52c2395d02d706cb8958342c8e1af8be2066b537bc7af9eb3da1fe3748536677ba0c0
-  data.tar.gz: 2264ea9fd32bd7b02e15453a17876c2ee5fa8d51fb5eca652242959254ead0fda4ee721e9c35a1a24c1dc005d42268fd49b4566bd844841499bb8933ba83b8a3
+  metadata.gz: e3a418d6d40392a157016b164455e8cdc83bffb696c182d68d2ce10cb1e7315be151fb4be78e5b985871ba75ef1882be262d05c93a0b3a65a3c3b8b9c7373fb2
+  data.tar.gz: db086e5ff1cdbc8cee9d1aea80601e2f9664c4806478aa556fd91e6b647bc71d23b9f0862ed60711365e06e67d513717c5e01b3d7b60c1a5b9438535ef8394e5

data/documentation/docs/api/browser.md

@@ -21,6 +21,14 @@ end
 
 
 
+## browser_type
+
+```
+def browser_type
+```
+
+Get the browser type (chromium, firefox or webkit) that the browser belongs to.
+
 ## close
 
 ```
@@ -33,6 +41,10 @@ were opened).
 In case this browser is connected to, clears all created contexts belonging to this browser and disconnects from the
 browser server.
 
+> NOTE: This is similar to force quitting the browser. Therefore, you should call [BrowserContext#close](./browser_context#close) on
+any [BrowserContext](./browser_context)'s you explicitly created earlier with [Browser#new_context](./browser#new_context) **before** calling
+[Browser#close](./browser#close).
+
 The [Browser](./browser) object itself is considered to be disposed and cannot be used anymore.
 
 ## contexts
@@ -93,12 +105,16 @@ def new_context(
       offline: nil,
       permissions: nil,
       proxy: nil,
+      record_har_content: nil,
+      record_har_mode: nil,
       record_har_omit_content: nil,
       record_har_path: nil,
+      record_har_url_filter: nil,
       record_video_dir: nil,
       record_video_size: nil,
       reducedMotion: nil,
       screen: nil,
+      serviceWorkers: nil,
       storageState: nil,
       strictSelectors: nil,
       timezoneId: nil,
@@ -109,14 +125,19 @@ def new_context(
 
 Creates a new browser context. It won't share cookies/cache with other browser contexts.
 
+> NOTE: If directly using this method to create [BrowserContext](./browser_context)s, it is best practice to explicilty close the returned
+context via [BrowserContext#close](./browser_context#close) when your code is done with the [BrowserContext](./browser_context), and before calling
+[Browser#close](./browser#close). This will ensure the `context` is closed gracefully and any artifacts—like HARs and
+videos—are fully flushed and saved.
+
 ```ruby
 playwright.firefox.launch do |browser| # or "chromium.launch" or "webkit.launch".
   # create a new incognito browser context.
-  context = browser.new_context
-
-  # create a new page in a pristine context.
-  page = context.new_page()
-  page.goto("https://example.com")
+  browser.new_context do |context|
+    # create a new page in a pristine context.
+    page = context.new_page
+    page.goto("https://example.com")
+  end
 end
 ```
 
@@ -144,12 +165,16 @@ def new_page(
       offline: nil,
       permissions: nil,
       proxy: nil,
+      record_har_content: nil,
+      record_har_mode: nil,
       record_har_omit_content: nil,
       record_har_path: nil,
+      record_har_url_filter: nil,
       record_video_dir: nil,
       record_video_size: nil,
       reducedMotion: nil,
       screen: nil,
+      serviceWorkers: nil,
       storageState: nil,
       strictSelectors: nil,
       timezoneId: nil,

data/documentation/docs/api/browser_context.md

@@ -23,7 +23,7 @@ page = context.new_page
 page.goto("https://example.com")
 
 # dispose context once it is no longer needed.
-context.close()
+context.close
 ```
 
 
@@ -161,7 +161,7 @@ page.content = <<~HTML
 <div></div>
 HTML
 
-page.click("button")
+page.locator("button").click
 ```
 
 An example of passing an element handle:
@@ -184,7 +184,7 @@ page.content = <<~HTML
 <div>Or click me</div>
 HTML
 
-page.click('div')
+page.locator('div').first.click
 ```
 
 
@@ -222,7 +222,7 @@ page.content = <<~HTML
 <button onclick="onClick()">Click me</button>
 <div></div>
 HTML
-page.click("button")
+page.locator("button").click
 ```
 
 
@@ -271,9 +271,9 @@ def route(url, handler, times: nil)
 Routing provides the capability to modify network requests that are made by any page in the browser context. Once route
 is enabled, every request matching the url pattern will stall unless it's continued, fulfilled or aborted.
 
-> NOTE: [Page#route](./page#route) will not intercept requests intercepted by Service Worker. See
+> NOTE: [BrowserContext#route](./browser_context#route) will not intercept requests intercepted by Service Worker. See
 [this](https://github.com/microsoft/playwright/issues/1090) issue. We recommend disabling Service Workers when using
-request interception. Via `await context.addInitScript(() => delete window.navigator.serviceWorker);`
+request interception by setting `Browser.newContext.serviceWorkers` to `'block'`.
 
 An example of a naive handler that aborts all image requests:
 
@@ -315,6 +315,19 @@ To remove a route with its handler you can use [BrowserContext#unroute](./browse
 
 > NOTE: Enabling routing disables http cache.
 
+## route_from_har
+
+```
+def route_from_har(har, notFound: nil, update: nil, url: nil)
+```
+
+If specified the network requests that are made in the context will be served from the HAR file. Read more about
+[Replaying from HAR](https://playwright.dev/python/docs/network).
+
+Playwright will not serve requests intercepted by Service Worker from the HAR file. See
+[this](https://github.com/microsoft/playwright/issues/1090) issue. We recommend disabling Service Workers when using
+request interception by setting `Browser.newContext.serviceWorkers` to `'block'`.
+
 ## service_workers
 
 ```
@@ -421,7 +434,7 @@ value. Will throw an error if the context closes before the event is fired. Retu
 
 ```ruby
 new_page = browser_context.expect_event('page') do
-  page.click('button')
+  page.locator('button').click
 end
 ```
 

data/documentation/docs/api/browser_type.md

@@ -131,12 +131,16 @@ def launch_persistent_context(
       offline: nil,
       permissions: nil,
       proxy: nil,
+      record_har_content: nil,
+      record_har_mode: nil,
       record_har_omit_content: nil,
       record_har_path: nil,
+      record_har_url_filter: nil,
       record_video_dir: nil,
       record_video_size: nil,
       reducedMotion: nil,
       screen: nil,
+      serviceWorkers: nil,
       slowMo: nil,
       strictSelectors: nil,
       timeout: nil,

data/documentation/docs/api/download.md

@@ -12,7 +12,7 @@ Download event is emitted once the download starts. Download path becomes availa
 
 ```ruby
 download = page.expect_download do
-  page.click('a')
+  page.locator('a').click
 end
 
 # wait for download to complete

data/documentation/docs/api/element_handle.md

@@ -55,7 +55,7 @@ def bounding_box
 This method returns the bounding box of the element, or `null` if the element is not visible. The bounding box is
 calculated relative to the main frame viewport - which is usually the same as the browser window.
 
-Scrolling affects the returned bonding box, similarly to
+Scrolling affects the returned bounding box, similarly to
 [Element.getBoundingClientRect](https://developer.mozilla.org/en-US/docs/Web/API/Element/getBoundingClientRect). That
 means `x` and/or `y` may be negative.
 
@@ -330,7 +330,10 @@ Returns the `element.innerText`.
 def input_value(timeout: nil)
 ```
 
-Returns `input.value` for `<input>` or `<textarea>` or `<select>` element. Throws for non-input elements.
+Returns `input.value` for the selected `<input>` or `<textarea>` or `<select>` element.
+
+Throws for non-input elements. However, if the element is inside the `<label>` element that has an associated
+[control](https://developer.mozilla.org/en-US/docs/Web/API/HTMLLabelElement/control), returns the value of the control.
 
 ## checked?
 
@@ -446,11 +449,15 @@ def screenshot(
       type: nil)
 ```
 
-Returns the buffer with the captured screenshot.
+This method captures a screenshot of the page, clipped to the size and position of this particular element. If the
+element is covered by other elements, it will not be actually visible on the screenshot. If the element is a scrollable
+container, only the currently scrolled content will be visible on the screenshot.
 
 This method waits for the [actionability](https://playwright.dev/python/docs/actionability) checks, then scrolls element into view before taking a
 screenshot. If the element is detached from DOM, the method throws an error.
 
+Returns the buffer with the captured screenshot.
+
 ## scroll_into_view_if_needed
 
 ```
@@ -497,11 +504,6 @@ element_handle.select_option(label: "blue")
 element_handle.select_option(value: ["red", "green", "blue"])
 ```
 
-```ruby
-# multiple selection for blue, red and second option
-element_handle.select_option(value: "blue", index: 2, label: "red")
-```
-
 
 
 ## select_text
@@ -513,6 +515,10 @@ def select_text(force: nil, timeout: nil)
 This method waits for [actionability](https://playwright.dev/python/docs/actionability) checks, then focuses the element and selects all its text
 content.
 
+If the element is inside the `<label>` element that has an associated
+[control](https://developer.mozilla.org/en-US/docs/Web/API/HTMLLabelElement/control), focuses and selects text in the
+control instead.
+
 ## set_checked
 
 ```
@@ -546,11 +552,13 @@ def set_input_files(files, noWaitAfter: nil, timeout: nil)
 ```
 alias: `input_files=`
 
-This method expects `elementHandle` to point to an
-[input element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input).
-
 Sets the value of the file input to these file paths or files. If some of the `filePaths` are relative paths, then they
-are resolved relative to the the current working directory. For empty array, clears the selected files.
+are resolved relative to the current working directory. For empty array, clears the selected files.
+
+This method expects [ElementHandle](./element_handle) to point to an
+[input element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input). However, if the element is inside the
+`<label>` element that has an associated
+[control](https://developer.mozilla.org/en-US/docs/Web/API/HTMLLabelElement/control), targets the control instead.
 
 ## tap_point
 

data/documentation/docs/api/experimental/android.md

@@ -33,7 +33,7 @@ PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD=1 npm i -D playwright
 ## devices
 
 ```
-def devices(omitDriverInstall: nil, port: nil)
+def devices(host: nil, omitDriverInstall: nil, port: nil)
 ```
 
 Returns the list of detected Android devices.

data/documentation/docs/api/experimental/android_device.md

@@ -45,12 +45,16 @@ def launch_browser(
       noViewport: nil,
       offline: nil,
       permissions: nil,
+      record_har_content: nil,
+      record_har_mode: nil,
       record_har_omit_content: nil,
       record_har_path: nil,
+      record_har_url_filter: nil,
       record_video_dir: nil,
       record_video_size: nil,
       reducedMotion: nil,
       screen: nil,
+      serviceWorkers: nil,
       strictSelectors: nil,
       timezoneId: nil,
       userAgent: nil,

data/documentation/docs/api/file_chooser.md

@@ -8,7 +8,7 @@ sidebar_position: 10
 
 ```ruby
 file_chooser = page.expect_file_chooser do
-  page.click("upload") # action to trigger file uploading
+  page.locator("upload").click # action to trigger file uploading
 end
 file_chooser.set_files("myfile.pdf")
 ```
@@ -47,4 +47,4 @@ def set_files(files, noWaitAfter: nil, timeout: nil)
 alias: `files=`
 
 Sets the value of the file input this chooser is associated with. If some of the `filePaths` are relative paths, then
-they are resolved relative to the the current working directory. For empty array, clears the selected files.
+they are resolved relative to the current working directory. For empty array, clears the selected files.

data/documentation/docs/api/frame.md

@@ -486,7 +486,10 @@ Returns `element.innerText`.
 def input_value(selector, strict: nil, timeout: nil)
 ```
 
-Returns `input.value` for the selected `<input>` or `<textarea>` or `<select>` element. Throws for non-input elements.
+Returns `input.value` for the selected `<input>` or `<textarea>` or `<select>` element.
+
+Throws for non-input elements. However, if the element is inside the `<label>` element that has an associated
+[control](https://developer.mozilla.org/en-US/docs/Web/API/HTMLLabelElement/control), returns the value of the control.
 
 ## checked?
 
@@ -556,6 +559,8 @@ The method returns an element locator that can be used to perform actions in the
 element immediately before performing an action, so a series of actions on the same locator can in fact be performed on
 different DOM elements. That would happen if the DOM structure between those actions has changed.
 
+[Learn more about locators](https://playwright.dev/python/docs/locators).
+
 ## name
 
 ```
@@ -724,11 +729,13 @@ def set_input_files(
       timeout: nil)
 ```
 
-This method expects `selector` to point to an
-[input element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input).
-
 Sets the value of the file input to these file paths or files. If some of the `filePaths` are relative paths, then they
-are resolved relative to the the current working directory. For empty array, clears the selected files.
+are resolved relative to the current working directory. For empty array, clears the selected files.
+
+This method expects `selector` to point to an
+[input element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input). However, if the element is inside the
+`<label>` element that has an associated
+[control](https://developer.mozilla.org/en-US/docs/Web/API/HTMLLabelElement/control), targets the control instead.
 
 ## tap_point
 

data/documentation/docs/api/locator.md

@@ -34,7 +34,7 @@ def bounding_box(timeout: nil)
 This method returns the bounding box of the element, or `null` if the element is not visible. The bounding box is
 calculated relative to the main frame viewport - which is usually the same as the browser window.
 
-Scrolling affects the returned bonding box, similarly to
+Scrolling affects the returned bounding box, similarly to
 [Element.getBoundingClientRect](https://developer.mozilla.org/en-US/docs/Web/API/Element/getBoundingClientRect). That
 means `x` and/or `y` may be negative.
 
@@ -285,6 +285,26 @@ instead.
 
 To send fine-grained keyboard events, use [Locator#type](./locator#type).
 
+## filter
+
+```
+def filter(has: nil, hasText: nil)
+```
+
+This method narrows existing locator according to the options, for example filters by text. It can be chained to filter
+multiple times.
+
+```ruby
+row_locator = page.locator("tr")
+# ...
+row_locator.
+    filter(has_text="text in column 1").
+    filter(has=page.locator("tr", has_text="column 2 button")).
+    screenshot
+```
+
+
+
 ## first
 
 ```
@@ -322,6 +342,7 @@ locator.click
 ```
 def get_attribute(name, timeout: nil)
 ```
+alias: `[]`
 
 Returns element attribute value.
 
@@ -378,7 +399,10 @@ Returns the `element.innerText`.
 def input_value(timeout: nil)
 ```
 
-Returns `input.value` for `<input>` or `<textarea>` or `<select>` element. Throws for non-input elements.
+Returns `input.value` for the selected `<input>` or `<textarea>` or `<select>` element.
+
+Throws for non-input elements. However, if the element is inside the `<label>` element that has an associated
+[control](https://developer.mozilla.org/en-US/docs/Web/API/HTMLLabelElement/control), returns the value of the control.
 
 ## checked?
 
@@ -442,7 +466,8 @@ Returns locator to the last matching element.
 def locator(selector, has: nil, hasText: nil)
 ```
 
-The method finds an element matching the specified selector in the [Locator](./locator)'s subtree.
+The method finds an element matching the specified selector in the [Locator](./locator)'s subtree. It also accepts filter options,
+similar to [Locator#filter](./locator#filter) method.
 
 ## nth
 
@@ -500,11 +525,15 @@ def screenshot(
       type: nil)
 ```
 
-Returns the buffer with the captured screenshot.
+This method captures a screenshot of the page, clipped to the size and position of a particular element matching the
+locator. If the element is covered by other elements, it will not be actually visible on the screenshot. If the element
+is a scrollable container, only the currently scrolled content will be visible on the screenshot.
 
 This method waits for the [actionability](https://playwright.dev/python/docs/actionability) checks, then scrolls element into view before taking a
 screenshot. If the element is detached from DOM, the method throws an error.
 
+Returns the buffer with the captured screenshot.
+
 ## scroll_into_view_if_needed
 
 ```
@@ -548,11 +577,6 @@ element.select_option(label: "blue")
 element.select_option(value: ["red", "green", "blue"])
 ```
 
-```ruby
-# multiple selection for blue, red and second option
-element.select_option(value: "blue", index: 2, label: "red")
-```
-
 
 
 ## select_text
@@ -564,6 +588,10 @@ def select_text(force: nil, timeout: nil)
 This method waits for [actionability](https://playwright.dev/python/docs/actionability) checks, then focuses the element and selects all its text
 content.
 
+If the element is inside the `<label>` element that has an associated
+[control](https://developer.mozilla.org/en-US/docs/Web/API/HTMLLabelElement/control), focuses and selects text in the
+control instead.
+
 ## set_checked
 
 ```
@@ -597,11 +625,13 @@ def set_input_files(files, noWaitAfter: nil, timeout: nil)
 ```
 alias: `input_files=`
 
-This method expects `element` to point to an
-[input element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input).
-
 Sets the value of the file input to these file paths or files. If some of the `filePaths` are relative paths, then they
-are resolved relative to the the current working directory. For empty array, clears the selected files.
+are resolved relative to the current working directory. For empty array, clears the selected files.
+
+This method expects [Locator](./locator) to point to an
+[input element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input). However, if the element is inside the
+`<label>` element that has an associated
+[control](https://developer.mozilla.org/en-US/docs/Web/API/HTMLLabelElement/control), targets the control instead.
 
 ## tap_point
 

data/documentation/docs/api/page.md

@@ -462,7 +462,7 @@ page.content = <<~HTML
 <button onclick="onClick()">Click me</button>
 <div></div>
 HTML
-page.click("button")
+page.locator("button").click
 ```
 
 An example of passing an element handle:
@@ -483,7 +483,7 @@ page.content = <<~HTML
 <div>Or click me</div>
 HTML
 
-page.click('div')
+page.locator('div').first.click
 ```
 
 
@@ -522,7 +522,7 @@ page.content = <<~HTML
 <button onclick="onClick()">Click me</button>
 <div></div>
 HTML
-page.click("button")
+page.locator("button").click
 ```
 
 
@@ -642,8 +642,8 @@ Navigate to the next page in history.
 def goto(url, referer: nil, timeout: nil, waitUntil: nil)
 ```
 
-Returns the main resource response. In case of multiple redirects, the navigation will resolve with the response of the
-last redirect.
+Returns the main resource response. In case of multiple redirects, the navigation will resolve with the first
+non-redirect response.
 
 The method will throw an error if:
 - there's an SSL error (e.g. in case of self-signed certificates).
@@ -711,7 +711,10 @@ Returns `element.innerText`.
 def input_value(selector, strict: nil, timeout: nil)
 ```
 
-Returns `input.value` for the selected `<input>` or `<textarea>` or `<select>` element. Throws for non-input elements.
+Returns `input.value` for the selected `<input>` or `<textarea>` or `<select>` element.
+
+Throws for non-input elements. However, if the element is inside the `<label>` element that has an associated
+[control](https://developer.mozilla.org/en-US/docs/Web/API/HTMLLabelElement/control), returns the value of the control.
 
 ## checked?
 
@@ -781,6 +784,8 @@ The method returns an element locator that can be used to perform actions on the
 element immediately before performing an action, so a series of actions on the same locator can in fact be performed on
 different DOM elements. That would happen if the DOM structure between those actions has changed.
 
+[Learn more about locators](https://playwright.dev/python/docs/locators).
+
 Shortcut for main frame's [Frame#locator](./frame#locator).
 
 ## main_frame
@@ -970,7 +975,7 @@ Once routing is enabled, every request matching the url pattern will stall unles
 > NOTE: The handler will only be called for the first url if the response is a redirect.
 > NOTE: [Page#route](./page#route) will not intercept requests intercepted by Service Worker. See
 [this](https://github.com/microsoft/playwright/issues/1090) issue. We recommend disabling Service Workers when using
-request interception. Via `await context.addInitScript(() => delete window.navigator.serviceWorker);`
+request interception by setting `Browser.newContext.serviceWorkers` to `'block'`.
 
 An example of a naive handler that aborts all image requests:
 
@@ -1008,6 +1013,19 @@ To remove a route with its handler you can use [Page#unroute](./page#unroute).
 
 > NOTE: Enabling routing disables http cache.
 
+## route_from_har
+
+```
+def route_from_har(har, notFound: nil, update: nil, url: nil)
+```
+
+If specified the network requests that are made in the page will be served from the HAR file. Read more about
+[Replaying from HAR](https://playwright.dev/python/docs/network).
+
+Playwright will not serve requests intercepted by Service Worker from the HAR file. See
+[this](https://github.com/microsoft/playwright/issues/1090) issue. We recommend disabling Service Workers when using
+request interception by setting `Browser.newContext.serviceWorkers` to `'block'`.
+
 ## screenshot
 
 ```
@@ -1155,11 +1173,13 @@ def set_input_files(
       timeout: nil)
 ```
 
-This method expects `selector` to point to an
-[input element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input).
-
 Sets the value of the file input to these file paths or files. If some of the `filePaths` are relative paths, then they
-are resolved relative to the the current working directory. For empty array, clears the selected files.
+are resolved relative to the current working directory. For empty array, clears the selected files.
+
+This method expects `selector` to point to an
+[input element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input). However, if the element is inside the
+`<label>` element that has an associated
+[control](https://developer.mozilla.org/en-US/docs/Web/API/HTMLLabelElement/control), targets the control instead.
 
 ## set_viewport_size
 

data/documentation/docs/api/request.md

@@ -56,7 +56,9 @@ Returns the [Frame](./frame) that initiated this request.
 def headers
 ```
 
-**DEPRECATED** Incomplete list of headers as seen by the rendering engine. Use [Request#all_headers](./request#all_headers) instead.
+An object with the request HTTP headers. The header names are lower-cased. Note that this method does not return
+security-related headers, including cookie-related ones. You can use [Request#all_headers](./request#all_headers) for complete list of
+headers that include `cookie` information.
 
 ## headers_array
 

data/documentation/docs/api/response.md

@@ -38,13 +38,24 @@ def frame
 
 Returns the [Frame](./frame) that initiated this response.
 
+## from_service_worker
+
+```
+def from_service_worker
+```
+
+Indicates whether this Response was fullfilled by a Service Worker's Fetch Handler (i.e. via
+[FetchEvent.respondWith](https://developer.mozilla.org/en-US/docs/Web/API/FetchEvent/respondWith)).
+
 ## headers
 
 ```
 def headers
 ```
 
-**DEPRECATED** Incomplete list of headers as seen by the rendering engine. Use [Response#all_headers](./response#all_headers) instead.
+An object with the response HTTP headers. The header names are lower-cased. Note that this method does not return
+security-related headers, including cookie-related ones. You can use [Response#all_headers](./response#all_headers) for complete list
+of headers that include `cookie` information.
 
 ## headers_array