playwright-ruby-client 0.8.0 → 1.14.beta2

data/lib/playwright_api/element_handle.rb

@@ -7,19 +7,8 @@ module Playwright
   # method.
   #
   # ```python sync
-  # from playwright.sync_api import sync_playwright
-  #
-  # def run(playwright):
-  #     chromium = playwright.chromium
-  #     browser = chromium.launch()
-  #     page = browser.new_page()
-  #     page.goto("https://example.com")
-  #     href_element = page.query_selector("a")
-  #     href_element.click()
-  #     # ...
-  #
-  # with sync_playwright() as playwright:
-  #     run(playwright)
+  # href_element = page.query_selector("a")
+  # href_element.click()
   # ```
   #
   # ElementHandle prevents DOM element from garbage collection unless the handle is disposed with
@@ -27,6 +16,31 @@ module Playwright
   #
   # ElementHandle instances can be used as an argument in [`method: Page.evalOnSelector`] and [`method: Page.evaluate`]
   # methods.
+  #
+  # > NOTE: In most cases, you would want to use the `Locator` object instead. You should only use `ElementHandle` if you
+  # want to retain a handle to a particular DOM Node that you intend to pass into [`method: Page.evaluate`] as an argument.
+  #
+  # The difference between the `Locator` and ElementHandle is that the ElementHandle points to a particular element, while
+  # `Locator` captures the logic of how to retrieve an element.
+  #
+  # In the example below, handle points to a particular DOM element on page. If that element changes text or is used by
+  # React to render an entirely different component, handle is still pointing to that very DOM element. This can lead to
+  # unexpected behaviors.
+  #
+  # ```python sync
+  # handle = page.query_selector("text=Submit")
+  # handle.hover()
+  # handle.click()
+  # ```
+  #
+  # With the locator, every time the `element` is used, up-to-date DOM element is located in the page using the selector. So
+  # in the snippet below, underlying DOM element is going to be located twice.
+  #
+  # ```python sync
+  # locator = page.locator("text=Submit")
+  # locator.hover()
+  # locator.click()
+  # ```
   class ElementHandle < JSHandle
 
     # This method returns the bounding box of the element, or `null` if the element is not visible. The bounding box is
@@ -254,7 +268,7 @@ module Playwright
       wrap_impl(@impl.inner_text)
     end
 
-    # Returns `input.value` for `<input>` or `<textarea>` element. Throws for non-input elements.
+    # Returns `input.value` for `<input>` or `<textarea>` or `<select>` element. Throws for non-input elements.
     def input_value(timeout: nil)
       wrap_impl(@impl.input_value(timeout: unwrap_impl(timeout)))
     end
@@ -515,12 +529,6 @@ module Playwright
       wrap_impl(@impl.wait_for_selector(unwrap_impl(selector), state: unwrap_impl(state), timeout: unwrap_impl(timeout)))
     end
 
-    # -- inherited from EventEmitter --
-    # @nodoc
-    def off(event, callback)
-      event_emitter_proxy.off(event, callback)
-    end
-
     # -- inherited from EventEmitter --
     # @nodoc
     def once(event, callback)
@@ -533,6 +541,12 @@ module Playwright
       event_emitter_proxy.on(event, callback)
     end
 
+    # -- inherited from EventEmitter --
+    # @nodoc
+    def off(event, callback)
+      event_emitter_proxy.off(event, callback)
+    end
+
     private def event_emitter_proxy
       @event_emitter_proxy ||= EventEmitterProxy.new(self, @impl)
     end

data/lib/playwright_api/frame.rb

@@ -65,9 +65,10 @@ module Playwright
           force: nil,
           noWaitAfter: nil,
           position: nil,
+          strict: nil,
           timeout: nil,
           trial: nil)
-      wrap_impl(@impl.check(unwrap_impl(selector), force: unwrap_impl(force), noWaitAfter: unwrap_impl(noWaitAfter), position: unwrap_impl(position), timeout: unwrap_impl(timeout), trial: unwrap_impl(trial)))
+      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
 
     def child_frames
@@ -93,9 +94,10 @@ module Playwright
           modifiers: nil,
           noWaitAfter: nil,
           position: nil,
+          strict: nil,
           timeout: nil,
           trial: nil)
-      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), timeout: unwrap_impl(timeout), trial: unwrap_impl(trial)))
+      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
 
     # Gets the full HTML contents of the frame, including the doctype.
@@ -124,9 +126,10 @@ module Playwright
           modifiers: nil,
           noWaitAfter: nil,
           position: nil,
+          strict: nil,
           timeout: nil,
           trial: nil)
-      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), timeout: unwrap_impl(timeout), trial: unwrap_impl(trial)))
+      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,
@@ -156,8 +159,26 @@ module Playwright
     # data_transfer = frame.evaluate_handle("new DataTransfer()")
     # frame.dispatch_event("#source", "dragstart", { "dataTransfer": data_transfer })
     # ```
-    def dispatch_event(selector, type, eventInit: nil, timeout: nil)
-      wrap_impl(@impl.dispatch_event(unwrap_impl(selector), unwrap_impl(type), eventInit: unwrap_impl(eventInit), timeout: unwrap_impl(timeout)))
+    def dispatch_event(
+          selector,
+          type,
+          eventInit: nil,
+          strict: nil,
+          timeout: nil)
+      wrap_impl(@impl.dispatch_event(unwrap_impl(selector), unwrap_impl(type), eventInit: unwrap_impl(eventInit), strict: unwrap_impl(strict), timeout: unwrap_impl(timeout)))
+    end
+
+    def drag_and_drop(
+          source,
+          target,
+          force: nil,
+          noWaitAfter: nil,
+          sourcePosition: nil,
+          strict: nil,
+          targetPosition: nil,
+          timeout: nil,
+          trial: nil)
+      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
 
     # Returns the return value of `expression`.
@@ -176,8 +197,8 @@ module Playwright
     # preload_href = frame.eval_on_selector("link[rel=preload]", "el => el.href")
     # html = frame.eval_on_selector(".main-container", "(e, suffix) => e.outerHTML + suffix", "hello")
     # ```
-    def eval_on_selector(selector, expression, arg: nil)
-      wrap_impl(@impl.eval_on_selector(unwrap_impl(selector), unwrap_impl(expression), arg: unwrap_impl(arg)))
+    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
 
     # Returns the return value of `expression`.
@@ -276,14 +297,15 @@ module Playwright
           value,
           force: nil,
           noWaitAfter: nil,
+          strict: nil,
           timeout: nil)
-      wrap_impl(@impl.fill(unwrap_impl(selector), unwrap_impl(value), force: unwrap_impl(force), noWaitAfter: unwrap_impl(noWaitAfter), timeout: unwrap_impl(timeout)))
+      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.
-    def focus(selector, timeout: nil)
-      wrap_impl(@impl.focus(unwrap_impl(selector), timeout: unwrap_impl(timeout)))
+    def focus(selector, strict: nil, timeout: nil)
+      wrap_impl(@impl.focus(unwrap_impl(selector), strict: unwrap_impl(strict), timeout: unwrap_impl(timeout)))
     end
 
     # Returns the `frame` or `iframe` element handle which corresponds to this frame.
@@ -303,8 +325,8 @@ module Playwright
     end
 
     # Returns element attribute value.
-    def get_attribute(selector, name, timeout: nil)
-      wrap_impl(@impl.get_attribute(unwrap_impl(selector), unwrap_impl(name), timeout: unwrap_impl(timeout)))
+    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
 
     # Returns the main resource response. In case of multiple redirects, the navigation will resolve with the response of the
@@ -344,29 +366,30 @@ module Playwright
           force: nil,
           modifiers: nil,
           position: nil,
+          strict: nil,
           timeout: nil,
           trial: nil)
-      wrap_impl(@impl.hover(unwrap_impl(selector), force: unwrap_impl(force), modifiers: unwrap_impl(modifiers), position: unwrap_impl(position), timeout: unwrap_impl(timeout), trial: unwrap_impl(trial)))
+      wrap_impl(@impl.hover(unwrap_impl(selector), force: unwrap_impl(force), modifiers: unwrap_impl(modifiers), position: unwrap_impl(position), strict: unwrap_impl(strict), timeout: unwrap_impl(timeout), trial: unwrap_impl(trial)))
     end
 
     # Returns `element.innerHTML`.
-    def inner_html(selector, timeout: nil)
-      wrap_impl(@impl.inner_html(unwrap_impl(selector), timeout: unwrap_impl(timeout)))
+    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, timeout: nil)
-      wrap_impl(@impl.inner_text(unwrap_impl(selector), timeout: unwrap_impl(timeout)))
+    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>` element. Throws for non-input elements.
-    def input_value(selector, timeout: nil)
-      wrap_impl(@impl.input_value(unwrap_impl(selector), timeout: unwrap_impl(timeout)))
+    # Returns `input.value` for the selected `<input>` or `<textarea>` or `<select>` element. Throws for non-input elements.
+    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, timeout: nil)
-      wrap_impl(@impl.checked?(unwrap_impl(selector), timeout: unwrap_impl(timeout)))
+    def checked?(selector, strict: nil, timeout: nil)
+      wrap_impl(@impl.checked?(unwrap_impl(selector), strict: unwrap_impl(strict), timeout: unwrap_impl(timeout)))
     end
 
     # Returns `true` if the frame has been detached, or `false` otherwise.
@@ -375,30 +398,39 @@ module Playwright
     end
 
     # Returns whether the element is disabled, the opposite of [enabled](./actionability.md#enabled).
-    def disabled?(selector, timeout: nil)
-      wrap_impl(@impl.disabled?(unwrap_impl(selector), timeout: unwrap_impl(timeout)))
+    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, timeout: nil)
-      wrap_impl(@impl.editable?(unwrap_impl(selector), timeout: unwrap_impl(timeout)))
+    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, timeout: nil)
-      wrap_impl(@impl.enabled?(unwrap_impl(selector), timeout: unwrap_impl(timeout)))
+    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.
-    def hidden?(selector, timeout: nil)
-      wrap_impl(@impl.hidden?(unwrap_impl(selector), timeout: unwrap_impl(timeout)))
+    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.
-    def visible?(selector, timeout: nil)
-      wrap_impl(@impl.visible?(unwrap_impl(selector), timeout: unwrap_impl(timeout)))
+    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 in the frame. Locator is resolved to the
+    # element immediately before performing an action, so a series of actions on the same locator can in fact be performed on
+    # different DOM elements. That would happen if the DOM structure between those actions has changed.
+    #
+    # Note that locator always implies visibility, so it will always be locating visible elements.
+    def locator(selector)
+      wrap_impl(@impl.locator(unwrap_impl(selector)))
     end
 
     # Returns frame's name attribute as specified in the tag.
@@ -441,16 +473,17 @@ module Playwright
           key,
           delay: nil,
           noWaitAfter: nil,
+          strict: nil,
           timeout: nil)
-      wrap_impl(@impl.press(unwrap_impl(selector), unwrap_impl(key), delay: unwrap_impl(delay), noWaitAfter: unwrap_impl(noWaitAfter), timeout: unwrap_impl(timeout)))
+      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
 
     # Returns the ElementHandle pointing to the frame element.
     #
     # The method finds an element matching the specified selector within the frame. See
     # [Working with selectors](./selectors.md) for more details. If no elements match the selector, returns `null`.
-    def query_selector(selector)
-      wrap_impl(@impl.query_selector(unwrap_impl(selector)))
+    def query_selector(selector, strict: nil)
+      wrap_impl(@impl.query_selector(unwrap_impl(selector), strict: unwrap_impl(strict)))
     end
 
     # Returns the ElementHandles pointing to the frame elements.
@@ -488,8 +521,9 @@ module Playwright
           label: nil,
           force: nil,
           noWaitAfter: nil,
+          strict: nil,
           timeout: nil)
-      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), timeout: unwrap_impl(timeout)))
+      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
 
     def set_content(html, timeout: nil, waitUntil: nil)
@@ -502,8 +536,13 @@ module Playwright
     #
     # 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 the current working directory. For empty array, clears the selected files.
-    def set_input_files(selector, files, noWaitAfter: nil, timeout: nil)
-      wrap_impl(@impl.set_input_files(unwrap_impl(selector), unwrap_impl(files), noWaitAfter: unwrap_impl(noWaitAfter), timeout: unwrap_impl(timeout)))
+    def set_input_files(
+          selector,
+          files,
+          noWaitAfter: nil,
+          strict: nil,
+          timeout: nil)
+      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
 
     # This method taps an element matching `selector` by performing the following steps:
@@ -524,14 +563,15 @@ module Playwright
           modifiers: nil,
           noWaitAfter: nil,
           position: nil,
+          strict: nil,
           timeout: nil,
           trial: nil)
-      wrap_impl(@impl.tap_point(unwrap_impl(selector), force: unwrap_impl(force), modifiers: unwrap_impl(modifiers), noWaitAfter: unwrap_impl(noWaitAfter), position: unwrap_impl(position), timeout: unwrap_impl(timeout), trial: unwrap_impl(trial)))
+      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, timeout: nil)
-      wrap_impl(@impl.text_content(unwrap_impl(selector), timeout: unwrap_impl(timeout)))
+    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 title.
@@ -553,8 +593,9 @@ module Playwright
           text,
           delay: nil,
           noWaitAfter: nil,
+          strict: nil,
           timeout: nil)
-      wrap_impl(@impl.type(unwrap_impl(selector), unwrap_impl(text), delay: unwrap_impl(delay), noWaitAfter: unwrap_impl(noWaitAfter), timeout: unwrap_impl(timeout)))
+      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 checks an element matching `selector` by performing the following steps:
@@ -575,9 +616,10 @@ module Playwright
           force: nil,
           noWaitAfter: nil,
           position: nil,
+          strict: nil,
           timeout: nil,
           trial: nil)
-      wrap_impl(@impl.uncheck(unwrap_impl(selector), force: unwrap_impl(force), noWaitAfter: unwrap_impl(noWaitAfter), position: unwrap_impl(position), timeout: unwrap_impl(timeout), trial: unwrap_impl(trial)))
+      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
 
     # Returns frame's url.
@@ -671,8 +713,8 @@ module Playwright
     # with sync_playwright() as playwright:
     #     run(playwright)
     # ```
-    def wait_for_selector(selector, state: nil, timeout: nil)
-      wrap_impl(@impl.wait_for_selector(unwrap_impl(selector), state: unwrap_impl(state), timeout: unwrap_impl(timeout)))
+    def wait_for_selector(selector, state: nil, strict: nil, timeout: nil)
+      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.
@@ -680,7 +722,7 @@ module Playwright
     # Note that `frame.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.
     def wait_for_timeout(timeout)
-      raise NotImplementedError.new('wait_for_timeout is not implemented yet.')
+      wrap_impl(@impl.wait_for_timeout(unwrap_impl(timeout)))
     end
 
     # Waits for the frame to navigate to the given URL.
@@ -698,12 +740,6 @@ module Playwright
       wrap_impl(@impl.detached=(unwrap_impl(req)))
     end
 
-    # -- inherited from EventEmitter --
-    # @nodoc
-    def off(event, callback)
-      event_emitter_proxy.off(event, callback)
-    end
-
     # -- inherited from EventEmitter --
     # @nodoc
     def once(event, callback)
@@ -716,6 +752,12 @@ module Playwright
       event_emitter_proxy.on(event, callback)
     end
 
+    # -- inherited from EventEmitter --
+    # @nodoc
+    def off(event, callback)
+      event_emitter_proxy.off(event, callback)
+    end
+
     private def event_emitter_proxy
       @event_emitter_proxy ||= EventEmitterProxy.new(self, @impl)
     end

data/lib/playwright_api/js_handle.rb

@@ -88,12 +88,6 @@ module Playwright
       wrap_impl(@impl.to_s)
     end
 
-    # -- inherited from EventEmitter --
-    # @nodoc
-    def off(event, callback)
-      event_emitter_proxy.off(event, callback)
-    end
-
     # -- inherited from EventEmitter --
     # @nodoc
     def once(event, callback)
@@ -106,6 +100,12 @@ module Playwright
       event_emitter_proxy.on(event, callback)
     end
 
+    # -- inherited from EventEmitter --
+    # @nodoc
+    def off(event, callback)
+      event_emitter_proxy.off(event, callback)
+    end
+
     private def event_emitter_proxy
       @event_emitter_proxy ||= EventEmitterProxy.new(self, @impl)
     end

data/lib/playwright_api/locator.rb

@@ -0,0 +1,509 @@
+module Playwright
+  # Locator represents a view to the element(s) on the page. It captures the logic sufficient to retrieve the element at any
+  # given moment. Locator can be created with the [`method: Page.locator`] method.
+  #
+  # ```python sync
+  # locator = page.locator("text=Submit")
+  # locator.click()
+  # ```
+  #
+  # The difference between the Locator and `ElementHandle` is that the latter points to a particular element, while Locator
+  # captures the logic of how to retrieve that element.
+  #
+  # In the example below, handle points to a particular DOM element on page. If that element changes text or is used by
+  # React to render an entirely different component, handle is still pointing to that very DOM element. This can lead to
+  # unexpected behaviors.
+  #
+  # ```python sync
+  # handle = page.query_selector("text=Submit")
+  # handle.hover()
+  # handle.click()
+  # ```
+  #
+  # With the locator, every time the `element` is used, up-to-date DOM element is located in the page using the selector. So
+  # in the snippet below, underlying DOM element is going to be located twice.
+  #
+  # ```python sync
+  # locator = page.locator("text=Submit")
+  # locator.hover()
+  # locator.click()
+  # ```
+  class Locator < PlaywrightApi
+
+    # Returns an array of `node.innerText` values for all matching nodes.
+    def all_inner_texts
+      wrap_impl(@impl.all_inner_texts)
+    end
+
+    # Returns an array of `node.textContent` values for all matching nodes.
+    def all_text_contents
+      wrap_impl(@impl.all_text_contents)
+    end
+
+    # This method returns the bounding box of the element, or `null` if the element is not visible. The bounding box is
+    # calculated relative to the main frame viewport - which is usually the same as the browser window.
+    #
+    # Scrolling affects the returned bonding 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.
+    #
+    # Elements from child frames return the bounding box relative to the main frame, unlike the
+    # [Element.getBoundingClientRect](https://developer.mozilla.org/en-US/docs/Web/API/Element/getBoundingClientRect).
+    #
+    # Assuming the page is static, it is safe to use bounding box coordinates to perform input. For example, the following
+    # snippet should click the center of the element.
+    #
+    # ```python sync
+    # box = element.bounding_box()
+    # page.mouse.click(box["x"] + box["width"] / 2, box["y"] + box["height"] / 2)
+    # ```
+    def bounding_box(timeout: nil)
+      wrap_impl(@impl.bounding_box(timeout: unwrap_impl(timeout)))
+    end
+
+    # This method checks the element by performing the following steps:
+    # 1. Ensure that element is a checkbox or a radio input. If not, this method throws. If the element is already checked,
+    #    this method returns immediately.
+    # 1. Wait for [actionability](./actionability.md) checks on the element, unless `force` option is set.
+    # 1. Scroll the element into view if needed.
+    # 1. Use [`property: Page.mouse`] to click in the center of the element.
+    # 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.
+    #
+    # If the element is detached from the DOM at any moment during the action, this method throws.
+    #
+    # When all steps combined have not finished during the specified `timeout`, this method throws a `TimeoutError`. Passing
+    # zero timeout disables this.
+    def check(
+          force: nil,
+          noWaitAfter: nil,
+          position: nil,
+          timeout: nil,
+          trial: nil)
+      wrap_impl(@impl.check(force: unwrap_impl(force), noWaitAfter: unwrap_impl(noWaitAfter), position: unwrap_impl(position), timeout: unwrap_impl(timeout), trial: unwrap_impl(trial)))
+    end
+
+    # This method clicks the element by performing the following steps:
+    # 1. Wait for [actionability](./actionability.md) checks on the element, unless `force` option is set.
+    # 1. Scroll the element into view if needed.
+    # 1. Use [`property: Page.mouse`] to 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.
+    #
+    # If the element is detached from the DOM at any moment during the action, this method throws.
+    #
+    # When all steps combined have not finished during the specified `timeout`, this method throws a `TimeoutError`. Passing
+    # zero timeout disables this.
+    def click(
+          button: nil,
+          clickCount: nil,
+          delay: nil,
+          force: nil,
+          modifiers: nil,
+          noWaitAfter: nil,
+          position: nil,
+          timeout: nil,
+          trial: nil)
+      wrap_impl(@impl.click(button: unwrap_impl(button), clickCount: unwrap_impl(clickCount), delay: unwrap_impl(delay), force: unwrap_impl(force), modifiers: unwrap_impl(modifiers), noWaitAfter: unwrap_impl(noWaitAfter), position: unwrap_impl(position), timeout: unwrap_impl(timeout), trial: unwrap_impl(trial)))
+    end
+
+    # Returns the number of elements matching given selector.
+    def count
+      wrap_impl(@impl.count)
+    end
+
+    # This method double clicks the element by performing the following steps:
+    # 1. Wait for [actionability](./actionability.md) checks on the element, unless `force` option is set.
+    # 1. Scroll the element into view if needed.
+    # 1. Use [`property: Page.mouse`] to double click in the center of the element, or the specified `position`.
+    # 1. Wait for initiated navigations to either succeed or fail, unless `noWaitAfter` option is set. Note that if the
+    #    first click of the `dblclick()` triggers a navigation event, this method will throw.
+    #
+    # If the element is detached from the DOM at any moment during the action, this method throws.
+    #
+    # When all steps combined have not finished during the specified `timeout`, this method throws a `TimeoutError`. Passing
+    # zero timeout disables this.
+    #
+    # > NOTE: `element.dblclick()` dispatches two `click` events and a single `dblclick` event.
+    def dblclick(
+          button: nil,
+          delay: nil,
+          force: nil,
+          modifiers: nil,
+          noWaitAfter: nil,
+          position: nil,
+          timeout: nil,
+          trial: nil)
+      wrap_impl(@impl.dblclick(button: unwrap_impl(button), delay: unwrap_impl(delay), force: unwrap_impl(force), modifiers: unwrap_impl(modifiers), noWaitAfter: unwrap_impl(noWaitAfter), position: unwrap_impl(position), timeout: unwrap_impl(timeout), trial: unwrap_impl(trial)))
+    end
+
+    # The snippet below dispatches the `click` event on the element. Regardless of the visibility state of the element,
+    # `click` is dispatched. This is equivalent to calling
+    # [element.click()](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/click).
+    #
+    # ```python sync
+    # element.dispatch_event("click")
+    # ```
+    #
+    # Under the hood, it creates an instance of an event based on the given `type`, initializes it with `eventInit` properties
+    # and dispatches it on the element. Events are `composed`, `cancelable` and bubble by default.
+    #
+    # 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)
+    # - [MouseEvent](https://developer.mozilla.org/en-US/docs/Web/API/MouseEvent/MouseEvent)
+    # - [PointerEvent](https://developer.mozilla.org/en-US/docs/Web/API/PointerEvent/PointerEvent)
+    # - [TouchEvent](https://developer.mozilla.org/en-US/docs/Web/API/TouchEvent/TouchEvent)
+    # - [Event](https://developer.mozilla.org/en-US/docs/Web/API/Event/Event)
+    #
+    # You can also specify `JSHandle` as the property value if you want live objects to be passed into the event:
+    #
+    # ```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})
+    # ```
+    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
+
+    # Resolves given locator to the first matching DOM element. If no elements matching the query are visible, waits for them
+    # up to a given timeout. If multiple elements match the selector, throws.
+    def element_handle(timeout: nil)
+      wrap_impl(@impl.element_handle(timeout: unwrap_impl(timeout)))
+    end
+
+    # Resolves given locator to all matching DOM elements.
+    def element_handles
+      wrap_impl(@impl.element_handles)
+    end
+
+    # Returns the return value of `expression`.
+    #
+    # This method passes this handle as the first argument to `expression`.
+    #
+    # If `expression` returns a [Promise], then `handle.evaluate` would wait for the promise to resolve and return its value.
+    #
+    # Examples:
+    #
+    # ```python sync
+    # tweets = page.locator(".tweet .retweets")
+    # assert tweets.evaluate("node => node.innerText") == "10 retweets"
+    # ```
+    def evaluate(expression, arg: nil, timeout: nil)
+      wrap_impl(@impl.evaluate(unwrap_impl(expression), arg: unwrap_impl(arg), timeout: unwrap_impl(timeout)))
+    end
+
+    # The method finds all elements matching the specified locator and passes an array of matched elements as a first argument
+    # to `expression`. Returns the result of `expression` invocation.
+    #
+    # If `expression` returns a [Promise], then [`Locator.evaluateAll`] would wait for the promise to resolve and return its
+    # value.
+    #
+    # Examples:
+    #
+    # ```python sync
+    # elements = page.locator("div")
+    # div_counts = elements("(divs, min) => divs.length >= min", 10)
+    # ```
+    def evaluate_all(expression, arg: nil)
+      wrap_impl(@impl.evaluate_all(unwrap_impl(expression), arg: unwrap_impl(arg)))
+    end
+
+    # Returns the return value of `expression` as a `JSHandle`.
+    #
+    # This method passes this handle as the first argument to `expression`.
+    #
+    # The only difference between [`method: Locator.evaluate`] and [`method: Locator.evaluateHandle`] is that
+    # [`method: Locator.evaluateHandle`] returns `JSHandle`.
+    #
+    # If the function passed to the [`method: Locator.evaluateHandle`] returns a [Promise], then
+    # [`method: Locator.evaluateHandle`] would wait for the promise to resolve and return its value.
+    #
+    # See [`method: Page.evaluateHandle`] for more details.
+    def evaluate_handle(expression, arg: nil, timeout: nil)
+      wrap_impl(@impl.evaluate_handle(unwrap_impl(expression), arg: unwrap_impl(arg), timeout: unwrap_impl(timeout)))
+    end
+
+    # This method waits for [actionability](./actionability.md) checks, focuses the element, fills it and triggers an `input`
+    # event after filling. Note that you can pass an empty string to clear the input field.
+    #
+    # If the target element is not an `<input>`, `<textarea>` or `[contenteditable]` element, this method throws an error.
+    # However, if the element is inside the `<label>` element that has an associated
+    # [control](https://developer.mozilla.org/en-US/docs/Web/API/HTMLLabelElement/control), the control will be filled
+    # instead.
+    #
+    # To send fine-grained keyboard events, use [`method: Locator.type`].
+    def fill(value, force: nil, noWaitAfter: nil, timeout: nil)
+      wrap_impl(@impl.fill(unwrap_impl(value), force: unwrap_impl(force), noWaitAfter: unwrap_impl(noWaitAfter), timeout: unwrap_impl(timeout)))
+    end
+
+    # Returns locator to the first matching element.
+    def first
+      wrap_impl(@impl.first)
+    end
+
+    # Calls [focus](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/focus) on the element.
+    def focus(timeout: nil)
+      wrap_impl(@impl.focus(timeout: unwrap_impl(timeout)))
+    end
+
+    # Returns element attribute value.
+    def get_attribute(name, timeout: nil)
+      wrap_impl(@impl.get_attribute(unwrap_impl(name), timeout: unwrap_impl(timeout)))
+    end
+
+    # This method hovers over the element by performing the following steps:
+    # 1. Wait for [actionability](./actionability.md) checks on the element, unless `force` option is set.
+    # 1. Scroll the element into view if needed.
+    # 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.
+    #
+    # If the element is detached from the DOM at any moment during the action, this method throws.
+    #
+    # When all steps combined have not finished during the specified `timeout`, this method throws a `TimeoutError`. Passing
+    # zero timeout disables this.
+    def hover(
+          force: nil,
+          modifiers: nil,
+          position: nil,
+          timeout: nil,
+          trial: nil)
+      wrap_impl(@impl.hover(force: unwrap_impl(force), modifiers: unwrap_impl(modifiers), position: unwrap_impl(position), timeout: unwrap_impl(timeout), trial: unwrap_impl(trial)))
+    end
+
+    # Returns the `element.innerHTML`.
+    def inner_html(timeout: nil)
+      wrap_impl(@impl.inner_html(timeout: unwrap_impl(timeout)))
+    end
+
+    # Returns the `element.innerText`.
+    def inner_text(timeout: nil)
+      wrap_impl(@impl.inner_text(timeout: unwrap_impl(timeout)))
+    end
+
+    # Returns `input.value` for `<input>` or `<textarea>` or `<select>` element. Throws for non-input elements.
+    def input_value(timeout: nil)
+      wrap_impl(@impl.input_value(timeout: unwrap_impl(timeout)))
+    end
+
+    # Returns whether the element is checked. Throws if the element is not a checkbox or radio input.
+    def checked?(timeout: nil)
+      wrap_impl(@impl.checked?(timeout: unwrap_impl(timeout)))
+    end
+
+    # Returns whether the element is disabled, the opposite of [enabled](./actionability.md#enabled).
+    def disabled?(timeout: nil)
+      wrap_impl(@impl.disabled?(timeout: unwrap_impl(timeout)))
+    end
+
+    # Returns whether the element is [editable](./actionability.md#editable).
+    def editable?(timeout: nil)
+      wrap_impl(@impl.editable?(timeout: unwrap_impl(timeout)))
+    end
+
+    # Returns whether the element is [enabled](./actionability.md#enabled).
+    def enabled?(timeout: nil)
+      wrap_impl(@impl.enabled?(timeout: unwrap_impl(timeout)))
+    end
+
+    # Returns whether the element is hidden, the opposite of [visible](./actionability.md#visible).
+    def hidden?(timeout: nil)
+      wrap_impl(@impl.hidden?(timeout: unwrap_impl(timeout)))
+    end
+
+    # Returns whether the element is [visible](./actionability.md#visible).
+    def visible?(timeout: nil)
+      wrap_impl(@impl.visible?(timeout: unwrap_impl(timeout)))
+    end
+
+    # Returns locator to the last matching element.
+    def last
+      wrap_impl(@impl.last)
+    end
+
+    # The method finds an element matching the specified selector in the `Locator`'s subtree. See
+    # [Working with selectors](./selectors.md) for more details.
+    def locator(selector)
+      wrap_impl(@impl.locator(unwrap_impl(selector)))
+    end
+
+    # Returns locator to the n-th matching element.
+    def nth(index)
+      wrap_impl(@impl.nth(unwrap_impl(index)))
+    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
+    # [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`,
+    # `Delete`, `Escape`, `ArrowDown`, `End`, `Enter`, `Home`, `Insert`, `PageDown`, `PageUp`, `ArrowRight`, `ArrowUp`, etc.
+    #
+    # Following modification shortcuts are also supported: `Shift`, `Control`, `Alt`, `Meta`, `ShiftLeft`.
+    #
+    # 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.
+    #
+    # 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.
+    def press(key, delay: nil, noWaitAfter: nil, timeout: nil)
+      wrap_impl(@impl.press(unwrap_impl(key), delay: unwrap_impl(delay), noWaitAfter: unwrap_impl(noWaitAfter), timeout: unwrap_impl(timeout)))
+    end
+
+    # Returns the buffer with the captured screenshot.
+    #
+    # This method waits for the [actionability](./actionability.md) checks, then scrolls element into view before taking a
+    # screenshot. If the element is detached from DOM, the method throws an error.
+    def screenshot(
+          omitBackground: nil,
+          path: nil,
+          quality: nil,
+          timeout: nil,
+          type: nil)
+      wrap_impl(@impl.screenshot(omitBackground: unwrap_impl(omitBackground), path: unwrap_impl(path), quality: unwrap_impl(quality), timeout: unwrap_impl(timeout), type: unwrap_impl(type)))
+    end
+
+    # This method waits for [actionability](./actionability.md) checks, then tries to scroll element into view, unless it is
+    # completely visible as defined by
+    # [IntersectionObserver](https://developer.mozilla.org/en-US/docs/Web/API/Intersection_Observer_API)'s `ratio`.
+    def scroll_into_view_if_needed(timeout: nil)
+      wrap_impl(@impl.scroll_into_view_if_needed(timeout: unwrap_impl(timeout)))
+    end
+
+    # This method waits for [actionability](./actionability.md) checks, waits until all specified options are present in the
+    # `<select>` element and selects these options.
+    #
+    # If the target element is not a `<select>` element, this method throws an error. However, if the element is inside the
+    # `<label>` element that has an associated
+    # [control](https://developer.mozilla.org/en-US/docs/Web/API/HTMLLabelElement/control), the control will be used instead.
+    #
+    # 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.
+    #
+    # ```python sync
+    # # single selection matching the value
+    # element.select_option("blue")
+    # # single selection matching both the label
+    # element.select_option(label="blue")
+    # # multiple selection
+    # element.select_option(value=["red", "green", "blue"])
+    # ```
+    #
+    # ```python sync
+    # # single selection matching the value
+    # element.select_option("blue")
+    # # single selection matching both the value and the label
+    # element.select_option(label="blue")
+    # # multiple selection
+    # element.select_option("red", "green", "blue")
+    # # multiple selection for blue, red and second option
+    # element.select_option(value="blue", { index: 2 }, "red")
+    # ```
+    def select_option(
+          element: nil,
+          index: nil,
+          value: nil,
+          label: nil,
+          force: nil,
+          noWaitAfter: nil,
+          timeout: nil)
+      wrap_impl(@impl.select_option(element: unwrap_impl(element), index: unwrap_impl(index), value: unwrap_impl(value), label: unwrap_impl(label), force: unwrap_impl(force), noWaitAfter: unwrap_impl(noWaitAfter), timeout: unwrap_impl(timeout)))
+    end
+
+    # This method waits for [actionability](./actionability.md) checks, then focuses the element and selects all its text
+    # content.
+    def select_text(force: nil, timeout: nil)
+      wrap_impl(@impl.select_text(force: unwrap_impl(force), timeout: unwrap_impl(timeout)))
+    end
+
+    # This method expects `element` to point to an
+    # [input element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input).
+    #
+    # 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 the current working directory. For empty array, clears the selected files.
+    def set_input_files(files, noWaitAfter: nil, timeout: nil)
+      wrap_impl(@impl.set_input_files(unwrap_impl(files), noWaitAfter: unwrap_impl(noWaitAfter), timeout: unwrap_impl(timeout)))
+    end
+    alias_method :input_files=, :set_input_files
+
+    # This method taps the element by performing the following steps:
+    # 1. Wait for [actionability](./actionability.md) checks on the element, unless `force` option is set.
+    # 1. Scroll the element into view if needed.
+    # 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.
+    #
+    # If the element is detached from the DOM at any moment during the action, this method throws.
+    #
+    # When all steps combined have not finished during the specified `timeout`, this method throws a `TimeoutError`. Passing
+    # zero timeout disables this.
+    #
+    # > NOTE: `element.tap()` requires that the `hasTouch` option of the browser context be set to true.
+    def tap_point(
+          force: nil,
+          modifiers: nil,
+          noWaitAfter: nil,
+          position: nil,
+          timeout: nil,
+          trial: nil)
+      wrap_impl(@impl.tap_point(force: unwrap_impl(force), modifiers: unwrap_impl(modifiers), noWaitAfter: unwrap_impl(noWaitAfter), position: unwrap_impl(position), timeout: unwrap_impl(timeout), trial: unwrap_impl(trial)))
+    end
+
+    # Returns the `node.textContent`.
+    def text_content(timeout: nil)
+      wrap_impl(@impl.text_content(timeout: unwrap_impl(timeout)))
+    end
+
+    # Focuses the element, and then sends a `keydown`, `keypress`/`input`, and `keyup` event for each character in the text.
+    #
+    # To press a special key, like `Control` or `ArrowDown`, use [`method: Locator.press`].
+    #
+    # ```python sync
+    # element.type("hello") # types instantly
+    # element.type("world", delay=100) # types slower, like a user
+    # ```
+    #
+    # An example of typing into a text field and then submitting the form:
+    #
+    # ```python sync
+    # element = page.locator("input")
+    # element.type("some text")
+    # element.press("Enter")
+    # ```
+    def type(text, delay: nil, noWaitAfter: nil, timeout: nil)
+      wrap_impl(@impl.type(unwrap_impl(text), delay: unwrap_impl(delay), noWaitAfter: unwrap_impl(noWaitAfter), timeout: unwrap_impl(timeout)))
+    end
+
+    # This method checks the element by performing the following steps:
+    # 1. Ensure that element is a checkbox or a radio input. If not, this method throws. If the element is already
+    #    unchecked, this method returns immediately.
+    # 1. Wait for [actionability](./actionability.md) checks on the element, unless `force` option is set.
+    # 1. Scroll the element into view if needed.
+    # 1. Use [`property: Page.mouse`] to click in the center of the element.
+    # 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.
+    #
+    # If the element is detached from the DOM at any moment during the action, this method throws.
+    #
+    # When all steps combined have not finished during the specified `timeout`, this method throws a `TimeoutError`. Passing
+    # zero timeout disables this.
+    def uncheck(
+          force: nil,
+          noWaitAfter: nil,
+          position: nil,
+          timeout: nil,
+          trial: nil)
+      wrap_impl(@impl.uncheck(force: unwrap_impl(force), noWaitAfter: unwrap_impl(noWaitAfter), position: unwrap_impl(position), timeout: unwrap_impl(timeout), trial: unwrap_impl(trial)))
+    end
+
+    # @nodoc
+    def to_s
+      wrap_impl(@impl.to_s)
+    end
+  end
+end