Principle:Puppeteer Puppeteer Browser Context Isolation
| Knowledge Sources | |
|---|---|
| Domains | Browser_Automation, Security |
| Last Updated | 2026-02-12 00:00 GMT |
Overview
Browser context isolation is the principle of creating independent browser profiles within a single browser instance such that each context maintains its own cookies, cache, local storage, and session state without sharing data with other contexts.
Description
Browser Context Isolation provides a mechanism for running multiple independent browsing sessions inside the same browser process. Each BrowserContext acts as an incognito-like profile: it has its own cookie jar, local storage partitions, IndexedDB databases, service worker registrations, and cache storage. Changes made in one context are completely invisible to all other contexts.
When a browser is launched, it always has a default browser context that cannot be closed. Additional contexts are created explicitly and can be closed independently, which destroys all pages and resources associated with them. This architecture is essential for:
- Test isolation: Running parallel tests that do not interfere with each other's authentication state or stored data.
- Multi-tenant simulation: Simulating multiple users interacting with the same application simultaneously.
- Permission sandboxing: Granting or revoking browser permissions (geolocation, notifications, etc.) on a per-context basis without affecting other contexts.
- Cookie partitioning: Each context can have its own cookie set, enabling scenarios like testing logged-in and logged-out states concurrently.
Contexts also emit lifecycle events (TargetCreated, TargetDestroyed, TargetChanged) for every page or worker that is opened or closed within them, allowing fine-grained monitoring of activity scoped to that context.
Usage
Use browser context isolation whenever you need to run multiple independent sessions within a single browser. This is especially important in automated testing where parallel test suites should not share cookies or storage, when simulating multiple users, or when you need to test permission-sensitive features in isolation. The default browser context is sufficient for single-session workflows, but any scenario requiring state separation demands the creation of additional contexts.
Theoretical Basis
The isolation model is conceptually equivalent to running multiple private browsing sessions. Each context maintains a separate storage partition:
BROWSER INSTANCE
|
+-- Default Context
| +-- Storage Partition A (cookies, cache, localStorage, IndexedDB)
| +-- Page 1
| +-- Page 2
|
+-- Incognito Context 1
| +-- Storage Partition B (cookies, cache, localStorage, IndexedDB)
| +-- Page 3
|
+-- Incognito Context 2
+-- Storage Partition C (cookies, cache, localStorage, IndexedDB)
+-- Page 4
Pseudocode for context lifecycle:
1. context = browser.createBrowserContext()
2. page = context.newPage() // page belongs to context
3. context.overridePermissions(origin, [permissions])
4. context.setCookie(cookieData) // cookie visible only in this context
5. ... perform actions ...
6. context.close() // destroys all pages + storage partition
The key guarantee is that no storage artifact (cookie, cache entry, service worker, or storage record) created in one context is ever accessible from another context. This is enforced at the browser engine level through per-context storage partitions, not through application-level filtering.