This document explains the Browser and BrowserContext APIs in Playwright, including browser launching options, isolation boundaries, cookie/storage management, and context-level configuration. The Browser class represents a browser instance launched from a BrowserType, while BrowserContext provides isolated browsing sessions with separate cookies, cache, and storage. For information about pages and frames within contexts, see Page and Frame Management. For network interception capabilities, see Network Interception.
Playwright uses a hierarchical model where a Browser instance contains one or more BrowserContext instances, each containing one or more Page instances. This hierarchy provides isolation and allows parallel test execution.
Sources: packages/playwright-core/types/types.d.ts1-100 packages/playwright-core/src/server/browserContext.ts50-113
Before working with browsers and contexts, a browser must be launched from a BrowserType instance. Playwright provides three browser types: chromium, firefox, and webkit.
Title: BrowserType Launch Methods
Launch Methods:
browserType.launch(options): Launches a new browser instancebrowserType.launchPersistentContext(userDataDir, options): Launches browser with persistent storagebrowserType.connect(wsEndpoint, options): Connects to remote browser via WebSocketbrowserType.connectOverCDP(endpointURL, options): (Chromium only) Connects via Chrome DevTools ProtocolSources: packages/playwright-core/types/types.d.ts14500-14700 packages/protocol/src/protocol.yml484-531
The LaunchOptions mixin in the protocol defines browser launch configuration:
Title: Browser Launch Options Structure
Key Launch Options:
| Category | Option | Description |
|---|---|---|
| Browser Selection | channel | Browser channel: "chrome", "msedge", etc. |
executablePath | Path to browser executable | |
| Arguments | args | Additional browser arguments |
ignoreDefaultArgs | Array of default args to skip | |
ignoreAllDefaultArgs | Skip all default arguments | |
| Process | timeout | Launch timeout in milliseconds |
env | Environment variables for browser process | |
handleSIGINT/SIGTERM/SIGHUP | Signal handling behavior | |
| Display | headless | Run browser in headless mode |
| Network | proxy | Proxy server configuration |
downloadsPath | Download directory path | |
| Storage | tracesDir | Trace files directory |
| Chromium | chromiumSandbox | Enable/disable sandbox |
cdpPort | Chrome DevTools Protocol port | |
| Firefox | firefoxUserPrefs | Firefox user preferences |
| All | slowMo | Slow down operations by N milliseconds |
Sources: packages/protocol/src/protocol.yml455-491 packages/playwright-core/src/protocol/validator.ts506-531
Title: Launch Method Comparison
launch() Use Cases:
launchPersistentContext() Use Cases:
Sources: packages/protocol/src/protocol.yml506-531 packages/protocol/src/protocol.yml535-617
The Browser class represents a single browser instance and provides the entry point for creating isolated browser contexts. Each browser type has its own implementation but exposes a unified API through the base Browser class.
The Browser class in packages/playwright-core/src/server/browser.ts1-200 represents a browser instance. Each browser type has its own implementation:
| Browser Type | Server Class | File Location | Protocol |
|---|---|---|---|
| Chromium | CRBrowser | packages/playwright-core/src/server/chromium/crBrowser.ts1-100 | Chrome DevTools Protocol (CDP) |
| Firefox | FFBrowser | packages/playwright-core/src/server/firefox/ffBrowser.ts1-100 | Juggler Protocol |
| WebKit | WKBrowser | packages/playwright-core/src/server/webkit/wkBrowser.ts1-100 | WebKit Inspector Protocol |
Sources: packages/playwright-core/src/server/browser.ts1-200 packages/playwright-core/src/server/chromium/crBrowser.ts1-100 packages/playwright-core/src/server/firefox/ffBrowser.ts1-100 packages/playwright-core/src/server/webkit/wkBrowser.ts1-100
The Browser class provides these key methods for context management:
browser.newContext(options): Creates a new isolated browser context with specified optionsbrowser.newPage(options): Convenience method that creates both context and pagebrowser.contexts(): Returns all active browser contextsbrowser.close(): Closes the browser and all contextsbrowser.version(): Returns the browser version stringbrowser.newBrowserCDPSession(): (Chromium only) Creates CDP sessionSources: packages/playwright-core/types/types.d.ts15000-15200 packages/playwright-core/src/client/browser.ts1-100
The server-side Browser class manages:
_defaultContext or newContext()_connection)_initializer.versionSources: packages/playwright-core/src/server/browser.ts1-200 packages/playwright-core/src/server/chromium/crBrowser.ts50-150
The BrowserContext class in packages/playwright-core/src/server/browserContext.ts90-138 provides an isolated browsing environment. Each context maintains complete isolation from other contexts within the same browser instance.
Title: BrowserContext Isolation Model
What is Isolated:
_downloads set_permissions mapWhat is Shared:
Sources: packages/playwright-core/src/server/browserContext.ts90-138 packages/playwright-core/src/server/browserContext.ts77
Title: Server-side BrowserContext Internal Structure
Key Server-Side Properties:
_options: Complete context configuration from types.BrowserContextOptions_browserContextId: Unique identifier (undefined for persistent contexts)_isPersistentContext: true for contexts with user data directory_browser: Parent Browser instance reference_permissions: Map from origin to granted permission strings_pageBindings: Page bindings available to all pages in contextrequestInterceptors: Network route handlers for request interception_downloads: Set of active download objectstracing: Tracing instance for recording tracesfetchRequest: BrowserContextAPIRequestContext for API requestsclock: Clock instance for time manipulation_selectors: Selectors instance with custom selector enginesdialogManager: DialogManager for handling JavaScript dialogsSources: packages/playwright-core/src/server/browserContext.ts87-133
The client-side BrowserContext class in packages/playwright-core/src/client/browserContext.ts1-100 provides the user-facing API:
Page Management:
context.newPage(): Creates a new Page in this contextcontext.pages(): Returns array of all pagescontext.waitForEvent(event): Waits for context eventsState Management:
context.storageState(): Retrieves cookies and storage statecontext.addCookies(cookies): Adds cookies to the contextcontext.cookies(urls?): Gets cookies, optionally filtered by URLcontext.clearCookies(): Clears all cookiesConfiguration:
context.setDefaultNavigationTimeout(timeout): Sets navigation timeoutcontext.setDefaultTimeout(timeout): Sets general timeoutcontext.setGeolocation(geolocation): Updates geolocationcontext.setExtraHTTPHeaders(headers): Sets extra HTTP headerscontext.setOffline(offline): Simulates offline/onlinePermissions and Features:
context.grantPermissions(permissions, origin?): Grants permissionscontext.clearPermissions(): Clears all permissionscontext.addInitScript(script): Adds script to run on page creationcontext.exposeBinding(name, callback): Exposes function to pagescontext.exposeFunction(name, callback): Exposes function to pagescontext.route(url, handler): Registers request route handlerLifecycle:
context.close(): Closes context and all pagesSources: packages/playwright-core/types/types.d.ts8000-9000 packages/playwright-core/src/client/browserContext.ts50-400
Non-persistent contexts are created with browser.newContext() and store no browsing data to disk. They are ideal for test isolation.
Sources: packages/playwright-core/src/server/browserContext.ts99-106
Persistent contexts are created with browserType.launchPersistentContext(userDataDir) and write all browsing data to a user data directory. Only one persistent context can exist per browser instance.
Key characteristics:
_isPersistentContext is true_browserContextId is undefinedSources: packages/playwright-core/src/server/browserContext.ts115-117 packages/protocol/src/protocol.yml526-609
The BrowserContextOptions type defines all configurable aspects of a context. These are specified in the protocol as ContextOptions:
| Option Category | Properties | Protocol Location |
|---|---|---|
| Viewport | viewport, screen, noDefaultViewport | packages/protocol/src/protocol.yml488-498 |
| Device Emulation | deviceScaleFactor, isMobile, hasTouch | packages/protocol/src/protocol.yml539-541 |
| Network | ignoreHTTPSErrors, extraHTTPHeaders, offline, proxy, httpCredentials | packages/protocol/src/protocol.yml499-538 |
| Permissions | permissions, geolocation | packages/protocol/src/protocol.yml515-523 |
| Locale/Timezone | locale, timezoneId | packages/protocol/src/protocol.yml513-514 |
| Media | colorScheme, reducedMotion, forcedColors, contrast | packages/protocol/src/protocol.yml542-572 |
| Storage | storageState | packages/protocol/src/protocol.yml705-708 |
The viewport determines the page size and is emulated consistently across pages:
The viewport emulation is implemented through:
BrowserContext._options.viewport stores the configurationPage._emulatedSize applies it per-pagePageDelegate.updateEmulatedViewportSize() sends commands to browserSources: packages/playwright-core/src/server/browserContext.ts70-71 packages/protocol/src/protocol.yml488-498
Permissions are managed on a per-origin basis:
Permission types include: 'geolocation', 'notifications', 'camera', 'microphone', 'clipboard-read', 'clipboard-write', and others.
Sources: packages/playwright-core/src/server/browserContext.ts77
Storage state includes cookies, localStorage, and indexedDB data. This enables saving and restoring authentication state across test runs.
Cookies are managed through the BrowserContext API and stored per-context:
Title: Cookie Management Flow
Cookie Types:
SetNetworkCookie: For adding cookies (input to protocol)NetworkCookie: For retrieving cookies (output from protocol)Cookie Properties:
name, value: Cookie datadomain, path: Scopeexpires: Expiration timestamphttpOnly, secure: Security flagssameSite: "Strict" | "Lax" | "None"partitionKey: Partition key for cookie isolationSources: packages/protocol/src/protocol.yml176-214 packages/playwright-core/src/server/browserContext.ts1-50
The storage state can be:
storageState option in BrowserContextOptionscontext.storageState(options?) methodImplementation details:
BrowserContext.storageState() collects cookies and origin storagerawStorageSource from packages/playwright-core/src/generated/storageScriptSource.tsSetOriginStorage (input) and OriginStorage (output) protocol typesindexedDB parameterSources: packages/protocol/src/protocol.yml261-281 packages/playwright-core/src/server/browserContext.ts39
The BrowserContextDispatcher in packages/playwright-core/src/server/dispatchers/browserContextDispatcher.ts1-25 bridges the protocol layer and the server-side BrowserContext implementation.
Title: BrowserContextDispatcher Communication Flow
Sources: packages/playwright-core/src/server/dispatchers/browserContextDispatcher.ts20-50
The BrowserContextDispatcher extends Dispatcher and manages:
Event Translation: Converts server events to protocol events
BrowserContext.Events.Page → page event with PageDispatcherBrowserContext.Events.Close → close eventBrowserContext.Events.Console → console eventMethod Dispatching: Handles protocol commands:
setDefaultNavigationTimeoutNoReply: Sets navigation timeoutsetDefaultTimeoutNoReply: Sets general timeoutexposeBinding: Exposes binding to pagesnewPage: Creates new page and returns PageDispatchercookies: Retrieves cookiesaddCookies: Adds cookiesgrantPermissions: Grants permissionsclearPermissions: Clears permissionssetGeolocation: Sets geolocationsetExtraHTTPHeaders: Sets HTTP headerssetOffline: Sets offline modestorageState: Gets storage stateclose: Closes contextObject Lifecycle: Creates and manages child dispatchers
PageDispatcher for each pageRouteDispatcher for network routesResponseDispatcher and RequestDispatcher for network eventsSources: packages/playwright-core/src/server/dispatchers/browserContextDispatcher.ts1-400
Title: Protocol Flow for Browser.newContext()
Sources: packages/protocol/src/protocol.yml649-728 packages/playwright-core/src/protocol/validator.ts649-728
Key protocol definitions from protocol.yml:
Context Options (ContextOptions mixin at packages/protocol/src/protocol.yml484-610):
viewport, screen, noDefaultViewport: Viewport configurationignoreHTTPSErrors, clientCertificates: HTTPS configurationjavaScriptEnabled, bypassCSP: JavaScript settingsuserAgent, locale, timezoneId: Browser fingerprintgeolocation, permissions: Permission settingsextraHTTPHeaders, offline, httpCredentials: Network settingsdeviceScaleFactor, isMobile, hasTouch: Device emulationcolorScheme, reducedMotion, forcedColors, contrast: Media featuresacceptDownloads, baseURL: Navigation settingsrecordVideo: Video recordingstrictSelectors, serviceWorkers: Feature flagsselectorEngines, testIdAttributeName: Selector configurationproxy, storageState: Network and storageContext Initializer (BrowserContextInitializer at packages/protocol/src/protocol.yml850-921):
This initializer is sent when creating the context channel and includes:
isChromium: Browser type flagrequestContext: Associated API request context channeltracing: Tracing context channeloptions: Complete context options as configuredSources: packages/protocol/src/protocol.yml484-921 packages/playwright-core/src/protocol/validator.ts850-921
Playwright supports context reuse for performance optimization in test scenarios. This is controlled through a hash-based matching system.
Key parameters that allow context reuse (don't affect hash):
storageStateselectorEnginestestIdAttributeNameThese are defined in paramsThatAllowContextReuse and can be changed without requiring a new context.
When a context is reused, BrowserContext.resetForReuse() performs:
about:blankSources: packages/playwright-core/src/server/browserContext.ts164-206
The _initialize() method sets up:
Sources: packages/playwright-core/src/server/browserContext.ts123-153
Context closing follows a multi-stage process:
Key aspects:
_closedStatus tracks state: 'open' → 'closing' → 'closed'_closePromise allows waiting for closureBeforeClose event allows cleanup hooksSources: packages/playwright-core/src/server/browserContext.ts74-76 packages/playwright-core/src/server/browserContext.ts250-300
The BrowserContext has both client and server implementations that communicate via the protocol layer:
Client responsibilities:
Server responsibilities:
Sources: packages/playwright-core/src/client/browserContext.ts1-100 packages/playwright-core/src/server/dispatchers/browserContextDispatcher.ts1-200
Refresh this wiki
This wiki was recently refreshed. Please wait 2 days to refresh again.