Recommended Free Tools
Use page.evaluate() when you need property values back in Node.js, and use page.evaluateHandle() with getProperty() or getProperties() when you need to keep working with an object in the page. The difference is whether you need a serialized result or a live in-page reference.
Choose the right Puppeteer method
| What you need | API | What you get |
|---|---|---|
| A few values from an object in Node.js | page.evaluate() |
A serialized and reconstructed value |
| A reference to an object that stays in the page | page.evaluateHandle() |
A JSHandle, or an ElementHandle for an element |
| One property from an existing handle | handle.getProperty(name) |
A handle for that property’s value |
| Properties represented by an existing handle | handle.getProperties() |
A Map<string, JSHandle> |
For ordinary data extraction, prefer evaluate() and return only the values your Node.js code needs. Use handles when you need to continue interacting with the original page-side object, or when the result is a DOM element.
As an Amazon Associate I earn from qualifying purchases.
Return property values with page.evaluate()
The callback runs in the browser page context. Read and shape the values there, then return a serializable result such as a primitive, array, or plain object:
The Tool Desk
Outbyte Driver Updater FREEScan for outdated or missing drivers - takes under a minuteDriver Scan →Outbyte PC Repair FREEClear out junk files and repair common Windows errorsFree Scan →const data = await page.evaluate(() => {
const item = window.somePageObject;
return {
title: item.title,
count: item.count,
};
});
console.log(data.title, data.count);evaluate() awaits a promise returned by the callback. Its result crosses from the page into Node.js as serialized data; it is not a live reference to the original object.
#1 Best Overall
Pass Node.js values as arguments
The callback is serialized and evaluated in the page. It cannot access Node.js lexical variables or call helper functions defined only in Node.js. Pass values as arguments instead:
const propertyName = 'title';
const value = await page.evaluate((name) => {
return window.somePageObject[name];
}, propertyName);Keep the page-side logic inside the callback, or pass in the data it needs. This also makes the boundary between Node.js and the page explicit.
Rank #2
Get one property from an object handle
Use evaluateHandle() to retain an in-page reference, then call getProperty() for one property. The method fetches a handle for that property’s value, so call jsonValue() if you need an ordinary serializable value in Node.js:
const objectHandle = await page.evaluateHandle(() => window.somePageObject);
const titleHandle = await objectHandle.getProperty('title');
try {
const title = await titleHandle.jsonValue();
console.log(title);
} finally {
await titleHandle.dispose();
await objectHandle.dispose();
}For getProperty()‘s documented behavior, see the Puppeteer JSHandle.getProperty() API reference.
Enumerate properties with getProperties()
getProperties() returns a map of handles representing properties of the current handle. Convert only the property handles you actually need. This example reads two named properties from the map:
const objectHandle = await page.evaluateHandle(() => window.somePageObject);
const properties = await objectHandle.getProperties();
try {
const titleHandle = properties.get('title');
const countHandle = properties.get('count');
const title = titleHandle ? await titleHandle.jsonValue() : undefined;
const count = countHandle ? await countHandle.jsonValue() : undefined;
console.log({ title, count });
} finally {
for (const propertyHandle of properties.values()) {
await propertyHandle.dispose();
}
await objectHandle.dispose();
}This retrieves properties represented in the returned map; do not treat it as a guarantee that every JavaScript property category is included. The official API describes the result as “a map of handles representing the properties of the current handle.” See JSHandle.getProperties().
Rank #4
Handle DOM elements as elements
An ordinary evaluate() return is designed for serializable data, not a usable Node-side DOM object. Returning a DOM node this way can produce an unexpected empty-looking object. For a page element, use handle-based evaluation and keep the resulting element handle:
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
const bodyHandle = await page.evaluateHandle(() => document.body);
const isElementHandle = bodyHandle.asElement() !== null;
console.log(isElementHandle);
await bodyHandle.dispose();When enumerating DOM children, property handles can be checked with asElement(); element results can then be used as ElementHandles rather than converted into ordinary object data.
Dispose handles when finished
A JSHandle keeps its referenced page object from being garbage-collected. Dispose property handles and parent handles after use, as in the examples. Puppeteer also automatically disposes handles when their frame navigates away or their parent execution context is destroyed, but explicit disposal makes the lifecycle clear in code that completes normally.
Common errors and fixes
- The result is empty-looking or not a DOM object: a node returned through
evaluate()is not a live Node-side DOM reference. UseevaluateHandle()for an element handle, or extract the specific text, attributes, or other serializable values inevaluate(). - A callback cannot see a Node.js variable: page callbacks run in the browser context after serialization. Pass the value as an argument rather than closing over it.
- A property result is not a plain value:
getProperty()andgetProperties()return handles. CalljsonValue()for serializable values, or continue using the handle where a page-side reference is required. - Property enumeration misses something expected:
getProperties()provides the properties represented by its returned map, not a documented exhaustive reflection of all possible JavaScript property categories. For a known property, request it by name withgetProperty(). - Handles accumulate during repeated work: dispose the property handles and their owning handle when finished; do not rely solely on navigation or context destruction for cleanup.
When to use queryObjects()
page.queryObjects(prototypeHandle) is a specialized heap-inspection method: it finds objects with a specified prototype and returns a handle to an array. It is not needed to read a property from an object you already have.
Or skip the browser setup
If the goal is a screenshot rather than reading JavaScript properties, ScreenshotNeo is a website screenshot API with a one-request capture. For example, this cURL request saves a WebP shot of Stripe:
Quick wins for a faster PC:
Scan for outdated or missing drivers - takes under a minuteDriver Scan →Repair Windows errors before they cause bigger problemsFix Now →Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpSee the ScreenshotNeo API documentation for request options. ScreenshotNeo accepts cookie or consent banners before capture and removes 60+ known consent platforms, newsletter popups, and chat widgets; each cleanup step can be disabled. Bot checks, blank pages, timeouts, failed loads, and cache hits cost nothing, and response headers identify the page verdict and billing status. Its MCP server provides take_screenshot, get_page_info, and capture_pdf for AI agents. The free plan includes 1,000 shots a month with no card; paid plans start at $5 for 3,000.
Sign up for ScreenshotNeo and get 1,000 free screenshots a month with no card.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
