Browser Context

What Is a Browser Context?

Browser → Context → Page is the hierarchy. One browser process can host multiple contexts that do not share cookies or localStorage. Each test typically gets a fresh context via the context and page fixtures.

Contexts let you simulate two users in one test: create two contexts, two pages, and interact independently — useful for chat, collaboration, or admin vs regular user scenarios.

test('admin and user sessions', async ({ browser }) => {
  const adminContext = await browser.newContext();
  const userContext = await browser.newContext();
  const adminPage = await adminContext.newPage();
  const userPage = await userContext.newPage();
  // each page has separate cookies/storage
});

Use browser fixture when you need multiple contexts in one test.

Context Options

const context = await browser.newContext({
  storageState: 'auth/admin.json',
  geolocation: { latitude: 37.7749, longitude: -122.4194 },
  permissions: ['geolocation'],
  locale: 'de-DE',
});

• storageState restores saved cookies and localStorage.
• permissions grants camera, geolocation, etc.
• locale and timezoneId affect Intl and Date formatting.
• viewport and isMobile emulate device characteristics.

Browser Context Cheat Sheet

Common context configuration options.

Default Isolation in the Test Runner

The test runner creates a new context for each test automatically. You rarely call newContext() unless testing multi-user flows or customizing options per test via test.use().

test.use({ locale: 'fr-FR' });

test('French UI', async ({ page }) => {
  await page.goto('/');
});

When to Use browser Fixture

• Multiple independent sessions in one test.
• Testing popups that need a separate context (rare — often page.waitForEvent('popup') suffices).
• Custom context options not expressible via test.use().

Common Mistakes

• Assuming two tabs in one context have separate cookies — they share storage.
• Not closing manually created contexts (leaks in long custom scripts outside test runner).
• Reusing storageState files that contain expired tokens.
• Confusing browser (process) with context (session).

Key Takeaways

• Contexts isolate cookies, storage, and permissions.
• Each test gets a fresh context by default.
• storageState enables fast authenticated tests.
• Use multiple contexts to simulate multiple users.