Playwright.JSHandle (Playwright v1.65.0-rc.3)

Copy Markdown View Source

JSHandle represents an in-page JavaScript object. JSHandles can be created with the Playwright.Page.evaluate_handle/4 method.

window_handle = Page.evaluate_handle!(page, "() => window")
# ...

JSHandle prevents the referenced JavaScript object being garbage collected unless the handle is exposed with Playwright.JSHandle.dispose/1. JSHandles are auto-disposed when their origin frame gets navigated or the parent context gets destroyed.

JSHandle instances can be used as an argument in Playwright.Page.eval_on_selector/4, Playwright.Page.evaluate/4 and Playwright.Page.evaluate_handle/4 methods.

Since Playwright 1.8.

The examples alias the modules they use (alias Playwright.{Locator, Page}).

Summary

Types

Options of evaluate_handle/4, see its docs.

Options of evaluate/4, see its docs.

t()

A JSHandle handle. Compare handles with ==, their fields are internal.

Functions

Returns either nil or the object handle itself, if the object handle is an instance of ElementHandle.

The Playwright.JSHandle.dispose/1 method stops referencing the element handle.

Like dispose/1, but returns the value and raises on error.

Returns the return value of expression.

Like evaluate/4, but returns the value and raises on error.

The method returns a map with own property names as keys and JSHandle instances for the property values.

Like get_properties/1, but returns the value and raises on error.

Fetches a single property from the referenced object.

Like get_property/2, but returns the value and raises on error.

Returns a JSON representation of the object. If the object has a toJSON function, it will not be called.

Like json_value/1, but returns the value and raises on error.

Types

evaluate_handle_options()

@type evaluate_handle_options() ::
  [{:expose_functions, boolean()}] | %{optional(:expose_functions) => boolean()}

Options of evaluate_handle/4, see its docs.

evaluate_options()

@type evaluate_options() ::
  [{:expose_functions, boolean()}] | %{optional(:expose_functions) => boolean()}

Options of evaluate/4, see its docs.

t()

@type t() ::
  %Playwright.JSHandle{
    conn: term(),
    guid: term(),
    initializer: term(),
    table: term(),
    type: term()
  }
  | %Playwright.ElementHandle{
      conn: term(),
      guid: term(),
      initializer: term(),
      table: term(),
      type: term()
    }

A JSHandle handle. Compare handles with ==, their fields are internal.

Functions

as_element(js_handle)

@spec as_element(t()) :: nil | Playwright.ElementHandle.t()

Returns either nil or the object handle itself, if the object handle is an instance of ElementHandle.

Since Playwright 1.8.

dispose(js_handle)

@spec dispose(t()) :: :ok | {:error, Playwright.error()}

The Playwright.JSHandle.dispose/1 method stops referencing the element handle.

Since Playwright 1.8.

dispose!(js_handle)

@spec dispose!(t()) :: :ok

Like dispose/1, but returns the value and raises on error.

evaluate(js_handle, expression, arg \\ nil, options \\ [])

@spec evaluate(t(), String.t(), term() | nil, evaluate_options()) ::
  {:ok, term()} | {:error, Playwright.error()}

Returns the return value of expression.

This method passes this handle as the first argument to expression.

If expression returns a Promise, then Playwright.JSHandle.evaluate/4 would wait for the promise to resolve and return its value.

Usage

tweet_handle = Page.query_selector!(page, ".tweet .retweets")
assert JSHandle.evaluate!(tweet_handle, "node => node.innerText") == "10 retweets"

Since Playwright 1.8.

Arguments

  • expression - Function to be evaluated in the page context.
  • arg - Optional argument to pass to expression.

Options

  • :expose_functions (boolean/0) - Since Playwright 1.62. When set to true, functions passed inside arg are exposed in the page and can be called from the page function. Calling one returns a Promise of its result. Under the hood, each function is exposed via Playwright.Page.expose_function/3, so it is technically accessible from all frames of the page. Exposed functions are cleared upon the top-level navigation. Defaults to false, in which case functions are not serializable and passing one fails.

evaluate!(js_handle, expression, arg \\ nil, options \\ [])

@spec evaluate!(t(), String.t(), term() | nil, evaluate_options()) :: term()

Like evaluate/4, but returns the value and raises on error.

evaluate_handle(js_handle, expression, arg \\ nil, options \\ [])

@spec evaluate_handle(t(), String.t(), term() | nil, evaluate_handle_options()) ::
  {:ok, t()} | {:error, Playwright.error()}

Returns the return value of expression as a JSHandle.

This method passes this handle as the first argument to expression.

The only difference between Playwright.JSHandle.evaluate/4 and Playwright.JSHandle.evaluate_handle/4 is that Playwright.JSHandle.evaluate_handle/4 returns JSHandle.

If the function passed to the Playwright.JSHandle.evaluate_handle/4 returns a Promise, then Playwright.JSHandle.evaluate_handle/4 would wait for the promise to resolve and return its value.

See Playwright.Page.evaluate_handle/4 for more details.

Since Playwright 1.8.

Arguments

  • expression - Function to be evaluated in the page context.
  • arg - Optional argument to pass to expression.

Options

  • :expose_functions (boolean/0) - Since Playwright 1.62. When set to true, functions passed inside arg are exposed in the page and can be called from the page function. Calling one returns a Promise of its result. Under the hood, each function is exposed via Playwright.Page.expose_function/3, so it is technically accessible from all frames of the page. Exposed functions are cleared upon the top-level navigation. Defaults to false, in which case functions are not serializable and passing one fails.

evaluate_handle!(js_handle, expression, arg \\ nil, options \\ [])

@spec evaluate_handle!(t(), String.t(), term() | nil, evaluate_handle_options()) ::
  t()

Like evaluate_handle/4, but returns the value and raises on error.

get_properties(js_handle)

@spec get_properties(t()) :: {:ok, term()} | {:error, Playwright.error()}

The method returns a map with own property names as keys and JSHandle instances for the property values.

Usage

handle = Page.evaluate_handle!(page, "() => ({ window, document })")
properties = JSHandle.get_properties!(handle)
window_handle = properties["window"]
document_handle = properties["document"]
JSHandle.dispose!(handle)

In Elixir, the result is a map of property name to handle; unlike JS's Map, it does not keep the property order.

Since Playwright 1.8.

get_properties!(js_handle)

@spec get_properties!(t()) :: term()

Like get_properties/1, but returns the value and raises on error.

get_property(js_handle, property_name)

@spec get_property(t(), String.t()) :: {:ok, t()} | {:error, Playwright.error()}

Fetches a single property from the referenced object.

Since Playwright 1.8.

Arguments

  • property_name - property to get

get_property!(js_handle, property_name)

@spec get_property!(t(), String.t()) :: t()

Like get_property/2, but returns the value and raises on error.

json_value(js_handle)

@spec json_value(t()) :: {:ok, term()} | {:error, Playwright.error()}

Returns a JSON representation of the object. If the object has a toJSON function, it will not be called.

Note

The method will return an empty JSON object if the referenced object is not stringifiable. It will fail if the object has circular references.

Since Playwright 1.8.

json_value!(js_handle)

@spec json_value!(t()) :: term()

Like json_value/1, but returns the value and raises on error.