playwright-ruby-client 1.29.1 → 1.30.beta1

data/lib/playwright_api/locator.rb

@@ -22,12 +22,24 @@ module Playwright
 
     #
     # Returns an array of `node.innerText` values for all matching nodes.
+    #
+    # **Usage**
+    #
+    # ```python sync
+    # texts = page.get_by_role("link").all_inner_texts()
+    # ```
     def all_inner_texts
       wrap_impl(@impl.all_inner_texts)
     end
 
     #
     # Returns an array of `node.textContent` values for all matching nodes.
+    #
+    # **Usage**
+    #
+    # ```python sync
+    # texts = page.get_by_role("link").all_text_contents()
+    # ```
     def all_text_contents
       wrap_impl(@impl.all_text_contents)
     end
@@ -39,9 +51,11 @@ module Playwright
     end
 
     #
-    # This method returns the bounding box of the element, or `null` if the element is not visible. The bounding box is
+    # This method returns the bounding box of the element matching the locator, 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.
     #
+    # **Details**
+    #
     # Scrolling affects the returned bounding box, similarly to
     # [Element.getBoundingClientRect](https://developer.mozilla.org/en-US/docs/Web/API/Element/getBoundingClientRect). That
     # means `x` and/or `y` may be negative.
@@ -55,7 +69,7 @@ module Playwright
     # **Usage**
     #
     # ```python sync
-    # box = element.bounding_box()
+    # box = page.get_by_role("button").bounding_box()
     # page.mouse.click(box["x"] + box["width"] / 2, box["y"] + box["height"] / 2)
     # ```
     def bounding_box(timeout: nil)
@@ -63,7 +77,11 @@ module Playwright
     end
 
     #
-    # This method checks the element by performing the following steps:
+    # Ensure that checkbox or radio element is checked.
+    #
+    # **Details**
+    #
+    # Performs 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. Wait for [actionability](../actionability.md) checks on the element, unless `force` option is set.
     # 1. Scroll the element into view if needed.
@@ -75,6 +93,12 @@ module Playwright
     #
     # When all steps combined have not finished during the specified `timeout`, this method throws a
     # `TimeoutError`. Passing zero timeout disables this.
+    #
+    # **Usage**
+    #
+    # ```python sync
+    # page.get_by_role("checkbox").check()
+    # ```
     def check(
           force: nil,
           noWaitAfter: nil,
@@ -84,10 +108,20 @@ 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
 
+    #
+    # Clear the input field.
+    #
+    # **Details**
     #
     # 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.
+    #
+    # **Usage**
+    #
+    # ```python sync
+    # page.get_by_role("textbox").clear()
+    # ```
     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
@@ -107,6 +141,22 @@ module Playwright
     #
     # When all steps combined have not finished during the specified `timeout`, this method throws a
     # `TimeoutError`. Passing zero timeout disables this.
+    #
+    # **Usage**
+    #
+    # Click a button:
+    #
+    # ```python sync
+    # page.get_by_role("button").click()
+    # ```
+    #
+    # Shift-right-click at a specific position on a canvas:
+    #
+    # ```python sync
+    # page.locator("canvas").click(
+    #     button="right", modifiers=["Shift"], position={"x": 23, "y": 32}
+    # )
+    # ```
     def click(
           button: nil,
           clickCount: nil,
@@ -121,11 +171,21 @@ module Playwright
     end
 
     #
-    # Returns the number of elements matching given selector.
+    # Returns the number of elements matching the locator.
+    #
+    # **Usage**
+    #
+    # ```python sync
+    # count = page.get_by_role("listitem").count()
+    # ```
     def count
       wrap_impl(@impl.count)
     end
 
+    #
+    # Double-click an element.
+    #
+    # **Details**
     #
     # 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.
@@ -152,16 +212,20 @@ module Playwright
     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
-    # [element.click()](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/click).
+    # Programmaticaly dispatch an event on the matching element.
     #
     # **Usage**
     #
     # ```python sync
-    # element.dispatch_event("click")
+    # locator.dispatch_event("click")
     # ```
     #
+    # **Details**
+    #
+    # The snippet above 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).
+    #
     # 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.
@@ -181,12 +245,16 @@ module Playwright
     # ```python sync
     # # note you can only create data_transfer in chromium and firefox
     # data_transfer = page.evaluate_handle("new DataTransfer()")
-    # element.dispatch_event("#source", "dragstart", {"dataTransfer": data_transfer})
+    # locator.dispatch_event("#source", "dragstart", {"dataTransfer": data_transfer})
     # ```
     def dispatch_event(type, eventInit: nil, timeout: nil)
       wrap_impl(@impl.dispatch_event(unwrap_impl(type), eventInit: unwrap_impl(eventInit), timeout: unwrap_impl(timeout)))
     end
 
+    #
+    # Drag the source element towards the target element and drop it.
+    #
+    # **Details**
     #
     # 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
@@ -218,24 +286,27 @@ module Playwright
     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 there are no matching elements, waits for one. If multiple elements match the locator, throws.
     def element_handle(timeout: nil)
       wrap_impl(@impl.element_handle(timeout: unwrap_impl(timeout)))
     end
 
     #
-    # Resolves given locator to all matching DOM elements.
+    # Resolves given locator to all matching DOM elements. If there are no matching elements, returns an empty list.
     def element_handles
       wrap_impl(@impl.element_handles)
     end
 
     #
-    # Returns the return value of `expression`.
+    # Execute JavaScript code in the page, taking the matching element as an argument.
+    #
+    # **Details**
     #
-    # This method passes this handle as the first argument to `expression`.
+    # Returns the return value of `expression`, called with the matching element as a first argument, and `arg` as a second argument.
     #
-    # If `expression` returns a [Promise], then `handle.evaluate` would wait for the promise to resolve and return
-    # its value.
+    # If `expression` returns a [Promise], this method will wait for the promise to resolve and return its value.
+    #
+    # If `expression` throws or rejects, this method throws.
     #
     # **Usage**
     #
@@ -248,37 +319,54 @@ module Playwright
     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.
+    # Execute JavaScript code in the page, taking all matching elements as an argument.
+    #
+    # **Details**
     #
-    # If `expression` returns a [Promise], then [`method: Locator.evaluateAll`] would wait for the promise
-    # to resolve and return its value.
+    # Returns the return value of `expression`, called with an array of all matching elements as a first argument, and `arg` as a second argument.
+    #
+    # If `expression` returns a [Promise], this method will wait for the promise to resolve and return its value.
+    #
+    # If `expression` throws or rejects, this method throws.
     #
     # **Usage**
     #
     # ```python sync
-    # elements = page.locator("div")
-    # div_counts = elements.evaluate_all("(divs, min) => divs.length >= min", 10)
+    # locator = page.locator("div")
+    # more_than_ten = locator.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`.
+    # Execute JavaScript code in the page, taking the matching element as an argument, and return a `JSHandle` with the result.
+    #
+    # **Details**
     #
-    # This method passes this handle as the first argument to `expression`.
+    # Returns the return value of `expression` as a`JSHandle`, called with the matching element as a first argument, and `arg` as a second argument.
     #
     # 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 `expression` returns a [Promise], this method will wait for the promise to resolve and return its value.
+    #
+    # If `expression` throws or rejects, this method throws.
     #
     # 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
 
+    #
+    # Set a value to the input field.
+    #
+    # **Usage**
+    #
+    # ```python sync
+    # page.get_by_role("textbox").fill("example value")
+    # ```
+    #
+    # **Details**
     #
     # 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.
     #
@@ -314,17 +402,17 @@ module Playwright
     end
 
     #
-    # Calls [focus](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/focus) on the element.
+    # Calls [focus](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/focus) on the matching element.
     def focus(timeout: nil)
       wrap_impl(@impl.focus(timeout: unwrap_impl(timeout)))
     end
 
     #
-    # **Usage**
-    #
-    # When working with iframes, you can create a frame locator that will enter the iframe and allow selecting elements
+    # When working with iframes, you can create a frame locator that will enter the iframe and allow locating elements
     # in that iframe:
     #
+    # **Usage**
+    #
     # ```python sync
     # locator = page.frame_locator("iframe").get_by_text("Submit")
     # locator.click()
@@ -334,47 +422,100 @@ module Playwright
     end
 
     #
-    # Returns element attribute value.
+    # Returns the matching element's 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":
+    # Allows locating elements by their alt text.
+    #
+    # **Usage**
+    #
+    # For example, this method will find the image by alt text "Playwright logo":
     #
     # ```html
-    # <img alt='Castle'>
+    # <img alt='Playwright logo'>
+    # ```
+    #
+    # ```python sync
+    # page.get_by_alt_text("Playwright logo").click()
     # ```
     def get_by_alt_text(text, exact: nil)
       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.
+    #
+    # **Usage**
+    #
+    # For example, this method will find the input by label text "Password" in the following DOM:
     #
     # ```html
     # <label for="password-input">Password:</label>
     # <input id="password-input">
     # ```
+    #
+    # ```python sync
+    # page.get_by_label("Password").fill("secret")
+    # ```
     def get_by_label(text, exact: nil)
       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.
+    #
+    # **Usage**
+    #
+    # For example, consider the following DOM structure.
     #
     # ```html
-    # <input placeholder="Country">
+    # <input type="email" placeholder="name@example.com" />
+    # ```
+    #
+    # You can fill the input after locating it by the placeholder text:
+    #
+    # ```python sync
+    # page.get_by_placeholder("name@example.com").fill("playwright@microsoft.com")
     # ```
     def get_by_placeholder(text, exact: nil)
       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.
+    # 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).
+    #
+    # **Usage**
+    #
+    # Consider the following DOM structure.
+    #
+    # ```html
+    # <h3>Sign up</h3>
+    # <label>
+    #   <input type="checkbox" /> Subscribe
+    # </label>
+    # <br/>
+    # <button>Submit</button>
+    # ```
+    #
+    # You can locate each element by it's implicit role:
+    #
+    # ```python sync
+    # expect(page.get_by_role("heading", name="Sign up")).to_be_visible()
+    #
+    # page.get_by_role("checkbox", name="Subscribe").check()
     #
-    # 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.
+    # page.get_by_role("button", name=re.compile("submit", re.IGNORECASE)).click()
+    # ```
+    #
+    # **Details**
+    #
+    # Role selector **does not replace** accessibility audits and conformance tests, but rather gives early feedback about the ARIA guidelines.
+    #
+    # 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,
@@ -390,13 +531,37 @@ module Playwright
     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.
+    #
+    # **Usage**
+    #
+    # Consider the following DOM structure.
+    #
+    # ```html
+    # <button data-testid="directions">Itinéraire</button>
+    # ```
+    #
+    # You can locate the element by it's test id:
+    #
+    # ```python sync
+    # page.get_by_test_id("directions").click()
+    # ```
+    #
+    # **Details**
+    #
+    # 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:
+    # Allows locating elements that contain given text.
+    #
+    # See also [`method: Locator.filter`] that allows to match by another criteria, like an accessible role, and then filter by the text content.
+    #
+    # **Usage**
+    #
+    # Consider the following DOM structure:
     #
     # ```html
     # <div>Hello <span>world</span></div>
@@ -422,20 +587,30 @@ 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.
+    # **Details**
     #
-    # **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.
+    # 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">`.
+    # 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":
+    # Allows locating elements by their title attribute.
+    #
+    # **Usage**
+    #
+    # Consider the following DOM structure.
     #
     # ```html
-    # <button title='Place the order'>Order Now</button>
+    # <span title='Issues count'>25 issues</span>
+    # ```
+    #
+    # You can check the issues count after locating it by the title text:
+    #
+    # ```python sync
+    # expect(page.get_by_title("Issues count")).to_have_text("25 issues")
     # ```
     def get_by_title(text, exact: nil)
       wrap_impl(@impl.get_by_title(unwrap_impl(text), exact: unwrap_impl(exact)))
@@ -447,6 +622,16 @@ module Playwright
       wrap_impl(@impl.highlight)
     end
 
+    #
+    # Hover over the matching element.
+    #
+    # **Usage**
+    #
+    # ```python sync
+    # page.get_by_role("link").hover()
+    # ```
+    #
+    # **Details**
     #
     # 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.
@@ -469,63 +654,113 @@ module Playwright
     end
 
     #
-    # Returns the `element.innerHTML`.
+    # Returns the [`element.innerHTML`](https://developer.mozilla.org/en-US/docs/Web/API/Element/innerHTML).
     def inner_html(timeout: nil)
       wrap_impl(@impl.inner_html(timeout: unwrap_impl(timeout)))
     end
 
     #
-    # Returns the `element.innerText`.
+    # Returns the [`element.innerText`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/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.
+    # Returns the value for the matching `<input>` or `<textarea>` or `<select>` element.
+    #
+    # **Usage**
+    #
+    # ```python sync
+    # value = page.get_by_role("textbox").input_value()
+    # ```
+    #
+    # **Details**
     #
-    # 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 elements that are not an input, textarea or a select. 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.
+    #
+    # **Usage**
+    #
+    # ```python sync
+    # checked = page.get_by_role("checkbox").is_checked()
+    # ```
     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).
+    #
+    # **Usage**
+    #
+    # ```python sync
+    # disabled = page.get_by_role("button").is_disabled()
+    # ```
     def disabled?(timeout: nil)
       wrap_impl(@impl.disabled?(timeout: unwrap_impl(timeout)))
     end
 
     #
     # Returns whether the element is [editable](../actionability.md#editable).
+    #
+    # **Usage**
+    #
+    # ```python sync
+    # editable = page.get_by_role("textbox").is_editable()
+    # ```
     def editable?(timeout: nil)
       wrap_impl(@impl.editable?(timeout: unwrap_impl(timeout)))
     end
 
     #
     # Returns whether the element is [enabled](../actionability.md#enabled).
+    #
+    # **Usage**
+    #
+    # ```python sync
+    # enabled = page.get_by_role("button").is_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).
+    #
+    # **Usage**
+    #
+    # ```python sync
+    # hidden = page.get_by_role("button").is_hidden()
+    # ```
     def hidden?(timeout: nil)
       wrap_impl(@impl.hidden?(timeout: unwrap_impl(timeout)))
     end
 
     #
     # Returns whether the element is [visible](../actionability.md#visible).
+    #
+    # **Usage**
+    #
+    # ```python sync
+    # visible = page.get_by_role("button").is_visible()
+    # ```
     def visible?(timeout: nil)
       wrap_impl(@impl.visible?(timeout: unwrap_impl(timeout)))
     end
 
     #
     # Returns locator to the last matching element.
+    #
+    # **Usage**
+    #
+    # ```python sync
+    # banana = page.get_by_role("listitem").last()
+    # ```
     def last
       wrap_impl(@impl.last)
     end
@@ -540,6 +775,12 @@ module Playwright
 
     #
     # Returns locator to the n-th matching element. It's zero based, `nth(0)` selects the first element.
+    #
+    # **Usage**
+    #
+    # ```python sync
+    # banana = page.get_by_role("listitem").nth(2)
+    # ```
     def nth(index)
       wrap_impl(@impl.nth(unwrap_impl(index)))
     end
@@ -550,6 +791,16 @@ module Playwright
       wrap_impl(@impl.page)
     end
 
+    #
+    # Focuses the mathing element and presses a combintation of the keys.
+    #
+    # **Usage**
+    #
+    # ```python sync
+    # page.get_by_role("textbox").press("Backspace")
+    # ```
+    #
+    # **Details**
     #
     # Focuses the element, and then uses [`method: Keyboard.down`] and [`method: Keyboard.up`].
     #
@@ -574,6 +825,22 @@ module Playwright
       wrap_impl(@impl.press(unwrap_impl(key), delay: unwrap_impl(delay), noWaitAfter: unwrap_impl(noWaitAfter), timeout: unwrap_impl(timeout)))
     end
 
+    #
+    # Take a screenshot of the element matching the locator.
+    #
+    # **Usage**
+    #
+    # ```python sync
+    # page.get_by_role("link").screenshot()
+    # ```
+    #
+    # Disable animations and save screenshot to a file:
+    #
+    # ```python sync
+    # page.get_by_role("link").screenshot(animations="disabled", path="link.png")
+    # ```
+    #
+    # **Details**
     #
     # 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.
     #
@@ -653,6 +920,16 @@ module Playwright
       wrap_impl(@impl.select_text(force: unwrap_impl(force), timeout: unwrap_impl(timeout)))
     end
 
+    #
+    # Set the state of a checkbox or a radio element.
+    #
+    # **Usage**
+    #
+    # ```python sync
+    # page.get_by_role("checkbox").set_checked(True)
+    # ```
+    #
+    # **Details**
     #
     # 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.
@@ -676,6 +953,30 @@ module Playwright
     end
     alias_method :checked=, :set_checked
 
+    #
+    # Upload file or multiple files into `<input type=file>`.
+    #
+    # **Usage**
+    #
+    # ```python sync
+    # # Select one file
+    # page.get_by_label("Upload file").set_input_files('myfile.pdf')
+    #
+    # # Select multiple files
+    # page.get_by_label("Upload files").set_input_files(['file1.txt', 'file2.txt'])
+    #
+    # # Remove all the selected files
+    # page.get_by_label("Upload file").set_input_files([])
+    #
+    # # Upload buffer from memory
+    # page.get_by_label("Upload file").set_input_files(
+    #     files=[
+    #         {"name": "test.txt", "mimeType": "text/plain", "buffer": b"this is a test"}
+    #     ],
+    # )
+    # ```
+    #
+    # **Details**
     #
     # 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.
@@ -687,6 +988,10 @@ module Playwright
     end
     alias_method :input_files=, :set_input_files
 
+    #
+    # Perform a tap gesture on the element matching the locator.
+    #
+    # **Details**
     #
     # 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.
@@ -711,7 +1016,7 @@ module Playwright
     end
 
     #
-    # Returns the `node.textContent`.
+    # Returns the [`node.textContent`](https://developer.mozilla.org/en-US/docs/Web/API/Node/textContent).
     def text_content(timeout: nil)
       wrap_impl(@impl.text_content(timeout: unwrap_impl(timeout)))
     end
@@ -740,7 +1045,17 @@ module Playwright
     end
 
     #
-    # This method checks the element by performing the following steps:
+    # Ensure that checkbox or radio element is unchecked.
+    #
+    # **Usage**
+    #
+    # ```python sync
+    # page.get_by_role("checkbox").uncheck()
+    # ```
+    #
+    # **Details**
+    #
+    # This method unchecks 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. Wait for [actionability](../actionability.md) checks on the element, unless `force` option is set.
     # 1. Scroll the element into view if needed.