playwright-ruby-client 1.28.1 → 1.29.0

data/lib/playwright_api/locator.rb

@@ -1,25 +1,44 @@
 module Playwright
-  # 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 [`method: 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 [`method: Page.locator`] method.
   #
   # [Learn more about locators](../locators.md).
   class Locator < PlaywrightApi
 
+    #
+    # When locator points to a list of elements, returns array of locators, pointing
+    # to respective elements.
+    #
+    # **Usage**
+    #
+    # ```python sync
+    # for li in page.get_by_role('listitem').all():
+    #   li.click();
+    # ```
+    def all
+      wrap_impl(@impl.all)
+    end
+
+    #
     # Returns an array of `node.innerText` values for all matching nodes.
     def all_inner_texts
       wrap_impl(@impl.all_inner_texts)
     end
 
+    #
     # Returns an array of `node.textContent` values for all matching nodes.
     def all_text_contents
       wrap_impl(@impl.all_text_contents)
     end
 
+    #
     # Calls [blur](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/blur) on the element.
     def blur(timeout: nil)
       wrap_impl(@impl.blur(timeout: unwrap_impl(timeout)))
     end
 
+    #
     # 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.
     #
@@ -33,6 +52,8 @@ module Playwright
     # 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**
+    #
     # ```python sync
     # box = element.bounding_box()
     # page.mouse.click(box["x"] + box["width"] / 2, box["y"] + box["height"] / 2)
@@ -41,9 +62,9 @@ module Playwright
       wrap_impl(@impl.bounding_box(timeout: unwrap_impl(timeout)))
     end
 
+    #
     # 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](../actionability.md) checks on the element, unless `force` option is set.
     # 1. Scroll the element into view if needed.
     # 1. Use [`property: Page.mouse`] to click in the center of the element.
@@ -52,8 +73,8 @@ module Playwright
     #
     # 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.
     def check(
           force: nil,
           noWaitAfter: nil,
@@ -63,17 +84,19 @@ module Playwright
       wrap_impl(@impl.check(force: unwrap_impl(force), noWaitAfter: unwrap_impl(noWaitAfter), position: unwrap_impl(position), timeout: unwrap_impl(timeout), trial: unwrap_impl(trial)))
     end
 
-    # This method waits for [actionability](../actionability.md) 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](../actionability.md) 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.
     def clear(force: nil, noWaitAfter: nil, timeout: nil)
       wrap_impl(@impl.clear(force: unwrap_impl(force), noWaitAfter: unwrap_impl(noWaitAfter), timeout: unwrap_impl(timeout)))
     end
 
+    #
+    # Click an element.
+    #
+    # **Details**
+    #
     # This method clicks the element by performing the following steps:
     # 1. Wait for [actionability](../actionability.md) checks on the element, unless `force` option is set.
     # 1. Scroll the element into view if needed.
@@ -82,8 +105,8 @@ module Playwright
     #
     # 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.
     def click(
           button: nil,
           clickCount: nil,
@@ -97,24 +120,25 @@ module Playwright
       wrap_impl(@impl.click(button: unwrap_impl(button), clickCount: unwrap_impl(clickCount), delay: unwrap_impl(delay), force: unwrap_impl(force), modifiers: unwrap_impl(modifiers), noWaitAfter: unwrap_impl(noWaitAfter), position: unwrap_impl(position), timeout: unwrap_impl(timeout), trial: unwrap_impl(trial)))
     end
 
+    #
     # Returns the number of elements matching given selector.
     def count
       wrap_impl(@impl.count)
     end
 
+    #
     # This method double clicks the element by performing the following steps:
     # 1. Wait for [actionability](../actionability.md) checks on the element, unless `force` option is set.
     # 1. Scroll the element into view if needed.
     # 1. Use [`property: 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.
     def dblclick(
           button: nil,
           delay: nil,
@@ -127,18 +151,23 @@ module Playwright
       wrap_impl(@impl.dblclick(button: unwrap_impl(button), delay: unwrap_impl(delay), force: unwrap_impl(force), modifiers: unwrap_impl(modifiers), noWaitAfter: unwrap_impl(noWaitAfter), position: unwrap_impl(position), timeout: unwrap_impl(timeout), trial: unwrap_impl(trial)))
     end
 
-    # 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**
+    #
     # ```python sync
     # 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)
@@ -158,8 +187,12 @@ module Playwright
       wrap_impl(@impl.dispatch_event(unwrap_impl(type), eventInit: unwrap_impl(eventInit), timeout: unwrap_impl(timeout)))
     end
 
-    # 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**
     #
     # ```python sync
     # source = page.locator("#source")
@@ -184,24 +217,27 @@ module Playwright
       wrap_impl(@impl.drag_to(unwrap_impl(target), force: unwrap_impl(force), noWaitAfter: unwrap_impl(noWaitAfter), sourcePosition: unwrap_impl(sourcePosition), targetPosition: unwrap_impl(targetPosition), timeout: unwrap_impl(timeout), trial: unwrap_impl(trial)))
     end
 
-    # 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.
     def element_handle(timeout: nil)
       wrap_impl(@impl.element_handle(timeout: unwrap_impl(timeout)))
     end
 
+    #
     # Resolves given locator to all matching DOM elements.
     def element_handles
       wrap_impl(@impl.element_handles)
     end
 
+    #
     # Returns the return value of `expression`.
     #
     # This method passes this handle as the first argument to `expression`.
     #
-    # If `expression` returns a [Promise], then `handle.evaluate` would wait for the promise to resolve and return its value.
+    # If `expression` returns a [Promise], then `handle.evaluate` would wait for the promise to resolve and return
+    # its value.
     #
-    # Examples:
+    # **Usage**
     #
     # ```python sync
     # tweets = page.locator(".tweet .retweets")
@@ -211,52 +247,53 @@ module Playwright
       wrap_impl(@impl.evaluate(unwrap_impl(expression), arg: unwrap_impl(arg), timeout: unwrap_impl(timeout)))
     end
 
-    # 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], then [`method: Locator.evaluateAll`] 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.
+    #
+    # If `expression` returns a [Promise], then [`method: Locator.evaluateAll`] would wait for the promise
+    # to resolve and return its value.
     #
-    # Examples:
+    # **Usage**
     #
     # ```python sync
     # elements = page.locator("div")
-    # div_counts = elements("(divs, min) => divs.length >= min", 10)
+    # div_counts = elements.evaluate_all("(divs, min) => divs.length >= min", 10)
     # ```
     def evaluate_all(expression, arg: nil)
       wrap_impl(@impl.evaluate_all(unwrap_impl(expression), arg: unwrap_impl(arg)))
     end
 
+    #
     # Returns the return value of `expression` as a `JSHandle`.
     #
     # This method passes this handle as the first argument to `expression`.
     #
-    # The only difference between [`method: Locator.evaluate`] and [`method: Locator.evaluateHandle`] is that
-    # [`method: Locator.evaluateHandle`] returns `JSHandle`.
+    # The only difference between [`method: Locator.evaluate`] and [`method: Locator.evaluateHandle`] is that [`method: Locator.evaluateHandle`] returns `JSHandle`.
     #
-    # If the function passed to the [`method: Locator.evaluateHandle`] returns a [Promise], then
-    # [`method: Locator.evaluateHandle`] would wait for the promise to resolve and return its value.
+    # If the function passed to the [`method: Locator.evaluateHandle`] returns a [Promise], then [`method: Locator.evaluateHandle`] would wait
+    # for the promise to resolve and return its value.
     #
     # See [`method: Page.evaluateHandle`] for more details.
     def evaluate_handle(expression, arg: nil, timeout: nil)
       wrap_impl(@impl.evaluate_handle(unwrap_impl(expression), arg: unwrap_impl(arg), timeout: unwrap_impl(timeout)))
     end
 
-    # This method waits for [actionability](../actionability.md) 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](../actionability.md) 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 [`method: Locator.type`].
     def fill(value, force: nil, noWaitAfter: nil, timeout: nil)
       wrap_impl(@impl.fill(unwrap_impl(value), force: unwrap_impl(force), noWaitAfter: unwrap_impl(noWaitAfter), timeout: unwrap_impl(timeout)))
     end
 
-    # 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**
     #
     # ```python sync
     # row_locator = page.locator("tr")
@@ -270,18 +307,23 @@ module Playwright
       wrap_impl(@impl.filter(has: unwrap_impl(has), hasText: unwrap_impl(hasText)))
     end
 
+    #
     # Returns locator to the first matching element.
     def first
       wrap_impl(@impl.first)
     end
 
+    #
     # Calls [focus](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/focus) on the element.
     def focus(timeout: nil)
       wrap_impl(@impl.focus(timeout: unwrap_impl(timeout)))
     end
 
-    # 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:
     #
     # ```python sync
     # locator = page.frame_locator("iframe").get_by_text("Submit")
@@ -291,12 +333,14 @@ module Playwright
       wrap_impl(@impl.frame_locator(unwrap_impl(selector)))
     end
 
+    #
     # Returns element attribute value.
     def get_attribute(name, timeout: nil)
       wrap_impl(@impl.get_attribute(unwrap_impl(name), timeout: unwrap_impl(timeout)))
     end
     alias_method :[], :get_attribute
 
+    #
     # Allows locating elements by their alt text. For example, this method will find the image by alt text "Castle":
     #
     # ```html
@@ -306,8 +350,8 @@ module Playwright
       wrap_impl(@impl.get_by_alt_text(unwrap_impl(text), exact: unwrap_impl(exact)))
     end
 
-    # 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>
@@ -317,8 +361,8 @@ module Playwright
       wrap_impl(@impl.get_by_label(unwrap_impl(text), exact: unwrap_impl(exact)))
     end
 
-    # 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">
@@ -327,15 +371,10 @@ module Playwright
       wrap_impl(@impl.get_by_placeholder(unwrap_impl(text), exact: unwrap_impl(exact)))
     end
 
-    # Allows locating elements by their [ARIA role](https://www.w3.org/TR/wai-aria-1.2/#roles),
-    # [ARIA attributes](https://www.w3.org/TR/wai-aria-1.2/#aria-attributes) and
-    # [accessible name](https://w3c.github.io/accname/#dfn-accessible-name). 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.
     def get_by_role(
           role,
           checked: nil,
@@ -350,12 +389,13 @@ module Playwright
       wrap_impl(@impl.get_by_role(unwrap_impl(role), checked: unwrap_impl(checked), disabled: unwrap_impl(disabled), exact: unwrap_impl(exact), expanded: unwrap_impl(expanded), includeHidden: unwrap_impl(includeHidden), level: unwrap_impl(level), name: unwrap_impl(name), pressed: unwrap_impl(pressed), selected: unwrap_impl(selected)))
     end
 
-    # Locate element by the test id. By default, the `data-testid` attribute is used as a test id. Use
-    # [`method: Selectors.setTestIdAttribute`] 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 [`method: Selectors.setTestIdAttribute`] to configure a different test id attribute if necessary.
     def get_by_test_id(testId)
       wrap_impl(@impl.get_by_test_id(unwrap_impl(testId)))
     end
 
+    #
     # Allows locating elements that contain given text. Consider the following DOM structure:
     #
     # ```html
@@ -382,17 +422,16 @@ module Playwright
     # page.get_by_text(re.compile("^hello$", re.IGNORECASE))
     # ```
     #
-    # See also [`method: Locator.filter`] that allows to match by another criteria, like an accessible role, and then filter
-    # by the text content.
+    # See also [`method: 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">`.
     def get_by_text(text, exact: nil)
       wrap_impl(@impl.get_by_text(unwrap_impl(text), exact: unwrap_impl(exact)))
     end
 
+    #
     # Allows locating elements by their title. For example, this method will find the button by its title "Place the order":
     #
     # ```html
@@ -402,12 +441,13 @@ module Playwright
       wrap_impl(@impl.get_by_title(unwrap_impl(text), exact: unwrap_impl(exact)))
     end
 
-    # Highlight the corresponding element(s) on the screen. Useful for debugging, don't commit the code that uses
-    # [`method: Locator.highlight`].
+    #
+    # Highlight the corresponding element(s) on the screen. Useful for debugging, don't commit the code that uses [`method: Locator.highlight`].
     def highlight
       wrap_impl(@impl.highlight)
     end
 
+    #
     # This method hovers over the element by performing the following steps:
     # 1. Wait for [actionability](../actionability.md) checks on the element, unless `force` option is set.
     # 1. Scroll the element into view if needed.
@@ -416,8 +456,8 @@ module Playwright
     #
     # 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.
     def hover(
           force: nil,
           modifiers: nil,
@@ -428,81 +468,94 @@ module Playwright
       wrap_impl(@impl.hover(force: unwrap_impl(force), modifiers: unwrap_impl(modifiers), noWaitAfter: unwrap_impl(noWaitAfter), position: unwrap_impl(position), timeout: unwrap_impl(timeout), trial: unwrap_impl(trial)))
     end
 
+    #
     # Returns the `element.innerHTML`.
     def inner_html(timeout: nil)
       wrap_impl(@impl.inner_html(timeout: unwrap_impl(timeout)))
     end
 
+    #
     # Returns the `element.innerText`.
     def inner_text(timeout: nil)
       wrap_impl(@impl.inner_text(timeout: unwrap_impl(timeout)))
     end
 
+    #
     # 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.
     def input_value(timeout: nil)
       wrap_impl(@impl.input_value(timeout: unwrap_impl(timeout)))
     end
 
+    #
     # Returns whether the element is checked. Throws if the element is not a checkbox or radio input.
     def checked?(timeout: nil)
       wrap_impl(@impl.checked?(timeout: unwrap_impl(timeout)))
     end
 
+    #
     # Returns whether the element is disabled, the opposite of [enabled](../actionability.md#enabled).
     def disabled?(timeout: nil)
       wrap_impl(@impl.disabled?(timeout: unwrap_impl(timeout)))
     end
 
+    #
     # Returns whether the element is [editable](../actionability.md#editable).
     def editable?(timeout: nil)
       wrap_impl(@impl.editable?(timeout: unwrap_impl(timeout)))
     end
 
+    #
     # Returns whether the element is [enabled](../actionability.md#enabled).
     def enabled?(timeout: nil)
       wrap_impl(@impl.enabled?(timeout: unwrap_impl(timeout)))
     end
 
+    #
     # Returns whether the element is hidden, the opposite of [visible](../actionability.md#visible).
     def hidden?(timeout: nil)
       wrap_impl(@impl.hidden?(timeout: unwrap_impl(timeout)))
     end
 
+    #
     # Returns whether the element is [visible](../actionability.md#visible).
     def visible?(timeout: nil)
       wrap_impl(@impl.visible?(timeout: unwrap_impl(timeout)))
     end
 
+    #
     # Returns locator to the last matching element.
     def last
       wrap_impl(@impl.last)
     end
 
-    # The method finds an element matching the specified selector in the locator's subtree. It also accepts filter options,
-    # similar to [`method: Locator.filter`] method.
+    #
+    # The method finds an element matching the specified selector in the locator's subtree. It also accepts filter options, similar to [`method: Locator.filter`] method.
     #
     # [Learn more about locators](../locators.md).
     def locator(selector, has: nil, hasText: nil)
       wrap_impl(@impl.locator(unwrap_impl(selector), has: unwrap_impl(has), hasText: unwrap_impl(hasText)))
     end
 
+    #
     # Returns locator to the n-th matching element. It's zero based, `nth(0)` selects the first element.
     def nth(index)
       wrap_impl(@impl.nth(unwrap_impl(index)))
     end
 
+    #
     # A page this locator belongs to.
     def page
       wrap_impl(@impl.page)
     end
 
+    #
     # Focuses the element, and then uses [`method: Keyboard.down`] and [`method: 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`,
@@ -512,8 +565,8 @@ module Playwright
     #
     # 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.
@@ -521,9 +574,8 @@ module Playwright
       wrap_impl(@impl.press(unwrap_impl(key), delay: unwrap_impl(delay), noWaitAfter: unwrap_impl(noWaitAfter), timeout: unwrap_impl(timeout)))
     end
 
-    # 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](../actionability.md) checks, then scrolls element into view before taking a
     # screenshot. If the element is detached from DOM, the method throws an error.
@@ -542,6 +594,7 @@ module Playwright
       wrap_impl(@impl.screenshot(animations: unwrap_impl(animations), caret: unwrap_impl(caret), mask: unwrap_impl(mask), omitBackground: unwrap_impl(omitBackground), path: unwrap_impl(path), quality: unwrap_impl(quality), scale: unwrap_impl(scale), timeout: unwrap_impl(timeout), type: unwrap_impl(type)))
     end
 
+    #
     # This method waits for [actionability](../actionability.md) 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`.
@@ -549,23 +602,35 @@ module Playwright
       wrap_impl(@impl.scroll_into_view_if_needed(timeout: unwrap_impl(timeout)))
     end
 
-    # This method waits for [actionability](../actionability.md) 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](../actionability.md) 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>
+    # ```
+    #
     # ```python sync
-    # # single selection matching the value
+    # # single selection matching the value or label
     # element.select_option("blue")
-    # # single selection matching both the label
+    # # single selection matching the label
     # element.select_option(label="blue")
-    # # multiple selection
+    # # multiple selection for blue, red and second option
     # element.select_option(value=["red", "green", "blue"])
     # ```
     def select_option(
@@ -579,28 +644,27 @@ module Playwright
       wrap_impl(@impl.select_option(element: unwrap_impl(element), index: unwrap_impl(index), value: unwrap_impl(value), label: unwrap_impl(label), force: unwrap_impl(force), noWaitAfter: unwrap_impl(noWaitAfter), timeout: unwrap_impl(timeout)))
     end
 
+    #
     # This method waits for [actionability](../actionability.md) 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.
     def select_text(force: nil, timeout: nil)
       wrap_impl(@impl.select_text(force: unwrap_impl(force), timeout: unwrap_impl(timeout)))
     end
 
+    #
     # 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](../actionability.md) 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](../actionability.md) 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 [`property: 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.
     def set_checked(
           checked,
           force: nil,
@@ -612,18 +676,18 @@ module Playwright
     end
     alias_method :checked=, :set_checked
 
+    #
     # 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` 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.
     def set_input_files(files, noWaitAfter: nil, timeout: nil)
       wrap_impl(@impl.set_input_files(unwrap_impl(files), noWaitAfter: unwrap_impl(noWaitAfter), timeout: unwrap_impl(timeout)))
     end
     alias_method :input_files=, :set_input_files
 
+    #
     # This method taps the element by performing the following steps:
     # 1. Wait for [actionability](../actionability.md) checks on the element, unless `force` option is set.
     # 1. Scroll the element into view if needed.
@@ -632,10 +696,10 @@ module Playwright
     #
     # 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.
     def tap_point(
           force: nil,
           modifiers: nil,
@@ -646,15 +710,19 @@ module Playwright
       wrap_impl(@impl.tap_point(force: unwrap_impl(force), modifiers: unwrap_impl(modifiers), noWaitAfter: unwrap_impl(noWaitAfter), position: unwrap_impl(position), timeout: unwrap_impl(timeout), trial: unwrap_impl(trial)))
     end
 
+    #
     # Returns the `node.textContent`.
     def text_content(timeout: nil)
       wrap_impl(@impl.text_content(timeout: unwrap_impl(timeout)))
     end
 
+    #
     # 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 [`method: Locator.press`].
     #
+    # **Usage**
+    #
     # ```python sync
     # element.type("hello") # types instantly
     # element.type("world", delay=100) # types slower, like a user
@@ -671,9 +739,9 @@ module Playwright
       wrap_impl(@impl.type(unwrap_impl(text), delay: unwrap_impl(delay), noWaitAfter: unwrap_impl(noWaitAfter), timeout: unwrap_impl(timeout)))
     end
 
+    #
     # 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](../actionability.md) checks on the element, unless `force` option is set.
     # 1. Scroll the element into view if needed.
     # 1. Use [`property: Page.mouse`] to click in the center of the element.
@@ -682,8 +750,8 @@ module Playwright
     #
     # 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.
     def uncheck(
           force: nil,
           noWaitAfter: nil,
@@ -693,10 +761,13 @@ module Playwright
       wrap_impl(@impl.uncheck(force: unwrap_impl(force), noWaitAfter: unwrap_impl(noWaitAfter), position: unwrap_impl(position), timeout: unwrap_impl(timeout), trial: unwrap_impl(trial)))
     end
 
+    #
     # 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**
     #
     # ```python sync
     # order_sent = page.locator("#order-sent")