The official Puppeteer API Reference is the place to look up classes, methods, functions, and interfaces. For a working browser-automation flow, start with the Getting started guide, then use the reference for specific APIs. The reference surfaced here is labeled version 25.12.0; check the documentation matching your installed Puppeteer version because API details and defaults can change.
Choose the right Puppeteer documentation page
- Need to find an API entry? Search the API Reference. It is organized into classes, enumerations, functions, and interfaces. Relevant classes include
Browser,BrowserContext,Page,Locator,ElementHandle,Keyboard,Mouse,Puppeteer, andPuppeteerNode. - New to Puppeteer? Follow Getting started for the browser-to-page workflow before looking up individual methods.
- Need to automate an interaction? Read Page interactions. It explains the recommended Locator approach and how it differs from lower-level APIs.
- Need browser setup details? Check LaunchOptions, the launch() reference, or @puppeteer/browsers for browser management.
Understand the basic API flow
Puppeteer’s common flow is to launch or connect to a browser, create a page, and use page APIs to navigate and interact. puppeteer.launch() accepts optional launch options and returns a Promise<Browser>. A browser can have multiple pages; each Page represents a tab or extension background page and provides methods for working with page content.
As an Amazon Associate I earn from qualifying purchases.
This compact Node.js example illustrates the flow. Install the puppeteer package in your project, save the code as example.js, then run node example.js. The bundled-browser setup is the simplest starting point; see the launch notes below before substituting a separately installed browser.
Free tools Windows power users keep installed
One-click scans. No signup required.
const puppeteer = require('puppeteer');
(async () => {
const browser = await puppeteer.launch();
try {
const page = await browser.newPage();
await page.goto('https://example.com');
await page.setViewport({ width: 1280, height: 800 });
console.log(await page.title());
} finally {
await browser.close();
}
})();The official Getting started guide covers a fuller example, including keyboard and locator operations. Check it against the version installed in your project rather than assuming a sample written for another release applies unchanged.
#1 Best Overall
Use Locators for most page interactions
The Puppeteer Page interactions guide says, “Locators is the recommended way to select an element and interact with it.” A locator waits for the target and checks action preconditions. Before clicking, the documented checks include that the element is in the viewport, visible, enabled, and has a stable bounding box across two consecutive animation frames. For form filling, Locator detects input type and can fill select and input elements.
Use page.locator() with a CSS selector or a function. The locator documentation also describes Puppeteer-specific query syntax for text, accessibility role and name, XPath, and queries across shadow roots. See the Page.locator() reference for supported forms.
Rank #2
- HTML CSS Design and Build Web Sites
- Comes with secure packaging
- It can be a gift option
When lower-level selector APIs make sense
page.$(selector)is an immediate first-match lookup. It resolves tonullif there is no match; it does not provide the locator action behavior.waitForSelector()is a lower-level option when you need to wait for a selector explicitly. It does not automatically retry a subsequent failed action.ElementHandlegives you a handle to a particular page element. If you use one, dispose of it when you are finished.
These APIs are not interchangeable in their waiting and cleanup responsibilities. The interaction guide explains the distinctions and cases where lower-level control is useful.
Choose a browser launch setup
The generic LaunchOptions interface documents settings such as browser, channel, headless mode, arguments, timeout, and user data directory. The surfaced reference says the browser defaults to Chrome and headless defaults to true; treat those as version-specific documented defaults and verify them in the reference for your installed version.
Rank #3
Puppeteer works best with the Chrome for Testing version it downloads by default, and the documentation does not guarantee compatibility with other browser versions. If you use puppeteer-core, its PuppeteerNode.launch() reference says you must provide either executablePath or channel. That makes the choice practical: bundled setup is convenient, while a separately installed browser requires you to manage the executable or channel and compatibility yourself.
The separate @puppeteer/browsers documentation describes CLI and programmatic browser management. It states that launching system browsers through that browser-management path is possible only for Chrome/Chromium; this limitation is specific to that path, not a statement that every Puppeteer API applies only to those browsers.
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
Common lookup and setup problems
- A sample does not match your installed package: Confirm the sample and API page correspond to your Puppeteer version. The API reference is versioned, and browser defaults may change.
puppeteer-corecannot launch: Supply anexecutablePathor achannel, as required by its launch reference.- An interaction runs before its target is ready: Prefer a Locator for ordinary actions so Puppeteer can wait and check readiness. With
waitForSelector()or a handle, manage the subsequent action and any needed retry yourself. - A selector lookup finds nothing: Remember that
page.$()returnsnullwhen there is no match. If the element appears asynchronously, use a Locator or explicitly wait for the selector. - A different browser version behaves unexpectedly: Compare it with the Chrome for Testing version Puppeteer downloads by default; the documentation warns that other versions are not guaranteed to work.
Or skip the browser setup
If your goal is to capture a website screenshot rather than automate arbitrary page interactions, ScreenshotNeo offers a one-request screenshot API. It is not a replacement for Puppeteer’s page automation APIs; it is an alternative for screenshot capture.
The Tool Desk
Outbyte PC Repair FREEClear out junk files and repair common Windows errorsFree Scan →Outbyte Driver Updater FREEFix the driver behind crashes, sound loss and screen glitchesFind Drivers →For a complete option reference, see the ScreenshotNeo documentation.
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://example.com -o shot.webp- Cookie banners are accepted and more than 60 known consent platforms, newsletter popups, and chat widgets are removed before capture; each step can be turned off.
- Bot checks or CAPTCHAs, blank pages, timeouts, failed loads, and cache hits cost nothing; response headers report the page verdict and billing status.
- An MCP server provides
take_screenshot,get_page_info, andcapture_pdftools 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 shots.
Sign up for 1,000 free screenshots a month, with no card required.
Frequently Asked Questions
Where should I begin if I only need to look up a Puppeteer method?
Use the official API Reference at pptr.dev/api, then open the relevant class or method page.
Does Puppeteer recommend Locator or ElementHandle for interactions?
The Page interactions guide recommends Locator for selecting elements and interacting with them; ElementHandle is a lower-level option with explicit disposal responsibility.
Do these 3 things before closing this tab:
1Fix the driver behind crashes, sound loss and screen glitches2Repair Windows errors before they cause bigger problems3Scan for outdated or missing drivers - takes under a minuteQuick 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.
