The official Puppeteer API Reference is the source for exact class, method, and type details; its index labels the documentation version 25.12.0. That label may not match the version installed in your project, so consult the reference for your dependency before relying on a signature, option, browser requirement, or experimental feature. For implementation, follow Puppeteer’s lifecycle: launch or connect to a browser, create a page, interact with it, collect a result, and close the browser.
Where is the Puppeteer API reference?
The API Reference is a navigable index of documented classes, enumerations, functions, interfaces, namespaces, variables, and type aliases—not a linear tutorial. Open the relevant type or member page for its current signature, overloads, options, return value, support status, and deprecation notes. The reference version label observed here is 25.12.0; match documentation to the Puppeteer version in your package rather than assuming that label describes every installation.
For the workflow that gives these entries context, start with the official Getting Started guide. Puppeteer’s API docs are generated from TSDoc and published with releases. Many classes say their constructors are internal: use documented factories and accessors instead of constructing or subclassing those classes directly. See the project’s contribution guidance for how the public API is distinguished from internal implementation.
How do Browser, BrowserContext, and Page fit together?
Think in terms of lifecycle and scope. A Browser is the launched or connected browser instance. A BrowserContext provides an isolated storage context, including cookies and local storage. A Page represents a browser tab or extension background page; one browser can contain multiple pages. Popups belong to the context of the page that opened them. Use the relevant entries in the API Reference to confirm current details for your specific operation.
PC Slower Than It Used to Be?
A free scan shows the junk files, broken settings and background clutter dragging Windows down - then fixes them in one click.Free scan · Windows 10 & 11Crashes, No Sound, or Screen Glitches?
Random freezes, missing sound and display glitches usually trace back to one bad driver. Find and replace yours safely.Free scan · under a minute#1 Best Overall
- Launch or connect: In Node.js,
puppeteerexposesPuppeteerNode, which extends the sharedPuppeteerclass and adds Node-specific browser fetching and downloading behavior.launchstarts a browser;connectattaches to an existing browser. - Create a page: Create a page through the browser and choose the relevant context for the storage isolation your workflow needs.
- Navigate and interact: Use the page-level APIs for navigation, waiting, selection, input, evaluation, and capture.
- Collect and clean up: Read the result or artifact you need, then close the browser when your work is complete.
A minimal Node.js lifecycle, adapted from the official getting-started workflow, looks like this:
const puppeteer = require('puppeteer');
(async () => {
const browser = await puppeteer.launch();
try {
const page = await browser.newPage();
await page.goto('https://example.com');
console.log(await page.title());
} finally {
await browser.close();
}
})();For an existing browser, use the documented connect flow instead of launch; the correct connection options depend on your setup and should be taken from the method’s version-matched reference entry.
Which Page methods should I use?
Page is the main high-level surface for tab work. It inherits from EventEmitter and exposes navigation, selection, evaluation, waiting, keyboard and mouse input, screenshots, and more. Its complete member list is on the Page class reference.
Rank #2
- HTML CSS Design and Build Web Sites
- Comes with secure packaging
- It can be a gift option
Locators for actions
A Locator describes a strategy for locating an object and performing an action. The API reference describes automatic precondition checks and retries for failed actions. It is more than a selector alias; consult the API Reference and Puppeteer’s interactions documentation for the behavior relevant to your action.
The Tool Desk
Outbyte Driver Updater FREEFix the driver behind crashes, sound loss and screen glitchesFind Drivers →Outbyte PC Repair FREERepair Windows errors before they cause bigger problemsFix Now →Selectors and evaluation
The selector helpers differ in their missing-match behavior, which matters when deciding whether absence is ordinary or exceptional:
| Method | What it does | If no element matches |
|---|---|---|
page.$(selector) |
Finds the first match in the main frame. | Resolves to null. |
page.$$(selector) |
Finds all matches in the main frame. | Returns an empty array. |
page.$eval(selector, fn) |
Passes the first matching element to a page function. | Throws. |
page.$$eval(selector, fn) |
Passes an array of all matching elements to a page function. | The callback receives an empty array. |
If an evaluation callback returns a promise, Puppeteer waits for it. These details are documented on the Page class page.
Rank #3
ElementHandle and JSHandle
ElementHandle and JSHandle represent references to DOM elements and JavaScript objects. A handle keeps its referenced object from being garbage-collected until the handle is disposed; documented navigation and context-destruction cases dispose handles automatically. Prefer a Locator for ordinary actions when its retry and precondition behavior fits. In TypeScript, ElementHandle<HTMLSelectElement> can provide element-specific type checking.
Input and keyboard events
page.type(selector, text) sends keydown, keypress/input, and keyup events for each character. For special keys such as Control or ArrowDown, use the keyboard API’s key-press methods. Puppeteer’s virtual keyboard is not identical to native desktop input: the Page reference notes that macOS shortcuts such as Command+A do not work in its documented virtual keyboard behavior. Check the Page reference for current input methods and caveats.
Free tools Windows power users keep installed
One-click scans. No signup required.
Navigation and event sequencing
waitForNavigation waits for navigation or reload and treats History API URL changes as navigation. When an action may trigger navigation, arrange the wait before triggering the action so the event is not missed; use the current method example in the Page method reference for exact sequencing.
Rank #4
- Brand: Wiley
- Set of 2 Volumes
- A handy two-book set that uniquely combines related technologies Highly visual format and accessible language makes these books highly effective learning tools Perfect for beginning web designers and front-end developers
Register waitForDevicePrompt and waitForFileChooser before the action that opens the prompt or chooser. The reference also describes limitations around DOM file-picker APIs, so check the method entry rather than assuming every browser picker path is supported.
How should I handle network events and lower-level browser APIs?
HTTP request and response events
HTTPRequest and HTTPResponse expose network request and response information. An HTTP 404 or 503 is still a successfully completed request from the HTTP standpoint: it produces requestfinished, not requestfailed. A redirect finishes one request and issues another. If your logic treats every non-2xx response as a transport failure, it will conflate HTTP status with request failure; use response status handling for the former and request-failure events for the latter. Confirm event details in the version-matched API Reference.
CDPSession
CDPSession provides access to raw Chrome DevTools Protocol methods and events. This is a lower-level escape hatch than Page or Locator APIs, and available operations depend on the browser and protocol capabilities. Puppeteer documents UnsupportedOperation for operations that the protocol in use does not support. Check compatibility before building a workflow around a raw protocol method.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
Specialized objects
Keyboard and Mouse provide virtual input. Tracing and Coverage expose tracing and JavaScript/CSS coverage from a page. Their APIs serve narrower needs than routine page interaction; follow the individual reference entries for exact methods and behavior.
Which browser binaries does Puppeteer support?
The separate @puppeteer/browsers programmatic API supports operations to install, launch, locate, and manage browser binaries. The documentation identifies Chrome for Testing as the default provider and says Puppeteer tests and guarantees Chrome for Testing binaries. Custom providers are not officially supported; an implementation using one takes responsibility for compatibility, feature testing, and maintenance as Puppeteer or download sources change. See the @puppeteer/browsers API documentation before choosing a provider.
How can I look up an exact method or type safely?
- Check your installed dependency version. Use the version recorded by your project’s package manager, not just the version label displayed by the current docs.
- Open the exact class or member entry. Verify parameters, overloads, return type, thrown errors, support notes, and deprecation status there.
- Check lifecycle scope. Establish whether the operation belongs to the browser, context, page, frame, or a handle.
- Check abstraction and waiting behavior. Decide whether a Locator, selector/handle, or raw CDP operation is appropriate, and confirm retries and event ordering.
- Check browser and protocol compatibility. This is especially important for custom providers, CDP operations, and experimental entries.
- Use public APIs as extension points. If a constructor is marked internal, do not instantiate or subclass it as though it were a supported public factory.
What should I troubleshoot when a Puppeteer call behaves unexpectedly?
- Selector returns no element: Choose behavior intentionally:
$returnsnull,$$returns an empty array, and$evalthrows. Confirm the selector and whether the page has reached the state you expect before acting. - Navigation wait hangs or is missed: Verify that the action actually causes navigation, remember that History API changes count, and register the wait before the triggering action.
- A failed-request handler misses an HTTP error: A 404 or 503 response is not a request failure in this event model. Inspect response status separately; redirects also involve a finished request followed by a new one.
- Prompt or chooser wait misses the event: Set up
waitForDevicePromptorwaitForFileChooserbefore the action that triggers it, and check documented DOM file-picker limitations. - CDP operation is unsupported: Check the browser’s protocol capabilities and the relevant method documentation; Puppeteer can report unsupported operations with
UnsupportedOperation. - Browser binary behaves differently: Confirm that the binary/provider is within the documented support boundary. Puppeteer’s stated tested and guaranteed binary is Chrome for Testing, not every Chromium-derived browser.
- Experimental API is unavailable: Verify both the installed Puppeteer documentation and required browser version or feature flag. For example,
Page.webmcpis marked experimental and the Page reference documents a Chrome 151+ requirement and feature flag; that requirement is version-sensitive.
Or skip the browser setup
If you only need a website screenshot or PDF rather than a programmable browser session, ScreenshotNeo is a website screenshot API and MCP server. Its one-call request can return a PNG, JPEG, WebP, or PDF:
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://example.com -o shot.webpSee the ScreenshotNeo API documentation for options and response details. It accepts cookie or consent banners before capture and removes more than 60 known consent platforms, newsletter popups, and chat widgets; each cleanup step can be turned off. Bot checks/CAPTCHAs, blank pages, timeouts, failed loads, and cache hits are not billed, and responses identify the page verdict and billing status in headers. Its MCP server gives AI agents tools for screenshots, page information, and PDF capture. The Free plan includes 1,000 shots a month with no card; paid plans start at $5 for 3,000 shots. Sign up for free and get 1,000 screenshots a month with no card.
Frequently Asked Questions
Is Puppeteer’s API reference a tutorial?
No. It is an index of documented API types and members; use the Getting Started guide for the workflow and the reference for exact member behavior.
Can I instantiate a Puppeteer API class directly?
Only use a constructor when its documentation presents it as public and intended for that use. Many classes mark constructors internal, so use documented factories and accessors instead.
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.
