Skip to main content
Version: 1.13.0

Handles

Playwright can create handles to the page DOM elements or any other objects inside the page. These handles live in the Playwright process, whereas the actual objects live in the browser. There are two types of handles:

  • JSHandle to reference any JavaScript objects in the page
  • ElementHandle to reference DOM elements in the page, it has extra methods that allow performing actions on the elements and asserting their properties.

Since any DOM element in the page is also a JavaScript object, any ElementHandle is a JSHandle as well.

Handles are used to perform operations on those actual objects in the page. You can evaluate on a handle, get handle properties, pass handle as an evaluation parameter, serialize page object into JSON etc. See the JSHandle class API for these and methods.

API reference#

Here is the easiest way to obtain a JSHandle.

JSHandle jsHandle = page.evaluateHandle("window");//  Use jsHandle for evaluations.
ElementHandle ulElementHandle = page.waitForSelector("ul");//  Use ulElementHandle for actions and evaluation.

Element Handles#

note

It is recommended to use selector-based actions like Page.click(selector[, options]) rather than using the ElementHandle for input actions, unless your use case specifically requires the use of handles.

When ElementHandle is required, it is recommended to fetch it with the Page.waitForSelector(selector[, options]) or Frame.waitForSelector(selector[, options]) methods. These APIs wait for the element to be attached and visible.

// Get the element handleJSHandle jsHandle = page.waitForSelector("#box");ElementHandle elementHandle = jsHandle.asElement();
// Assert bounding box for the elementBoundingBox boundingBox = elementHandle.boundingBox();assertEquals(100, boundingBox.width);
// Assert attribute for the elementString classNames = elementHandle.getAttribute("class");assertTrue(classNames.contains("highlighted"));

Handles as parameters#

Handles can be passed into the Page.evaluate(expression[, arg]) and similar methods. The following snippet creates a new array in the page, initializes it with data and returns a handle to this array into Playwright. It then uses the handle in subsequent evaluations:

// Create new array in page.JSHandle myArrayHandle = page.evaluateHandle("() => {\n" +  "  window.myArray = [1];\n" +  "  return myArray;\n" +  "}");
// Get the length of the array.int length = (int) page.evaluate("a => a.length", myArrayHandle);
// Add one more element to the array using the handleMap<String, Object> arg = new HashMap<>();arg.put("myArray", myArrayHandle);arg.put("newElement", 2);page.evaluate("arg => arg.myArray.add(arg.newElement)", arg);
// Release the object when it is no longer needed.myArrayHandle.dispose();

Handle Lifecycle#

Handles can be acquired using the page methods such as Page.evaluateHandle(expression[, arg]), Page.querySelector(selector) or Page.querySelectorAll(selector) or their frame counterparts Frame.evaluateHandle(expression[, arg]), Frame.querySelector(selector) or Frame.querySelectorAll(selector). Once created, handles will retain object from garbage collection unless page navigates or the handle is manually disposed via the JsHandle.dispose() method.

API reference#