Implementation:Puppeteer Puppeteer BrowserContext
| Sources | packages/puppeteer-core/src/api/BrowserContext.ts |
|---|---|
| Domains | Browser Automation, Context Isolation, Cookie Management |
| Last Updated | 2026-02-12 |
Overview
BrowserContext is the abstract base class that represents an isolated user context within a browser, providing session isolation for cookies, local storage, and permissions.
Description
The BrowserContext class extends EventEmitter and models the concept of isolated browser sessions. When a browser is launched, it has at least one default browser context, and additional contexts can be created via Browser.createBrowserContext(). Each context maintains its own isolated storage (cookies, localStorage, etc.), making it suitable for scenarios that require session separation such as multi-user testing or incognito browsing.
The class emits three target-lifecycle events through the BrowserContextEvent enum: TargetChanged, TargetCreated, and TargetDestroyed. It provides abstract methods for page management (newPage, pages), permission control (overridePermissions, setPermission, clearPermissionOverrides), cookie management (cookies, setCookie, deleteCookie, deleteMatchingCookies), and lifecycle operations (close, browser).
Internally, the class also manages a screenshot mutex to coordinate concurrent screenshot operations across pages within the same context. The class implements both synchronous and asynchronous dispose symbols, enabling use with the using keyword for automatic resource cleanup.
In Chrome, all non-default contexts are incognito. The default browser context may also be incognito if the browser is launched with the --incognito argument.
Usage
BrowserContext is not instantiated directly. Consumers obtain instances through Browser.createBrowserContext() or Browser.defaultBrowserContext(). Concrete protocol-specific implementations (CDP or BiDi) extend this abstract class to provide the actual browser communication.
Code Reference
Source Location
packages/puppeteer-core/src/api/BrowserContext.ts
Signature
export abstract class BrowserContext extends EventEmitter<BrowserContextEvents> {
abstract targets(): Target[];
abstract pages(includeAll?: boolean): Promise<Page[]>;
abstract overridePermissions(origin: string, permissions: Permission[]): Promise<void>;
abstract setPermission(origin: string | '*', ...permissions: Array<{ permission: PermissionDescriptor; state: PermissionState }>): Promise<void>;
abstract clearPermissionOverrides(): Promise<void>;
abstract newPage(options?: CreatePageOptions): Promise<Page>;
abstract browser(): Browser;
abstract close(): Promise<void>;
abstract cookies(): Promise<Cookie[]>;
abstract setCookie(...cookies: CookieData[]): Promise<void>;
async deleteCookie(...cookies: Cookie[]): Promise<void>;
async deleteMatchingCookies(...filters: DeleteCookiesRequest[]): Promise<void>;
async waitForTarget(predicate: (x: Target) => boolean | Promise<boolean>, options?: WaitForTargetOptions): Promise<Target>;
get closed(): boolean;
get id(): string | undefined;
}
Import
import type {BrowserContext} from 'puppeteer-core/src/api/BrowserContext.js';
I/O Contract
Inputs
| Parameter | Type | Description |
|---|---|---|
| predicate (waitForTarget) | Promise<boolean> | Filter function to match a target |
| options (waitForTarget) | WaitForTargetOptions |
Optional timeout configuration (default 30000ms) |
| origin (overridePermissions) | string |
The origin to grant permissions to |
| permissions (overridePermissions) | Permission[] |
Array of permissions to grant |
| cookies (setCookie) | CookieData[] |
Cookie data objects to set |
| cookies (deleteCookie) | Cookie[] |
Complete cookie objects to remove |
| filters (deleteMatchingCookies) | DeleteCookiesRequest[] |
Filters for matching cookies to delete |
| options (newPage) | CreatePageOptions |
Optional page creation options |
Outputs
| Method | Return Type | Description |
|---|---|---|
| targets() | Target[] |
All active targets in this context |
| pages() | Promise<Page[]> |
All open pages in this context |
| waitForTarget() | Promise<Target> |
The first target matching the predicate |
| newPage() | Promise<Page> |
A newly created page |
| browser() | Browser |
The parent browser instance |
| cookies() | Promise<Cookie[]> |
All cookies in this context |
| closed | boolean |
Whether this context has been closed |
| id | undefined | The context identifier |
Usage Examples
// Create a new isolated browser context
const context = await browser.createBrowserContext();
// Create a page inside the context
const page = await context.newPage();
await page.goto('https://example.com');
// Dispose context once done
await context.close();
// Wait for a target opened via window.open
await page.evaluate(() => window.open('https://www.example.com/'));
const newWindowTarget = await browserContext.waitForTarget(
target => target.url() === 'https://www.example.com/',
);
// Override permissions in the default browser context
const context = browser.defaultBrowserContext();
await context.overridePermissions('https://html5demos.com', [
'geolocation',
]);
// Manage cookies in a browser context
const cookies = await context.cookies();
await context.setCookie({ name: 'session', value: 'abc123', domain: 'example.com' });
await context.deleteMatchingCookies({ name: 'session', domain: 'example.com' });