Puppeteer

Puppeteer is a JavaScript/TypeScript library that gives Node.js code high-level control over Chrome or Firefox, either headless or headful, by driving the browser through the Chrome DevTools Protocol or the standards-based WebDriver BiDi protocol. It ships as a full browser download plus API by default, or as the lighter puppeteer-core when you want to manage the browser binary yourself.

Beyond navigation and DOM interaction, Puppeteer exposes low-level primitives for network interception, PDF and screenshot generation, mobile device emulation, and CDP session access, making it a common foundation for end-to-end test suites, scraping pipelines, and headless-browser tooling such as browser-based MCP servers.

What You Get

• A Browser/Page/Frame/ElementHandle object model covering navigation, input (mouse, keyboard, touch), and DOM querying, including accessibility-based and custom query selectors
• Built-in network interception and request/response inspection via the HTTPRequest/HTTPResponse API
• Screenshot and PDF generation, device/viewport emulation, geolocation and permission overrides
• A puppeteer-core variant for connecting to an existing browser (e.g. a remote/cloud browser) without downloading a bundled Chrome
• A companion @puppeteer/browsers CLI/library for downloading and managing browser binaries (npx puppeteer browsers install)
• Direct CDPSession access for teams that need raw Chrome DevTools Protocol commands alongside the high-level API

Common Use Cases

• Driving end-to-end and integration test suites against a real rendered page
• Web scraping and data extraction from JavaScript-heavy sites that require a real browser
• Generating PDFs or screenshots of server-rendered or client-rendered pages (invoices, reports, social-preview images)
• Powering browser-automation MCP servers and AI agent tooling that need programmatic browser control
• Automating repetitive browser workflows: form submission, UI monitoring, visual regression checks

Under The Hood

Architecture

Puppeteer is a monorepo (npm workspaces under packages/*) split into puppeteer (the batteries-included entry point that bundles a Chrome download via postinstall/install.mjs) and puppeteer-core (the actual implementation, no browser download). Inside puppeteer-core/src, the code is layered into api/ (the public-facing Browser, BrowserContext, Page, Frame, ElementHandle, CDPSession, Target classes consumers interact with), common/ (shared primitives: EventEmitter, QueryHandler variants for CSS/XPath/ARIA/Pierce/text selectors, Errors, Cookie, Configuration, WaitTask), and two protocol backends — cdp/ for the Chrome DevTools Protocol and bidi/ for the newer standards-based WebDriver BiDi (via the chromium-bidi and webdriver-bidi-protocol packages) — letting the same api/ classes target either protocol depending on how the browser was launched. node/ (BrowserLauncher, ChromeLauncher, FirefoxLauncher, PipeTransport, NodeWebSocketTransport, ScreenRecorder) holds Node-specific process/launch logic, while injected/ holds code executed inside the page context itself. Browser binary acquisition is delegated to the separate @puppeteer/browsers package.

Tech Stack

Written in TypeScript (94% of the codebase) targeting Node >=22.12.0, built with tsc plus API Extractor for .d.ts rollup and Rollup for an ES5 IIFE browser bundle. Core runtime dependencies are minimal and protocol-focused: devtools-protocol (generated CDP types), chromium-bidi/webdriver-bidi-protocol (BiDi implementation), ws (WebSocket transport), and typed-query-selector (typed CSS selector inference). The monorepo uses wireit for incremental/cached build orchestration across packages and mocha/Node’s built-in test runner for unit tests, with a large separate test/ suite driving real browser instances end-to-end.

Code Quality

The repo has substantial test coverage: 28 *.test.ts files colocated with source in packages/puppeteer-core/src (unit-level, e.g. HTTPRequest.test.ts, ChromeLauncher.test.ts, EventEmitter.test.ts) plus a much larger integration suite under test/src (56+ files) that runs real Chrome/Firefox sessions across headless, headful, BiDi, and pipe-transport configurations — reflecting the project’s need to validate against actual browser behavior, not just mocks. Error handling is structured through a PuppeteerError base class in common/Errors.ts with specific subtypes (TimeoutError, ProtocolError, TargetCloseError, ConnectionClosedError, UnsupportedOperation) rather than raw throws. ESLint (with TSDoc and import-sorting plugins) and Prettier are enforced via wireit-wrapped lint/format scripts, and every public API surface carries TSDoc @public/@internal annotations consumed by API Extractor to generate the published .d.ts and docs site.

API Design The public API favors a small number of consistent, promise-based verbs (page.goto, page.click, page.locator(...).fill(...)) over protocol-shaped boilerplate, and the newer Locator API adds built-in auto-waiting/retry semantics on top of raw ElementHandle access, reducing flaky-test patterns common in browser automation. Dual protocol support (CDP and WebDriver BiDi) is exposed transparently through the same api/ classes, so consumers don’t need to know which protocol backs a given browser launch. Documentation is strong for a low-level automation library: a dedicated docs site (pptr.dev) with guides, a generated API reference, and inline TSDoc comments across the public API, though the breadth of the object model (Browser/BrowserContext/Page/Frame/ElementHandle/CDPSession) does impose a real learning curve for newcomers.