Implementation:Puppeteer Puppeteer Cdp Browser

Property	Value
sources	packages/puppeteer-core/src/cdp/Browser.ts
domains	Browser Management, CDP, Browser Automation
last_updated	2026-02-12 00:00 GMT

Overview

Description

The CdpBrowser class is the CDP-specific implementation of the abstract Browser base class. It represents a connected browser instance and provides the primary entry point for interacting with the browser through the Chrome DevTools Protocol.

Key responsibilities include:

• Browser lifecycle management -- Creating the browser via the static _create factory method, closing, and disconnecting.
• Browser context management -- Creating and disposing of isolated browser contexts with optional proxy settings and download behaviors.
• Target management -- Tracking all browser targets (tabs, workers, pages, etc.) using a TargetManager instance, and emitting events when targets are created, destroyed, or changed.
• Page creation -- Creating new pages in browser contexts via Target.createTarget CDP commands, including support for DevTools pages and windowed pages.
• Extension management -- Installing and uninstalling browser extensions.
• Screen management -- Managing virtual screens for multi-display emulation.
• Window management -- Getting and setting window bounds for browser windows.

The class uses a TargetManager for auto-attach-based target discovery and creates different target types (PageTarget, WorkerTarget, DevToolsTarget, OtherTarget) based on the target info received from CDP.

Usage

CdpBrowser instances are created internally by Puppeteer when launching or connecting to a Chrome browser. Users interact with the browser through the public Browser API returned by puppeteer.launch() or puppeteer.connect().

Code Reference

Source Location: packages/puppeteer-core/src/cdp/Browser.ts (541 lines)

Signature:

export class CdpBrowser extends BrowserBase {
  readonly protocol = 'cdp';

  static async _create(
    connection: Connection,
    contextIds: string[],
    acceptInsecureCerts: boolean,
    defaultViewport?: Viewport | null,
    downloadBehavior?: DownloadBehavior,
    process?: ChildProcess,
    closeCallback?: BrowserCloseCallback,
    targetFilterCallback?: TargetFilterCallback,
    isPageTargetCallback?: IsPageTargetCallback,
    waitForInitiallyDiscoveredTargets?: boolean,
    networkEnabled?: boolean,
    handleDevToolsAsPage?: boolean,
  ): Promise<CdpBrowser>;

  override async createBrowserContext(options?: BrowserContextOptions): Promise<CdpBrowserContext>;
  override browserContexts(): CdpBrowserContext[];
  override defaultBrowserContext(): CdpBrowserContext;
  override async newPage(options?: CreatePageOptions): Promise<Page>;
  override targets(): CdpTarget[];
  override target(): CdpTarget;
  override async version(): Promise<string>;
  override async userAgent(): Promise<string>;
  override async close(): Promise<void>;
  override disconnect(): Promise<void>;
  override get connected(): boolean;
}

Import:

import { CdpBrowser } from 'puppeteer-core/lib/cdp/Browser.js';

I/O Contract

Inputs (Factory Method _create):

Parameter	Type	Required	Description
connection	Connection	Yes	The CDP WebSocket connection
contextIds	string[]	Yes	Initial browser context IDs
acceptInsecureCerts	boolean	Yes	Whether to ignore certificate errors
defaultViewport	null	No	Default viewport for new pages
downloadBehavior	DownloadBehavior	No	Default download behavior configuration
process	ChildProcess	No	The browser child process
closeCallback	BrowserCloseCallback	No	Callback invoked on browser close
targetFilterCallback	TargetFilterCallback	No	Filter function for targets
isPageTargetCallback	IsPageTargetCallback	No	Custom callback to determine if a target is a page

Outputs:

Output	Type	Description
browser	CdpBrowser	A fully initialized browser instance connected via CDP
newPage()	Promise<Page>	A new page in the default browser context
targets()	CdpTarget[]	All available and initialized targets
version()	Promise<string>	The browser version string (e.g., "Chrome/XX.X.XXXX.XX")

Usage Examples

import puppeteer from 'puppeteer';

// Launch creates a CdpBrowser instance internally
const browser = await puppeteer.launch({ headless: true });

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

// Get browser version
const version = await browser.version();
console.log(version); // e.g., "Chrome/120.0.6099.0"

// Create an isolated browser context
const context = await browser.createBrowserContext({
  proxyServer: 'http://proxy:8080',
});
const contextPage = await context.newPage();

// List all targets
const targets = browser.targets();
for (const target of targets) {
  console.log(target.type(), target.url());
}

// Get the WebSocket endpoint
const wsEndpoint = browser.wsEndpoint();

// Install an extension
const extensionId = await browser.installExtension('/path/to/extension');

// Close the browser
await browser.close();

Related Pages

• Environment:Puppeteer_Puppeteer_Node_18_Runtime