Implementation:Puppeteer Puppeteer Puppeteer Class

Property	Value
sources	packages/puppeteer-core/src/common/Puppeteer.ts
domains	Core, Browser Management, Entry Point
last_updated	2026-02-12 00:00 GMT

Overview

Description

Puppeteer is the main base class for the Puppeteer library. It provides the core functionality shared across all environments, including browser connection and custom query handler management. In a Node.js environment, users receive an instance of PuppeteerNode (which extends this class) when importing puppeteer, adding additional capabilities like browser launching and downloading.

The class provides the following static methods for custom query handler management, which delegate to the singleton customQueryHandlers registry:

• registerCustomQueryHandler -- Registers a custom query handler under a given name.
• unregisterCustomQueryHandler -- Removes a registered custom query handler.
• customQueryHandlerNames -- Returns the names of all registered handlers.
• clearCustomQueryHandlers -- Removes all registered custom query handlers.

The instance method connect attaches Puppeteer to an existing browser instance using the provided ConnectOptions (such as a browser WebSocket endpoint or transport), delegating to the internal _connectToBrowser function.

The class also tracks whether it is running as puppeteer-core via the _isPuppeteerCore flag and whether the browser has been changed via the _changedBrowsers flag.

Usage

Users interact with the Puppeteer class indirectly through the default export of the puppeteer package. The connect method is used to attach to an already-running browser, while the static custom query handler methods allow extending Puppeteer's selector engine.

Code Reference

Source Location

packages/puppeteer-core/src/common/Puppeteer.ts

Signature

export interface CommonPuppeteerSettings {
  isPuppeteerCore: boolean;
}

export class Puppeteer {
  static customQueryHandlers: CustomQueryHandlerRegistry;

  static registerCustomQueryHandler(
    name: string,
    queryHandler: CustomQueryHandler,
  ): void;

  static unregisterCustomQueryHandler(name: string): void;

  static customQueryHandlerNames(): string[];

  static clearCustomQueryHandlers(): void;

  _isPuppeteerCore: boolean;
  protected _changedBrowsers: boolean;

  constructor(settings: CommonPuppeteerSettings);

  connect(options: ConnectOptions): Promise<Browser>;
}

Import

import {Puppeteer} from './Puppeteer.js';

I/O Contract

Method	Parameters	Return Type	Description
constructor	CommonPuppeteerSettings	instance	Creates a new Puppeteer instance with the given settings
connect	ConnectOptions	Promise<Browser>	Connects to an existing browser instance
registerCustomQueryHandler (static)	name: string, handler: CustomQueryHandler	void	Registers a custom query handler
unregisterCustomQueryHandler (static)	name: string	void	Unregisters a custom query handler
customQueryHandlerNames (static)	none	string[]	Returns all registered handler names
clearCustomQueryHandlers (static)	none	void	Clears all custom query handlers

Usage Examples

import puppeteer from 'puppeteer';

// Connect to an existing browser instance via WebSocket
const browser = await puppeteer.connect({
  browserWSEndpoint: 'ws://127.0.0.1:9222/devtools/browser/...',
});

const page = await browser.newPage();
await page.goto('https://example.com');

// Register a custom query handler
puppeteer.registerCustomQueryHandler('getById', {
  queryOne: (element, selector) => {
    return element.querySelector(`[id="${selector}"]`);
  },
});

// Use the custom handler
const el = await page.$('getById/my-element');

// List registered handlers
console.log(puppeteer.customQueryHandlerNames()); // ['getById']

// Clean up
puppeteer.clearCustomQueryHandlers();
await browser.close();

Related Pages

• Environment:Puppeteer_Puppeteer_Node_18_Runtime