Puppeteer API Reference: Classes, Methods, and Types

Puppeteer’s API reference is the navigable index of its documented classes, enumerations, functions, interfaces, namespaces, variables, and type aliases. The reference reviewed for this guide is labeled version 25.12.0; that is the documentation version, not a guarantee about the version installed in your project. Match method signatures, options, browser support, and experimental features to the documentation for your installed release. Start at the Puppeteer API Reference, then follow links to the exact class or method you need.

The practical lifecycle is launch or connect to a browser → create a page → navigate and interact → collect a result or artifact → close the browser. In Node.js, the puppeteer package exposes Node-specific behavior, including browser fetching and downloading, through PuppeteerNode, which extends the shared Puppeteer API.

1. Where is the Puppeteer API reference?

The official reference is at pptr.dev/api. It is organized by API type and member, rather than as a single linear tutorial. Use the getting started guide to learn the workflow, then consult the individual reference entries for signatures, overloads, parameters, return values, support, and deprecation or experimental status.

1. Check the version of Puppeteer your project uses in its package manifest or lockfile.
2. Open the documentation for that release. Do not assume the current API index matches an older installed package.
3. Search for the class or method that owns the operation. For example, page navigation and page evaluation belong to Page.
4. Read the exact method page before relying on an option, return type, error behavior, or browser requirement.
5. Prefer documented public factories and accessors. Many classes have internal constructors and are not extension points.

The reference is broad by design. This guide gives you a map of the common concepts and points to the primary documentation for exact details; it does not replace the version-specific method entries.

2. How do Browser, BrowserContext, and Page fit together?

A Browser represents a launched or connected browser instance. A BrowserContext scopes isolated browser storage, including cookies and local storage. A Page represents a browser tab (or an extension background page) and is the main high-level surface for navigation, DOM access, waiting, input, evaluation, and screenshots. One browser can contain multiple pages. A popup belongs to the context of its parent page.

Think of the objects by scope:

Object	Scope and role	Typical use
Browser	Whole browser instance	Launch or connect, create contexts or pages, manage browser lifetime.
BrowserContext	Isolated session storage within a browser	Separate cookies and local storage for independent sessions.
Page	One tab or extension background page	Navigate, find elements, interact, evaluate, wait, capture output.
Frame	A document within a page	Work with content in an iframe or the main document.

Use the lifecycle and ownership documented in the relevant class pages when adding contexts, pages, or frames to a longer-running process. Close resources at the scope where they were created; in a short script, closing the browser at the end is the simplest cleanup strategy.

3. A complete Node.js example

The official getting started workflow launches a browser, creates a page, navigates, interacts, reads a value, and closes the browser. This compact runnable example shows that shape. Install the package with npm install puppeteer, save as example.js, then run node example.js.

const puppeteer = require('puppeteer');

async function main() {
  const browser = await puppeteer.launch();
  try {
    const page = await browser.newPage();
    await page.setViewport({ width: 1280, height: 800 });
    await page.goto('https://pptr.dev/', { waitUntil: 'domcontentloaded' });

    const title = await page.title();
    const heading = await page.$eval('h1', element => element.textContent?.trim() ?? '');
    console.log({ title, heading });
  } finally {
    await browser.close();
  }
}

main().catch(error => {
  console.error(error);
  process.exitCode = 1;
});

launch is the common way to start a browser, while connect attaches to an existing instance. Navigation options and defaults can vary by release, so check the matching Page.goto and launch reference pages when configuring a real job. If you already have a browser connection, follow its documented ownership rules before closing it.

4. Which Page methods should I use?

Page inherits from EventEmitter and collects the higher-level operations most scripts need. The official Page class reference is the source of truth for all members. These common method distinctions prevent frequent mistakes:

Need	API shape	Behavior to remember
Find one element	page.$(selector)	Returns the first matching handle, or null when none matches.
Find all elements	page.$$(selector)	Returns all matching handles, or an empty array.
Read from one match	page.$eval(selector, callback)	Calls the page function with the first element; throws if there is no match.
Read from all matches	page.$$eval(selector, callback)	Passes the matching element array to the page function.
Perform retryable actions	Locator	Locators describe a strategy; failed actions are retried and preconditions are checked automatically. Read the interactions guide for behavior and configuration.
Access a DOM node directly	ElementHandle	Use when a direct node reference is needed; dispose of handles when finished.
Access a page JavaScript object	JSHandle	References a JavaScript object and keeps it from garbage collection until disposed, subject to documented automatic disposal cases.

For interactions, prefer the Locator abstraction where it suits the task; it is more than a selector alias. Use handles when the operation genuinely needs a persistent reference to a particular DOM element or JavaScript object. In TypeScript, an ElementHandle<HTMLSelectElement> can provide element-specific type checking.

Selection and page evaluation

Use $ and $$ for handle-oriented selection, and $eval or $$eval for a direct page-side read or transformation. A callback passed to $eval or $$eval can return a promise; Puppeteer waits for it. Handle the missing-element case deliberately: check the result of $ before accessing a handle, or use a method whose documented behavior matches your intended failure policy.

Text input and special keys

page.type(selector, text) emits keyboard events for each character. For special keys such as Control or ArrowDown, use the keyboard API, for example page.keyboard.press('ArrowDown'). Virtual keyboard behavior is not identical to every native operating-system shortcut; the Page reference specifically notes that macOS shortcuts such as Command+A do not work in the documented virtual keyboard behavior.

Navigation and event ordering

waitForNavigation waits for navigation or reload and treats History API URL changes as navigation. When a click or other action causes navigation, set up the wait around the triggering action so the navigation event cannot occur before the wait is registered. Check the method page for the current supported options and examples.

const navigation = page.waitForNavigation();
await page.click('a.next');
await navigation;

Some prompts must be registered before the action that opens them. In particular, register waitForDevicePrompt or waitForFileChooser before triggering the corresponding prompt. The reference also documents limitations around DOM file-picker APIs.

5. Classes and types beyond Page

The API index includes far more than Page. These concepts help choose the right abstraction level:

• Locator: A strategy for locating objects and performing actions, with retry and precondition behavior documented by Puppeteer. Use the interactions guide for details.
• ElementHandle and JSHandle: References to DOM elements and JavaScript objects. Referenced objects are kept alive until disposal, with automatic disposal in documented navigation or context-destruction cases.
• HTTPRequest and HTTPResponse: Network events and response details. A 404 or 503 is still a completed HTTP request, so it emits requestfinished, not requestfailed. Redirects finish one request and issue another. Do not treat every unsuccessful status code as a network failure.
• CDPSession: A lower-level path to Chrome DevTools Protocol methods and events. Available methods depend on protocol and browser capabilities. The API documents UnsupportedOperation for operations the protocol does not support.
• Keyboard and Mouse: Virtual input surfaces. Distinguish text entry from special-key presses, and consult the relevant method pages for supported inputs.
• Tracing and Coverage: Specialized surfaces for collecting traces and JavaScript or CSS coverage.

Many reference entries describe internal constructors. Use Puppeteer’s documented access paths rather than instantiating or subclassing these classes yourself. The project’s contribution guidance explains that the public API is identified in source with TSDoc tags and that API documentation is generated and versioned on release.

6. Browser binaries and compatibility

The separate @puppeteer/browsers programmatic API supports installing, launching, locating, and managing browser binaries. Puppeteer states that Chrome for Testing is its default provider and the browser binary it tests and guarantees. Custom providers are not officially supported; teams choosing one own compatibility checks, feature testing, and maintenance as Puppeteer and download sources change.

Do not infer that every Chromium-derived browser has identical support. For a reproducible automation environment, record the Puppeteer package version and browser build, use the documented provider and installation path, and verify any protocol-dependent behavior against the actual browser you deploy.

7. Version, types, and experimental entries

The version label on the reference reviewed here is 25.12.0. Your project may use another release, so verify the installed dependency before copying method names or options. Experimental entries can have additional browser requirements and flags. For example, the Page reference marks Page.webmcp experimental and documents a Chrome 151+ requirement plus a feature flag; verify that entry on the current versioned page before depending on it.

In TypeScript, use the types exposed by the installed package and the exact method page for parameter and return types. Avoid assuming a method is public because it appears in implementation code: the published reference is the supported surface, and internal constructors are not intended as user-facing extension points.

8. Troubleshooting common API mistakes

Symptom	Likely cause	Fix
$eval throws for an element that is not present	$eval requires a match.	Wait for the expected state or use $ and handle its null result when absence is valid.
A selector query returns nothing	The element may not exist yet, may be inside a frame, or the selector may not match.	Check the selector and page state, wait using the appropriate documented mechanism, and target the correct frame when needed.
A click navigation wait hangs or misses navigation	The wait was attached after the action, or the action did not navigate.	Register waitForNavigation before the action; verify whether the page uses a navigation, History API change, or an in-page update.
HTTP error status is not reported as a failed request	HTTP 404 and 503 responses still complete at the network-request level.	Inspect the response status separately; reserve requestfailed for actual request failures.
Special keyboard shortcut has no effect	Text typing and special-key presses are different, and virtual input is not fully native-equivalent.	Use the keyboard API for special keys and check documented platform limitations.
A file chooser or device prompt wait misses its event	The listener was registered after the event-triggering action.	Register the appropriate wait first, then trigger the action.
A CDP method rejects or is unavailable	The protocol or connected browser does not support that operation.	Check browser/protocol capability and handle documented unsupported-operation errors.
Behavior differs from an example found online	The example may target another Puppeteer version or browser build.	Match documentation to the installed package and verify the browser version and experimental feature requirements.
Custom browser binary behaves differently	Puppeteer’s guaranteed browser coverage is Chrome for Testing, not arbitrary custom providers.	Use the documented supported binary where possible; otherwise own compatibility and feature testing.

9. Reliability, performance, and cost considerations

The API reference does not provide a universal performance benchmark, and this guide makes no speed claim. Reliability depends on matching the library and browser versions, waiting for the state your task actually needs, handling absent elements and failed requests explicitly, and cleaning up browser resources. For navigation-triggered actions, register event waits before the action. For request monitoring, distinguish HTTP status failures from transport failures. For handles, dispose of references when they are no longer needed.

Launching a browser, maintaining browser binaries, and operating automation infrastructure all have resource and maintenance costs, but no single cost applies to every deployment. Measure your own workload and deployment environment. If the task is simply to obtain a web page screenshot, a screenshot API can avoid managing a browser binary and automation lifecycle; ScreenshotNeo is one option described below.

10. Or skip the browser setup

For a screenshot, ScreenshotNeo accepts one GET request and returns a PNG, JPEG, WebP, or PDF. Its API options include full-page capture with lazy images loaded, element capture by CSS selector, viewport and device presets, dark mode, custom CSS or JavaScript, wait conditions, request blocking, caching, asynchronous jobs, and bulk capture. See the ScreenshotNeo API documentation.

curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp

import requests

r = requests.get(
    "https://api.screenshotneo.com/v1/shot",
    params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"},
    timeout=90,
)
open("shot.webp", "wb").write(r.content)

const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);
if (!res.ok) throw new Error(`Screenshot request failed: ${res.status}`);
const bytes = new Uint8Array(await res.arrayBuffer());
await import('node:fs/promises').then(fs => fs.writeFile('shot.webp', bytes));

Cookie banners, newsletter popups, and chat widgets are removed before the screenshot; each cleanup step can be turned off. Bot checks, blank pages, timeouts, failed loads, and cache hits are never billed, and response headers identify the page verdict and billing status. Its MCP server offers take_screenshot, get_page_info, and capture_pdf tools for Claude, Cursor, and other MCP clients. The free plan includes 1,000 screenshots per month without a card; paid plans start at $5 for 3,000 screenshots. See ScreenshotNeo and sign up for 1,000 free screenshots a month with no card.

11. Frequently asked questions

Does the API reference cover every Puppeteer method?

It organizes the documented public API, including classes and members. Use the reference entry for the exact release rather than treating implementation details as supported API.

Should I instantiate API classes directly?

Usually no. Many classes document internal constructors. Follow their documented factory, accessor, or owning-object path.

Can I use Puppeteer with any Chromium browser?

Puppeteer says Chrome for Testing is the binary it tests and guarantees. Other providers require your own compatibility work.

Where should I look for the exact signature of a method?

Open that method’s entry from the version-matched API reference. The class overview is a useful map, but method pages carry the precise options, return types, and caveats.

Primary references: API index, Page class, getting started guide, browser API, and contribution guidance.