Browser and Context Management

Relevant source files

• docs/src/api/class-credentials.md
• docs/src/api/class-websocket.md
• docs/src/api/class-worker.md
• docs/src/auth.md
• docs/src/browser-contexts.md
• docs/src/chrome-extensions-js-python.md
• docs/src/videos.md
• packages/isomorphic/cssTokenizer.ts
• packages/isomorphic/imageUtils.ts
• packages/playwright-core/src/browserServerImpl.ts
• packages/playwright-core/src/cli/driver.ts
• packages/playwright-core/src/client/android.ts
• packages/playwright-core/src/client/browser.ts
• packages/playwright-core/src/client/browserType.ts
• packages/playwright-core/src/client/credentials.ts
• packages/playwright-core/src/client/electron.ts
• packages/playwright-core/src/client/network.ts
• packages/playwright-core/src/client/types.ts
• packages/playwright-core/src/client/waiter.ts
• packages/playwright-core/src/client/worker.ts
• packages/playwright-core/src/remote/playwrightConnection.ts
• packages/playwright-core/src/remote/playwrightServer.ts
• packages/playwright-core/src/server/artifact.ts
• packages/playwright-core/src/server/credentials.ts
• packages/playwright-core/src/server/dispatchers/artifactDispatcher.ts
• packages/playwright-core/src/server/dispatchers/cdpSessionDispatcher.ts
• packages/playwright-core/src/server/dispatchers/electronDispatcher.ts
• packages/playwright-core/src/server/dispatchers/elementHandlerDispatcher.ts
• packages/playwright-core/src/server/dispatchers/jsHandleDispatcher.ts
• packages/playwright-core/src/server/dispatchers/tracingDispatcher.ts
• packages/playwright-core/src/server/download.ts
• packages/trace-viewer/src/ui/playbackControl.tsx
• packages/utils/image_tools/compare.ts
• packages/utils/network.ts
• tests/assets/csp.html
• tests/config/browserTest.ts
• tests/config/proxy.ts
• tests/config/remote-server-impl.js
• tests/config/remoteServer.ts
• tests/config/testserver/index.ts
• tests/image_tools/unit.spec.ts
• tests/library/browsercontext-add-cookies.spec.ts
• tests/library/browsercontext-cookies-third-party.spec.ts
• tests/library/browsercontext-cookies.spec.ts
• tests/library/browsercontext-csp.spec.ts
• tests/library/browsercontext-proxy.spec.ts
• tests/library/browsercontext-webauthn.spec.ts
• tests/library/browsertype-connect.spec.ts
• tests/library/chromium/connect-over-cdp.spec.ts
• tests/library/chromium/launcher.spec.ts
• tests/library/defaultbrowsercontext-1.spec.ts
• tests/library/headful.spec.ts
• tests/library/launcher.spec.ts
• tests/library/proxy.spec.ts
• tests/library/signals.spec.ts
• tests/page/elementhandle-screenshot.spec.ts
• tests/page/elementhandle-screenshot.spec.ts-snapshots/screenshot-element-padding-border-webkit.png
• tests/page/page-autowaiting-basic.spec.ts
• tests/page/page-network-idle.spec.ts
• tests/third_party/proxy/LICENSE
• tests/third_party/proxy/README.md
• tests/third_party/proxy/index.ts

Purpose and Scope

This document explains the Browser and BrowserContext APIs in Playwright, including browser launching via BrowserType, connection strategies (CDP and WebSocket), and the management of isolated browsing sessions. It covers the internal implementation of context-level features such as permissions, cookies, storage state, and geolocation.

Architecture Overview

Playwright uses a hierarchical model where a BrowserType launches a Browser instance, which contains one or more BrowserContext instances. Each context provides a completely isolated session, containing its own pages, cookies, and local storage.

Title: Playwright Object Hierarchy

Sources: packages/playwright-core/src/client/browserType.ts66-84 packages/playwright-core/src/client/browser.ts62-64 packages/playwright-core/src/client/browser.ts143-151

Browser Management

Browsers are managed by BrowserType implementations. Playwright provides specialized classes for Chromium, Firefox, and WebKit to handle engine-specific protocols and process launching.

Browser Launching and Connection

Playwright supports launching local instances, connecting to remote instances via WebSocket, or connecting via the Chrome DevTools Protocol (CDP).

Title: BrowserType Implementation Space

Key APIs:

• launch(): Starts a local browser process. It wraps the launch channel call and connects the resulting Browser object to the BrowserType instance packages/playwright-core/src/client/browserType.ts66-84
• connect(): Attaches to a remote PlaywrightServer via WebSocket. It utilizes connectToBrowser to establish the connection and wire up the client-side Browser object packages/playwright-core/src/client/browserType.ts124-139
• connectOverCDP(): Connects to an existing browser instance using the Chrome DevTools Protocol. This is primarily used for Chromium and supports managing downloads and traces via a local artifactsDir packages/playwright-core/src/client/browserType.ts141-158

Sources: packages/playwright-core/src/client/browserType.ts66-84 packages/playwright-core/src/client/browserType.ts124-139 packages/playwright-core/src/client/browserType.ts141-158

Browser Class Implementation

The Browser class tracks active contexts and handles global browser events like disconnection. It serves as a ChannelOwner for the BrowserChannel packages/playwright-core/src/client/browser.ts33-56

Property/Method	Description	File
newContext()	Creates a new isolated session.	packages/playwright-core/src/client/browser.ts62-64
newPage()	Convenience method to create a context and a page in one call.	packages/playwright-core/src/client/browser.ts143-151
version()	Returns the browser version string.	packages/playwright-core/src/client/browser.ts130-132
isConnected()	Returns whether the browser is still connected to the server.	packages/playwright-core/src/client/browser.ts153-155

Sources: packages/playwright-core/src/client/browser.ts33-56 packages/playwright-core/src/client/browser.ts62-64 packages/playwright-core/src/client/browser.ts143-151

BrowserContext and Isolation

BrowserContext is the primary unit of isolation. It manages its own set of pages, cookies, and storage state.

State Management

Title: BrowserContext Internal Structure

Isolation boundaries:

• Cookies: Contexts manage their own cookie jars. Cookies can be retrieved via context.cookies() and added via context.addCookies() tests/library/browsercontext-cookies.spec.ts20-41
• Storage State: The entire session state (cookies and local storage) can be exported and re-imported using storageState. This is a core feature for authentication reuse docs/src/auth.md71-77
• Permissions: Permissions are scoped to the context and can be granted to specific origins.

Sources: packages/playwright-core/src/client/browser.ts81-94 docs/src/auth.md71-77 tests/library/browsercontext-cookies.spec.ts20-41

Persistent Contexts

A "Persistent Context" uses a physical disk directory for the user profile, allowing state to persist across browser restarts.

• Created via browserType.launchPersistentContext(userDataDir, ...) packages/playwright-core/src/client/browserType.ts93-122
• It combines the creation of a browser process and a context into a single operation, with the userDataDir being mandatory packages/playwright-core/src/client/browserType.ts109-111

Sources: packages/playwright-core/src/client/browserType.ts93-122

Remote Connection Implementation

Remote connections are facilitated by the PlaywrightServer, which exposes a WebSocket endpoint for clients to connect to.

PlaywrightServer and Dispatchers

The server handles incoming connections and dispatches them to the appropriate internal controllers.

1. WSServer: Handles the low-level WebSocket upgrade and User-Agent validation packages/playwright-core/src/remote/playwrightServer.ts69-85
2. PlaywrightConnection: Manages the lifecycle of a single client connection. It uses a Semaphore to enforce maxConnections packages/playwright-core/src/remote/playwrightConnection.ts34-50
3. DispatcherConnection: Routes JSON-RPC messages between the client and the server-side PlaywrightDispatcher packages/playwright-core/src/remote/playwrightConnection.ts52-80

Sources: packages/playwright-core/src/remote/playwrightServer.ts65-92 packages/playwright-core/src/remote/playwrightConnection.ts34-80

Connection Lifecycle

When a client connects, the PlaywrightConnection initializes a RootDispatcher. This dispatcher sets up the PlaywrightDispatcher, which in turn manages browsers and contexts. If the transport closes, the connection performs a cleanup of all allocated resources, including stopping pending operations packages/playwright-core/src/remote/playwrightConnection.ts91-118 packages/playwright-core/src/remote/playwrightConnection.ts126-136

Sources: packages/playwright-core/src/remote/playwrightConnection.ts91-118 packages/playwright-core/src/remote/playwrightConnection.ts126-136