Search the Puppeteer API Documentation

Start at the official Puppeteer API Reference when you know the class or method you need. Start with Getting started if you need a working example first. The reference is organized into classes, enumerations, functions, and interfaces; its surfaced version is 25.12.0. Check the reference that matches your installed package because APIs and defaults can change between versions.

The basic flow is: launch or connect to a browser, create a page, then use the page API to navigate and interact. For most element interactions, use a Locator: Puppeteer’s guide recommends locators because they wait for elements and check that an action is ready. Use Page.$() for an immediate first-match lookup, and lower-level selector or handle APIs when their control is useful.

1. Find the right Puppeteer documentation

Need	Start here
Find a class, method, option, or type	API Reference
Build a first browser automation flow	Getting started
Choose how to locate and interact with page elements	Page interactions
Understand browser launch configuration	LaunchOptions and launch()
Use a separately installed browser with puppeteer-core	PuppeteerNode.launch()
Manage browser downloads and launches	@puppeteer/browsers

The reference includes classes such as Browser, BrowserContext, Page, Locator, ElementHandle, Keyboard, Mouse, Puppeteer, and PuppeteerNode. Search the reference for the symbol you already have; use the guide when you are deciding how the pieces fit together.

2. Understand the browser-to-page flow

1. Launch or connect. puppeteer.launch() accepts launch options and resolves to a Browser.
2. Create a page. A browser can have multiple pages. A Page represents a tab or extension background page.
3. Navigate and set conditions. Set the URL, viewport, and any required browser or page configuration.
4. Interact. Use page locators for normal element actions, then close the browser when work is complete.

This runnable Node.js example follows the official getting-started shape. Install Puppeteer with npm install puppeteer; the package’s browser setup is version-dependent, so consult the getting-started guide if installation or browser download behavior differs.

const puppeteer = require('puppeteer');

(async () => {
  const browser = await puppeteer.launch();
  try {
    const page = await browser.newPage();
    await page.setViewport({ width: 1280, height: 800 });
    await page.goto('https://example.com');

    const heading = page.locator('h1');
    console.log(await heading.evaluate(element => element.textContent));
  } finally {
    await browser.close();
  }
})();

For an ES module project, use import puppeteer from 'puppeteer'; in place of the CommonJS import. The exact methods available should be confirmed against the version installed in your project.

3. Choose a page interaction API

Use Locator for ordinary actions

Puppeteer’s interaction guide says: “Locators is the recommended way to select an element and interact with it.” A locator waits for matching elements and checks action preconditions. Before clicking, documented checks include that the target is in the viewport, visible, enabled, and has a stable bounding box across two animation frames. For filling forms, the locator detects input type and can fill input and select elements.

const submit = page.locator('button[type="submit"]');
await submit.click();

const email = page.locator('input[name="email"]');
await email.fill('reader@example.com');

const plan = page.locator('select[name="plan"]');
await plan.fill('standard');

Locators support CSS selectors and Puppeteer-specific query syntax for text, accessibility role and name, XPath, and queries across shadow roots. See the Page.locator() reference for supported syntax in your installed version.

Use Page.$() for an immediate first match

Page.$(selector) returns the first matching element handle or null if there is no match. It is useful when the page state is already known and an immediate lookup is intended; it does not provide the same automatic wait-and-retry behavior as locator actions.

const button = await page.$('button[type="submit"]');
if (!button) {
  throw new Error('Submit button was not present');
}
await button.click();
await button.dispose();

Use lower-level waits and handles deliberately

waitForSelector() waits for a selector condition and returns an ElementHandle. It does not automatically retry a subsequent failed action in the way a locator action does. Dispose of handles when you are done with them.

const button = await page.waitForSelector('button[type="submit"]', {
  visible: true,
  timeout: 10_000,
});
if (!button) {
  throw new Error('Submit button was not found');
}
try {
  await button.click();
} finally {
  await button.dispose();
}

Choose a locator for the normal “find and act” path. Choose a handle when you need direct element-level work and are prepared to manage waiting, action failures, and disposal yourself.

4. Configure browser launch and compatibility

The LaunchOptions interface documents controls including browser, channel, headless mode, arguments, timeout, and user data directory. In the surfaced reference, the browser default is Chrome and headless defaults to true. Treat defaults as version-specific and check the docs for the version in your lockfile.

Setting or choice	What to check
browser	Which supported browser family is requested; consult the installed version’s options reference.
channel	Whether Puppeteer should use a named installed browser channel.
headless	Whether the run should use headless mode; the documented default can change.
args	Additional browser command-line arguments required by your environment.
timeout	How long launch may take before it fails.
userDataDir	Whether to use a specified browser profile directory.

puppeteer-core does not bundle the same browser setup as the full puppeteer package. Its launch call requires an executablePath or a channel. Puppeteer documents its best fit as the Chrome for Testing version it downloads by default and does not guarantee compatibility with a different version. If you manage browsers separately, the @puppeteer/browsers documentation describes its CLI and programmatic API; its system-browser launching path is limited to Chrome/Chromium.

const puppeteer = require('puppeteer-core');

(async () => {
  const browser = await puppeteer.launch({
    executablePath: '/absolute/path/to/chrome',
    headless: true,
    timeout: 30_000,
  });
  try {
    const page = await browser.newPage();
    await page.goto('https://example.com');
    console.log(await page.title());
  } finally {
    await browser.close();
  }
})();

Replace the example path with the browser executable available in your environment. Do not assume an arbitrary system browser version will match Puppeteer; use the browser pairing documented for your package version.

5. Troubleshoot common problems

Symptom	Likely cause	What to do
Launch fails with a missing executable	You are using puppeteer-core without telling it where a browser is.	Provide executablePath or channel, or use the package and browser setup described by the getting-started guide.
Browser starts but page operations behave unexpectedly	The browser version differs from the Chrome for Testing version paired with Puppeteer.	Check the package version and use its supported downloaded browser pairing, or verify compatibility for the chosen executable.
Page.$() returns null	No element matched at the moment of lookup, perhaps because navigation or rendering has not completed.	Confirm the selector and page state. Use a locator or an explicit selector wait when the element is expected to appear later.
Click fails after a selector wait	The element changed, became disabled, moved, or is otherwise not actionable after the wait.	Prefer a locator action that checks readiness and retries; if using a handle, re-check state and handle errors explicitly.
Element handle operations fail or memory grows during repeated work	Handles were retained after use or refer to elements replaced by navigation or rerendering.	Dispose handles in a finally block and reacquire elements after page changes.
A locator never resolves	The selector is wrong, targets the wrong frame or shadow boundary, or the element does not appear.	Verify the selector against the rendered page, check frame/shadow-root context, and set an intentional timeout where supported.

6. Performance, reliability, and cost considerations

• Keep browser lifetimes intentional. Reuse a launched browser for related pages when appropriate, while closing pages and the browser when the job ends. The API models one browser with multiple pages.
• Prefer locators for dynamic interfaces. Their waiting and action-readiness checks reduce timing-sensitive code. Lower-level handles can be efficient for controlled flows, but require explicit waits and disposal.
• Set timeouts for your workload. Launch and selector waits can otherwise fail at defaults that do not fit a slow environment. Check the versioned API for the relevant timeout options.
• Match the browser version. Using the browser version paired with Puppeteer improves compatibility; a separately installed executable adds setup and compatibility checks.
• Budget the browser environment. Puppeteer runs a real browser process, so deployment resource use depends on browser and page workload. The cited reference gives no general benchmark or fixed cost figure; measure in the target environment.

7. Or skip the browser setup

If your goal is a page image or PDF rather than browser automation, ScreenshotNeo provides a website screenshot API and MCP server. One GET request accepts a URL and returns PNG, JPEG, WebP, or PDF. Its capture can accept cookie banners and remove more than 60 known consent platforms, newsletter popups, and chat widgets before the shot; each step can be turned off. Bot checks and CAPTCHAs, blank pages, timeouts, failed loads, and cache hits cost nothing, and the response reports the page verdict and billing status in headers. AI agents can use its MCP tools, including take_screenshot, get_page_info, and capture_pdf.

See the ScreenshotNeo API documentation. This cURL request saves a WebP screenshot:

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

Python:

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)

Node.js:

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}`);
await require('node:fs/promises').writeFile('shot.webp', Buffer.from(await res.arrayBuffer()));

Free includes 1,000 screenshots per month with no card; paid plans start at $5 for 3,000 screenshots. All features are on every plan. Sign up free for 1,000 screenshots a month, with no card required.

8. FAQ

Which Puppeteer page should I bookmark?

Bookmark the API Reference for symbol lookup and the Page interactions guide for decisions about selectors and actions.

Does a Locator return an ElementHandle?

Use the Locator API for interactions as documented; use explicit handle APIs when your code needs direct element-handle operations and can manage their lifecycle.

Should I use Puppeteer or puppeteer-core?

Use the package whose browser setup fits your deployment. With puppeteer-core, supply a browser path or channel and account for version compatibility.