JSHandle

JSHandle represents an in-page JavaScript object reference

JSHandle 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 from being garbage collected unless the handle is disposed. JSHandles are automatically disposed when their origin frame gets navigated or the parent context gets destroyed.

JSHandle instances can be used as arguments for page.evaluate().

Methods

evaluate

Evaluates a function in the browser context with this handle as the first argument.

pageFunction · function · required

Function to be evaluated in the page context

arg · any

Optional argument to pass to the function

Returns: Promise<R> - Promise that resolves to the return value of the function

const tweetHandle = await page.evaluateHandle(() => document.querySelector('.tweet'));
const text = await tweetHandle.evaluate(node => node.innerText);

evaluateHandle

Evaluates a function in the browser context with this handle as the first argument, returns a JSHandle.

pageFunction · function · required

Function to be evaluated

arg · any

Optional argument to pass to the function

Returns: Promise<JSHandle> - Promise that resolves to a JSHandle

const aHandle = await page.evaluateHandle(() => document.body);
const bHandle = await aHandle.evaluateHandle(body => body.firstChild);

getProperty

Fetches a single property from the referenced object.

propertyName · string · required

Name of the property to get

Returns: Promise<JSHandle> - Promise that resolves to a JSHandle of the property value

const handle = await page.evaluateHandle(() => ({ foo: 'bar' }));
const fooHandle = await handle.getProperty('foo');
const fooValue = await fooHandle.jsonValue();
console.log(fooValue); // 'bar'

getProperties

Returns a map with property names as keys and JSHandle instances for property values.

Returns: Promise<Map<string, JSHandle>> - Map of property names to JSHandles

const handle = await page.evaluateHandle(() => ({ a: 1, b: 'two' }));
const map = await handle.getProperties();
const aHandle = map.get('a');
const aValue = await aHandle.jsonValue();
console.log(aValue); // 1

jsonValue

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

Returns: Promise<T> - JSON representation of the object

const handle = await page.evaluateHandle(() => ({ foo: 'bar' }));
const json = await handle.jsonValue();
console.log(json); // { foo: 'bar' }

The method will throw an error if the referenced object is not stringifiable. It will also throw if the object has circular references.

asElement

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

Returns: ElementHandle | null - ElementHandle pointing to the referenced object or null

const handle = await page.evaluateHandle(() => document.body);
const element = handle.asElement();
// element is an ElementHandle

dispose

Stops referencing the element handle and disposes it.

Returns: Promise<void>

const handle = await page.evaluateHandle(() => document.body);
await handle.dispose();

Examples

Working with object properties

import { test } from '@playwright/test';

test('extract object properties', async ({ page }) => {
  await page.goto('https://example.com');
  
  const handle = await page.evaluateHandle(() => ({
    name: 'John',
    age: 30,
    address: { city: 'New York' }
  }));
  
  // Get all properties
  const properties = await handle.getProperties();
  const nameHandle = properties.get('name');
  const name = await nameHandle.jsonValue();
  console.log(name); // 'John'
  
  // Get nested property
  const addressHandle = properties.get('address');
  const address = await addressHandle.jsonValue();
  console.log(address); // { city: 'New York' }
  
  await handle.dispose();
});

Passing JSHandles to evaluate

const aHandle = await page.evaluateHandle(() => document.body);
const resultHandle = await page.evaluateHandle(
  ([body, suffix]) => body.textContent + suffix,
  [aHandle, ' - modified']
);
const result = await resultHandle.jsonValue();
console.log(result);
await aHandle.dispose();
await resultHandle.dispose();

Working with arrays

const arrayHandle = await page.evaluateHandle(() => [1, 2, 3]);

// Get array length
const length = await arrayHandle.evaluate(arr => arr.length);
console.log(length); // 3

// Get array values
const values = await arrayHandle.jsonValue();
console.log(values); // [1, 2, 3]

await arrayHandle.dispose();

Related

• Page.evaluateHandle() - Create a JSHandle
• ElementHandle - Subclass representing DOM elements
• Frame.evaluateHandle() - Evaluate and get JSHandle in frame