Puppeteer is a Node.js library which provides a high-level API to control Chrome or Chromium over the DevTools Protocol. It's often used for web scraping, automated testing, and other browser automation tasks.

Installation

To install Puppeteer, you can use npm or yarn:

npm install puppeteer

Puppeteer downloads a recent version of Chromium by default. For scenarios where you want to connect to an existing browser installation or a remote one, you can use puppeteer-core:

npm install puppeteer-core

Refer to the official documentation for the differences between puppeteer and puppeteer-core.

Environment Variables

Several environment variables can be used to configure Puppeteer's behavior, especially regarding Chromium downloads and proxy settings:

• HTTP_PROXY, HTTPS_PROXY, NO_PROXY: Configure proxy settings for downloads.
• PUPPETEER_SKIP_CHROMIUM_DOWNLOAD: Prevents downloading the bundled Chromium.
• PUPPETEER_DOWNLOAD_HOST: Overrides the default download URL for Chromium.
• PUPPETEER_CHROMIUM_REVISION: Specifies a particular Chromium revision to use.
• PUPPETEER_EXECUTABLE_PATH: Sets the path to an existing Chromium executable.
• PUPPETEER_PRODUCT: Specifies the browser to use (e.g., 'chrome' or 'firefox').

Core API Concepts

Puppeteer Module

The main entry point for interacting with Puppeteer.

const puppeteer = require('puppeteer');

• puppeteer.devices: Predefined device configurations for emulation.
• puppeteer.errors: Access to specific error classes.
• puppeteer.product: The name of the browser being automated.
• puppeteer.connect(options): Connects to an existing Chromium instance.
• puppeteer.createBrowserFetcher([options]): Manages Chromium downloads.
• puppeteer.defaultArgs([options]): Retrieves default launch arguments for Chromium.
• puppeteer.executablePath(): Gets the path to the bundled Chromium executable.
• puppeteer.launch([options]): Launches a new Chromium instance.

BrowserFetcher

Used for downloading and managing different versions of Chromium.

const browserFetcher = puppeteer.createBrowserFetcher();

• browserFetcher.canDownload(revision): Checks if a revision can be downloaded.
• browserFetcher.download(revision[, progressCallback]): Downloads a specific Chromium revision.
• browserFetcher.localRevisions(): Lists locally available Chromium revisions.
• browserFetcher.platform(): Returns the current platform identifier.
• browserFetcher.remove(revision): Removes a local Chromium revision.
• browserFetcher.revisionInfo(revision): Gets detailed information about a revision.

Browser

Represents a Chromium instance. Obtained via puppeteer.launch() or puppeteer.connect().

• browser.on('disconnected'): Event for browser disconnection.
• browser.on('targetchanged'): Event for target URL changes.
• browser.on('targetcreated'): Event for new targets (pages, workers).
• browser.on('targetdestroyed'): Event for target destruction.
• browser.browserContexts(): Returns all open browser contexts.
• browser.close(): Closes the browser and all its pages.
• browser.createIncognitoBrowserContext(): Creates a new incognito context.
• browser.defaultBrowserContext(): Gets the default browser context.
• browser.disconnect(): Disconnects from the browser process.
• browser.isConnected(): Checks if the browser is connected.
• browser.newPage(): Opens a new tab (page).
• browser.pages(): Returns an array of all open pages.
• browser.process(): Returns the spawned browser process.
• browser.targets(): Returns an array of all active targets.
• browser.userAgent(): Gets the browser's user agent string.
• browser.version(): Gets the browser version string.
• browser.waitForTarget(predicate[, options]): Waits for a target matching a predicate.
• browser.wsEndpoint(): Returns the WebSocket endpoint URL.

BrowserContext

Provides isolated browsing sessions. Can be incognito.

• browserContext.on('targetchanged'), browserContext.on('targetcreated'), browserContext.on('targetdestroyed'): Events for targets within the context.
• browserContext.browser(): Returns the parent browser.
• browserContext.close(): Closes the browser context.
• browserContext.isIncognito(): Checks if the context is incognito.
• browserContext.newPage(): Creates a new page within this context.
• browserContext.overridePermissions(origin, permissions): Overrides browser permissions for a given origin.
• browserContext.pages(): Returns pages within this context.
• browserContext.targets(): Returns targets within this context.
• browserContext.waitForTarget(predicate[, options]): Waits for a target within this context.

Page

Represents a single tab or extension background page.

• page.on('close'), page.on('console'), page.on('dialog'), page.on('domcontentloaded'), page.on('error'), page.on('frameattached'), page.on('framedetached'), page.on('framenavigated'), page.on('load'), page.on('metrics'), page.on('pageerror'), page.on('popup'), page.on('request'), page.on('requestfailed'), page.on('requestfinished'), page.on('response'), page.on('workercreated'), page.on('workerdestroyed'): Various events related to page activity.
• page.accessibility, page.coverage, page.keyboard, page.mouse, page.touchscreen, page.tracing: Access to specialized interaction modules.
• page.$(selector): Selects a single DOM element.
• page.$$(selector): Selects multiple DOM elements.
• page.$eval(selector, pageFunction[, ...args]): Evaluates a function on the first matching element.
• page.$$eval(selector, pageFunction[, ...args]): Evaluates a function on all matching elements.
• page.$x(expression): Selects elements using XPath.
• page.addScriptTag(options): Injects a script tag.
• page.addStyleTag(options): Injects a style tag.
• page.authenticate(credentials): Handles HTTP authentication.
• page.bringToFront(): Brings the tab to the foreground.
• page.browser(): Returns the parent browser.
• page.browserContext(): Returns the parent browser context.
• page.click(selector[, options]): Clicks an element.
• page.close([options]): Closes the page.
• page.content(): Gets the page's HTML content.
• page.cookies([...urls]): Gets cookies.
• page.deleteCookie(...cookies): Deletes cookies.
• page.emulate(options): Emulates a device.
• page.emulateMediaFeatures(features): Emulates CSS media features.
• page.emulateMediaType(type): Sets the media type (e.g., 'screen', 'print').
• page.emulateTimezone(timezoneId): Sets the page's timezone.
• page.evaluate(pageFunction[, ...args]): Executes JavaScript in the page context.
• page.evaluateHandle(pageFunction[, ...args]): Executes JavaScript and returns a JSHandle.
• page.evaluateOnNewDocument(pageFunction[, ...args]): Executes JavaScript before the page loads.
• page.exposeFunction(name, puppeteerFunction): Exposes a Node.js function to the page's JavaScript.
• page.focus(selector): Focuses an element.
• page.frames(): Returns an array of all frames on the page.
• page.goBack([options]): Navigates back in history.
• page.goForward([options]): Navigates forward in history.
• page.goto(url[, options]): Navigates to a URL.
• page.hover(selector): Hovers over an element.
• page.isClosed(): Checks if the page is closed.
• page.mainFrame(): Returns the main frame of the page.
• page.metrics(): Retrieves page performance metrics.
• page.pdf([options]): Generates a PDF of the page.
• page.queryObjects(prototypeHandle): Queries JavaScript heap objects.
• page.reload([options]): Reloads the page.
• page.screenshot([options]): Takes a screenshot.
• page.select(selector, ...values): Selects options in a select element.
• page.setBypassCSP(enabled): Toggles Content Security Policy bypass.
• page.setCacheEnabled([enabled]): Toggles cache usage.
• page.setContent(html[, options]): Sets the page's HTML content.
• page.setCookie(...cookies): Sets cookies.
• page.setDefaultNavigationTimeout(timeout): Sets the default timeout for navigation.
• page.setDefaultTimeout(timeout): Sets the default timeout for all operations.
• page.setExtraHTTPHeaders(headers): Sets custom HTTP headers.
• page.setGeolocation(options): Sets the page's geolocation.
• page.setJavaScriptEnabled(enabled): Enables or disables JavaScript.
• page.setOfflineMode(enabled): Enables or disables offline mode.
• page.setRequestInterception(value): Enables or disables request interception.
• page.setUserAgent(userAgent): Sets the user agent string.
• page.setViewport(viewport): Sets the page's viewport dimensions.
• page.tap(selector): Taps an element (for touch devices).
• page.target(): Returns the target associated with the page.
• page.title(): Gets the page's title.
• page.type(selector, text[, options]): Types text into an input field.
• page.url(): Gets the current page URL.
• page.viewport(): Gets the current viewport information.
• page.waitFor(selectorOrFunctionOrTimeout[, options[, ...args]]): Waits for a condition.
• page.waitForFileChooser([options]): Waits for a file chooser dialog.
• page.waitForFunction(pageFunction[, options[, ...args]]): Waits for a JavaScript function to return a truthy value.
• page.waitForNavigation([options]): Waits for navigation to complete.
• page.waitForRequest(urlOrPredicate[, options]): Waits for a specific network request.
• page.waitForResponse(urlOrPredicate[, options]): Waits for a specific network response.
• page.waitForSelector(selector[, options]): Waits for a DOM element to appear.
• page.waitForXPath(xpath[, options]): Waits for a DOM element matching an XPath.
• page.workers(): Returns an array of Web Workers associated with the page.

Worker

Represents a Web Worker.

• worker.evaluate(pageFunction[, ...args]): Evaluates JavaScript in the worker context.
• worker.evaluateHandle(pageFunction[, ...args]): Evaluates JavaScript and returns a JSHandle.
• worker.executionContext(): Returns the worker's execution context.
• worker.url(): Returns the worker's script URL.

Accessibility

Provides access to the accessibility tree.

• accessibility.snapshot([options]): Captures the accessibility tree.

Keyboard

Simulates keyboard input.

• keyboard.down(key[, options]): Presses a key down.
• keyboard.press(key[, options]): Presses and releases a key.
• keyboard.sendCharacter(char): Sends a character without keydown/keyup.
• keyboard.type(text[, options]): Types a string of text.
• keyboard.up(key): Releases a key.

Mouse

Simulates mouse input.

• mouse.click(x, y[, options]): Clicks at specified coordinates.
• mouse.down([options]): Presses the mouse button down.
• mouse.move(x, y[, options]): Moves the mouse cursor.
• mouse.up([options]): Releases the mouse button.

Touchscreen

Simulates touch input.

• touchscreen.tap(x, y): Taps at specified coordinates.

Tracing

Collects performance traces.

• tracing.start([options]): Starts tracing.
• tracing.stop(): Stops tracing and returns the trace data.

FileChooser

Represents a file input dialog.

• fileChooser.accept(filePaths): Accepts the file chooser with specified files.
• fileChooser.cancel(): Cancels the file chooser.
• fileChooser.isMultiple(): Checks if multiple files can be selected.

Dialog

Represents JavaScript dialogs (alert, confirm, prompt).

• dialog.accept([promptText]): Accepts the dialog.
• dialog.defaultValue(): Gets the default value for prompt dialogs.
• dialog.dismiss(): Dismisses the dialog.
• dialog.message(): Gets the dialog message.
• dialog.type(): Gets the dialog type.

ConsoleMessage

Represents messages logged to the browser console.

• consoleMessage.args(): Gets the arguments passed to the console method.
• consoleMessage.location(): Gets the location (URL, line number) of the message.
• consoleMessage.text(): Gets the message text.
• consoleMessage.type(): Gets the message type (e.g., 'log', 'error').

Frame

Represents an iframe or the main frame.

• frame.$(selector), frame.$$(selector), frame.$eval(), frame.$$eval(), frame.$x(): DOM querying methods within the frame.
• frame.addScriptTag(), frame.addStyleTag(): Injecting tags into the frame.
• frame.childFrames(): Returns child frames.
• frame.click(), frame.focus(), frame.hover(), frame.tap(), frame.type(): Interaction methods within the frame.
• frame.content(): Gets the frame's HTML content.
• frame.evaluate(), frame.evaluateHandle(): Executes JavaScript in the frame.
• frame.executionContext(): Gets the frame's execution context.
• frame.goto(url[, options]): Navigates the frame to a URL.
• frame.isDetached(): Checks if the frame is detached.
• frame.name(): Gets the frame's name.
• frame.parentFrame(): Returns the parent frame.
• frame.select(): Selects options in a select element within the frame.
• frame.setContent(html[, options]): Sets the frame's HTML content.
• frame.title(): Gets the frame's title.
• frame.url(): Gets the frame's URL.
• frame.waitFor(), frame.waitForFunction(), frame.waitForSelector(), frame.waitForXPath(): Waiting methods within the frame.

ExecutionContext

Represents a JavaScript execution context.

• executionContext.evaluate(), executionContext.evaluateHandle(): Evaluate JavaScript.
• executionContext.frame(): Returns the associated frame.
• executionContext.queryObjects(): Queries JavaScript heap objects.

JSHandle

Represents an in-page JavaScript object.

• jsHandle.asElement(): Returns an ElementHandle if applicable.
• jsHandle.dispose(): Disposes of the handle.
• jsHandle.evaluate(), jsHandle.evaluateHandle(): Evaluate JavaScript within the handle's context.
• jsHandle.executionContext(): Returns the execution context.
• jsHandle.getProperties(): Gets properties of the object.
• jsHandle.getProperty(propertyName): Gets a specific property.
• jsHandle.jsonValue(): Returns a JSON representation of the object.

ElementHandle

Represents an in-page DOM element.

• elementHandle.$(selector), elementHandle.$$(selector), elementHandle.$eval(), elementHandle.$$eval(), elementHandle.$x(): DOM querying methods relative to the element.
• elementHandle.asElement(): Returns the ElementHandle itself.
• elementHandle.boundingBox(): Gets the element's bounding box.
• elementHandle.boxModel(): Gets the element's box model.
• elementHandle.click([options]): Clicks the element.
• elementHandle.contentFrame(): Returns the content frame if the element is an iframe.
• elementHandle.dispose(): Disposes of the handle.
• elementHandle.evaluate(), elementHandle.evaluateHandle(): Evaluate JavaScript within the element's context.
• elementHandle.executionContext(): Returns the execution context.
• elementHandle.focus(): Focuses the element.
• elementHandle.getProperties(): Gets properties of the element.
• elementHandle.getProperty(propertyName): Gets a specific property.
• elementHandle.hover(): Hovers over the element.
• elementHandle.isIntersectingViewport(): Checks if the element is in the viewport.
• elementHandle.jsonValue(): Returns a JSON representation of the element.
• elementHandle.press(key[, options]): Presses a key while the element is focused.
• elementHandle.screenshot([options]): Takes a screenshot of the element.
• elementHandle.select(...values): Selects options in a select element.
• elementHandle.tap(): Taps the element.
• elementHandle.type(text[, options]): Types text into the element.
• elementHandle.uploadFile(...filePaths): Uploads files to an input element.

Request

Represents a network request initiated by a page.

• request.abort([errorCode]): Aborts the request.
• request.continue([overrides]): Continues the request with optional overrides.
• request.failure(): Returns failure information if the request failed.
• request.frame(): Returns the frame that initiated the request.
• request.headers(): Gets the request headers.
• request.isNavigationRequest(): Checks if this request is driving navigation.
• request.method(): Gets the request method (GET, POST, etc.).
• request.postData(): Gets the request's post data.
• request.redirectChain(): Returns the redirect chain.
• request.resourceType(): Gets the resource type.
• request.respond(response): Responds to the request.
• request.response(): Gets the response object if available.
• request.url(): Gets the request URL.

Response

Represents a network response received by a page.

• response.buffer(): Resolves to a buffer with the response body.
• response.frame(): Returns the frame that initiated the response.
• response.fromCache(): Checks if the response was served from cache.
• response.fromServiceWorker(): Checks if the response was served by a service worker.
• response.headers(): Gets the response headers.
• response.json(): Resolves to a JSON representation of the response body.
• response.ok(): Checks if the response status is OK (200-299).
• response.remoteAddress(): Gets the remote address.
• response.request(): Gets the corresponding request object.
• response.securityDetails(): Gets security details for secure connections.
• response.status(): Gets the HTTP status code.
• response.statusText(): Gets the HTTP status text.
• response.text(): Resolves to a text representation of the response body.
• response.url(): Gets the response URL.

SecurityDetails

Details about a secure connection.

• securityDetails.issuer(): Gets the certificate issuer.
• securityDetails.protocol(): Gets the security protocol.
• securityDetails.subjectName(): Gets the certificate subject name.
• securityDetails.validFrom(): Gets the certificate validity start date.
• securityDetails.validTo(): Gets the certificate validity end date.

Target

Represents a target (page, worker, etc.) within a browser.

• target.browser(): Gets the parent browser.
• target.browserContext(): Gets the parent browser context.
• target.createCDPSession(): Creates a Chrome DevTools Protocol session.
• target.opener(): Gets the target that opened this target.
• target.page(): Gets the page associated with the target.
• target.type(): Identifies the type of target.
• target.url(): Gets the target's URL.
• target.worker(): Gets the worker associated with the target.

CDPSession

Used for direct communication with the Chrome DevTools Protocol.

• cdpSession.detach(): Detaches the session.
• cdpSession.send(method[, params]): Sends a CDP command.

Coverage

Gathers information about used JavaScript and CSS.

• coverage.startCSSCoverage([options]): Starts CSS coverage tracking.
• coverage.startJSCoverage([options]): Starts JS coverage tracking.
• coverage.stopCSSCoverage(): Stops CSS coverage tracking.
• coverage.stopJSCoverage(): Stops JS coverage tracking.

External Resources

• Puppeteer Official Documentation
• Chrome DevTools Protocol
• MDN JavaScript Guide