Playwright.ElementHandle (playwright v0.1.16-preview-3) View Source

ElementHandle represents an in-page DOM element.

ElementHandles can be created with the Playwright.Page.query_selector/3 function, and similar.

⚠️ DISCOURAGED

The use of Playwright.ElementHandle is discouraged; use Playwright.Locator instances and web-first assertions instead.

Example

{:ok, handle} = Page.q(page, "a")
:ok = ElementHandle.click(handle)

ElementHandle prevents DOM elements from garbage collection unless the handle is disposed with Playwright.JSHandle.dispose/1. ElementHandles are auto-disposed when their origin frame is navigated.

An ElementHandle instance can be used as an argument in Playwright.Page.eval_on_selector/5 and Playwright.Page.evaluate/3.

NOTE

In most cases, you would want to use Playwright.Locator instead. You should only use ElementHandle if you want to retain a handle to a particular DOM node that you intend to pass into Playwright.Page.evaluate/3 as an argument.

The difference between Playwright.Locator and ElementHandle is that ElementHandle points to a particular element, while Playwright.Locator captures the logic of how to retrieve an element.

In the example below, handle points to a particular DOM element on the page. If that element changes text or is used by JavaScript to render an entirely different component, handle still points to that very DOM element. This can lead to unexpected behaviors.

{:ok, handle} = Page.q("text=Submit")
ElementHandle.hover(handle)
ElementHandle.click(handle)

With the Playwright.Locator, every time the locator is used, an up-to-date DOM element is located in the page using the selector. So, in the snippet below, the underlying DOM element is going to be located twice.

{:ok, locator} = Page.locator("text=Submit")
Locator.hover(locator)
Locator.click(locator)

Link to this section Summary

Types

A map/struct providing call options

t()

%Playwright.ElementHandle{}

Functions

Clicks on the element, performing the following steps

Returns the Playwright.Frame for element handles referencing iframe nodes, or `nil otherwise.

Returns the value of an element's attribute.

Searches within an element for a DOM element matching the given selector.

Returns the node.textContent (all text within the element).

Link to this section Types

Specs

options() :: map()

A map/struct providing call options

Specs

t() :: %Playwright.ElementHandle{
  connection: term(),
  guid: term(),
  listeners: term(),
  parent: term(),
  preview: term(),
  type: term()
}

%Playwright.ElementHandle{}

Link to this section Functions

Link to this function

click(owner, options \\ %{})

View Source

Specs

click(t() | {:ok, t()}, options()) :: :ok

Clicks on the element, performing the following steps:

  1. Wait for "actionability (guide)" checks on the element, unless force: true option is set.
  2. Scroll the element into view, if needed.
  3. Use Playwright.Page.Mouse to click the center of the elemnt, or the specified option: position.
  4. Wait for initiated navigations to either succeed or fail, unless no_wait_after: true option is set.

If the element is detached from the DOM at any moment during the action, this function raises.

When all steps combined have not finished during the specified :timeout, this function raises a TimeoutError. Passing zero (0) for timeout disables this.

Specs

content_frame(t() | {:ok, t()}) :: {:ok, Playwright.Frame.t() | nil}

Returns the Playwright.Frame for element handles referencing iframe nodes, or `nil otherwise.

Link to this function

get_attribute(owner, name)

View Source

Specs

get_attribute(t() | {:ok, t()}, binary()) :: {:ok, binary() | nil}

Returns the value of an element's attribute.

See Playwright.ElementHandle.query_selector/2.

Link to this function

query_selector(owner, selector)

View Source

Specs

query_selector(t() | {:ok, t()}, binary()) :: {:ok, t() | nil}

Searches within an element for a DOM element matching the given selector.

Finds an element matching the specified selector within the subtree of the ElementHandle. See "working with selectors (guide)" for more details.

If no elements match the selector, returns nil.

Specs

text_content(t() | {:ok, t()}) :: {:ok, binary() | nil}

Returns the node.textContent (all text within the element).