Implementation:Puppeteer Puppeteer Bidi Browser

Property	Value
Implementation	BidiBrowser
Source File	packages/puppeteer-core/src/bidi/Browser.ts
Repository	puppeteer/puppeteer
Lines	378
License	Apache-2.0
Copyright	2022 Google Inc.

Overview

Description

BidiBrowser is the WebDriver BiDi implementation of Puppeteer's Browser abstract class. It represents a connected browser instance and serves as the top-level entry point for creating pages, managing browser contexts, and controlling the browser lifecycle.

Key responsibilities:

• Session initialization: The static create() factory method establishes a BiDi session with capability negotiation (including acceptInsecureCerts, unhandledPromptBehavior, webSocketUrl, and Chrome-specific options like goog:prerenderingDisabled). It subscribes to BiDi modules (browsingContext, network, log, script, input) and optionally to CDP events (for coverage, tracing, etc.) when a CDP connection is available. It also sets up network data collectors with a 20 MB buffer.

• Browser context management: Creates and tracks BidiBrowserContext instances backed by BiDi user contexts. createBrowserContext() creates new isolated contexts, browserContexts() lists all contexts, and defaultBrowserContext() returns the default context.

• Page creation: newPage() delegates to the default browser context.

• Connection and lifecycle: Provides wsEndpoint(), connected, close(), disconnect(), and process() for managing the browser connection and process. Emits BrowserEvent.Disconnected when the connection is lost.

• Target management: Maintains a BidiBrowserTarget and delegates target listing to browser contexts. Forwards TargetCreated, TargetChanged, and TargetDestroyed events from contexts to the browser level.

• Window management: getWindowBounds() and setWindowBounds() for controlling browser window position, size, and state via browser.getClientWindows and browser.setClientWindowState.

• Extensions: installExtension() and uninstallExtension() via webExtension.install / webExtension.uninstall.

• CDP support detection: The cdpSupported getter indicates whether a CDP connection is available for fallback operations.

Usage

BidiBrowser is created internally by Puppeteer's launcher or connect flow. Users receive a Browser instance from puppeteer.launch() or puppeteer.connect().

Code Reference

Source Location

packages/puppeteer-core/src/bidi/Browser.ts (GitHub)

Signature

export interface BidiBrowserOptions {
  process?: ChildProcess;
  closeCallback?: BrowserCloseCallback;
  connection: BidiConnection;
  cdpConnection?: CdpConnection;
  defaultViewport: Viewport | null;
  acceptInsecureCerts?: boolean;
  capabilities?: SupportedWebDriverCapabilities;
  networkEnabled: boolean;
}

export class BidiBrowser extends Browser {
  readonly protocol = 'webDriverBiDi';
  static readonly subscribeModules: [string, ...string[]];
  static readonly subscribeCdpEvents: Array<CdpEvent['method']>;

  static async create(opts: BidiBrowserOptions): Promise<BidiBrowser>;

  get cdpSupported(): boolean;
  get cdpConnection(): CdpConnection | undefined;
  get connection(): BidiConnection;

  override async userAgent(): Promise<string>;
  override wsEndpoint(): string;
  override async close(): Promise<void>;
  override get connected(): boolean;
  override process(): ChildProcess | null;
  override async createBrowserContext(options?: BrowserContextOptions): Promise<BidiBrowserContext>;
  override async version(): Promise<string>;
  override browserContexts(): BidiBrowserContext[];
  override defaultBrowserContext(): BidiBrowserContext;
  override newPage(options?: CreatePageOptions): Promise<Page>;
  override installExtension(path: string): Promise<string>;
  override async uninstallExtension(id: string): Promise<void>;
  override async getWindowBounds(windowId: WindowId): Promise<WindowBounds>;
  override async setWindowBounds(windowId: WindowId, windowBounds: WindowBounds): Promise<void>;
  override targets(): Target[];
  override target(): BidiBrowserTarget;
  override async disconnect(): Promise<void>;
  override get debugInfo(): DebugInfo;
  override isNetworkEnabled(): boolean;
}

Import

import {BidiBrowser} from './Browser.js';

I/O Contract

Inputs

Parameter	Type	Description
opts.connection	BidiConnection	The WebDriver BiDi WebSocket connection
opts.cdpConnection	CdpConnection	Optional CDP connection for fallback features
opts.defaultViewport	null	Default viewport to apply to new pages
opts.acceptInsecureCerts	boolean	Whether to accept insecure TLS certificates
opts.capabilities	SupportedWebDriverCapabilities	WebDriver session capabilities
opts.process	ChildProcess	The browser child process handle
opts.networkEnabled	boolean	Whether network event subscription is enabled

Outputs

Method	Return Type	Description
create	Promise<BidiBrowser>	A fully initialized browser instance
version	Promise<string>	Browser name and version (e.g., "Chrome/120.0")
userAgent	Promise<string>	The browser's user agent string
wsEndpoint	string	The WebSocket URL of the BiDi connection
browserContexts	BidiBrowserContext[]	All browser contexts
createBrowserContext	Promise<BidiBrowserContext>	A new isolated browser context
newPage	Promise<Page>	A new page in the default context
connected	boolean	Whether the browser is still connected
targets	Target[]	All active targets across all contexts

Usage Examples

import puppeteer from 'puppeteer';

// Launch a browser (internally creates BidiBrowser)
const browser = await puppeteer.launch({
  protocol: 'webDriverBiDi',
  headless: true,
});

// Browser info
console.log(await browser.version());
console.log(browser.wsEndpoint());

// Create an isolated browser context
const context = await browser.createBrowserContext();
const page = await context.newPage();
await page.goto('https://example.com');

// Window management
const windowId = await page.windowId();
const bounds = await browser.getWindowBounds(windowId);
await browser.setWindowBounds(windowId, {
  width: 1024,
  height: 768,
  windowState: 'normal',
});

// Extension management
const extId = await browser.installExtension('/path/to/extension');
await browser.uninstallExtension(extId);

// Cleanup
await context.close();
await browser.close();

Related Pages

• Environment:Puppeteer_Puppeteer_Node_18_Runtime