or run

npx @tessl/cli init
Log in

Version

Files

docs

browser-management.mddevice-emulation.mdelement-handling.mdindex.mdinput-interaction.mdlocators-waiting.mdmedia-generation.mdnetwork-control.mdpage-interaction.mdperformance-debugging.md
tile.json

tessl/npm-puppeteer

A high-level API to control headless Chrome over the DevTools Protocol

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/puppeteer@24.19.x

To install, run

npx @tessl/cli install tessl/npm-puppeteer@24.19.0

index.mddocs/

Puppeteer

Puppeteer is a comprehensive browser automation library that provides a high-level JavaScript API for controlling Chrome and Firefox browsers programmatically via the DevTools Protocol and WebDriver BiDi. It enables developers to automate web interactions, perform web scraping, generate PDFs and screenshots, run performance tests, and create end-to-end testing solutions.

Package Information

  • Package Name: puppeteer
  • Package Type: npm
  • Language: TypeScript/JavaScript
  • Installation: npm install puppeteer

Core Imports

import puppeteer, { Browser, Page, ElementHandle } from "puppeteer";

For CommonJS:

const puppeteer = require("puppeteer");
const { Browser, Page, ElementHandle } = require("puppeteer");

Basic Usage

import puppeteer from "puppeteer";

// Launch browser and create page
const browser = await puppeteer.launch();
const page = await browser.newPage();

// Navigate and interact
await page.goto("https://example.com");
await page.type("#search", "query");
await page.click("button[type=submit]");

// Take screenshot
await page.screenshot({ path: "example.png" });

// Extract data
const title = await page.title();
const links = await page.$$eval("a", (anchors) => 
  anchors.map((a) => ({ text: a.textContent, href: a.href }))
);

await browser.close();

Architecture

Puppeteer is built around several key components:

  • PuppeteerNode: Main entry point for launching and connecting to browsers
  • Browser: Represents a browser instance that can manage multiple contexts and pages
  • BrowserContext: Isolated browser environment (incognito-like) for managing related pages
  • Page: Individual browser tab/window with navigation, interaction, and evaluation capabilities
  • Frame: Represents frames within pages, including main frame and iframes
  • ElementHandle: Handle to DOM elements for direct interaction and property access
  • JSHandle: Handle to JavaScript objects in the browser context
  • Network Classes: HTTPRequest and HTTPResponse for network monitoring and interception
  • Input Classes: Keyboard, Mouse, and Touchscreen for simulating user interactions
  • Locators: Modern element selection with automatic waiting and retry logic

Capabilities

Browser Management

Core browser lifecycle operations including launching browsers, creating contexts, and managing browser-level settings.

function launch(options?: LaunchOptions): Promise<Browser>;
function connect(options: ConnectOptions): Promise<Browser>;
function defaultArgs(options?: LaunchOptions): string[];
function executablePath(): string;

Browser Management

Page Navigation & Interaction

Page-level operations for navigation, content manipulation, element interaction, and JavaScript execution.

class Page {
  goto(url: string, options?: GoToOptions): Promise<HTTPResponse | null>;
  click(selector: string, options?: ClickOptions): Promise<void>;
  type(selector: string, text: string, options?: TypeOptions): Promise<void>;
  $(selector: string): Promise<ElementHandle | null>;
  $$(selector: string): Promise<ElementHandle[]>;
  evaluate(pageFunction: Function, ...args: any[]): Promise<any>;
}

Page Navigation & Interaction

Element Handling

Direct element manipulation through ElementHandle for precise control over DOM elements.

class ElementHandle {
  click(options?: ClickOptions): Promise<void>;
  type(text: string, options?: TypeOptions): Promise<void>;
  $(selector: string): Promise<ElementHandle | null>;
  boundingBox(): Promise<BoundingBox | null>;
  screenshot(options?: ScreenshotOptions): Promise<Uint8Array>;
}

Element Handling

Locators & Waiting

Modern element selection with automatic waiting, retries, and fluent interface for reliable element interactions.

class Locator<T> {
  click(options?: LocatorClickOptions): Promise<void>;
  fill(value: string, options?: ActionOptions): Promise<void>;
  waitHandle(options?: ActionOptions): Promise<HandleFor<T>>;
  filter<U extends T>(predicate: Predicate<T, U>): Locator<U>;
}

Locators & Waiting

Network Control

Request and response interception, network monitoring, and offline mode simulation.

class HTTPRequest {
  url(): string;
  method(): string;
  headers(): Record<string, string>;
  abort(errorCode?: ErrorCode): Promise<void>;
  continue(overrides?: ContinueRequestOverrides): Promise<void>;
  respond(response: Partial<ResponseForRequest>): Promise<void>;
}

class HTTPResponse {
  status(): number;
  headers(): Record<string, string>;
  text(): Promise<string>;
  json(): Promise<any>;
  buffer(): Promise<Buffer>;
}

Network Control

Input & Interaction

Keyboard, mouse, and touch input simulation for comprehensive user interaction automation.

class Keyboard {
  type(text: string, options?: {delay?: number}): Promise<void>;
  press(key: KeyInput, options?: PressOptions): Promise<void>;
  down(key: KeyInput): Promise<void>;
  up(key: KeyInput): Promise<void>;
}

class Mouse {
  click(x: number, y: number, options?: MouseClickOptions): Promise<void>;
  move(x: number, y: number, options?: {steps?: number}): Promise<void>;
  dragAndDrop(start: Point, target: Point): Promise<void>;
}

Input & Interaction

Media Generation

Screenshot capture and PDF generation with extensive customization options.

interface ScreenshotOptions {
  path?: string;
  type?: "png" | "jpeg" | "webp";
  quality?: number;
  fullPage?: boolean;
  clip?: {x: number; y: number; width: number; height: number};
}

interface PDFOptions {
  path?: string;
  scale?: number;
  displayHeaderFooter?: boolean;
  headerTemplate?: string;
  footerTemplate?: string;
  printBackground?: boolean;
  landscape?: boolean;
  pageRanges?: string;
  format?: string;
  margin?: {top?: string; right?: string; bottom?: string; left?: string};
}

Media Generation

Device Emulation

Mobile device emulation, viewport management, and browser environment simulation.

interface Device {
  name: string;
  userAgent: string;
  viewport: Viewport;
}

interface Viewport {
  width: number;
  height: number;
  deviceScaleFactor?: number;
  isMobile?: boolean;
  hasTouch?: boolean;
  isLandscape?: boolean;
}

Device Emulation

Performance & Debugging

Performance tracing, code coverage collection, and accessibility tree inspection.

class Coverage {
  startJSCoverage(options?: JSCoverageOptions): Promise<void>;
  stopJSCoverage(): Promise<JSCoverageEntry[]>;
  startCSSCoverage(options?: CSSCoverageOptions): Promise<void>;
  stopCSSCoverage(): Promise<CSSCoverageEntry[]>;
}

class Tracing {
  start(options?: TracingOptions): Promise<void>;
  stop(): Promise<Uint8Array>;
}

Performance & Debugging

Core Types

interface LaunchOptions {
  headless?: boolean | "new" | "shell";
  executablePath?: string;
  args?: string[];
  ignoreDefaultArgs?: boolean | string[];
  handleSIGINT?: boolean;
  handleSIGTERM?: boolean;
  handleSIGHUP?: boolean;
  timeout?: number;
  dumpio?: boolean;
  env?: Record<string, string | undefined>;
  devtools?: boolean;
  slowMo?: number;
  defaultViewport?: Viewport | null;
  ignoreHTTPSErrors?: boolean;
}

interface ConnectOptions {
  browserWSEndpoint?: string;
  browserURL?: string;
  ignoreHTTPSErrors?: boolean;
  defaultViewport?: Viewport | null;
  slowMo?: number;
  targetFilter?: (target: Target) => boolean;
}

interface GoToOptions {
  timeout?: number;
  waitUntil?: "load" | "domcontentloaded" | "networkidle0" | "networkidle2" | Array<"load" | "domcontentloaded" | "networkidle0" | "networkidle2">;
  referer?: string;
}

interface ClickOptions {
  button?: "left" | "right" | "middle";
  clickCount?: number;
  delay?: number;
  offset?: {x: number; y: number};
}

type KeyInput = "F1" | "F2" | "F3" | "F4" | "F5" | "F6" | "F7" | "F8" | "F9" | "F10" | "F11" | "F12" | "Digit0" | "Digit1" | "Digit2" | "Digit3" | "Digit4" | "Digit5" | "Digit6" | "Digit7" | "Digit8" | "Digit9" | "KeyA" | "KeyB" | "KeyC" | "KeyD" | "KeyE" | "KeyF" | "KeyG" | "KeyH" | "KeyI" | "KeyJ" | "KeyK" | "KeyL" | "KeyM" | "KeyN" | "KeyO" | "KeyP" | "KeyQ" | "KeyR" | "KeyS" | "KeyT" | "KeyU" | "KeyV" | "KeyW" | "KeyX" | "KeyY" | "KeyZ" | "Comma" | "Period" | "Semicolon" | "Quote" | "BracketLeft" | "BracketRight" | "Backquote" | "Backslash" | "Minus" | "Equal" | "IntlBackslash" | "IntlRo" | "IntlYen" | "ControlLeft" | "ControlRight" | "ShiftLeft" | "ShiftRight" | "AltLeft" | "AltRight" | "MetaLeft" | "MetaRight" | "ContextMenu" | "Escape" | "Tab" | "CapsLock" | "Space" | "PageUp" | "PageDown" | "End" | "Home" | "ArrowLeft" | "ArrowUp" | "ArrowRight" | "ArrowDown" | "PrintScreen" | "Insert" | "Delete" | "Backspace" | "Enter";

interface BoundingBox {
  x: number;
  y: number;
  width: number;
  height: number;
}

interface Point {
  x: number;
  y: number;
}

interface Cookie {
  name: string;
  value: string;
  domain: string;
  path: string;
  expires?: number;
  size?: number;
  httpOnly?: boolean;
  secure?: boolean;
  session?: boolean;
  sameSite?: "Strict" | "Lax" | "None";
}