playwright-ruby-client 1.28.1 → 1.29.1.alpha1

data/documentation/docs/api/locator.md

@@ -4,17 +4,37 @@ sidebar_position: 10
 
 # Locator
 
-Locators are the central piece of Playwright's auto-waiting and retry-ability. In a nutshell, locators represent a way
-to find element(s) on the page at any moment. Locator can be created with the [Page#locator](./page#locator) method.
+
+Locators are the central piece of Playwright's auto-waiting and retry-ability. In a nutshell, locators represent
+a way to find element(s) on the page at any moment. Locator can be created with the [Page#locator](./page#locator) method.
 
 [Learn more about locators](https://playwright.dev/python/docs/locators).
 
+## all
+
+```
+def all
+```
+
+
+When locator points to a list of elements, returns array of locators, pointing
+to respective elements.
+
+**Usage**
+
+```ruby
+page.get_by_role('listitem').all.each do |li|
+  li.click
+end
+```
+
 ## all_inner_texts
 
 ```
 def all_inner_texts
 ```
 
+
 Returns an array of `node.innerText` values for all matching nodes.
 
 ## all_text_contents
@@ -23,6 +43,7 @@ Returns an array of `node.innerText` values for all matching nodes.
 def all_text_contents
 ```
 
+
 Returns an array of `node.textContent` values for all matching nodes.
 
 ## blur
@@ -31,6 +52,7 @@ Returns an array of `node.textContent` values for all matching nodes.
 def blur(timeout: nil)
 ```
 
+
 Calls [blur](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/blur) on the element.
 
 ## bounding_box
@@ -39,6 +61,7 @@ Calls [blur](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/blur)
 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.
 
@@ -52,6 +75,8 @@ Elements from child frames return the bounding box relative to the main frame, u
 Assuming the page is static, it is safe to use bounding box coordinates to perform input. For example, the following
 snippet should click the center of the element.
 
+**Usage**
+
 ```ruby
 box = element.bounding_box
 page.mouse.click(
@@ -60,8 +85,6 @@ page.mouse.click(
 )
 ```
 
-
-
 ## check
 
 ```
@@ -73,9 +96,9 @@ def check(
       trial: nil)
 ```
 
+
 This method checks the element by performing the following steps:
-1. Ensure that element is a checkbox or a radio input. If not, this method throws. If the element is already checked,
-   this method returns immediately.
+1. Ensure that element is a checkbox or a radio input. If not, this method throws. If the element is already checked, this method returns immediately.
 1. Wait for [actionability](https://playwright.dev/python/docs/actionability) checks on the element, unless `force` option is set.
 1. Scroll the element into view if needed.
 1. Use [Page#mouse](./page#mouse) to click in the center of the element.
@@ -84,8 +107,8 @@ This method checks the element by performing the following steps:
 
 If the element is detached from the DOM at any moment during the action, this method throws.
 
-When all steps combined have not finished during the specified `timeout`, this method throws a `TimeoutError`. Passing
-zero timeout disables this.
+When all steps combined have not finished during the specified `timeout`, this method throws a
+`TimeoutError`. Passing zero timeout disables this.
 
 ## clear
 
@@ -93,13 +116,10 @@ zero timeout disables this.
 def clear(force: nil, noWaitAfter: nil, timeout: nil)
 ```
 
-This method waits for [actionability](https://playwright.dev/python/docs/actionability) checks, focuses the element, clears it and triggers an
-`input` event after clearing.
 
-If the target element is not an `<input>`, `<textarea>` or `[contenteditable]` element, this method throws an error.
-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), the control will be cleared
-instead.
+This method waits for [actionability](https://playwright.dev/python/docs/actionability) checks, focuses the element, clears it and triggers an `input` event after clearing.
+
+If the target element is not an `<input>`, `<textarea>` or `[contenteditable]` element, this method throws an error. 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), the control will be cleared instead.
 
 ## click
 
@@ -116,6 +136,11 @@ def click(
       trial: nil)
 ```
 
+
+Click an element.
+
+**Details**
+
 This method clicks the element by performing the following steps:
 1. Wait for [actionability](https://playwright.dev/python/docs/actionability) checks on the element, unless `force` option is set.
 1. Scroll the element into view if needed.
@@ -124,8 +149,8 @@ This method clicks the element by performing the following steps:
 
 If the element is detached from the DOM at any moment during the action, this method throws.
 
-When all steps combined have not finished during the specified `timeout`, this method throws a `TimeoutError`. Passing
-zero timeout disables this.
+When all steps combined have not finished during the specified `timeout`, this method throws a
+`TimeoutError`. Passing zero timeout disables this.
 
 ## count
 
@@ -133,6 +158,7 @@ zero timeout disables this.
 def count
 ```
 
+
 Returns the number of elements matching given selector.
 
 ## dblclick
@@ -149,19 +175,19 @@ def dblclick(
       trial: nil)
 ```
 
+
 This method double clicks the element by performing the following steps:
 1. Wait for [actionability](https://playwright.dev/python/docs/actionability) checks on the element, unless `force` option is set.
 1. Scroll the element into view if needed.
 1. Use [Page#mouse](./page#mouse) to double click in the center of the element, or the specified `position`.
-1. Wait for initiated navigations to either succeed or fail, unless `noWaitAfter` option is set. Note that if the
-   first click of the `dblclick()` triggers a navigation event, this method will throw.
+1. Wait for initiated navigations to either succeed or fail, unless `noWaitAfter` option is set. Note that if the first click of the `dblclick()` triggers a navigation event, this method will throw.
 
 If the element is detached from the DOM at any moment during the action, this method throws.
 
-When all steps combined have not finished during the specified `timeout`, this method throws a `TimeoutError`. Passing
-zero timeout disables this.
+When all steps combined have not finished during the specified `timeout`, this method throws a
+`TimeoutError`. Passing zero timeout disables this.
 
-> NOTE: `element.dblclick()` dispatches two `click` events and a single `dblclick` event.
+**NOTE**: `element.dblclick()` dispatches two `click` events and a single `dblclick` event.
 
 ## dispatch_event
 
@@ -169,18 +195,23 @@ zero timeout disables this.
 def dispatch_event(type, eventInit: nil, timeout: nil)
 ```
 
-The snippet below dispatches the `click` event on the element. Regardless of the visibility state of the element,
-`click` is dispatched. This is equivalent to calling
+
+The snippet below dispatches the `click` event on the element. Regardless of the visibility state of the element, `click`
+is dispatched. This is equivalent to calling
 [element.click()](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/click).
 
+**Usage**
+
 ```ruby
 element.dispatch_event("click")
 ```
 
-Under the hood, it creates an instance of an event based on the given `type`, initializes it with `eventInit` properties
-and dispatches it on the element. Events are `composed`, `cancelable` and bubble by default.
+Under the hood, it creates an instance of an event based on the given `type`, initializes it with
+`eventInit` properties and dispatches it on the element. Events are `composed`, `cancelable` and bubble by
+default.
 
-Since `eventInit` is event-specific, please refer to the events documentation for the lists of initial properties:
+Since `eventInit` is event-specific, please refer to the events documentation for the lists of initial
+properties:
 - [DragEvent](https://developer.mozilla.org/en-US/docs/Web/API/DragEvent/DragEvent)
 - [FocusEvent](https://developer.mozilla.org/en-US/docs/Web/API/FocusEvent/FocusEvent)
 - [KeyboardEvent](https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/KeyboardEvent)
@@ -197,8 +228,6 @@ data_transfer = page.evaluate_handle("new DataTransfer()")
 element.dispatch_event("dragstart", eventInit: { dataTransfer: data_transfer })
 ```
 
-
-
 ## drag_to
 
 ```
@@ -212,8 +241,12 @@ def drag_to(
       trial: nil)
 ```
 
-This method drags the locator to another target locator or target position. It will first move to the source element,
-perform a `mousedown`, then move to the target element or position and perform a `mouseup`.
+
+This method drags the locator to another target locator or target position. It will
+first move to the source element, perform a `mousedown`, then move to the target
+element or position and perform a `mouseup`.
+
+**Usage**
 
 ```ruby
 source = page.locator("#source")
@@ -228,16 +261,14 @@ source.drag_to(
 )
 ```
 
-
-
 ## element_handle
 
 ```
 def element_handle(timeout: nil)
 ```
 
-Resolves given locator to the first matching DOM element. If no elements matching the query are visible, waits for them
-up to a given timeout. If multiple elements match the selector, throws.
+
+Resolves given locator to the first matching DOM element. If no elements matching the query are visible, waits for them up to a given timeout. If multiple elements match the selector, throws.
 
 ## element_handles
 
@@ -245,6 +276,7 @@ up to a given timeout. If multiple elements match the selector, throws.
 def element_handles
 ```
 
+
 Resolves given locator to all matching DOM elements.
 
 ## evaluate
@@ -253,57 +285,56 @@ Resolves given locator to all matching DOM elements.
 def evaluate(expression, arg: nil, timeout: nil)
 ```
 
+
 Returns the return value of `expression`.
 
 This method passes this handle as the first argument to `expression`.
 
-If `expression` returns a [Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise), then `handle.evaluate` would wait for the promise to resolve and return its value.
+If `expression` returns a [Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise), then `handle.evaluate` would wait for the promise to resolve and return
+its value.
 
-Examples:
+**Usage**
 
 ```ruby
 tweet = page.query_selector(".tweet .retweets")
 tweet.evaluate("node => node.innerText") # => "10 retweets"
 ```
 
-
-
 ## evaluate_all
 
 ```
 def evaluate_all(expression, arg: nil)
 ```
 
-The method finds all elements matching the specified locator and passes an array of matched elements as a first argument
-to `expression`. Returns the result of `expression` invocation.
 
-If `expression` returns a [Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise), then [Locator#evaluate_all](./locator#evaluate_all) would wait for the promise to resolve and
-return its value.
+The method finds all elements matching the specified locator and passes an array of matched elements as
+a first argument to `expression`. Returns the result of `expression` invocation.
 
-Examples:
+If `expression` returns a [Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise), then [Locator#evaluate_all](./locator#evaluate_all) would wait for the promise
+to resolve and return its value.
+
+**Usage**
 
 ```ruby
 elements = page.locator("div")
-elements.evaluate_all("(divs, min) => divs.length >= min", arg: 10)
+div_counts = elements.evaluate_all("(divs, min) => divs.length >= min", arg: 10)
 ```
 
-
-
 ## evaluate_handle
 
 ```
 def evaluate_handle(expression, arg: nil, timeout: nil)
 ```
 
+
 Returns the return value of `expression` as a [JSHandle](./js_handle).
 
 This method passes this handle as the first argument to `expression`.
 
-The only difference between [Locator#evaluate](./locator#evaluate) and [Locator#evaluate_handle](./locator#evaluate_handle) is that
-[Locator#evaluate_handle](./locator#evaluate_handle) returns [JSHandle](./js_handle).
+The only difference between [Locator#evaluate](./locator#evaluate) and [Locator#evaluate_handle](./locator#evaluate_handle) is that [Locator#evaluate_handle](./locator#evaluate_handle) returns [JSHandle](./js_handle).
 
-If the function passed to the [Locator#evaluate_handle](./locator#evaluate_handle) returns a [Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise), then
-[Locator#evaluate_handle](./locator#evaluate_handle) would wait for the promise to resolve and return its value.
+If the function passed to the [Locator#evaluate_handle](./locator#evaluate_handle) returns a [Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise), then [Locator#evaluate_handle](./locator#evaluate_handle) would wait
+for the promise to resolve and return its value.
 
 See [Page#evaluate_handle](./page#evaluate_handle) for more details.
 
@@ -313,13 +344,10 @@ See [Page#evaluate_handle](./page#evaluate_handle) for more details.
 def fill(value, force: nil, noWaitAfter: nil, timeout: nil)
 ```
 
-This method waits for [actionability](https://playwright.dev/python/docs/actionability) checks, focuses the element, fills it and triggers an `input`
-event after filling. Note that you can pass an empty string to clear the input field.
 
-If the target element is not an `<input>`, `<textarea>` or `[contenteditable]` element, this method throws an error.
-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), the control will be filled
-instead.
+This method waits for [actionability](https://playwright.dev/python/docs/actionability) checks, focuses the element, fills it and triggers an `input` event after filling. Note that you can pass an empty string to clear the input field.
+
+If the target element is not an `<input>`, `<textarea>` or `[contenteditable]` element, this method throws an error. 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), the control will be filled instead.
 
 To send fine-grained keyboard events, use [Locator#type](./locator#type).
 
@@ -329,8 +357,11 @@ To send fine-grained keyboard events, use [Locator#type](./locator#type).
 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.
+
+This method narrows existing locator according to the options, for example filters by text.
+It can be chained to filter multiple times.
+
+**Usage**
 
 ```ruby
 row_locator = page.locator("tr")
@@ -341,14 +372,13 @@ row_locator.
     screenshot
 ```
 
-
-
 ## first
 
 ```
 def first
 ```
 
+
 Returns locator to the first matching element.
 
 ## focus
@@ -357,6 +387,7 @@ Returns locator to the first matching element.
 def focus(timeout: nil)
 ```
 
+
 Calls [focus](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/focus) on the element.
 
 ## frame_locator
@@ -365,16 +396,17 @@ Calls [focus](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/focus
 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:
+
+**Usage**
+
+When working with iframes, you can create a frame locator that will enter the iframe and allow selecting elements
+in that iframe:
 
 ```ruby
 locator = page.frame_locator("iframe").get_by_text("Submit")
 locator.click
 ```
 
-
-
 ## get_attribute
 
 ```
@@ -382,6 +414,7 @@ def get_attribute(name, timeout: nil)
 ```
 alias: `[]`
 
+
 Returns element attribute value.
 
 ## get_by_alt_text
@@ -390,42 +423,40 @@ Returns element attribute value.
 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:
+
+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":
+
+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
 
 ```
@@ -442,15 +473,10 @@ def get_by_role(
       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.
+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
 
@@ -458,10 +484,8 @@ recommend** duplicating implicit roles and attributes by setting `role` and/or `
 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.
-
 
+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
 
@@ -469,6 +493,7 @@ Locate element by the test id. By default, the `data-testid` attribute is used a
 def get_by_text(text, exact: nil)
 ```
 
+
 Allows locating elements that contain given text. Consider the following DOM structure:
 
 ```html
@@ -507,13 +532,11 @@ 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.
+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">`.
+**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
 
@@ -521,21 +544,21 @@ example, locating by text `"Log in"` matches `<input type=button value="Log in">
 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>
 ```
 
-
 ## highlight
 
 ```
 def highlight
 ```
 
-Highlight the corresponding element(s) on the screen. Useful for debugging, don't commit the code that uses
-[Locator#highlight](./locator#highlight).
+
+Highlight the corresponding element(s) on the screen. Useful for debugging, don't commit the code that uses [Locator#highlight](./locator#highlight).
 
 ## hover
 
@@ -549,6 +572,7 @@ def hover(
       trial: nil)
 ```
 
+
 This method hovers over the element by performing the following steps:
 1. Wait for [actionability](https://playwright.dev/python/docs/actionability) checks on the element, unless `force` option is set.
 1. Scroll the element into view if needed.
@@ -557,8 +581,8 @@ This method hovers over the element by performing the following steps:
 
 If the element is detached from the DOM at any moment during the action, this method throws.
 
-When all steps combined have not finished during the specified `timeout`, this method throws a `TimeoutError`. Passing
-zero timeout disables this.
+When all steps combined have not finished during the specified `timeout`, this method throws a
+`TimeoutError`. Passing zero timeout disables this.
 
 ## inner_html
 
@@ -566,6 +590,7 @@ zero timeout disables this.
 def inner_html(timeout: nil)
 ```
 
+
 Returns the `element.innerHTML`.
 
 ## inner_text
@@ -574,6 +599,7 @@ Returns the `element.innerHTML`.
 def inner_text(timeout: nil)
 ```
 
+
 Returns the `element.innerText`.
 
 ## input_value
@@ -582,10 +608,10 @@ Returns the `element.innerText`.
 def input_value(timeout: nil)
 ```
 
+
 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.
+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?
 
@@ -593,6 +619,7 @@ Throws for non-input elements. However, if the element is inside the `<label>` e
 def checked?(timeout: nil)
 ```
 
+
 Returns whether the element is checked. Throws if the element is not a checkbox or radio input.
 
 ## disabled?
@@ -601,7 +628,8 @@ Returns whether the element is checked. Throws if the element is not a checkbox
 def disabled?(timeout: nil)
 ```
 
-Returns whether the element is disabled, the opposite of [enabled](https://playwright.dev/python/docs/actionability).
+
+Returns whether the element is disabled, the opposite of [enabled](https://playwright.dev/python/docs/actionability#enabled).
 
 ## editable?
 
@@ -609,7 +637,8 @@ Returns whether the element is disabled, the opposite of [enabled](https://playw
 def editable?(timeout: nil)
 ```
 
-Returns whether the element is [editable](https://playwright.dev/python/docs/actionability).
+
+Returns whether the element is [editable](https://playwright.dev/python/docs/actionability#editable).
 
 ## enabled?
 
@@ -617,7 +646,8 @@ Returns whether the element is [editable](https://playwright.dev/python/docs/act
 def enabled?(timeout: nil)
 ```
 
-Returns whether the element is [enabled](https://playwright.dev/python/docs/actionability).
+
+Returns whether the element is [enabled](https://playwright.dev/python/docs/actionability#enabled).
 
 ## hidden?
 
@@ -625,7 +655,8 @@ Returns whether the element is [enabled](https://playwright.dev/python/docs/acti
 def hidden?(timeout: nil)
 ```
 
-Returns whether the element is hidden, the opposite of [visible](https://playwright.dev/python/docs/actionability).
+
+Returns whether the element is hidden, the opposite of [visible](https://playwright.dev/python/docs/actionability#visible).
 
 ## visible?
 
@@ -633,7 +664,8 @@ Returns whether the element is hidden, the opposite of [visible](https://playwri
 def visible?(timeout: nil)
 ```
 
-Returns whether the element is [visible](https://playwright.dev/python/docs/actionability).
+
+Returns whether the element is [visible](https://playwright.dev/python/docs/actionability#visible).
 
 ## last
 
@@ -641,6 +673,7 @@ Returns whether the element is [visible](https://playwright.dev/python/docs/acti
 def last
 ```
 
+
 Returns locator to the last matching element.
 
 ## locator
@@ -649,8 +682,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's subtree. It also accepts filter options,
-similar to [Locator#filter](./locator#filter) method.
+
+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).
 
@@ -660,6 +693,7 @@ similar to [Locator#filter](./locator#filter) method.
 def nth(index)
 ```
 
+
 Returns locator to the n-th matching element. It's zero based, `nth(0)` selects the first element.
 
 ## page
@@ -668,6 +702,7 @@ Returns locator to the n-th matching element. It's zero based, `nth(0)` selects
 def page
 ```
 
+
 A page this locator belongs to.
 
 ## press
@@ -676,10 +711,12 @@ A page this locator belongs to.
 def press(key, delay: nil, noWaitAfter: nil, timeout: nil)
 ```
 
+
 Focuses the element, and then uses [Keyboard#down](./keyboard#down) and [Keyboard#up](./keyboard#up).
 
-`key` can specify the intended [keyboardEvent.key](https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/key)
-value or a single character to generate the text for. A superset of the `key` values can be found
+`key` can specify the intended
+[keyboardEvent.key](https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/key) value or a single character to
+generate the text for. A superset of the `key` values can be found
 [here](https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/key/Key_Values). Examples of the keys are:
 
 `F1` - `F12`, `Digit0`- `Digit9`, `KeyA`- `KeyZ`, `Backquote`, `Minus`, `Equal`, `Backslash`, `Backspace`, `Tab`,
@@ -689,8 +726,8 @@ Following modification shortcuts are also supported: `Shift`, `Control`, `Alt`,
 
 Holding down `Shift` will type the text that corresponds to the `key` in the upper case.
 
-If `key` is a single character, it is case-sensitive, so the values `a` and `A` will generate different respective
-texts.
+If `key` is a single character, it is case-sensitive, so the values `a` and `A` will generate different
+respective texts.
 
 Shortcuts such as `key: "Control+o"` or `key: "Control+Shift+T"` are supported as well. When specified with the
 modifier, modifier is pressed and being held while the subsequent key is being pressed.
@@ -710,9 +747,8 @@ def screenshot(
       type: nil)
 ```
 
-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 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.
@@ -725,6 +761,7 @@ Returns the buffer with the captured screenshot.
 def scroll_into_view_if_needed(timeout: nil)
 ```
 
+
 This method waits for [actionability](https://playwright.dev/python/docs/actionability) checks, then tries to scroll element into view, unless it is
 completely visible as defined by
 [IntersectionObserver](https://developer.mozilla.org/en-US/docs/Web/API/Intersection_Observer_API)'s `ratio`.
@@ -742,19 +779,31 @@ def select_option(
       timeout: nil)
 ```
 
-This method waits for [actionability](https://playwright.dev/python/docs/actionability) checks, waits until all specified options are present in the
-`<select>` element and selects these options.
 
-If the target element is not a `<select>` element, this method throws an error. 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), the control will be used instead.
+Selects option or options in `<select>`.
+
+**Details**
+
+This method waits for [actionability](https://playwright.dev/python/docs/actionability) checks, waits until all specified options are present in the `<select>` element and selects these options.
+
+If the target element is not a `<select>` element, this method throws an error. 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), the control will be used instead.
 
 Returns the array of option values that have been successfully selected.
 
 Triggers a `change` and `input` event once all the provided options have been selected.
 
+**Usage**
+
+```html
+<select multiple>
+  <option value="red">Red</div>
+  <option value="green">Green</div>
+  <option value="blue">Blue</div>
+</select>
+```
+
 ```ruby
-# single selection matching the value
+# single selection matching the value or label
 element.select_option(value: "blue")
 # single selection matching both the label
 element.select_option(label: "blue")
@@ -762,20 +811,17 @@ element.select_option(label: "blue")
 element.select_option(value: ["red", "green", "blue"])
 ```
 
-
-
 ## select_text
 
 ```
 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.
+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
 
@@ -790,18 +836,18 @@ def set_checked(
 ```
 alias: `checked=`
 
+
 This method checks or unchecks an element by performing the following steps:
 1. Ensure that matched element is a checkbox or a radio input. If not, this method throws.
 1. If the element already has the right checked state, this method returns immediately.
-1. Wait for [actionability](https://playwright.dev/python/docs/actionability) checks on the matched element, unless `force` option is set. If the
-   element is detached during the checks, the whole action is retried.
+1. Wait for [actionability](https://playwright.dev/python/docs/actionability) checks on the matched element, unless `force` option is set. If the element is detached during the checks, the whole action is retried.
 1. Scroll the element into view if needed.
 1. Use [Page#mouse](./page#mouse) to click in the center of the element.
 1. Wait for initiated navigations to either succeed or fail, unless `noWaitAfter` option is set.
 1. Ensure that the element is now checked or unchecked. If not, this method throws.
 
-When all steps combined have not finished during the specified `timeout`, this method throws a `TimeoutError`. Passing
-zero timeout disables this.
+When all steps combined have not finished during the specified `timeout`, this method throws a
+`TimeoutError`. Passing zero timeout disables this.
 
 ## set_input_files
 
@@ -810,13 +856,12 @@ def set_input_files(files, noWaitAfter: nil, timeout: nil)
 ```
 alias: `input_files=`
 
+
 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 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.
+[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
 
@@ -830,6 +875,7 @@ def tap_point(
       trial: nil)
 ```
 
+
 This method taps the element by performing the following steps:
 1. Wait for [actionability](https://playwright.dev/python/docs/actionability) checks on the element, unless `force` option is set.
 1. Scroll the element into view if needed.
@@ -838,10 +884,10 @@ This method taps the element by performing the following steps:
 
 If the element is detached from the DOM at any moment during the action, this method throws.
 
-When all steps combined have not finished during the specified `timeout`, this method throws a `TimeoutError`. Passing
-zero timeout disables this.
+When all steps combined have not finished during the specified `timeout`, this method throws a
+`TimeoutError`. Passing zero timeout disables this.
 
-> NOTE: `element.tap()` requires that the `hasTouch` option of the browser context be set to true.
+**NOTE**: `element.tap()` requires that the `hasTouch` option of the browser context be set to true.
 
 ## text_content
 
@@ -849,6 +895,7 @@ zero timeout disables this.
 def text_content(timeout: nil)
 ```
 
+
 Returns the `node.textContent`.
 
 ## type
@@ -857,10 +904,13 @@ Returns the `node.textContent`.
 def type(text, delay: nil, noWaitAfter: nil, timeout: nil)
 ```
 
+
 Focuses the element, and then sends a `keydown`, `keypress`/`input`, and `keyup` event for each character in the text.
 
 To press a special key, like `Control` or `ArrowDown`, use [Locator#press](./locator#press).
 
+**Usage**
+
 ```ruby
 element.type("hello") # types instantly
 element.type("world", delay: 100) # types slower, like a user
@@ -874,8 +924,6 @@ element.type("my password")
 element.press("Enter")
 ```
 
-
-
 ## uncheck
 
 ```
@@ -887,9 +935,9 @@ def uncheck(
       trial: nil)
 ```
 
+
 This method checks the element by performing the following steps:
-1. Ensure that element is a checkbox or a radio input. If not, this method throws. If the element is already
-   unchecked, this method returns immediately.
+1. Ensure that element is a checkbox or a radio input. If not, this method throws. If the element is already unchecked, this method returns immediately.
 1. Wait for [actionability](https://playwright.dev/python/docs/actionability) checks on the element, unless `force` option is set.
 1. Scroll the element into view if needed.
 1. Use [Page#mouse](./page#mouse) to click in the center of the element.
@@ -898,8 +946,8 @@ This method checks the element by performing the following steps:
 
 If the element is detached from the DOM at any moment during the action, this method throws.
 
-When all steps combined have not finished during the specified `timeout`, this method throws a `TimeoutError`. Passing
-zero timeout disables this.
+When all steps combined have not finished during the specified `timeout`, this method throws a
+`TimeoutError`. Passing zero timeout disables this.
 
 ## wait_for
 
@@ -907,14 +955,15 @@ zero timeout disables this.
 def wait_for(state: nil, timeout: nil)
 ```
 
+
 Returns when element specified by locator satisfies the `state` option.
 
-If target element already satisfies the condition, the method returns immediately. Otherwise, waits for up to `timeout`
-milliseconds until the condition is met.
+If target element already satisfies the condition, the method returns immediately. Otherwise, waits for up to
+`timeout` milliseconds until the condition is met.
+
+**Usage**
 
 ```ruby
 order_sent = page.locator("#order-sent")
 order_sent.wait_for
 ```
-
-