Implementation:Microsoft Playwright Server BrowserContext

Knowledge Sources	Microsoft_Playwright
Domains	Browser Automation, Isolation Context
Last Updated	2026-02-12 00:00 GMT

Overview

Concrete tool for managing browser isolation contexts on the server side provided by the Playwright library.

Description

The `BrowserContext` abstract class extends `SdkObject` and represents an isolated browser session with its own cookies, storage, and configuration. It is the server-side base for all browser-specific context implementations (Chromium, Firefox, WebKit, BiDi). The class manages pages, request interception via `RouteHandler`, page bindings, init scripts, tracing (`Tracing`), HAR recording (`HarRecorder`), dialog management (`DialogManager`), clock simulation (`Clock`), and the browser context lifecycle. It emits events for page creation/closure, requests, responses, console messages, and errors. Context options include viewport, user agent, locale, geolocation, permissions, proxy, and storage state.

Usage

Use this abstract class as the base for browser-specific context implementations. It provides the shared logic for all context operations across Chromium, Firefox, WebKit, and BiDi backends.

Code Reference

Source Location

Repository: Microsoft_Playwright
File: packages/playwright-core/src/server/browserContext.ts

Signature

export abstract class BrowserContext<EM extends EventMap = EventMap> extends SdkObject<BrowserContextEventMap | EM> {
  static Events: typeof BrowserContextEvent;
  readonly _pageBindings: Map<string, PageBinding>;
  readonly _options: types.BrowserContextOptions;
  readonly requestInterceptors: network.RouteHandler[];

  constructor(browser: Browser, options: types.BrowserContextOptions, browserContextId: string | undefined);
  abstract pages(): Page[];
  abstract newPageDelegate(): Promise<PageDelegate>;
  abstract addCookies(cookies: types.SetNetworkCookieParam[]): Promise<void>;
  abstract clearCookies(options?: channels.BrowserContextClearCookiesParams): Promise<void>;
  abstract doGrantPermissions(origin: string, permissions: string[]): Promise<void>;
  abstract doSetHTTPCredentials(httpCredentials: types.Credentials | undefined): Promise<void>;
  abstract doClose(reason: string | undefined): Promise<void>;
}

Import

import { BrowserContext } from '../server/browserContext';

I/O Contract

Inputs

Name	Type	Required	Description
browser	Browser	Yes	Parent browser instance
options	types.BrowserContextOptions	Yes	Context configuration (viewport, userAgent, locale, etc.)
browserContextId	string or undefined	Yes	Unique context ID (undefined for default/persistent context)

Outputs

Name	Type	Description
pages	Page[]	All pages in this context
newPage	Page	Newly created page within the context
cookies	NetworkCookie[]	Cookies associated with the context
storageState	SerializedStorage	Serialized storage state for persistence

Usage Examples

// Browser-specific subclasses implement the abstract methods
class CRBrowserContext extends BrowserContext {
  async pages(): Page[] { /* ... */ }
  async newPageDelegate(): Promise<PageDelegate> { /* ... */ }
  // ... other abstract method implementations
}

// Usage via the browser
const context = await browser.newContext({
  viewport: { width: 1280, height: 720 },
  userAgent: 'Custom Agent',
  locale: 'en-US',
});
const page = await context.newPage();
await context.close();

Related Pages

Environment:Microsoft_Playwright_Node_Runtime_Environment

Page Connections

Double-click a node to navigate. Hold to expand connections.

Principle

Implementation

Heuristic

Environment