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
});
Under the hood:
- Playwright launches a browser
- Creates a new browser context
- Creates a page inside that context
- 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();
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',
},
});
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', '[email protected]');
await page.fill('#password', 'password');
await page.click('button[type=submit]');
await context.storageState({ path: 'auth.json' });
await browser.close();
};
2️⃣ Reference it in config
export default defineConfig({
globalSetup: './global-setup.ts',
use: {
storageState: 'auth.json',
},
});
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();
});
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);
},
});
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');
});
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',
},
},
],
});
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
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:
beforeAllcreating a page- Globals holding
pageorcontext
- 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
SOCIAL SHARE CARD GENERATOR