🎯 What You Will Learn
Build the right mental model for browser processes, isolated contexts, pages, tabs, and persistent CLI sessions.
- Distinguish browsers, contexts, pages, tabs, and CLI sessions
- Keep unrelated workflows isolated
- Manage several pages without losing track of the active tab
- Close browser resources cleanly
Start with the Browser Process
The browser process is the running Chromium, Firefox, or WebKit instance. It can contain one or more isolated contexts, and each context can contain one or more pages.
| Layer | Think of it as |
|---|---|
| Browser | The running browser application |
| Context | An isolated browser profile |
| Page | One document, normally shown as a tab |
| CLI session | A named handle used across terminal commands |
Create a Named CLI Session
A named session lets separate terminal commands control the same browser. Use a short name related to the workflow.
"$PWCLI" -s=docs open https://playwright.dev --headed
"$PWCLI" -s=docs snapshot
"$PWCLI" listSeparate Unrelated Workflows
Use different session names when two tasks should not share tabs, cookies, or history. This makes it much harder to send a command to the wrong browser.
"$PWCLI" -s=checkout open https://example.com/checkout
"$PWCLI" -s=docs open https://playwright.dev/docs/intro
"$PWCLI" listPages and Tabs
In Playwright, a tab is represented by a Page. The CLI exposes tab commands so you can create and select pages without writing JavaScript.
"$PWCLI" -s=docs tab-new https://playwright.dev/docs/locators
"$PWCLI" -s=docs tab-list
"$PWCLI" -s=docs tab-select 0
"$PWCLI" -s=docs snapshotBrowser Contexts and Isolation
A BrowserContext owns cookies, permissions, storage, and pages. Playwright Test creates a fresh context for each test by default.
import { test, expect } from '@playwright/test';
test('starts with isolated storage', async ({ page, context }) => {
await page.goto('https://example.com');
expect(await context.cookies()).toEqual([]);
});Use Contexts for Multiple Roles
One browser can host an admin context and a customer context without sharing authentication. This is useful for chat, approvals, and role-based workflows.
test('admin and customer stay isolated', async ({ browser }) => {
const admin = await browser.newContext();
const customer = await browser.newContext();
const adminPage = await admin.newPage();
const customerPage = await customer.newPage();
// Sign in each page with a different test account.
await admin.close();
await customer.close();
});Keep Track of the Active Page
After a popup or tab selection, take a fresh snapshot. References belong to the active page's current DOM and should never be assumed to work in another tab.
Common mistake: A valid reference from tab 0 can point to nothing after you switch to tab 1. Select the tab, snapshot, then interact.
Close What You Open
Closing sessions avoids forgotten browser processes and clears the mental model for the next run. Use close for one session and close-all when finishing a set of workflows.
"$PWCLI" -s=docs tab-close
"$PWCLI" -s=docs close
"$PWCLI" close-allRecap
- A browser contains isolated contexts, and contexts contain pages.
- A CLI session preserves control across terminal commands.
- Use separate sessions or contexts for unrelated identities and tasks.
- Re-snapshot after tab switches and close resources when finished.
Checkpoint: You have completed the workflow and have a repeatable reference for your next Playwright project.