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.
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.
Returns the return value of expression as a JSHandle.
Like evaluate_handle/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
@type evaluate_handle_options() :: [{:expose_functions, boolean()}] | %{optional(:expose_functions) => boolean()}
Options of evaluate_handle/4, see its docs.
@type evaluate_options() :: [{:expose_functions, boolean()}] | %{optional(:expose_functions) => boolean()}
Options of evaluate/4, see its docs.
@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
@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.
@spec dispose(t()) :: :ok | {:error, Playwright.error()}
The Playwright.JSHandle.dispose/1 method stops referencing the element handle.
Since Playwright 1.8.
@spec dispose!(t()) :: :ok
Like dispose/1, but returns the value and raises on error.
@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 toexpression.
Options
:expose_functions(boolean/0) - Since Playwright 1.62. When set totrue, functions passed insideargare exposed in the page and can be called from the page function. Calling one returns aPromiseof its result. Under the hood, each function is exposed viaPlaywright.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 tofalse, in which case functions are not serializable and passing one fails.
@spec evaluate!(t(), String.t(), term() | nil, evaluate_options()) :: term()
Like evaluate/4, but returns the value and raises on error.
@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 toexpression.
Options
:expose_functions(boolean/0) - Since Playwright 1.62. When set totrue, functions passed insideargare exposed in the page and can be called from the page function. Calling one returns aPromiseof its result. Under the hood, each function is exposed viaPlaywright.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 tofalse, in which case functions are not serializable and passing one fails.
@spec evaluate_handle!(t(), String.t(), term() | nil, evaluate_handle_options()) :: t()
Like evaluate_handle/4, but returns the value and raises on error.
@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.
Like get_properties/1, but returns the value and raises on error.
@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
Like get_property/2, but returns the value and raises on error.
@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.
Like json_value/1, but returns the value and raises on error.