JSHandle
Added in: v1.8JSHandle represents an in-page JavaScript object. JSHandles can be created with the page.evaluateHandle() method.
const windowHandle = await 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.$eval(), page.evaluate() and page.evaluateHandle() methods.
Methods
jsHandle.asElement()
Added in: v1.8Returns either null or the object handle itself, if the object handle is an instance of ElementHandle.
Returns
null | ElementHandle
jsHandle.dispose()
Added in: v1.8 asyncThe jsHandle.dispose method stops referencing the element handle.
jsHandle.evaluate()
Added in: v1.8 asyncReturns the return value of pageFunction.
This method passes this handle as the first argument to pageFunction.
If pageFunction returns a [Promise], then handle.evaluate would wait for the promise to resolve and return its value.
Usage
const tweetHandle = await page.$('.tweet .retweets');
expect(await tweetHandle.evaluate(node => node.innerText)).toBe('10 retweets');Arguments
pageFunctionfunction() | stringFunction to be evaluated in the page context.
argEvaluationArgument(optional)Optional argument to pass to
pageFunction.exposeFunctionsboolean(optional) Added in: v1.62When set to
true, functions passed insideargare 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 viapage.exposeFunction(), 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 throws an error.
Returns
Promise<Serializable>
jsHandle.evaluateHandle()
Added in: v1.8 asyncReturns the return value of pageFunction as a JSHandle.
This method passes this handle as the first argument to pageFunction.
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.
Arguments
pageFunctionfunction() | stringFunction to be evaluated in the page context.
argEvaluationArgument(optional)Optional argument to pass to
pageFunction.exposeFunctionsboolean(optional) Added in: v1.62When set to
true, functions passed insideargare 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 viapage.exposeFunction(), 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 throws an error.
Returns
Promise<JSHandle>
jsHandle.getProperties()
Added in: v1.8 asyncThe method returns a map with own property names as keys and JSHandle instances for the property values.
Usage
const handle = await page.evaluateHandle(() => ({ window, document }));
const properties = await handle.getProperties();
const windowHandle = properties.get('window');
const documentHandle = properties.get('document');
await handle.dispose();Returns
Promise<Map<string, JSHandle>>
jsHandle.getProperty()
Added in: v1.8 asyncFetches a single property from the referenced object.
Arguments
Returns
Promise<JSHandle>
jsHandle.jsonValue()
Added in: v1.8 asyncReturns a JSON representation of the object. If the object has a toJSON function, it will not be called.
INFO
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.
Returns
Promise<Serializable>