DEV Community

Juan G. Vazquez Jr.
Juan G. Vazquez Jr.

Posted on

Playwright BrowserContext: What It Is, Why It Matters, and How to Configure It

If you’ve been using Playwright for a while, you’ve definitely used browserContext—even if you didn’t fully realize it. It’s one of those core concepts that quietly shapes test isolation, speed, flakiness, auth state, parallelism, and even how sane your test suite feels over time.

This article is a practical, real-world deep dive into:

  • What a BrowserContext actually is (and why it exists)
  • How Playwright creates and manages contexts for you
  • How to configure contexts globally in playwright.config.ts
  • How to share setup across tests without sharing state
  • When and how to use multiple setup files / projects
  • Common anti-patterns and real-world use cases

This is written for engineers who already know Playwright basics and want to level up their test architecture.


First: What Is a BrowserContext?

A BrowserContext is an isolated browser profile.

Think of it like this:

  • One Browser → the actual Chrome / Firefox / WebKit instance
  • Multiple BrowserContexts → separate incognito-like sessions

Each context has its own:

  • Cookies
  • LocalStorage / SessionStorage
  • IndexedDB
  • Cache
  • Permissions
  • Auth state

But they all share the same browser process, which is why contexts are fast and cheap.

If you’ve ever opened two incognito windows side by side — that’s basically two browser contexts.


Why BrowserContexts Exist (And Why You Should Care)

Playwright is opinionated about test isolation.

By default:

test('example', async ({ page }) => {
  // This page lives in a fresh browser context
});
Enter fullscreen mode Exit fullscreen mode

Under the hood:

  1. Playwright launches a browser
  2. Creates a new browser context
  3. Creates a page inside that context
  4. Destroys the context after the test

This gives you:

  • No state leakage between tests
  • Safe parallel execution
  • Predictable failures

If you’ve ever fought flaky Selenium tests caused by leftover cookies — this is why Playwright feels so much better.


The Hidden Relationship: browser → context → page

You almost never create this manually, but it’s worth understanding:

const browser = await chromium.launch();
const context = await browser.newContext();
const page = await context.newPage();
Enter fullscreen mode Exit fullscreen mode

Playwright’s test runner does this for every test, unless you tell it otherwise.

Key takeaway:

Pages never exist without a BrowserContext.


Configuring BrowserContexts in playwright.config.ts

Most context configuration happens via the use block.

Basic Example

import { defineConfig } from '@playwright/test';

export default defineConfig({
  use: {
    baseURL: 'https://my-app.com',
    headless: true,
    viewport: { width: 1280, height: 720 },
    locale: 'en-US',
    timezoneId: 'America/New_York',
  },
});
Enter fullscreen mode Exit fullscreen mode

Everything inside use becomes default BrowserContext options.

This means every test gets:

  • The same viewport
  • Same locale
  • Same timezone

…but still not the same state.


Auth State: The #1 Real-World BrowserContext Feature

Let’s talk about the killer feature: storageState.

Problem

Logging in before every test is:

  • Slow
  • Brittle
  • Redundant

Solution: Auth Setup + storageState

1️⃣ Create a global setup

// global-setup.ts
import { chromium } from '@playwright/test';

export default async () => {
  const browser = await chromium.launch();
  const context = await browser.newContext();
  const page = await context.newPage();

  await page.goto('https://my-app.com/login');
  await page.fill('#email', 'user@test.com');
  await page.fill('#password', 'password');
  await page.click('button[type=submit]');

  await context.storageState({ path: 'auth.json' });
  await browser.close();
};
Enter fullscreen mode Exit fullscreen mode

2️⃣ Reference it in config

export default defineConfig({
  globalSetup: './global-setup.ts',
  use: {
    storageState: 'auth.json',
  },
});
Enter fullscreen mode Exit fullscreen mode

Now every test:

  • Starts logged in
  • Still runs in a fresh browser context

This is isolation with convenience.


Sharing Setup Without Sharing State

This is where many teams mess up.

❌ Anti-pattern

let sharedPage;

beforeAll(async ({ browser }) => {
  const context = await browser.newContext();
  sharedPage = await context.newPage();
});
Enter fullscreen mode Exit fullscreen mode

This:

  • Breaks test isolation
  • Breaks parallelism
  • Causes order-dependent failures

✅ Correct Pattern: Fixtures

import { test as base } from '@playwright/test';

export const test = base.extend({
  authenticatedPage: async ({ page }, use) => {
    await page.goto('/dashboard');
    await use(page);
  },
});
Enter fullscreen mode Exit fullscreen mode

Each test still gets:

  • Its own context
  • Its own page

But setup logic is shared cleanly.


Multiple BrowserContexts in One Test (Yes, You Can)

Sometimes you need multiple users.

Example: chat apps, admin/user flows, invitations.

test('admin invites user', async ({ browser }) => {
  const adminContext = await browser.newContext({ storageState: 'admin.json' });
  const userContext = await browser.newContext({ storageState: 'user.json' });

  const adminPage = await adminContext.newPage();
  const userPage = await userContext.newPage();

  await adminPage.goto('/admin');
  await userPage.goto('/dashboard');
});
Enter fullscreen mode Exit fullscreen mode

This is powerful — and still fast.


Multiple Setup Files Using Projects

This is where Playwright really shines.

Use Case Examples

  • Logged-in user vs logged-out user
  • Admin vs regular user
  • Mobile vs desktop
  • Different feature flags

Example: Multiple Projects

export default defineConfig({
  projects: [
    {
      name: 'guest',
      use: {
        storageState: undefined,
      },
    },
    {
      name: 'user',
      use: {
        storageState: 'auth.json',
      },
    },
    {
      name: 'admin',
      use: {
        storageState: 'admin.json',
      },
    },
  ],
});
Enter fullscreen mode Exit fullscreen mode

Each project:

  • Uses the same tests
  • Spins up different browser contexts
  • Runs in parallel if you want

You can even target them:

npx playwright test --project=admin
Enter fullscreen mode Exit fullscreen mode

Can BrowserContexts Be Shared?

No — and that’s the point.

Contexts are designed to be:

  • Cheap
  • Disposable
  • Isolated

What can be shared:

  • Config (use)
  • Storage snapshots (storageState)
  • Fixtures and helpers

What should never be shared:

  • Live pages
  • Live contexts
  • Mutable global state

Mental Model to Remember

If you remember nothing else, remember this:

One test = one browser context

Unless you explicitly create more.

That rule alone explains:

  • Why Playwright scales
  • Why parallel runs work
  • Why tests don’t leak state

Common BrowserContext Mistakes (and How to Avoid Them)

1. Sharing Pages or Contexts Across Tests

This is the fastest way to introduce flaky, order-dependent tests.

If you see patterns like:

  • beforeAll creating a page
  • Globals holding page or context
  • Tests depending on previous navigation

You’re fighting Playwright instead of using it.

Fix: Let Playwright create a fresh context per test. Share setup logic via fixtures or storageState, not live objects.


2. Logging In Inside Every Test

Repeated UI logins:

  • Slow down your suite
  • Increase flakiness
  • Add zero test value

Fix: Use a dedicated auth setup and storageState. Test login flows separately.


3. Overusing beforeAll

beforeAll feels convenient, but it breaks:

  • Parallel execution
  • Isolation guarantees
  • Debuggability

Fix: Prefer per-test setup with fixtures. If something must run once, make sure it does not create shared browser state.


4. Confusing Config Sharing with State Sharing

Config options like use, projects, and fixtures are safe to share.

Browser contexts, pages, and mutable globals are not.

If a failure only happens when tests run together, this is usually the reason.


5. Avoiding Multiple Contexts When You Actually Need Them

Some teams try to force complex multi-user flows into a single page.

This leads to:

  • Unreadable tests
  • Fake mocks instead of real behavior
  • Missed bugs

Fix: Use multiple browser contexts intentionally when modeling real users.


Final Thoughts

BrowserContext is one of Playwright’s most important architectural concepts.

Once you understand how contexts work, your test suite naturally becomes:

  • Faster
  • More reliable
  • Easier to scale
  • Easier to reason about

If your Playwright tests feel fragile or hard to maintain, there’s a strong chance the root cause is how browser contexts are being managed.

Design around them correctly, and the rest of Playwright starts to feel effortless.

Happy testing

Top comments (0)