playwright-ruby-client 1.28.1 → 1.29.0

data/lib/playwright_api/page.rb

@@ -44,9 +44,6 @@ module Playwright
   # ```
   class Page < PlaywrightApi
 
-    # **DEPRECATED** This property is deprecated. Please use other libraries such as [Axe](https://www.deque.com/axe/) if you
-    # need to test page accessibility. See our Node.js [guide](https://playwright.dev/docs/accessibility-testing) for
-    # integration with Axe.
     def accessibility # property
       wrap_impl(@impl.accessibility)
     end
@@ -59,6 +56,7 @@ module Playwright
       wrap_impl(@impl.mouse)
     end
 
+    #
     # API testing helper associated with this page. This method returns the same instance as
     # [`property: BrowserContext.request`] on the page's context. See [`property: BrowserContext.request`] for more details.
     def request # property
@@ -69,14 +67,16 @@ module Playwright
       wrap_impl(@impl.touchscreen)
     end
 
+    #
     # Adds a script which would be evaluated in one of the following scenarios:
     # - Whenever the page is navigated.
-    # - Whenever the child frame is attached or navigated. In this case, the script is evaluated in the context of the newly
-    #   attached frame.
+    # - Whenever the child frame is attached or navigated. In this case, the script is evaluated in the context of the newly attached frame.
     #
     # The script is evaluated after the document was created but before any of its scripts were run. This is useful to amend
     # the JavaScript environment, e.g. to seed `Math.random`.
     #
+    # **Usage**
+    #
     # An example of overriding `Math.random` before the page loads:
     #
     # ```python sync
@@ -84,48 +84,44 @@ module Playwright
     # page.add_init_script(path="./preload.js")
     # ```
     #
-    # > NOTE: The order of evaluation of multiple scripts installed via [`method: BrowserContext.addInitScript`] and
+    # **NOTE**: The order of evaluation of multiple scripts installed via [`method: BrowserContext.addInitScript`] and
     # [`method: Page.addInitScript`] is not defined.
     def add_init_script(path: nil, script: nil)
       wrap_impl(@impl.add_init_script(path: unwrap_impl(path), script: unwrap_impl(script)))
     end
 
+    #
     # Adds a `<script>` tag into the page with the desired url or content. Returns the added tag when the script's onload
     # fires or when the script content was injected into frame.
-    #
-    # Shortcut for main frame's [`method: Frame.addScriptTag`].
     def add_script_tag(content: nil, path: nil, type: nil, url: nil)
       wrap_impl(@impl.add_script_tag(content: unwrap_impl(content), path: unwrap_impl(path), type: unwrap_impl(type), url: unwrap_impl(url)))
     end
 
+    #
     # Adds a `<link rel="stylesheet">` tag into the page with the desired url or a `<style type="text/css">` tag with the
     # content. Returns the added tag when the stylesheet's onload fires or when the CSS content was injected into frame.
-    #
-    # Shortcut for main frame's [`method: Frame.addStyleTag`].
     def add_style_tag(content: nil, path: nil, url: nil)
       wrap_impl(@impl.add_style_tag(content: unwrap_impl(content), path: unwrap_impl(path), url: unwrap_impl(url)))
     end
 
+    #
     # Brings page to front (activates tab).
     def bring_to_front
       wrap_impl(@impl.bring_to_front)
     end
 
+    #
     # This method checks an element matching `selector` by performing the following steps:
     # 1. Find an element matching `selector`. If there is none, wait until a matching element is attached to the DOM.
-    # 1. Ensure that matched 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 matched element, unless `force` option is set. If the
-    #    element is detached during the checks, the whole action is retried.
+    # 1. Ensure that matched 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 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. 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.
-    #
-    # Shortcut for main frame's [`method: Frame.check`].
+    # When all steps combined have not finished during the specified `timeout`, this method throws a
+    # `TimeoutError`. Passing zero timeout disables this.
     def check(
           selector,
           force: nil,
@@ -137,18 +133,16 @@ module Playwright
       wrap_impl(@impl.check(unwrap_impl(selector), force: unwrap_impl(force), noWaitAfter: unwrap_impl(noWaitAfter), position: unwrap_impl(position), strict: unwrap_impl(strict), timeout: unwrap_impl(timeout), trial: unwrap_impl(trial)))
     end
 
+    #
     # This method clicks an element matching `selector` by performing the following steps:
     # 1. Find an element matching `selector`. If there is none, wait until a matching element is attached to the DOM.
-    # 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, or the specified `position`.
     # 1. Wait for initiated navigations to either succeed or fail, unless `noWaitAfter` option is set.
     #
-    # When all steps combined have not finished during the specified `timeout`, this method throws a `TimeoutError`. Passing
-    # zero timeout disables this.
-    #
-    # Shortcut for main frame's [`method: Frame.click`].
+    # When all steps combined have not finished during the specified `timeout`, this method throws a
+    # `TimeoutError`. Passing zero timeout disables this.
     def click(
           selector,
           button: nil,
@@ -164,42 +158,42 @@ module Playwright
       wrap_impl(@impl.click(unwrap_impl(selector), 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), strict: unwrap_impl(strict), timeout: unwrap_impl(timeout), trial: unwrap_impl(trial)))
     end
 
+    #
     # If `runBeforeUnload` is `false`, does not run any unload handlers and waits for the page to be closed. If
     # `runBeforeUnload` is `true` the method will run unload handlers, but will **not** wait for the page to close.
     #
     # By default, `page.close()` **does not** run `beforeunload` handlers.
     #
-    # > NOTE: if `runBeforeUnload` is passed as true, a `beforeunload` dialog might be summoned and should be handled manually
-    # via [`event: Page.dialog`] event.
+    # **NOTE**: if `runBeforeUnload` is passed as true, a `beforeunload` dialog might be summoned and should be handled
+    # manually via [`event: Page.dialog`] event.
     def close(runBeforeUnload: nil)
       wrap_impl(@impl.close(runBeforeUnload: unwrap_impl(runBeforeUnload)))
     end
 
+    #
     # Gets the full HTML contents of the page, including the doctype.
     def content
       wrap_impl(@impl.content)
     end
 
+    #
     # Get the browser context that the page belongs to.
     def context
       wrap_impl(@impl.context)
     end
 
+    #
     # This method double clicks an element matching `selector` by performing the following steps:
     # 1. Find an element matching `selector`. If there is none, wait until a matching element is attached to the DOM.
-    # 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 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.
     #
-    # 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: `page.dblclick()` dispatches two `click` events and a single `dblclick` event.
-    #
-    # Shortcut for main frame's [`method: Frame.dblclick`].
+    # **NOTE**: `page.dblclick()` dispatches two `click` events and a single `dblclick` event.
     def dblclick(
           selector,
           button: nil,
@@ -214,18 +208,23 @@ module Playwright
       wrap_impl(@impl.dblclick(unwrap_impl(selector), button: unwrap_impl(button), delay: unwrap_impl(delay), force: unwrap_impl(force), modifiers: unwrap_impl(modifiers), noWaitAfter: unwrap_impl(noWaitAfter), position: unwrap_impl(position), strict: unwrap_impl(strict), 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
     # page.dispatch_event("button#submit", "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)
@@ -250,8 +249,12 @@ module Playwright
       wrap_impl(@impl.dispatch_event(unwrap_impl(selector), unwrap_impl(type), eventInit: unwrap_impl(eventInit), strict: unwrap_impl(strict), timeout: unwrap_impl(timeout)))
     end
 
-    # This method drags the source element to the target element. It will first move to the source element, perform a
-    # `mousedown`, then move to the target element and perform a `mouseup`.
+    #
+    # This method drags the source element to the target element.
+    # It will first move to the source element, perform a `mousedown`,
+    # then move to the target element and perform a `mouseup`.
+    #
+    # **Usage**
     #
     # ```python sync
     # page.drag_and_drop("#source", "#target")
@@ -276,8 +279,10 @@ module Playwright
       wrap_impl(@impl.drag_and_drop(unwrap_impl(source), unwrap_impl(target), force: unwrap_impl(force), noWaitAfter: unwrap_impl(noWaitAfter), sourcePosition: unwrap_impl(sourcePosition), strict: unwrap_impl(strict), targetPosition: unwrap_impl(targetPosition), timeout: unwrap_impl(timeout), trial: unwrap_impl(trial)))
     end
 
-    # This method changes the `CSS media type` through the `media` argument, and/or the `'prefers-colors-scheme'` media
-    # feature, using the `colorScheme` argument.
+    #
+    # This method changes the `CSS media type` through the `media` argument, and/or the `'prefers-colors-scheme'` media feature, using the `colorScheme` argument.
+    #
+    # **Usage**
     #
     # ```python sync
     # page.evaluate("matchMedia('screen').matches")
@@ -310,30 +315,25 @@ module Playwright
       wrap_impl(@impl.emulate_media(colorScheme: unwrap_impl(colorScheme), forcedColors: unwrap_impl(forcedColors), media: unwrap_impl(media), reducedMotion: unwrap_impl(reducedMotion)))
     end
 
-    # > NOTE: This method does not wait for the element to pass actionability checks and therefore can lead to the flaky
-    # tests. Use [`method: Locator.evaluate`], other `Locator` helper methods or web-first assertions instead.
     #
     # The method finds an element matching the specified selector within the page and passes it as a first argument to
-    # `expression`. If no elements match the selector, the method throws an error. Returns the value of `expression`.
+    # `expression`. If no elements match the selector, the method throws an error. Returns the value of
+    # `expression`.
     #
     # If `expression` returns a [Promise], then [`method: Page.evalOnSelector`] would wait for the promise to resolve and
     # return its value.
     #
-    # Examples:
+    # **Usage**
     #
     # ```python sync
     # search_value = page.eval_on_selector("#search", "el => el.value")
     # preload_href = page.eval_on_selector("link[rel=preload]", "el => el.href")
     # html = page.eval_on_selector(".main-container", "(e, suffix) => e.outer_html + suffix", "hello")
     # ```
-    #
-    # Shortcut for main frame's [`method: Frame.evalOnSelector`].
     def eval_on_selector(selector, expression, arg: nil, strict: nil)
       wrap_impl(@impl.eval_on_selector(unwrap_impl(selector), unwrap_impl(expression), arg: unwrap_impl(arg), strict: unwrap_impl(strict)))
     end
 
-    # > NOTE: In most cases, [`method: Locator.evaluateAll`], other `Locator` helper methods and web-first assertions do a
-    # better job.
     #
     # The method finds all elements matching the specified selector within the page and passes an array of matched elements as
     # a first argument to `expression`. Returns the result of `expression` invocation.
@@ -341,7 +341,7 @@ module Playwright
     # If `expression` returns a [Promise], then [`method: Page.evalOnSelectorAll`] would wait for the promise to resolve and
     # return its value.
     #
-    # Examples:
+    # **Usage**
     #
     # ```python sync
     # div_counts = page.eval_on_selector_all("div", "(divs, min) => divs.length >= min", 10)
@@ -350,14 +350,17 @@ module Playwright
       wrap_impl(@impl.eval_on_selector_all(unwrap_impl(selector), unwrap_impl(expression), arg: unwrap_impl(arg)))
     end
 
+    #
     # Returns the value of the `expression` invocation.
     #
     # If the function passed to the [`method: Page.evaluate`] returns a [Promise], then [`method: Page.evaluate`] would wait
     # for the promise to resolve and return its value.
     #
     # If the function passed to the [`method: Page.evaluate`] returns a non-[Serializable] value, then
-    # [`method: Page.evaluate`] resolves to `undefined`. Playwright also supports transferring some additional values that are
-    # not serializable by `JSON`: `-0`, `NaN`, `Infinity`, `-Infinity`.
+    # [`method: Page.evaluate`] resolves to `undefined`. Playwright also supports transferring some
+    # additional values that are not serializable by `JSON`: `-0`, `NaN`, `Infinity`, `-Infinity`.
+    #
+    # **Usage**
     #
     # Passing argument to `expression`:
     #
@@ -381,19 +384,19 @@ module Playwright
     # html = page.evaluate("([body, suffix]) => body.innerHTML + suffix", [body_handle, "hello"])
     # body_handle.dispose()
     # ```
-    #
-    # Shortcut for main frame's [`method: Frame.evaluate`].
     def evaluate(expression, arg: nil)
       wrap_impl(@impl.evaluate(unwrap_impl(expression), arg: unwrap_impl(arg)))
     end
 
+    #
     # Returns the value of the `expression` invocation as a `JSHandle`.
     #
-    # The only difference between [`method: Page.evaluate`] and [`method: Page.evaluateHandle`] is that
-    # [`method: Page.evaluateHandle`] returns `JSHandle`.
+    # The only difference between [`method: Page.evaluate`] and [`method: Page.evaluateHandle`] is that [`method: Page.evaluateHandle`] returns `JSHandle`.
+    #
+    # If the function passed to the [`method: Page.evaluateHandle`] returns a [Promise], then [`method: Page.evaluateHandle`] would wait for the
+    # promise to resolve and return its value.
     #
-    # If the function passed to the [`method: Page.evaluateHandle`] returns a [Promise], then [`method: Page.evaluateHandle`]
-    # would wait for the promise to resolve and return its value.
+    # **Usage**
     #
     # ```python sync
     # a_window_handle = page.evaluate_handle("Promise.resolve(window)")
@@ -418,16 +421,19 @@ module Playwright
       wrap_impl(@impl.evaluate_handle(unwrap_impl(expression), arg: unwrap_impl(arg)))
     end
 
-    # The method adds a function called `name` on the `window` object of every frame in this page. When called, the function
-    # executes `callback` and returns a [Promise] which resolves to the return value of `callback`. If the `callback` returns
-    # a [Promise], it will be awaited.
     #
-    # The first argument of the `callback` function contains information about the caller: `{ browserContext: BrowserContext,
-    # page: Page, frame: Frame }`.
+    # The method adds a function called `name` on the `window` object of every frame in this page. When called, the
+    # function executes `callback` and returns a [Promise] which resolves to the return value of `callback`.
+    # If the `callback` returns a [Promise], it will be awaited.
+    #
+    # The first argument of the `callback` function contains information about the caller: `{ browserContext:
+    # BrowserContext, page: Page, frame: Frame }`.
     #
     # See [`method: BrowserContext.exposeBinding`] for the context-wide version.
     #
-    # > NOTE: Functions installed via [`method: Page.exposeBinding`] survive navigations.
+    # **NOTE**: Functions installed via [`method: Page.exposeBinding`] survive navigations.
+    #
+    # **Usage**
     #
     # An example of exposing page URL to all frames in a page:
     #
@@ -474,14 +480,17 @@ module Playwright
       wrap_impl(@impl.expose_binding(unwrap_impl(name), unwrap_impl(callback), handle: unwrap_impl(handle)))
     end
 
-    # The method adds a function called `name` on the `window` object of every frame in the page. When called, the function
-    # executes `callback` and returns a [Promise] which resolves to the return value of `callback`.
+    #
+    # The method adds a function called `name` on the `window` object of every frame in the page. When called, the
+    # function executes `callback` and returns a [Promise] which resolves to the return value of `callback`.
     #
     # If the `callback` returns a [Promise], it will be awaited.
     #
     # See [`method: BrowserContext.exposeFunction`] for context-wide exposed function.
     #
-    # > NOTE: Functions installed via [`method: Page.exposeFunction`] survive navigations.
+    # **NOTE**: Functions installed via [`method: Page.exposeFunction`] survive navigations.
+    #
+    # **Usage**
     #
     # An example of adding a `sha256` function to the page:
     #
@@ -518,18 +527,12 @@ module Playwright
       wrap_impl(@impl.expose_function(unwrap_impl(name), unwrap_impl(callback)))
     end
 
-    # This method waits for an element matching `selector`, 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 an element matching `selector`, 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.
     #
-    # To send fine-grained keyboard events, use [`method: Page.type`].
+    # 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.
     #
-    # Shortcut for main frame's [`method: Frame.fill`].
+    # To send fine-grained keyboard events, use [`method: Page.type`].
     def fill(
           selector,
           value,
@@ -540,16 +543,18 @@ module Playwright
       wrap_impl(@impl.fill(unwrap_impl(selector), unwrap_impl(value), force: unwrap_impl(force), noWaitAfter: unwrap_impl(noWaitAfter), strict: unwrap_impl(strict), timeout: unwrap_impl(timeout)))
     end
 
-    # This method fetches an element with `selector` and focuses it. If there's no element matching `selector`, the method
-    # waits until a matching element appears in the DOM.
     #
-    # Shortcut for main frame's [`method: Frame.focus`].
+    # This method fetches an element with `selector` and focuses it. If there's no element matching
+    # `selector`, the method waits until a matching element appears in the DOM.
     def focus(selector, strict: nil, timeout: nil)
       wrap_impl(@impl.focus(unwrap_impl(selector), strict: unwrap_impl(strict), timeout: unwrap_impl(timeout)))
     end
 
+    #
     # Returns frame matching the specified criteria. Either `name` or `url` must be specified.
     #
+    # **Usage**
+    #
     # ```py
     # frame = page.frame(name="frame-name")
     # ```
@@ -561,9 +566,14 @@ module Playwright
       wrap_impl(@impl.frame(name: unwrap_impl(name), url: unwrap_impl(url)))
     end
 
-    # When working with iframes, you can create a frame locator that will enter the iframe and allow selecting elements in
-    # that iframe. Following snippet locates element with text "Submit" in the iframe with id `my-frame`, like `<iframe
-    # id="my-frame">`:
+    #
+    # When working with iframes, you can create a frame locator that will enter the iframe and allow selecting elements
+    # in that iframe.
+    #
+    # **Usage**
+    #
+    # Following snippet locates element with text "Submit" in the iframe with id `my-frame`,
+    # like `<iframe id="my-frame">`:
     #
     # ```python sync
     # locator = page.frame_locator("#my-iframe").get_by_text("Submit")
@@ -573,16 +583,19 @@ module Playwright
       wrap_impl(@impl.frame_locator(unwrap_impl(selector)))
     end
 
+    #
     # An array of all frames attached to the page.
     def frames
       wrap_impl(@impl.frames)
     end
 
+    #
     # Returns element attribute value.
     def get_attribute(selector, name, strict: nil, timeout: nil)
       wrap_impl(@impl.get_attribute(unwrap_impl(selector), unwrap_impl(name), strict: unwrap_impl(strict), timeout: unwrap_impl(timeout)))
     end
 
+    #
     # Allows locating elements by their alt text. For example, this method will find the image by alt text "Castle":
     #
     # ```html
@@ -592,8 +605,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>
@@ -603,8 +616,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">
@@ -613,15 +626,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,
@@ -636,12 +644,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
@@ -668,17 +677,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
@@ -688,6 +696,7 @@ module Playwright
       wrap_impl(@impl.get_by_title(unwrap_impl(text), exact: unwrap_impl(exact)))
     end
 
+    #
     # Returns the main resource response. In case of multiple redirects, the navigation will resolve with the response of the
     # last redirect. If can not go back, returns `null`.
     #
@@ -696,6 +705,7 @@ module Playwright
       wrap_impl(@impl.go_back(timeout: unwrap_impl(timeout), waitUntil: unwrap_impl(waitUntil)))
     end
 
+    #
     # Returns the main resource response. In case of multiple redirects, the navigation will resolve with the response of the
     # last redirect. If can not go forward, returns `null`.
     #
@@ -704,6 +714,7 @@ module Playwright
       wrap_impl(@impl.go_forward(timeout: unwrap_impl(timeout), waitUntil: unwrap_impl(waitUntil)))
     end
 
+    #
     # Returns the main resource response. In case of multiple redirects, the navigation will resolve with the first
     # non-redirect response.
     #
@@ -718,28 +729,25 @@ module Playwright
     # Found" and 500 "Internal Server Error".  The status code for such responses can be retrieved by calling
     # [`method: Response.status`].
     #
-    # > NOTE: The method either throws an error or returns a main resource response. The only exceptions are navigation to
+    # **NOTE**: The method either throws an error or returns a main resource response. The only exceptions are navigation to
     # `about:blank` or navigation to the same URL with a different hash, which would succeed and return `null`.
-    # > NOTE: Headless mode doesn't support navigation to a PDF document. See the
-    # [upstream issue](https://bugs.chromium.org/p/chromium/issues/detail?id=761295).
     #
-    # Shortcut for main frame's [`method: Frame.goto`]
+    # **NOTE**: Headless mode doesn't support navigation to a PDF document. See the
+    # [upstream issue](https://bugs.chromium.org/p/chromium/issues/detail?id=761295).
     def goto(url, referer: nil, timeout: nil, waitUntil: nil)
       wrap_impl(@impl.goto(unwrap_impl(url), referer: unwrap_impl(referer), timeout: unwrap_impl(timeout), waitUntil: unwrap_impl(waitUntil)))
     end
 
+    #
     # This method hovers over an element matching `selector` by performing the following steps:
     # 1. Find an element matching `selector`. If there is none, wait until a matching element is attached to the DOM.
-    # 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 hover over the center of the element, or the specified `position`.
     # 1. Wait for initiated navigations to either succeed or fail, unless `noWaitAfter` option is set.
     #
-    # When all steps combined have not finished during the specified `timeout`, this method throws a `TimeoutError`. Passing
-    # zero timeout disables this.
-    #
-    # Shortcut for main frame's [`method: Frame.hover`].
+    # When all steps combined have not finished during the specified `timeout`, this method throws a
+    # `TimeoutError`. Passing zero timeout disables this.
     def hover(
           selector,
           force: nil,
@@ -752,110 +760,124 @@ module Playwright
       wrap_impl(@impl.hover(unwrap_impl(selector), force: unwrap_impl(force), modifiers: unwrap_impl(modifiers), noWaitAfter: unwrap_impl(noWaitAfter), position: unwrap_impl(position), strict: unwrap_impl(strict), timeout: unwrap_impl(timeout), trial: unwrap_impl(trial)))
     end
 
+    #
     # Returns `element.innerHTML`.
     def inner_html(selector, strict: nil, timeout: nil)
       wrap_impl(@impl.inner_html(unwrap_impl(selector), strict: unwrap_impl(strict), timeout: unwrap_impl(timeout)))
     end
 
+    #
     # Returns `element.innerText`.
     def inner_text(selector, strict: nil, timeout: nil)
       wrap_impl(@impl.inner_text(unwrap_impl(selector), strict: unwrap_impl(strict), 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(selector, strict: nil, timeout: nil)
       wrap_impl(@impl.input_value(unwrap_impl(selector), strict: unwrap_impl(strict), timeout: unwrap_impl(timeout)))
     end
 
+    #
     # Returns whether the element is checked. Throws if the element is not a checkbox or radio input.
     def checked?(selector, strict: nil, timeout: nil)
       wrap_impl(@impl.checked?(unwrap_impl(selector), strict: unwrap_impl(strict), timeout: unwrap_impl(timeout)))
     end
 
+    #
     # Indicates that the page has been closed.
     def closed?
       wrap_impl(@impl.closed?)
     end
 
+    #
     # Returns whether the element is disabled, the opposite of [enabled](../actionability.md#enabled).
     def disabled?(selector, strict: nil, timeout: nil)
       wrap_impl(@impl.disabled?(unwrap_impl(selector), strict: unwrap_impl(strict), timeout: unwrap_impl(timeout)))
     end
 
+    #
     # Returns whether the element is [editable](../actionability.md#editable).
     def editable?(selector, strict: nil, timeout: nil)
       wrap_impl(@impl.editable?(unwrap_impl(selector), strict: unwrap_impl(strict), timeout: unwrap_impl(timeout)))
     end
 
+    #
     # Returns whether the element is [enabled](../actionability.md#enabled).
     def enabled?(selector, strict: nil, timeout: nil)
       wrap_impl(@impl.enabled?(unwrap_impl(selector), strict: unwrap_impl(strict), timeout: unwrap_impl(timeout)))
     end
 
-    # Returns whether the element is hidden, the opposite of [visible](../actionability.md#visible).  `selector` that does not
-    # match any elements is considered hidden.
+    #
+    # Returns whether the element is hidden, the opposite of [visible](../actionability.md#visible).  `selector` that does not match any elements is considered hidden.
     def hidden?(selector, strict: nil, timeout: nil)
       wrap_impl(@impl.hidden?(unwrap_impl(selector), strict: unwrap_impl(strict), timeout: unwrap_impl(timeout)))
     end
 
-    # Returns whether the element is [visible](../actionability.md#visible). `selector` that does not match any elements is
-    # considered not visible.
+    #
+    # Returns whether the element is [visible](../actionability.md#visible). `selector` that does not match any elements is considered not visible.
     def visible?(selector, strict: nil, timeout: nil)
       wrap_impl(@impl.visible?(unwrap_impl(selector), strict: unwrap_impl(strict), timeout: unwrap_impl(timeout)))
     end
 
-    # 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.
+    #
+    # 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](../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
 
+    #
     # The page's main frame. Page is guaranteed to have a main frame which persists during navigations.
     def main_frame
       wrap_impl(@impl.main_frame)
     end
 
+    #
     # Returns the opener for popup pages and `null` for others. If the opener has been closed already the returns `null`.
     def opener
       wrap_impl(@impl.opener)
     end
 
-    # Pauses script execution. Playwright will stop executing the script and wait for the user to either press 'Resume' button
-    # in the page overlay or to call `playwright.resume()` in the DevTools console.
+    #
+    # Pauses script execution. Playwright will stop executing the script and wait for the user to either press 'Resume'
+    # button in the page overlay or to call `playwright.resume()` in the DevTools console.
     #
     # User can inspect selectors or perform manual steps while paused. Resume will continue running the original script from
     # the place it was paused.
     #
-    # > NOTE: This method requires Playwright to be started in a headed mode, with a falsy `headless` value in the
-    # [`method: BrowserType.launch`].
+    # **NOTE**: This method requires Playwright to be started in a headed mode, with a falsy `headless` value in
+    # the [`method: BrowserType.launch`].
     def pause
       wrap_impl(@impl.pause)
     end
 
+    #
     # Returns the PDF buffer.
     #
-    # > NOTE: Generating a pdf is currently only supported in Chromium headless.
+    # **NOTE**: Generating a pdf is currently only supported in Chromium headless.
     #
     # `page.pdf()` generates a pdf of the page with `print` css media. To generate a pdf with `screen` media, call
     # [`method: Page.emulateMedia`] before calling `page.pdf()`:
     #
-    # > NOTE: By default, `page.pdf()` generates a pdf with modified colors for printing. Use the
+    # **NOTE**: By default, `page.pdf()` generates a pdf with modified colors for printing. Use the
     # [`-webkit-print-color-adjust`](https://developer.mozilla.org/en-US/docs/Web/CSS/-webkit-print-color-adjust) property to
     # force rendering of exact colors.
     #
+    # **Usage**
+    #
     # ```python sync
     # # generates a pdf with "screen" media type.
     # page.emulate_media(media="screen")
     # page.pdf(path="page.pdf")
     # ```
     #
-    # The `width`, `height`, and `margin` options accept values labeled with units. Unlabeled values are treated as pixels.
+    # The `width`, `height`, and `margin` options accept values labeled with units. Unlabeled
+    # values are treated as pixels.
     #
     # A few examples:
     # - `page.pdf({width: 100})` - prints with width set to 100 pixels
@@ -881,8 +903,8 @@ module Playwright
     # - `A5`: 5.83in x 8.27in
     # - `A6`: 4.13in x 5.83in
     #
-    # > NOTE: `headerTemplate` and `footerTemplate` markup have the following limitations: > 1. Script tags inside templates
-    # are not evaluated. > 2. Page styles are not visible inside templates.
+    # **NOTE**: `headerTemplate` and `footerTemplate` markup have the following limitations: > 1. Script tags inside
+    # templates are not evaluated. > 2. Page styles are not visible inside templates.
     def pdf(
           displayHeaderFooter: nil,
           footerTemplate: nil,
@@ -900,10 +922,12 @@ module Playwright
       wrap_impl(@impl.pdf(displayHeaderFooter: unwrap_impl(displayHeaderFooter), footerTemplate: unwrap_impl(footerTemplate), format: unwrap_impl(format), headerTemplate: unwrap_impl(headerTemplate), height: unwrap_impl(height), landscape: unwrap_impl(landscape), margin: unwrap_impl(margin), pageRanges: unwrap_impl(pageRanges), path: unwrap_impl(path), preferCSSPageSize: unwrap_impl(preferCSSPageSize), printBackground: unwrap_impl(printBackground), scale: unwrap_impl(scale), width: unwrap_impl(width)))
     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`,
@@ -913,12 +937,14 @@ 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.
     #
+    # **Usage**
+    #
     # ```python sync
     # page = browser.new_page()
     # page.goto("https://keycode.info")
@@ -940,40 +966,38 @@ module Playwright
       wrap_impl(@impl.press(unwrap_impl(selector), unwrap_impl(key), delay: unwrap_impl(delay), noWaitAfter: unwrap_impl(noWaitAfter), strict: unwrap_impl(strict), timeout: unwrap_impl(timeout)))
     end
 
-    # > NOTE: The use of `ElementHandle` is discouraged, use `Locator` objects and web-first assertions instead.
     #
     # The method finds an element matching the specified selector within the page. If no elements match the selector, the
     # return value resolves to `null`. To wait for an element on the page, use [`method: Locator.waitFor`].
-    #
-    # Shortcut for main frame's [`method: Frame.querySelector`].
     def query_selector(selector, strict: nil)
       wrap_impl(@impl.query_selector(unwrap_impl(selector), strict: unwrap_impl(strict)))
     end
 
-    # > NOTE: The use of `ElementHandle` is discouraged, use `Locator` objects and web-first assertions instead.
     #
     # The method finds all elements matching the specified selector within the page. If no elements match the selector, the
     # return value resolves to `[]`.
-    #
-    # Shortcut for main frame's [`method: Frame.querySelectorAll`].
     def query_selector_all(selector)
       wrap_impl(@impl.query_selector_all(unwrap_impl(selector)))
     end
 
-    # This method reloads the current page, in the same way as if the user had triggered a browser refresh. Returns the main
-    # resource response. In case of multiple redirects, the navigation will resolve with the response of the last redirect.
+    #
+    # This method reloads the current page, in the same way as if the user had triggered a browser refresh.
+    # Returns the main resource response. In case of multiple redirects, the navigation will resolve with the response of the
+    # last redirect.
     def reload(timeout: nil, waitUntil: nil)
       wrap_impl(@impl.reload(timeout: unwrap_impl(timeout), waitUntil: unwrap_impl(waitUntil)))
     end
 
+    #
     # Routing provides the capability to modify network requests that are made by a page.
     #
     # Once routing is enabled, every request matching the url pattern will stall unless it's continued, fulfilled or aborted.
     #
-    # > NOTE: The handler will only be called for the first url if the response is a redirect.
-    # > NOTE: [`method: Page.route`] will not intercept requests intercepted by Service Worker. See
-    # [this](https://github.com/microsoft/playwright/issues/1090) issue. We recommend disabling Service Workers when using
-    # request interception by setting `Browser.newContext.serviceWorkers` to `'block'`.
+    # **NOTE**: The handler will only be called for the first url if the response is a redirect.
+    #
+    # **NOTE**: [`method: Page.route`] will not intercept requests intercepted by Service Worker. See [this](https://github.com/microsoft/playwright/issues/1090) issue. We recommend disabling Service Workers when using request interception by setting `Browser.newContext.serviceWorkers` to `'block'`.
+    #
+    # **Usage**
     #
     # An example of a naive handler that aborts all image requests:
     #
@@ -993,8 +1017,7 @@ module Playwright
     # browser.close()
     # ```
     #
-    # It is possible to examine the request to decide the route action. For example, mocking all requests that contain some
-    # post data, and leaving all other requests as is:
+    # It is possible to examine the request to decide the route action. For example, mocking all requests that contain some post data, and leaving all other requests as is:
     #
     # ```python sync
     # def handle_route(route):
@@ -1010,21 +1033,20 @@ module Playwright
     #
     # To remove a route with its handler you can use [`method: Page.unroute`].
     #
-    # > NOTE: Enabling routing disables http cache.
+    # **NOTE**: Enabling routing disables http cache.
     def route(url, handler, times: nil)
       wrap_impl(@impl.route(unwrap_impl(url), unwrap_impl(handler), times: unwrap_impl(times)))
     end
 
-    # If specified the network requests that are made in the page will be served from the HAR file. Read more about
-    # [Replaying from HAR](../network.md#replaying-from-har).
     #
-    # Playwright will not serve requests intercepted by Service Worker from the HAR file. See
-    # [this](https://github.com/microsoft/playwright/issues/1090) issue. We recommend disabling Service Workers when using
-    # request interception by setting `Browser.newContext.serviceWorkers` to `'block'`.
+    # If specified the network requests that are made in the page will be served from the HAR file. Read more about [Replaying from HAR](../network.md#replaying-from-har).
+    #
+    # Playwright will not serve requests intercepted by Service Worker from the HAR file. See [this](https://github.com/microsoft/playwright/issues/1090) issue. We recommend disabling Service Workers when using request interception by setting `Browser.newContext.serviceWorkers` to `'block'`.
     def route_from_har(har, notFound: nil, update: nil, url: nil)
       wrap_impl(@impl.route_from_har(unwrap_impl(har), notFound: unwrap_impl(notFound), update: unwrap_impl(update), url: unwrap_impl(url)))
     end
 
+    #
     # Returns the buffer with the captured screenshot.
     def screenshot(
           animations: nil,
@@ -1041,17 +1063,17 @@ module Playwright
       wrap_impl(@impl.screenshot(animations: unwrap_impl(animations), caret: unwrap_impl(caret), clip: unwrap_impl(clip), fullPage: unwrap_impl(fullPage), 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 an element matching `selector`, 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.
+    # This method waits for an element matching `selector`, 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**
+    #
     # ```python sync
     # # single selection matching the value
     # page.select_option("select#colors", "blue")
@@ -1060,8 +1082,6 @@ module Playwright
     # # multiple selection
     # page.select_option("select#colors", value=["red", "green", "blue"])
     # ```
-    #
-    # Shortcut for main frame's [`method: Frame.selectOption`].
     def select_option(
           selector,
           element: nil,
@@ -1075,21 +1095,19 @@ module Playwright
       wrap_impl(@impl.select_option(unwrap_impl(selector), element: unwrap_impl(element), index: unwrap_impl(index), value: unwrap_impl(value), label: unwrap_impl(label), force: unwrap_impl(force), noWaitAfter: unwrap_impl(noWaitAfter), strict: unwrap_impl(strict), timeout: unwrap_impl(timeout)))
     end
 
+    #
     # This method checks or unchecks an element matching `selector` by performing the following steps:
     # 1. Find an element matching `selector`. If there is none, wait until a matching element is attached to the DOM.
     # 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.
-    #
-    # Shortcut for main frame's [`method: Frame.setChecked`].
+    # When all steps combined have not finished during the specified `timeout`, this method throws a
+    # `TimeoutError`. Passing zero timeout disables this.
     def set_checked(
           selector,
           checked,
@@ -1107,6 +1125,7 @@ module Playwright
     end
     alias_method :content=, :set_content
 
+    #
     # This setting will change the default maximum navigation time for the following methods and related shortcuts:
     # - [`method: Page.goBack`]
     # - [`method: Page.goForward`]
@@ -1116,36 +1135,37 @@ module Playwright
     # - [`method: Page.waitForNavigation`]
     # - [`method: Page.waitForURL`]
     #
-    # > NOTE: [`method: Page.setDefaultNavigationTimeout`] takes priority over [`method: Page.setDefaultTimeout`],
+    # **NOTE**: [`method: Page.setDefaultNavigationTimeout`] takes priority over [`method: Page.setDefaultTimeout`],
     # [`method: BrowserContext.setDefaultTimeout`] and [`method: BrowserContext.setDefaultNavigationTimeout`].
     def set_default_navigation_timeout(timeout)
       wrap_impl(@impl.set_default_navigation_timeout(unwrap_impl(timeout)))
     end
     alias_method :default_navigation_timeout=, :set_default_navigation_timeout
 
+    #
     # This setting will change the default maximum time for all the methods accepting `timeout` option.
     #
-    # > NOTE: [`method: Page.setDefaultNavigationTimeout`] takes priority over [`method: Page.setDefaultTimeout`].
+    # **NOTE**: [`method: Page.setDefaultNavigationTimeout`] takes priority over [`method: Page.setDefaultTimeout`].
     def set_default_timeout(timeout)
       wrap_impl(@impl.set_default_timeout(unwrap_impl(timeout)))
     end
     alias_method :default_timeout=, :set_default_timeout
 
+    #
     # The extra HTTP headers will be sent with every request the page initiates.
     #
-    # > NOTE: [`method: Page.setExtraHTTPHeaders`] does not guarantee the order of headers in the outgoing requests.
+    # **NOTE**: [`method: Page.setExtraHTTPHeaders`] does not guarantee the order of headers in the outgoing requests.
     def set_extra_http_headers(headers)
       wrap_impl(@impl.set_extra_http_headers(unwrap_impl(headers)))
     end
     alias_method :extra_http_headers=, :set_extra_http_headers
 
+    #
     # 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 `selector` to point to an
-    # [input element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input). However, if the element is inside the
-    # `<label>` element that has an associated
-    # [control](https://developer.mozilla.org/en-US/docs/Web/API/HTMLLabelElement/control), targets the control instead.
+    # [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(
           selector,
           files,
@@ -1155,13 +1175,14 @@ module Playwright
       wrap_impl(@impl.set_input_files(unwrap_impl(selector), unwrap_impl(files), noWaitAfter: unwrap_impl(noWaitAfter), strict: unwrap_impl(strict), timeout: unwrap_impl(timeout)))
     end
 
+    #
     # In the case of multiple pages in a single browser, each page can have its own viewport size. However,
     # [`method: Browser.newContext`] allows to set viewport size (and more) for all pages in the context at once.
     #
-    # [`method: Page.setViewportSize`] will resize the page. A lot of websites don't expect phones to change size, so you
-    # should set the viewport size before navigating to the page. [`method: Page.setViewportSize`] will also reset `screen`
-    # size, use [`method: Browser.newContext`] with `screen` and `viewport` parameters if you need better control of these
-    # properties.
+    # [`method: Page.setViewportSize`] will resize the page. A lot of websites don't expect phones to change size, so you should set the
+    # viewport size before navigating to the page. [`method: Page.setViewportSize`] will also reset `screen` size, use [`method: Browser.newContext`] with `screen` and `viewport` parameters if you need better control of these properties.
+    #
+    # **Usage**
     #
     # ```python sync
     # page = browser.new_page()
@@ -1173,20 +1194,18 @@ module Playwright
     end
     alias_method :viewport_size=, :set_viewport_size
 
+    #
     # This method taps an element matching `selector` by performing the following steps:
     # 1. Find an element matching `selector`. If there is none, wait until a matching element is attached to the DOM.
-    # 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.touchscreen`] to tap the center of the element, or the specified `position`.
     # 1. Wait for initiated navigations to either succeed or fail, unless `noWaitAfter` option is set.
     #
-    # 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: [`method: Page.tap`] requires that the `hasTouch` option of the browser context be set to true.
-    #
-    # Shortcut for main frame's [`method: Frame.tap`].
+    # **NOTE**: [`method: Page.tap`] requires that the `hasTouch` option of the browser context be set to true.
     def tap_point(
           selector,
           force: nil,
@@ -1199,27 +1218,30 @@ module Playwright
       wrap_impl(@impl.tap_point(unwrap_impl(selector), force: unwrap_impl(force), modifiers: unwrap_impl(modifiers), noWaitAfter: unwrap_impl(noWaitAfter), position: unwrap_impl(position), strict: unwrap_impl(strict), timeout: unwrap_impl(timeout), trial: unwrap_impl(trial)))
     end
 
+    #
     # Returns `element.textContent`.
     def text_content(selector, strict: nil, timeout: nil)
       wrap_impl(@impl.text_content(unwrap_impl(selector), strict: unwrap_impl(strict), timeout: unwrap_impl(timeout)))
     end
 
-    # Returns the page's title. Shortcut for main frame's [`method: Frame.title`].
+    #
+    # Returns the page's title.
     def title
       wrap_impl(@impl.title)
     end
 
+    #
     # Sends a `keydown`, `keypress`/`input`, and `keyup` event for each character in the text. `page.type` can be used to send
     # fine-grained keyboard events. To fill values in form fields, use [`method: Page.fill`].
     #
     # To press a special key, like `Control` or `ArrowDown`, use [`method: Keyboard.press`].
     #
+    # **Usage**
+    #
     # ```python sync
     # page.type("#mytextarea", "hello") # types instantly
     # page.type("#mytextarea", "world", delay=100) # types slower, like a user
     # ```
-    #
-    # Shortcut for main frame's [`method: Frame.type`].
     def type(
           selector,
           text,
@@ -1230,21 +1252,18 @@ module Playwright
       wrap_impl(@impl.type(unwrap_impl(selector), unwrap_impl(text), delay: unwrap_impl(delay), noWaitAfter: unwrap_impl(noWaitAfter), strict: unwrap_impl(strict), timeout: unwrap_impl(timeout)))
     end
 
+    #
     # This method unchecks an element matching `selector` by performing the following steps:
     # 1. Find an element matching `selector`. If there is none, wait until a matching element is attached to the DOM.
-    # 1. Ensure that matched 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 matched element, unless `force` option is set. If the
-    #    element is detached during the checks, the whole action is retried.
+    # 1. Ensure that matched 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 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 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.
-    #
-    # Shortcut for main frame's [`method: Frame.uncheck`].
+    # When all steps combined have not finished during the specified `timeout`, this method throws a
+    # `TimeoutError`. Passing zero timeout disables this.
     def uncheck(
           selector,
           force: nil,
@@ -1256,16 +1275,18 @@ module Playwright
       wrap_impl(@impl.uncheck(unwrap_impl(selector), force: unwrap_impl(force), noWaitAfter: unwrap_impl(noWaitAfter), position: unwrap_impl(position), strict: unwrap_impl(strict), timeout: unwrap_impl(timeout), trial: unwrap_impl(trial)))
     end
 
-    # Removes a route created with [`method: Page.route`]. When `handler` is not specified, removes all routes for the `url`.
+    #
+    # Removes a route created with [`method: Page.route`]. When `handler` is not specified, removes all routes for
+    # the `url`.
     def unroute(url, handler: nil)
       wrap_impl(@impl.unroute(unwrap_impl(url), handler: unwrap_impl(handler)))
     end
 
-    # Shortcut for main frame's [`method: Frame.url`].
     def url
       wrap_impl(@impl.url)
     end
 
+    #
     # Video object associated with this page.
     def video
       wrap_impl(@impl.video)
@@ -1275,23 +1296,28 @@ module Playwright
       wrap_impl(@impl.viewport_size)
     end
 
+    #
     # Performs action and waits for a `ConsoleMessage` to be logged by in the page. If predicate is provided, it passes
-    # `ConsoleMessage` value into the `predicate` function and waits for `predicate(message)` to return a truthy value. Will
-    # throw an error if the page is closed before the [`event: Page.console`] event is fired.
+    # `ConsoleMessage` value into the `predicate` function and waits for `predicate(message)` to return a truthy value.
+    # Will throw an error if the page is closed before the [`event: Page.console`] event is fired.
     def expect_console_message(predicate: nil, timeout: nil, &block)
       wrap_impl(@impl.expect_console_message(predicate: unwrap_impl(predicate), timeout: unwrap_impl(timeout), &wrap_block_call(block)))
     end
 
-    # Performs action and waits for a new `Download`. If predicate is provided, it passes `Download` value into the
-    # `predicate` function and waits for `predicate(download)` to return a truthy value. Will throw an error if the page is
-    # closed before the download event is fired.
+    #
+    # Performs action and waits for a new `Download`. If predicate is provided, it passes
+    # `Download` value into the `predicate` function and waits for `predicate(download)` to return a truthy value.
+    # Will throw an error if the page is closed before the download event is fired.
     def expect_download(predicate: nil, timeout: nil, &block)
       wrap_impl(@impl.expect_download(predicate: unwrap_impl(predicate), timeout: unwrap_impl(timeout), &wrap_block_call(block)))
     end
 
+    #
     # Waits for event to fire and passes its value into the predicate function. Returns when the predicate returns truthy
     # value. Will throw an error if the page is closed before the event is fired. Returns the event data value.
     #
+    # **Usage**
+    #
     # ```python sync
     # with page.expect_event("framenavigated") as event_info:
     #     page.get_by_role("button")
@@ -1301,15 +1327,19 @@ module Playwright
       wrap_impl(@impl.expect_event(unwrap_impl(event), predicate: unwrap_impl(predicate), timeout: unwrap_impl(timeout), &wrap_block_call(block)))
     end
 
-    # Performs action and waits for a new `FileChooser` to be created. If predicate is provided, it passes `FileChooser` value
-    # into the `predicate` function and waits for `predicate(fileChooser)` to return a truthy value. Will throw an error if
-    # the page is closed before the file chooser is opened.
+    #
+    # Performs action and waits for a new `FileChooser` to be created. If predicate is provided, it passes
+    # `FileChooser` value into the `predicate` function and waits for `predicate(fileChooser)` to return a truthy value.
+    # Will throw an error if the page is closed before the file chooser is opened.
     def expect_file_chooser(predicate: nil, timeout: nil, &block)
       wrap_impl(@impl.expect_file_chooser(predicate: unwrap_impl(predicate), timeout: unwrap_impl(timeout), &wrap_block_call(block)))
     end
 
+    #
     # Returns when the `expression` returns a truthy value. It resolves to a JSHandle of the truthy value.
     #
+    # **Usage**
+    #
     # The [`method: Page.waitForFunction`] can be used to observe viewport size change:
     #
     # ```python sync
@@ -1333,17 +1363,18 @@ module Playwright
     # selector = ".foo"
     # page.wait_for_function("selector => !!document.querySelector(selector)", selector)
     # ```
-    #
-    # Shortcut for main frame's [`method: Frame.waitForFunction`].
     def wait_for_function(expression, arg: nil, polling: nil, timeout: nil)
       wrap_impl(@impl.wait_for_function(unwrap_impl(expression), arg: unwrap_impl(arg), polling: unwrap_impl(polling), timeout: unwrap_impl(timeout)))
     end
 
+    #
     # Returns when the required load state has been reached.
     #
     # This resolves when the page reaches a required load state, `load` by default. The navigation must have been committed
     # when this method is called. If current document has already reached the required state, resolves immediately.
     #
+    # **Usage**
+    #
     # ```python sync
     # page.get_by_role("button").click() # click triggers navigation.
     # page.wait_for_load_state() # the promise resolves after "load" event.
@@ -1353,19 +1384,20 @@ module Playwright
     # with page.expect_popup() as page_info:
     #     page.get_by_role("button").click() # click triggers a popup.
     # popup = page_info.value
-    #  # Following resolves after "domcontentloaded" event.
+    # # Wait for the "DOMContentLoaded" event.
     # popup.wait_for_load_state("domcontentloaded")
     # print(popup.title()) # popup is ready to use.
     # ```
-    #
-    # Shortcut for main frame's [`method: Frame.waitForLoadState`].
     def wait_for_load_state(state: nil, timeout: nil)
       wrap_impl(@impl.wait_for_load_state(state: unwrap_impl(state), timeout: unwrap_impl(timeout)))
     end
 
-    # Waits for the main frame navigation and returns the main resource response. In case of multiple redirects, the
-    # navigation will resolve with the response of the last redirect. In case of navigation to a different anchor or
-    # navigation due to History API usage, the navigation will resolve with `null`.
+    #
+    # Waits for the main frame navigation and returns the main resource response. In case of multiple redirects, the navigation
+    # will resolve with the response of the last redirect. In case of navigation to a different anchor or navigation due to
+    # History API usage, the navigation will resolve with `null`.
+    #
+    # **Usage**
     #
     # This resolves when the page navigates to a new URL or reloads. It is useful for when you run code which will indirectly
     # cause the page to navigate. e.g. The click target has an `onclick` handler that triggers navigation from a `setTimeout`.
@@ -1373,60 +1405,66 @@ module Playwright
     #
     # ```python sync
     # with page.expect_navigation():
-    #     page.click("a.delayed-navigation") # clicking the link will indirectly cause a navigation
+    #     # This action triggers the navigation after a timeout.
+    #     page.get_by_text("Navigate after timeout").click()
     # # Resolves after navigation has finished
     # ```
     #
-    # > NOTE: Usage of the [History API](https://developer.mozilla.org/en-US/docs/Web/API/History_API) to change the URL is
-    # considered a navigation.
-    #
-    # Shortcut for main frame's [`method: Frame.waitForNavigation`].
+    # **NOTE**: Usage of the [History API](https://developer.mozilla.org/en-US/docs/Web/API/History_API) to change the URL is considered
+    # a navigation.
     def expect_navigation(timeout: nil, url: nil, waitUntil: nil, &block)
       wrap_impl(@impl.expect_navigation(timeout: unwrap_impl(timeout), url: unwrap_impl(url), waitUntil: unwrap_impl(waitUntil), &wrap_block_call(block)))
     end
 
-    # Performs action and waits for a popup `Page`. If predicate is provided, it passes [Popup] value into the `predicate`
-    # function and waits for `predicate(page)` to return a truthy value. Will throw an error if the page is closed before the
-    # popup event is fired.
+    #
+    # Performs action and waits for a popup `Page`. If predicate is provided, it passes
+    # [Popup] value into the `predicate` function and waits for `predicate(page)` to return a truthy value.
+    # Will throw an error if the page is closed before the popup event is fired.
     def expect_popup(predicate: nil, timeout: nil, &block)
       wrap_impl(@impl.expect_popup(predicate: unwrap_impl(predicate), timeout: unwrap_impl(timeout), &wrap_block_call(block)))
     end
 
-    # Waits for the matching request and returns it. See [waiting for event](../events.md#waiting-for-event) for more details
-    # about events.
+    #
+    # Waits for the matching request and returns it. See [waiting for event](../events.md#waiting-for-event) for more details about events.
+    #
+    # **Usage**
     #
     # ```python sync
     # with page.expect_request("http://example.com/resource") as first:
-    #     page.click('button')
+    #     page.get_by_text("trigger request").click()
     # first_request = first.value
     #
     # # or with a lambda
     # with page.expect_request(lambda request: request.url == "http://example.com" and request.method == "get") as second:
-    #     page.click('img')
+    #     page.get_by_text("trigger request").click()
     # second_request = second.value
     # ```
     def expect_request(urlOrPredicate, timeout: nil, &block)
       wrap_impl(@impl.expect_request(unwrap_impl(urlOrPredicate), timeout: unwrap_impl(timeout), &wrap_block_call(block)))
     end
 
-    # Performs action and waits for a `Request` to finish loading. If predicate is provided, it passes `Request` value into
-    # the `predicate` function and waits for `predicate(request)` to return a truthy value. Will throw an error if the page is
-    # closed before the [`event: Page.requestFinished`] event is fired.
+    #
+    # Performs action and waits for a `Request` to finish loading. If predicate is provided, it passes
+    # `Request` value into the `predicate` function and waits for `predicate(request)` to return a truthy value.
+    # Will throw an error if the page is closed before the [`event: Page.requestFinished`] event is fired.
     def expect_request_finished(predicate: nil, timeout: nil, &block)
       wrap_impl(@impl.expect_request_finished(predicate: unwrap_impl(predicate), timeout: unwrap_impl(timeout), &wrap_block_call(block)))
     end
 
+    #
     # Returns the matched response. See [waiting for event](../events.md#waiting-for-event) for more details about events.
     #
+    # **Usage**
+    #
     # ```python sync
     # with page.expect_response("https://example.com/resource") as response_info:
-    #     page.click("input")
+    #     page.get_by_text("trigger response").click()
     # response = response_info.value
     # return response.ok
     #
     # # or with a lambda
     # with page.expect_response(lambda response: response.url == "https://example.com" and response.status == 200) as response_info:
-    #     page.click("input")
+    #     page.get_by_text("trigger response").click()
     # response = response_info.value
     # return response.ok
     # ```
@@ -1434,15 +1472,19 @@ module Playwright
       wrap_impl(@impl.expect_response(unwrap_impl(urlOrPredicate), timeout: unwrap_impl(timeout), &wrap_block_call(block)))
     end
 
+    #
     # Returns when element specified by selector satisfies `state` option. Returns `null` if waiting for `hidden` or
     # `detached`.
     #
-    # > NOTE: Playwright automatically waits for element to be ready before performing an action. Using `Locator` objects and
-    # web-first assertions makes the code wait-for-selector-free.
+    # **NOTE**: Playwright automatically waits for element to be ready before performing an action. Using
+    # `Locator` objects and web-first assertions makes the code wait-for-selector-free.
+    #
+    # Wait for the `selector` to satisfy `state` option (either appear/disappear from dom, or become
+    # visible/hidden). If at the moment of calling the method `selector` already satisfies the condition, the method
+    # will return immediately. If the selector doesn't satisfy the condition for the `timeout` milliseconds, the
+    # function will throw.
     #
-    # Wait for the `selector` to satisfy `state` option (either appear/disappear from dom, or become visible/hidden). If at
-    # the moment of calling the method `selector` already satisfies the condition, the method will return immediately. If the
-    # selector doesn't satisfy the condition for the `timeout` milliseconds, the function will throw.
+    # **Usage**
     #
     # This method works across navigations:
     #
@@ -1466,60 +1508,66 @@ module Playwright
       wrap_impl(@impl.wait_for_selector(unwrap_impl(selector), state: unwrap_impl(state), strict: unwrap_impl(strict), timeout: unwrap_impl(timeout)))
     end
 
+    #
     # Waits for the given `timeout` in milliseconds.
     #
     # Note that `page.waitForTimeout()` should only be used for debugging. Tests using the timer in production are going to be
     # flaky. Use signals such as network events, selectors becoming visible and others instead.
     #
+    # **Usage**
+    #
     # ```python sync
     # # wait for 1 second
     # page.wait_for_timeout(1000)
     # ```
-    #
-    # Shortcut for main frame's [`method: Frame.waitForTimeout`].
     def wait_for_timeout(timeout)
       wrap_impl(@impl.wait_for_timeout(unwrap_impl(timeout)))
     end
 
+    #
     # Waits for the main frame to navigate to the given URL.
     #
+    # **Usage**
+    #
     # ```python sync
     # page.click("a.delayed-navigation") # clicking the link will indirectly cause a navigation
     # page.wait_for_url("**/target.html")
     # ```
-    #
-    # Shortcut for main frame's [`method: Frame.waitForURL`].
     def wait_for_url(url, timeout: nil, waitUntil: nil)
       wrap_impl(@impl.wait_for_url(unwrap_impl(url), timeout: unwrap_impl(timeout), waitUntil: unwrap_impl(waitUntil)))
     end
 
-    # Performs action and waits for a new `WebSocket`. If predicate is provided, it passes `WebSocket` value into the
-    # `predicate` function and waits for `predicate(webSocket)` to return a truthy value. Will throw an error if the page is
-    # closed before the WebSocket event is fired.
+    #
+    # Performs action and waits for a new `WebSocket`. If predicate is provided, it passes
+    # `WebSocket` value into the `predicate` function and waits for `predicate(webSocket)` to return a truthy value.
+    # Will throw an error if the page is closed before the WebSocket event is fired.
     def expect_websocket(predicate: nil, timeout: nil, &block)
       wrap_impl(@impl.expect_websocket(predicate: unwrap_impl(predicate), timeout: unwrap_impl(timeout), &wrap_block_call(block)))
     end
 
-    # Performs action and waits for a new `Worker`. If predicate is provided, it passes `Worker` value into the `predicate`
-    # function and waits for `predicate(worker)` to return a truthy value. Will throw an error if the page is closed before
-    # the worker event is fired.
+    #
+    # Performs action and waits for a new `Worker`. If predicate is provided, it passes
+    # `Worker` value into the `predicate` function and waits for `predicate(worker)` to return a truthy value.
+    # Will throw an error if the page is closed before the worker event is fired.
     def expect_worker(predicate: nil, timeout: nil, &block)
       wrap_impl(@impl.expect_worker(predicate: unwrap_impl(predicate), timeout: unwrap_impl(timeout), &wrap_block_call(block)))
     end
 
+    #
     # This method returns all of the dedicated [WebWorkers](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API)
     # associated with the page.
     #
-    # > NOTE: This does not contain ServiceWorkers
+    # **NOTE**: This does not contain ServiceWorkers
     def workers
       wrap_impl(@impl.workers)
     end
 
-    # > NOTE: In most cases, you should use [`method: Page.waitForEvent`].
     #
-    # Waits for given `event` to fire. If predicate is provided, it passes event's value into the `predicate` function and
-    # waits for `predicate(event)` to return a truthy value. Will throw an error if the page is closed before the `event` is
-    # fired.
+    # **NOTE**: In most cases, you should use [`method: Page.waitForEvent`].
+    #
+    # Waits for given `event` to fire. If predicate is provided, it passes
+    # event's value into the `predicate` function and waits for `predicate(event)` to return a truthy value.
+    # Will throw an error if the page is closed before the `event` is fired.
     def wait_for_event(event, predicate: nil, timeout: nil)
       raise NotImplementedError.new('wait_for_event is not implemented yet.')
     end