Implementation:Puppeteer Puppeteer Bidi BrowserContext

Property	Value
Implementation	BidiBrowserContext
Source File	packages/puppeteer-core/src/bidi/BrowserContext.ts
Repository	puppeteer/puppeteer
Lines	394
License	Apache-2.0
Copyright	2022 Google Inc.

Overview

Description

BidiBrowserContext is the WebDriver BiDi implementation of Puppeteer's BrowserContext abstract class. It represents an isolated browser context (analogous to an incognito profile) backed by a BiDi UserContext. Each browser context maintains its own set of pages, cookies, permissions, and storage.

Key responsibilities:

• Page management: newPage() creates new pages (tabs or windows) within the user context, applying the default viewport and optional window bounds. Tracks pages via a WeakMap from browsing contexts to BidiPage instances. Handles popup events by detecting originalOpener on new browsing contexts.

• Target tracking: Maintains a comprehensive target map with BidiPageTarget, BidiFrameTarget, and BidiWorkerTarget instances. Emits BrowserContextEvent.TargetCreated, TargetChanged, and TargetDestroyed for each frame attachment/navigation/detachment and worker creation/destruction.

• Permission management: overridePermissions() sets all known web permissions to granted or denied for a given origin. setPermission() provides fine-grained control over individual permission descriptors with state (granted, denied, prompt). clearPermissionOverrides() resets all overridden permissions to prompt.

• Cookie management: cookies() retrieves all cookies for the user context (with composite partition key support). setCookie() sets cookies with full BiDi storage API support including sameSite, expiry, and Chrome-specific properties.

• Lifecycle: close() removes the user context (asserts it is not the default context). The id getter returns undefined for the default context and the user context ID for custom contexts.

Usage

BidiBrowserContext instances are created by BidiBrowser either during initialization (for existing user contexts) or via browser.createBrowserContext(). Users obtain contexts through the Browser API.

Code Reference

Source Location

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

Signature

export interface BidiBrowserContextOptions {
  defaultViewport: Viewport | null;
}

export class BidiBrowserContext extends BrowserContext {
  static from(
    browser: BidiBrowser,
    userContext: UserContext,
    options: BidiBrowserContextOptions,
  ): BidiBrowserContext;

  accessor trustedEmitter: EventEmitter<BrowserContextEvents>;
  readonly userContext: UserContext;

  override targets(): Target[];
  override async newPage(options?: CreatePageOptions): Promise<Page>;
  override async close(): Promise<void>;
  override browser(): BidiBrowser;
  override async pages(_includeAll?: boolean): Promise<BidiPage[]>;
  override async overridePermissions(origin: string, permissions: Permission[]): Promise<void>;
  override async setPermission(
    origin: string | '*',
    ...permissions: Array<{permission: PermissionDescriptor; state: PermissionState}>
  ): Promise<void>;
  override async clearPermissionOverrides(): Promise<void>;
  override get id(): string | undefined;
  override async cookies(): Promise<Cookie[]>;
  override async setCookie(...cookies: CookieData[]): Promise<void>;
}

Import

import {BidiBrowserContext} from './BrowserContext.js';

I/O Contract

Inputs

Parameter	Type	Description
browser	BidiBrowser	The parent browser instance
userContext	UserContext	The low-level BiDi user context
options.defaultViewport	null	Default viewport applied to new pages

Key Method Parameters

Method	Parameter	Type	Description
newPage	options.type	'window'	Whether to create a tab or a new window
newPage	options.background	boolean	Whether to open the page in the background
newPage	options.windowBounds	WindowBounds	Window size/position (only for 'window' type)
overridePermissions	origin	string	The origin to override permissions for
overridePermissions	permissions	Permission[]	List of permissions to grant
setPermission	origin	string	The origin for permission (cannot be '*')
setCookie	cookies	CookieData[]	Cookie objects with name, value, domain, path, etc.

Outputs

Method	Return Type	Description
newPage	Promise<Page>	A new page in this context
pages	Promise<BidiPage[]>	All pages in this context
targets	Target[]	All targets (pages, frames, workers) in this context
cookies	Promise<Cookie[]>	All cookies for the user context
id	undefined	The context ID, or undefined for the default context
browser	BidiBrowser	The parent browser

Usage Examples

// Create an isolated browser context
const context = await browser.createBrowserContext();

// Create a page in the context
const page = await context.newPage();
await page.goto('https://example.com');

// Create a new window
const windowPage = await context.newPage({
  type: 'window',
  windowBounds: {width: 800, height: 600},
});

// Permission management
await context.overridePermissions('https://example.com', [
  'geolocation',
  'notifications',
]);

// Fine-grained permission control
await context.setPermission('https://example.com', {
  permission: {name: 'camera'},
  state: 'granted',
});

// Cookie management at context level
await context.setCookie({
  name: 'token',
  value: 'xyz',
  domain: '.example.com',
});
const cookies = await context.cookies();

// List all pages
const pages = await context.pages();

// Close the context (also closes all pages)
await context.close();

Related Pages

• Environment:Puppeteer_Puppeteer_Node_18_Runtime