Isolation and Control at the Browser Boundary

Puppeteer does not control only what a user can see on a page; it also controls selected browser state and, when asked, the traffic that lets the page progress. This chapter focuses on two decisions: where independent sessions should be separated, and how network observation or interception should be coordinated. Readers will be able to choose browser contexts for the state they actually need to isolate, prepare cookies and permissions deliberately, and review request handlers without creating hangs or protocol-specific surprises.

The distinction matters because browser state has several owners. Two pages may be separate tabs but share a context. Two contexts may separate cookies and local storage while still living inside one browser process. A request listener may observe traffic without changing it, while an interceptor becomes part of the request’s progress path. Treating all of these as one generic notion of isolation or waiting produces designs that look clean and fail at their boundaries.

Choose the state boundary before the page

A browser context is Puppeteer’s primary unit for separating user-like browser state. A browser starts with a default context, and the caller can create additional contexts. Pages created in a context share that context’s storage; cookies and local storage are not shared with other contexts. Closing a non-default context closes its pages, which makes the context a useful disposable boundary for a test or temporary session.

Imagine a test that exercises an application as two users. If it opens two pages in the default context, both pages are still inside the same cookie and local-storage boundary. A login cookie written by one flow can affect the other. If it creates two contexts first, each user can receive a page and prepare its own session state. The page objects remain separate, but the important separation is owned by the contexts around them.

That choice is more precise than creating a new browser for every task by reflex. Multiple contexts can provide independent browser storage while sharing the browser process and its protocol connection. This can be useful when the work needs the same browser build or a coordinated browser, and it avoids treating process creation as the only way to express separate sessions. It does not follow, however, that contexts provide every kind of isolation a deployment may require.

Puppeteer’s documented claim is about named browser state: cookies and local storage. A context should not be described as a complete security boundary for the operating system, filesystem, browser process, or application. Pages in different contexts can still be controlled by the same Node process, and the browser itself remains a shared resource. If the requirement is independent credentials, context storage may be the relevant boundary. If the requirement is protection between mutually untrusted jobs, the source does not justify assuming that a context alone is sufficient.

Cookies make state visible enough to manage explicitly. Puppeteer can read cookies from the default browser context through browser-level helpers, and the same operations are available on a selected context. A test can set or restore cookies before the page performs its main work instead of reproducing every login screen.