playwright-ruby-client 1.26.0 → 1.28.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: beca54a9f8e488cefb33f9266bd227bdb002ea5e379f6525733375f30a26aad2
-  data.tar.gz: a8cb017751e740755cb92a7525a59afde927b9393ed13d71e0af2797c857496e
+  metadata.gz: 6d96f4cf4c170f020d8b73571e23f61e994e535708759b0148aec799110f3d72
+  data.tar.gz: cc6471e1da4e8f02d8b98b960a84feb67251bafd7781dec9c0d103385474f098
 SHA512:
-  metadata.gz: f7ede551835e7916acf830ef26664cd6421910c966d96f9e85c599383c48fc7707467f2d095a848c6f23071310e6072cde47b7412b4d83d1f381373dc42b6011
-  data.tar.gz: c4aa082a27871b37b64236c0fc40c17083884696fb2ceef8a3bd9e6c72d5089081a81ac616fd1a8116cf7052575888fa63abc47866d2cff413b21aee9a695f10
+  metadata.gz: 953724a4d98d278b2bcd63a580f433b1defb630534023ae2c3c2df426ef4717a89c6c0e546fb76df5df7ae0b16cfd01d494be36c277d890f1774d65551932fdc
+  data.tar.gz: 92be169ac6c6adeac4ac7346df21dd929de1021e38f99f01eba73a74c4327d0436b97e6ea074560f49520eada9a6cd29f399ae144a7baa93fd64cec1c63c9cd4

data/documentation/docs/api/api_request_context.md

@@ -106,15 +106,47 @@ def fetch(
 Sends HTTP(S) request and returns its response. The method will populate request cookies from the context and update
 context cookies from the response. The method will automatically follow redirects.
 
+JSON objects can be passed directly to the request:
+
+```ruby
+data = {
+  title: "Book Title",
+  body: "John Doe",
+}
+api_request_context.fetch("https://example.com/api/create_book", method: 'post', data: data)
+```
+
+The common way to send file(s) in the body of a request is to encode it as form fields with `multipart/form-data`
+encoding. You can achieve that with Playwright API like this:
+
+```ruby
+api_request_context.fetch(
+  "https://example.com/api/upload_script",
+  method: 'post',
+  multipart: {
+    fileField: {
+      name: "f.js",
+      mimeType: "text/javascript",
+      buffer: "console.log(2022);",
+    },
+  },
+)
+```
+
+
+
 ## get
 
 ```
 def get(
       url,
+      data: nil,
       failOnStatusCode: nil,
+      form: nil,
       headers: nil,
       ignoreHTTPSErrors: nil,
       maxRedirects: nil,
+      multipart: nil,
       params: nil,
       timeout: nil)
 ```
@@ -123,15 +155,30 @@ Sends HTTP(S) [GET](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/GE
 method will populate request cookies from the context and update context cookies from the response. The method will
 automatically follow redirects.
 
+Request parameters can be configured with `params` option, they will be serialized into the URL search parameters:
+
+```ruby
+query_params = {
+  isbn: "1234",
+  page: "23"
+}
+api_request_context.get("https://example.com/api/get_text", params: query_params)
+```
+
+
+
 ## head
 
 ```
 def head(
       url,
+      data: nil,
       failOnStatusCode: nil,
+      form: nil,
       headers: nil,
       ignoreHTTPSErrors: nil,
       maxRedirects: nil,
+      multipart: nil,
       params: nil,
       timeout: nil)
 ```
@@ -180,6 +227,45 @@ Sends HTTP(S) [POST](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/P
 The method will populate request cookies from the context and update context cookies from the response. The method will
 automatically follow redirects.
 
+JSON objects can be passed directly to the request:
+
+```ruby
+data = {
+  title: "Book Title",
+  body: "John Doe",
+}
+api_request_context.post("https://example.com/api/create_book", data: data)
+```
+
+To send form data to the server use `form` option. Its value will be encoded into the request body with
+`application/x-www-form-urlencoded` encoding (see below how to use `multipart/form-data` form encoding to send files):
+
+```ruby
+form_data = {
+  title: "Book Title",
+  body: "John Doe",
+}
+api_request_context.post("https://example.com/api/find_book", form: form_data)
+```
+
+The common way to send file(s) in the body of a request is to upload them as form fields with `multipart/form-data`
+encoding. You can achieve that with Playwright API like this:
+
+```ruby
+api_request_context.post(
+  "https://example.com/api/upload_script",
+  multipart: {
+    fileField: {
+      name: "f.js",
+      mimeType: "text/javascript",
+      buffer: "console.log(2022);",
+    },
+  },
+)
+```
+
+
+
 ## put
 
 ```

data/documentation/docs/api/browser_context.md

@@ -161,7 +161,7 @@ page.content = <<~HTML
 <div></div>
 HTML
 
-page.locator("button").click
+page.get_by_role("button").click
 ```
 
 An example of passing an element handle:
@@ -222,7 +222,7 @@ page.content = <<~HTML
 <button onclick="onClick()">Click me</button>
 <div></div>
 HTML
-page.locator("button").click
+page.get_by_role("button").click
 ```
 
 
@@ -434,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.locator('button').click
+  page.get_by_role("button").click
 end
 ```
 

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.locator('a').click
+  page.get_by_text("Download file").click
 end
 
 # wait for download to complete

data/documentation/docs/api/element_handle.md

@@ -39,7 +39,7 @@ With the locator, every time the `element` is used, up-to-date DOM element is lo
 in the snippet below, underlying DOM element is going to be located twice.
 
 ```ruby
-locator = page.locator("text=Submit")
+locator = page.get_by_text("Submit")
 locator.hover
 locator.click
 ```
@@ -292,6 +292,7 @@ Returns element attribute value.
 def hover(
       force: nil,
       modifiers: nil,
+      noWaitAfter: nil,
       position: nil,
       timeout: nil,
       trial: nil)

data/documentation/docs/api/file_chooser.md

@@ -8,7 +8,7 @@ sidebar_position: 10
 
 ```ruby
 file_chooser = page.expect_file_chooser do
-  page.locator("upload").click # action to trigger file uploading
+  page.get_by_text("Upload").click # action to trigger file uploading
 end
 file_chooser.set_files("myfile.pdf")
 ```

data/documentation/docs/api/frame.md

@@ -401,7 +401,7 @@ that iframe. Following snippet locates element with text "Submit" in the iframe
 id="my-frame">`:
 
 ```ruby
-locator = frame.frame_locator("#my-iframe").locator("text=Submit")
+locator = frame.frame_locator("#my-iframe").get_by_text("Submit")
 locator.click
 ```
 
@@ -415,6 +415,150 @@ def get_attribute(selector, name, strict: nil, timeout: nil)
 
 Returns element attribute value.
 
+## get_by_alt_text
+
+```
+def get_by_alt_text(text, exact: nil)
+```
+
+Allows locating elements by their alt text. For example, this method will find the image by alt text "Castle":
+
+```html
+<img alt='Castle'>
+```
+
+
+## get_by_label
+
+```
+def get_by_label(text, exact: nil)
+```
+
+Allows locating input elements by the text of the associated label. For example, this method will find the input by
+label text "Password" in the following DOM:
+
+```html
+<label for="password-input">Password:</label>
+<input id="password-input">
+```
+
+
+## get_by_placeholder
+
+```
+def get_by_placeholder(text, exact: nil)
+```
+
+Allows locating input elements by the placeholder text. For example, this method will find the input by placeholder
+"Country":
+
+```html
+<input placeholder="Country">
+```
+
+
+## get_by_role
+
+```
+def get_by_role(
+      role,
+      checked: nil,
+      disabled: nil,
+      exact: nil,
+      expanded: nil,
+      includeHidden: nil,
+      level: nil,
+      name: nil,
+      pressed: nil,
+      selected: nil)
+```
+
+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). Note that role selector **does not replace**
+accessibility audits and conformance tests, but rather gives early feedback about the ARIA guidelines.
+
+Note that many html elements have an implicitly
+[defined role](https://w3c.github.io/html-aam/#html-element-role-mappings) that is recognized by the role selector. You
+can find all the [supported roles here](https://www.w3.org/TR/wai-aria-1.2/#role_definitions). ARIA guidelines **do not
+recommend** duplicating implicit roles and attributes by setting `role` and/or `aria-*` attributes to default values.
+
+## get_by_test_id
+
+```
+def get_by_test_id(testId)
+```
+
+Locate element by the test id. By default, the `data-testid` attribute is used as a test id. Use
+[Selectors#set_test_id_attribute](./selectors#set_test_id_attribute) to configure a different test id attribute if necessary.
+
+
+
+## get_by_text
+
+```
+def get_by_text(text, exact: nil)
+```
+
+Allows locating elements that contain given text. Consider the following DOM structure:
+
+```html
+<div>Hello <span>world</span></div>
+<div>Hello</div>
+```
+
+You can locate by text substring, exact string, or a regular expression:
+
+```ruby
+page.content = <<~HTML
+  <div>Hello <span>world</span></div>
+  <div>Hello</div>
+HTML
+
+# Matches <span>
+locator = page.get_by_text("world")
+expect(locator.evaluate('e => e.outerHTML')).to eq('<span>world</span>')
+
+# Matches first <div>
+locator = page.get_by_text("Hello world")
+expect(locator.evaluate('e => e.outerHTML')).to eq('<div>Hello <span>world</span></div>')
+
+# Matches second <div>
+locator = page.get_by_text("Hello", exact: true)
+expect(locator.evaluate('e => e.outerHTML')).to eq('<div>Hello</div>')
+
+# Matches both <div>s
+locator = page.get_by_text(/Hello/)
+expect(locator.count).to eq(2)
+expect(locator.first.evaluate('e => e.outerHTML')).to eq('<div>Hello <span>world</span></div>')
+expect(locator.last.evaluate('e => e.outerHTML')).to eq('<div>Hello</div>')
+
+# Matches second <div>
+locator = page.get_by_text(/^hello$/i)
+expect(locator.evaluate('e => e.outerHTML')).to eq('<div>Hello</div>')
+```
+
+See also [Locator#filter](./locator#filter) that allows to match by another criteria, like an accessible role, and then filter
+by the text content.
+
+> NOTE: Matching by text always normalizes whitespace, even with exact match. For example, it turns multiple spaces into
+one, turns line breaks into spaces and ignores leading and trailing whitespace.
+> NOTE: Input elements of the type `button` and `submit` are matched by their `value` instead of the text content. For
+example, locating by text `"Log in"` matches `<input type=button value="Log in">`.
+
+## get_by_title
+
+```
+def get_by_title(text, exact: nil)
+```
+
+Allows locating elements by their title. For example, this method will find the button by its title "Place the order":
+
+```html
+<button title='Place the order'>Order Now</button>
+```
+
+
 ## goto
 
 ```
@@ -447,6 +591,7 @@ def hover(
       selector,
       force: nil,
       modifiers: nil,
+      noWaitAfter: nil,
       position: nil,
       strict: nil,
       timeout: nil,
@@ -555,9 +700,11 @@ considered not visible.
 def locator(selector, has: nil, hasText: nil)
 ```
 
-The method returns an element locator that can be used to perform actions in the frame. Locator is resolved to 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.
+The method returns an element locator that can be used to perform actions on this page / frame. Locator is resolved to
+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).
 
 [Learn more about locators](https://playwright.dev/python/docs/locators).
 

data/documentation/docs/api/frame_locator.md

@@ -9,7 +9,7 @@ and locate elements in that iframe. FrameLocator can be created with either [Pag
 [Locator#frame_locator](./locator#frame_locator) method.
 
 ```ruby
-locator = page.frame_locator("my-frame").locator("text=Submit")
+locator = page.frame_locator("my-frame").get_by_text("Submit")
 locator.click
 ```
 
@@ -20,10 +20,10 @@ a given selector.
 
 ```ruby
 # Throws if there are several frames in DOM:
-page.frame_locator('.result-frame').locator('button').click
+page.frame_locator('.result-frame').get_by_role('button').click
 
 # Works because we explicitly tell locator to pick the first frame:
-page.frame_locator('.result-frame').first.locator('button').click
+page.frame_locator('.result-frame').first.get_by_role('button').click
 ```
 
 **Converting Locator to FrameLocator**
@@ -54,6 +54,150 @@ def frame_locator(selector)
 When working with iframes, you can create a frame locator that will enter the iframe and allow selecting elements in
 that iframe.
 
+## get_by_alt_text
+
+```
+def get_by_alt_text(text, exact: nil)
+```
+
+Allows locating elements by their alt text. For example, this method will find the image by alt text "Castle":
+
+```html
+<img alt='Castle'>
+```
+
+
+## get_by_label
+
+```
+def get_by_label(text, exact: nil)
+```
+
+Allows locating input elements by the text of the associated label. For example, this method will find the input by
+label text "Password" in the following DOM:
+
+```html
+<label for="password-input">Password:</label>
+<input id="password-input">
+```
+
+
+## get_by_placeholder
+
+```
+def get_by_placeholder(text, exact: nil)
+```
+
+Allows locating input elements by the placeholder text. For example, this method will find the input by placeholder
+"Country":
+
+```html
+<input placeholder="Country">
+```
+
+
+## get_by_role
+
+```
+def get_by_role(
+      role,
+      checked: nil,
+      disabled: nil,
+      exact: nil,
+      expanded: nil,
+      includeHidden: nil,
+      level: nil,
+      name: nil,
+      pressed: nil,
+      selected: nil)
+```
+
+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). Note that role selector **does not replace**
+accessibility audits and conformance tests, but rather gives early feedback about the ARIA guidelines.
+
+Note that many html elements have an implicitly
+[defined role](https://w3c.github.io/html-aam/#html-element-role-mappings) that is recognized by the role selector. You
+can find all the [supported roles here](https://www.w3.org/TR/wai-aria-1.2/#role_definitions). ARIA guidelines **do not
+recommend** duplicating implicit roles and attributes by setting `role` and/or `aria-*` attributes to default values.
+
+## get_by_test_id
+
+```
+def get_by_test_id(testId)
+```
+
+Locate element by the test id. By default, the `data-testid` attribute is used as a test id. Use
+[Selectors#set_test_id_attribute](./selectors#set_test_id_attribute) to configure a different test id attribute if necessary.
+
+
+
+## get_by_text
+
+```
+def get_by_text(text, exact: nil)
+```
+
+Allows locating elements that contain given text. Consider the following DOM structure:
+
+```html
+<div>Hello <span>world</span></div>
+<div>Hello</div>
+```
+
+You can locate by text substring, exact string, or a regular expression:
+
+```ruby
+page.content = <<~HTML
+  <div>Hello <span>world</span></div>
+  <div>Hello</div>
+HTML
+
+# Matches <span>
+locator = page.get_by_text("world")
+expect(locator.evaluate('e => e.outerHTML')).to eq('<span>world</span>')
+
+# Matches first <div>
+locator = page.get_by_text("Hello world")
+expect(locator.evaluate('e => e.outerHTML')).to eq('<div>Hello <span>world</span></div>')
+
+# Matches second <div>
+locator = page.get_by_text("Hello", exact: true)
+expect(locator.evaluate('e => e.outerHTML')).to eq('<div>Hello</div>')
+
+# Matches both <div>s
+locator = page.get_by_text(/Hello/)
+expect(locator.count).to eq(2)
+expect(locator.first.evaluate('e => e.outerHTML')).to eq('<div>Hello <span>world</span></div>')
+expect(locator.last.evaluate('e => e.outerHTML')).to eq('<div>Hello</div>')
+
+# Matches second <div>
+locator = page.get_by_text(/^hello$/i)
+expect(locator.evaluate('e => e.outerHTML')).to eq('<div>Hello</div>')
+```
+
+See also [Locator#filter](./locator#filter) that allows to match by another criteria, like an accessible role, and then filter
+by the text content.
+
+> NOTE: Matching by text always normalizes whitespace, even with exact match. For example, it turns multiple spaces into
+one, turns line breaks into spaces and ignores leading and trailing whitespace.
+> NOTE: Input elements of the type `button` and `submit` are matched by their `value` instead of the text content. For
+example, locating by text `"Log in"` matches `<input type=button value="Log in">`.
+
+## get_by_title
+
+```
+def get_by_title(text, exact: nil)
+```
+
+Allows locating elements by their title. For example, this method will find the button by its title "Place the order":
+
+```html
+<button title='Place the order'>Order Now</button>
+```
+
+
 ## last
 
 ```
@@ -68,7 +212,10 @@ Returns locator to the last matching frame.
 def locator(selector, has: nil, hasText: nil)
 ```
 
-The method finds an element matching the specified selector in the FrameLocator's subtree.
+The method finds an element matching the specified selector in the locator's subtree. It also accepts filter options,
+similar to [Locator#filter](./locator#filter) method.
+
+[Learn more about locators](https://playwright.dev/python/docs/locators).
 
 ## nth
 

data/documentation/docs/api/js_handle.md

@@ -85,10 +85,12 @@ The method returns a map with **own property names** as keys and JSHandle instan
 
 ```ruby
 page.goto('https://example.com/')
-window_handle = page.evaluate_handle("window")
-properties = window_handle.properties
+handle = page.evaluate_handle("({window, document})")
+properties = handle.properties
 puts properties
-window_handle.dispose
+window_handle = properties["window"]
+document_handle = properties["document"]
+handle.dispose
 ```
 
 

data/documentation/docs/api/keyboard.md

@@ -5,7 +5,7 @@ sidebar_position: 10
 # Keyboard
 
 Keyboard provides an api for managing a virtual keyboard. The high level api is [Keyboard#type](./keyboard#type), which takes
-raw characters and generates proper keydown, keypress/input, and keyup events on your page.
+raw characters and generates proper `keydown`, `keypress`/`input`, and `keyup` events on your page.
 
 For finer control, you can use [Keyboard#down](./keyboard#down), [Keyboard#up](./keyboard#up), and [Keyboard#insert_text](./keyboard#insert_text)
 to manually fire events as if they were generated from a real keyboard.