or run

npx @tessl/cli init
Log in

Version

Files

docs

browser-contexts.mdbrowser-management.mdelement-handling.mdindex.mdinput-simulation.mdlocators-selectors.mdnetwork-management.mdpage-interaction.md

evals

scenario-1

rubric.jsontask.md

scenario-10

rubric.jsontask.md

scenario-2

rubric.jsontask.md

scenario-3

rubric.jsontask.md

scenario-4

rubric.jsontask.md

scenario-5

rubric.jsontask.md

scenario-6

rubric.jsontask.md

scenario-7

rubric.jsontask.md

scenario-8

rubric.jsontask.md

scenario-9

rubric.jsontask.md
tile.json

tessl/npm-puppeteer-core

A high-level API to control headless Chrome and Firefox browsers over the DevTools Protocol and WebDriver BiDi

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

With Tessl

Agent performance with Tessl

94%

Improvement

Agent performance improvement using Tessl

+2%

To install, run

npx @tessl/cli install tessl/npm-puppeteer-core@24.19.0
OverviewEval results

index.mddocs/

Puppeteer Core

Puppeteer Core is a Node.js library providing a high-level API to control headless Chrome and Firefox browsers over the DevTools Protocol (CDP) and WebDriver BiDi. It enables browser automation for testing, scraping, PDF generation, performance monitoring, and accessibility analysis without bundling Chrome.

Package Information

  • Package Name: puppeteer-core
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install puppeteer-core

Core Imports

import puppeteer, { Browser, Page, ElementHandle, Locator, Protocol, CDPSession } from "puppeteer-core";

For CommonJS:

const puppeteer = require("puppeteer-core");
const { Browser, Page, ElementHandle, Locator, Protocol, CDPSession } = puppeteer;

Basic Usage

import puppeteer from "puppeteer-core";

// Launch browser
const browser = await puppeteer.launch({
  executablePath: "/path/to/chrome", // Required for puppeteer-core
  headless: true
});

// Create page
const page = await browser.newPage();

// Navigate and interact
await page.goto("https://example.com");
await page.setViewport({ width: 1024, height: 768 });

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

// Close browser
await browser.close();

Architecture

Puppeteer Core is built around several key components:

  • Browser Management: Launch, connect, and control browser instances across Chrome and Firefox
  • Page Interaction: Navigate pages, interact with elements, handle JavaScript execution
  • Protocol Support: Dual implementation supporting both CDP (Chrome DevTools Protocol) and WebDriver BiDi
  • Input Simulation: Keyboard, mouse, and touchscreen input with realistic timing
  • Network Control: Request interception, response mocking, and traffic monitoring
  • Element Location: Advanced locator system with multiple query strategies
  • Event Handling: Comprehensive event system for browser, page, and element events

Capabilities

Browser Management

Core browser lifecycle management including launching new browser instances, connecting to existing ones, and managing browser contexts for isolation.

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

Browser Management

Page Navigation and Interaction

Complete page automation including navigation, element interaction, JavaScript execution, and content extraction.

interface Page extends EventEmitter {
  goto(url: string, options?: GoToOptions): Promise<HTTPResponse | null>;
  setViewport(viewport: Viewport): Promise<void>;
  screenshot(options?: ScreenshotOptions): Promise<Buffer>;
  pdf(options?: PDFOptions): Promise<Buffer>;
  evaluate<T>(pageFunction: Function, ...args: any[]): Promise<T>;
  waitForSelector(selector: string, options?: WaitForSelectorOptions): Promise<ElementHandle | null>;
  click(selector: string, options?: ClickOptions): Promise<void>;
  type(selector: string, text: string, options?: TypeOptions): Promise<void>;
}

Page Navigation and Interaction

Element Handling

Advanced element selection, interaction, and manipulation with comprehensive locator strategies and event handling.

interface ElementHandle extends JSHandle {
  click(options?: ClickOptions): Promise<void>;
  type(text: string, options?: TypeOptions): Promise<void>;
  focus(): Promise<void>;
  hover(): Promise<void>;
  select(...values: string[]): Promise<string[]>;
  uploadFile(...filePaths: string[]): Promise<void>;
  boundingBox(): Promise<BoundingBox | null>;
  screenshot(options?: ScreenshotOptions): Promise<Buffer>;
}

Element Handling

Input Simulation

Realistic keyboard, mouse, and touchscreen input simulation with timing controls and platform-specific key mappings.

interface Keyboard {
  down(key: string, options?: KeyDownOptions): Promise<void>;
  up(key: string): Promise<void>;
  press(key: string, options?: PressOptions): Promise<void>;
  type(text: string, options?: TypeOptions): Promise<void>;
  sendCharacter(char: string): Promise<void>;
}

interface Mouse {
  move(x: number, y: number, options?: MouseMoveOptions): Promise<void>;
  click(x: number, y: number, options?: ClickOptions): Promise<void>;
  down(options?: MouseDownOptions): Promise<void>;
  up(options?: MouseUpOptions): Promise<void>;
  wheel(options?: MouseWheelOptions): Promise<void>;
}

Input Simulation

Network Management

Request interception, response mocking, and comprehensive network monitoring for testing and debugging.

interface HTTPRequest {
  url(): string;
  method(): string;
  headers(): Record<string, string>;
  postData(): string | undefined;
  response(): HTTPResponse | null;
  abort(errorCode?: string): Promise<void>;
  continue(overrides?: ContinueRequestOverrides): Promise<void>;
  respond(response: ResponseForRequest): Promise<void>;
}

interface HTTPResponse {
  ok(): boolean;
  status(): number;
  statusText(): string;
  headers(): Record<string, string>;
  url(): string;
  text(): Promise<string>;
  json(): Promise<any>;
  buffer(): Promise<Buffer>;
}

Network Management

Locators and Selectors

Advanced element location strategies including CSS selectors, XPath, text content, custom query handlers, and the modern Locator API.

interface Locator<T> {
  click(options?: LocatorClickOptions): Promise<void>;
  fill(value: string, options?: LocatorFillOptions): Promise<void>;
  hover(options?: LocatorHoverOptions): Promise<void>;
  scroll(options?: LocatorScrollOptions): Promise<void>;
  wait(options?: LocatorWaitOptions): Promise<T>;
  waitFor(options?: LocatorWaitOptions): Promise<void>;
  map<U>(mapper: (value: T) => Promise<U>): Locator<U>;
  filter<U extends T>(predicate: (value: T) => Promise<boolean>): Locator<U>;
}

Locators and Selectors

Browser Contexts

Isolated browser contexts for managing sessions, cookies, permissions, and parallel test execution.

interface BrowserContext extends EventEmitter {
  newPage(): Promise<Page>;
  pages(): Page[];
  cookies(...urls: string[]): Promise<Cookie[]>;
  setCookie(...cookies: CookieParam[]): Promise<void>;
  clearPermissionOverrides(): Promise<void>;
  overridePermissions(origin: string, permissions: Permission[]): Promise<void>;
  setGeolocation(options: GeolocationOptions): Promise<void>;
  close(): Promise<void>;
}

Browser Contexts

Core Types

interface LaunchOptions {
  executablePath?: string;
  headless?: boolean | "new";
  args?: string[];
  ignoreDefaultArgs?: boolean | string[];
  handleSIGINT?: boolean;
  handleSIGTERM?: boolean;
  handleSIGHUP?: boolean;
  timeout?: number;
  dumpio?: boolean;
  userDataDir?: string;
  env?: Record<string, string | undefined>;
  devtools?: boolean;
  pipe?: 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;
  headers?: Record<string, string>;
}

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

interface Cookie {
  name: string;
  value: string;
  domain?: string;
  path?: string;
  expires?: number;
  size?: number;
  httpOnly?: boolean;
  secure?: boolean;
  session?: boolean;
  sameSite?: "Strict" | "Lax" | "None";
  priority?: "Low" | "Medium" | "High";
  sameParty?: boolean;
  sourceScheme?: "Unset" | "NonSecure" | "Secure";
  partitionKey?: string;
}

type Protocol = "cdp" | "webDriverBiDi";

interface Target {
  createCDPSession(): Promise<CDPSession>;
  page(): Promise<Page | null>;
  url(): string;
  type(): "page" | "background_page" | "service_worker" | "shared_worker" | "other" | "browser" | "webview";
  browser(): Browser;
  browserContext(): BrowserContext;
  opener(): Target | undefined;
}

interface CDPSession extends EventEmitter {
  send<T = any>(method: string, ...paramArgs: any[]): Promise<T>;
  connection(): Connection | undefined;
  detach(): Promise<void>;
  id(): string;
}

interface Connection extends EventEmitter {
  url(): string;
  send<T = any>(method: string, ...paramArgs: any[]): Promise<T>;
  createSession(targetInfo: Target): Promise<CDPSession>;
  dispose(): void;
}

interface ExecutionContext {
  evaluate<T>(pageFunction: Function, ...args: any[]): Promise<T>;
  evaluateHandle<T>(pageFunction: Function, ...args: any[]): Promise<JSHandle<T>>;
  frame(): Frame | null;
  queryObjects<T>(prototypeHandle: JSHandle<T>): Promise<HandleFor<T[]>>;
}

interface FileChooser {
  isMultiple(): boolean;
  accept(filePaths: string[]): Promise<void>;
  cancel(): Promise<void>;
}

type HandleFor<T> = T extends Node ? ElementHandle<T> : JSHandle<T>;

Error Classes

class PuppeteerError extends Error {
  constructor(message?: string, options?: ErrorOptions);
}

class TimeoutError extends PuppeteerError {
  constructor(message?: string, options?: ErrorOptions);
}

class TouchError extends PuppeteerError {
  constructor(message?: string, options?: ErrorOptions);
}

class ProtocolError extends PuppeteerError {
  constructor(message?: string, options?: ErrorOptions);
  code?: number;
  originalMessage: string;
}

class UnsupportedOperation extends PuppeteerError {
  constructor(message?: string, options?: ErrorOptions);
}

class TargetCloseError extends ProtocolError {
  constructor(message?: string, options?: ErrorOptions);
}

class ConnectionClosedError extends ProtocolError {
  constructor(message?: string, options?: ErrorOptions);
}

Protocol Types

namespace Protocol {
  // Chrome DevTools Protocol types (re-exported from devtools-protocol package)
  namespace Runtime {
    interface RemoteObject {
      type: "object" | "function" | "undefined" | "string" | "number" | "boolean" | "symbol" | "bigint";
      subtype?: "array" | "null" | "node" | "regexp" | "date" | "map" | "set" | "weakmap" | "weakset" | "iterator" | "generator" | "error" | "proxy" | "promise" | "typedarray" | "arraybuffer" | "dataview";
      className?: string;
      value?: any;
      unserializableValue?: string;
      description?: string;
      objectId?: string;
      preview?: ObjectPreview;
      customPreview?: CustomPreview;
    }

    interface ObjectPreview {
      type: "object" | "function" | "undefined" | "string" | "number" | "boolean" | "symbol" | "bigint";
      subtype?: "array" | "null" | "node" | "regexp" | "date" | "map" | "set" | "weakmap" | "weakset" | "iterator" | "generator" | "error" | "proxy" | "promise" | "typedarray" | "arraybuffer" | "dataview";
      description?: string;
      overflow: boolean;
      properties: PropertyPreview[];
      entries?: EntryPreview[];
    }

    interface PropertyPreview {
      name: string;
      type: "object" | "function" | "undefined" | "string" | "number" | "boolean" | "symbol" | "bigint" | "accessor";
      value?: string;
      valuePreview?: ObjectPreview;
      subtype?: "array" | "null" | "node" | "regexp" | "date" | "map" | "set" | "weakmap" | "weakset" | "iterator" | "generator" | "error" | "proxy" | "promise" | "typedarray" | "arraybuffer" | "dataview";
    }

    interface EntryPreview {
      key?: ObjectPreview;
      value: ObjectPreview;
    }

    interface CustomPreview {
      header: string;
      bodyGetterId?: string;
    }
  }
}