com.microsoft.playwright

Interface JSHandle

All Known Subinterfaces:

ElementHandle

public interface JSHandle

JSHandle represents an in-page JavaScript object. JSHandles can be created with the Page.evaluateHandle() method.

 JSHandle windowHandle = page.evaluateHandle("() => window");
 // ...
 

JSHandle prevents the referenced JavaScript object being garbage collected unless the handle is exposed with JSHandle.dispose(). 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 Page.evalOnSelector(), Page.evaluate() and Page.evaluateHandle() methods.

Method Summary

Modifier and Type	Method and Description
ElementHandle	asElement() Returns either null or the object handle itself, if the object handle is an instance of ElementHandle.
void	dispose() The jsHandle.dispose method stops referencing the element handle.
default Object	evaluate(String expression) Returns the return value of expression.
Object	evaluate(String expression, Object arg) Returns the return value of expression.
default JSHandle	evaluateHandle(String expression) Returns the return value of expression as a JSHandle.
JSHandle	evaluateHandle(String expression, Object arg) Returns the return value of expression as a JSHandle.
Map<String,JSHandle>	getProperties() The method returns a map with **own property names** as keys and JSHandle instances for the property values.
JSHandle	getProperty(String propertyName) Fetches a single property from the referenced object.
Object	jsonValue() Returns a JSON representation of the object.

Method Detail

asElement

ElementHandle asElement()

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

dispose

void dispose()

The jsHandle.dispose method stops referencing the element handle.

evaluate

default Object evaluate(String expression)

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:

 ElementHandle tweetHandle = page.querySelector(".tweet .retweets");
 assertEquals("10 retweets", tweetHandle.evaluate("node => node.innerText"));
 

Parameters:

expression - JavaScript expression to be evaluated in the browser context. If it looks like a function declaration, it is interpreted as a function. Otherwise, evaluated as an expression.

evaluate

Object evaluate(String expression,
                Object arg)

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:

 ElementHandle tweetHandle = page.querySelector(".tweet .retweets");
 assertEquals("10 retweets", tweetHandle.evaluate("node => node.innerText"));
 

Parameters:

expression - JavaScript expression to be evaluated in the browser context. If it looks like a function declaration, it is interpreted as a function. Otherwise, evaluated as an expression.

arg - Optional argument to pass to expression.

evaluateHandle

default JSHandle evaluateHandle(String expression)

Returns the return value of expression as a JSHandle.

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

The only difference between jsHandle.evaluate and jsHandle.evaluateHandle is that jsHandle.evaluateHandle returns JSHandle.

If the function passed to the jsHandle.evaluateHandle returns a Promise, then jsHandle.evaluateHandle would wait for the promise to resolve and return its value.

See Page.evaluateHandle() for more details.

Parameters:

expression - JavaScript expression to be evaluated in the browser context. If it looks like a function declaration, it is interpreted as a function. Otherwise, evaluated as an expression.

evaluateHandle

JSHandle evaluateHandle(String expression,
                        Object arg)

Returns the return value of expression as a JSHandle.

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

The only difference between jsHandle.evaluate and jsHandle.evaluateHandle is that jsHandle.evaluateHandle returns JSHandle.

If the function passed to the jsHandle.evaluateHandle returns a Promise, then jsHandle.evaluateHandle would wait for the promise to resolve and return its value.

See Page.evaluateHandle() for more details.

Parameters:

expression - JavaScript expression to be evaluated in the browser context. If it looks like a function declaration, it is interpreted as a function. Otherwise, evaluated as an expression.

arg - Optional argument to pass to expression.

getProperties

Map<String,JSHandle> getProperties()

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

 JSHandle handle = page.evaluateHandle("() => ({window, document}"););
 Map<String, JSHandle> properties = handle.getProperties();
 JSHandle windowHandle = properties.get("window");
 JSHandle documentHandle = properties.get("document");
 handle.dispose();
 

getProperty

JSHandle getProperty(String propertyName)

Fetches a single property from the referenced object.

Parameters:

propertyName - property to get

jsonValue

Object jsonValue()

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 throw an error if the object has circular references.