What is a BrowserContext in Playwright?
A BrowserContext is an isolated browser session that lives inside a single browser process. Think of it as a fresh incognito window: it has its own cookies, localStorage, session storage, cache, permissions and open pages, and nothing leaks into any other context in the same browser. Launching a browser takes a noticeable amount of time; creating a context takes milliseconds. That difference is why Playwright is built around contexts.
Browser, context and page
Playwright works with three nested objects:
- Browser: one running Chromium, Firefox or WebKit process.
- BrowserContext: an independent session inside that browser. You can open many of them side by side.
- Page: a single tab inside a context. Pages in the same context share cookies and storage, just like two tabs of the same normal browser window. See what a Page is in Playwright.
A context is also where you set how the "device" looks to the site: viewport size, locale, time zone, geolocation, permissions, user agent, colour scheme and whether the device is mobile.
Example: two users in one test
Suppose an LMS lets an admin publish a course and a student must see it. You need two logged-in people at the same time, and their sessions must not mix. Two contexts solve this inside one test. The URLs and labels below are placeholders for your own app.
// tests/two-users.spec.ts
import { test, expect } from '@playwright/test';
test('student sees a course after admin publishes it', async ({ browser }) => {
const adminContext = await browser.newContext({
storageState: 'auth/admin.json', // saved admin login
locale: 'en-IN',
timezoneId: 'Asia/Kolkata',
});
const studentContext = await browser.newContext({
storageState: 'auth/student.json', // saved student login
viewport: { width: 390, height: 844 },
isMobile: true,
});
const admin = await adminContext.newPage();
const student = await studentContext.newPage();
await admin.goto('/admin/courses/new');
await admin.getByLabel('Course title').fill('Playwright Basics');
await admin.getByRole('button', { name: 'Publish' }).click();
await student.goto('/my-courses');
await expect(student.getByText('Playwright Basics')).toBeVisible();
await adminContext.close();
await studentContext.close();
});
Each context keeps its own login. Closing a context closes all of its pages and throws away its data, so always close contexts you create yourself.
How the test runner uses contexts for you
In @playwright/test you rarely call newContext() by hand. The built-in context and page fixtures give every test a brand-new context, and the runner closes it when the test ends. That is the reason one test's login or cart never affects the next test. The page-level reasons for this design are covered in browser isolation in Playwright.
You change the options of that automatic context with use, either for the whole project or for one file:
// playwright.config.ts
import { defineConfig } from '@playwright/test';
export default defineConfig({
use: {
baseURL: 'http://localhost:3000',
locale: 'en-IN',
timezoneId: 'Asia/Kolkata',
viewport: { width: 1280, height: 720 },
},
});
// inside a spec file: only these tests run in Hindi
test.use({ locale: 'hi-IN' });
Contexts you create yourself with browser.newContext() inside a test also pick up these use options, such as baseURL and locale. Anything you pass to newContext() overrides them. That is why goto('/my-courses') works in the two-user example above.
More on these settings in the Playwright config file and how viewports are managed.
Useful context methods
| Method | What it does |
|---|---|
context.newPage() | Opens a new tab in this context |
context.pages() | Lists the open tabs |
context.waitForEvent('page') | Waits for a tab opened by the site, for example a target="_blank" link |
context.addCookies() / cookies() | Sets or reads cookies for every page in the context |
context.storageState({ path }) | Saves cookies and local storage to a file so a later context can reuse a login |
context.route() | Intercepts network requests from all its pages |
context.grantPermissions() | Grants permissions such as geolocation |
Common mistakes
- Launching a new browser per test. Slow and unnecessary. Keep one browser and create contexts.
- Expecting two pages of one context to have different logins. They share cookies. Use two contexts.
- Forgetting to close manual contexts. Open contexts keep memory and, if video recording is on, the video is only saved when the context closes.
- Sharing one context across tests "for speed". Tests then depend on each other's state and fail randomly when run in parallel. Reuse a saved
storageStateinstead.
Related reading: how Playwright manages cookies and handling multiple tabs.
Want to master Playwright hands-on?
Join Uncodemy's Playwright Automation Testing Course in Noida — Dedicated Placement Support.
Explore the Course →