Playwright (and Puppeteer) exposes its API through Browser, BrowserContext, and Page objects with a blurry definition of their boundaries. This article covers their definition, how to leverage them, and how to avoid common pitfalls.

What are BrowserContexts and Pages?

A typical Playwright program looks as follows:

import { chromium } from "playwright-core";

(async () => {
  // 1. Get a Browser instance
  const browser = await chromium.connectOverCDP(
    `wss://connect.browserbase.com?apiKey=${process.env.BROWSERBASE_API_KEY}`
  );

  // 2. Get a BrowserContext
  const defaultContext = browser.contexts()[0];
  
  // 3. Get a Page
  const page = defaultContext.pages()[0];

  // 4. Act on Page
  await page.goto("<https://browserbase.com>");
  await page.close();
  await browser.close();
})().catch((error) => console.error(error.message));

Let's have a closer look at the Browser, BrowserContext, and Page definitions by comparing them to our day-to-day Browser:

| Concept | Framework definition (Puppeteer/Playwright) | Browser equivalent (Chrome/Firefox) | | --- | --- | --- | | Browser | A Browser instance (dedicated cache, user sessions) | The running Browser application | | BrowserContext | A Browser Session (dedicated cookies, shared cache) | A Browser Window or Profile or Incognito Window | | Page | A Browser tab (dedicated history, shared cookies, and cache) | Tabs |

Each concept accounts for a level of isolation and shared resources: BrowserContext gets a dedicated cache, later shared between Pages.

We can now visualize the relationship between them as follows:

Browser, BrowserContext, and Page are encapsulated concepts that enable developers to control different parts of the Browser.

Let’s now see how to leverage each concept when building automation.

How to use BrowserContexts and Pages

The most common use cases benefiting from using multiple BrowserContexts or Pages are parallelization and cookie management.

Leverage BrowserContexts for parallelization