state object. Variables, pages, and listeners persist between calls. Browser tabs are shared, but state is not.playwriter session new # => 1 playwriter session new # => 2 # List all sessions with their stored keys playwriter session list # ID State Keys # -------------- # 1 page, userData # 2 -
-s <id> to all commands to use a specific session:playwriter -s 1 -e "state.users = ['Alice', 'Bob']" playwriter -s 2 -e "console.log(state.users)" # undefined (isolated)
state object persists between execute calls within the same session. Use it to store pages, data, listeners, and anything else you need across calls:// Call 1: store data state.page = await context.newPage() await state.page.goto('https://example.com') state.results = [] // Call 2: data is still there console.log(state.results.length) // 0 state.results.push(await state.page.title())
context.pages() returns all browser tabs with Playwriter enabled, shared across all sessions. Multiple agents see the same tabs. There is no default page. Always create your own page:// First call: create a tab and navigate immediately state.page = await context.newPage() await state.page.goto('https://example.com') // Use state.page for ALL subsequent operations
if (!state.page || state.page.isClosed()) { state.page = await context.newPage() } await state.page.goto('https://example.com')
context.pages() if the user points you to a specific tab. Find it by URL. findLast picks the most recently opened match:state.page = context.pages().findLast((p) => p.url().includes('myapp.com')) if (!state.page) throw new Error('No myapp.com page found')
playwriter by default. Use the shortest clear single-word name with no spaces, such as docs, shop, test, or scrape.# Tabs created by this session join a group named "docs" playwriter session new --tab-group docs # Pick the group color yourself (any Chrome color) playwriter session new --tab-group docs --tab-group-color blue # Rename the group later — moves the session's existing tabs playwriter session update 1 --tab-group research # Change only the color — also works on the default playwriter group playwriter session update 1 --tab-group-color red
playwriter session new --tab-group scrape --tab-group-color grey
--tab-group. That keeps many open tabs readable instead of one mixed strip:playwriter session new --tab-group agent1 --tab-group-color blue playwriter session new --tab-group agent2 --tab-group-color pink
playwriter session new --tab-group done --tab-group-color grey
playwriter group only moves tabs that session created. Manually enabled tabs and other sessions' tabs stay in the default group. Renaming a custom group moves everything in it, including tabs you dragged in.--tab-group-color, each custom group gets a deterministic color derived from its name (the default playwriter group stays green). The flag accepts every Chrome group color: grey, blue, red, yellow, green, pink, purple, cyan, orange. playwriter session list shows the group per session in the GROUP column.connectViaExtension() from the playwriter package. It starts the relay if needed, waits for the Chrome extension, creates a session, and connects over CDP.import { connectViaExtension } from 'playwriter' await using connection = await connectViaExtension({ tabGroup: 'email-check', tabGroupColor: 'grey', }) // the page closes its tab when the scope ends, also on throw await using page = await connection.browser.contexts()[0].newPage() await page.goto('https://example.com')
tabGroupColor is typed as Chrome's tab group colors: grey, blue, red, yellow, green, pink, purple, cyan, orange. await using calls close() at scope end: it disconnects CDP and deletes the session. It needs Node 24+ (or a TypeScript 5.2+ / tsx build). Without await using, call await connection.close() in finally.connection.close() does not close any tab. Use await using page or call page.close() for every tab your script opens. Pass closeTabsOnEnd: true to make close() also close every tab this connection opened, plus popups they opened (never other sessions' tabs).context.pages():// process A await using a = await connectViaExtension({ tabGroup: 'job' }) await (await a.browser.contexts()[0].newPage()).goto('https://example.com') // process B, later await using b = await connectViaExtension({ tabGroup: 'job' }) const page = b.browser.contexts()[0].pages().findLast((p) => p.url() === 'https://example.com/')
startsWith or includes. context.pages() lists every Playwriter tab, also tabs other sessions opened for unrelated work (a download tab, a song page), and a loose match picks one of those.fetch inside a signed-in site can share one tab instead of each loading the site again. Two rules make it safe:closeTabsOnEnd: true. It closes the tab when the session that created it ends, while another process still uses it.page.evaluate. The page runs JS on one thread, so each evaluate is atomic. The last holder closes the tab.process A ──▶ no tab with exact url ──▶ open it ──▶ window.__shared = { holders: [A] } process B ──▶ finds it ──▶ evaluate: closing? no ──▶ holders: [A, B] A leaves ──▶ evaluate: holders: [B] tab stays open B leaves ──▶ evaluate: holders: [], closing = true ──▶ page.close()
import { randomUUID } from 'node:crypto' import { connectViaExtension, type Page, type PlaywriterBrowserConnection } from 'playwriter' type Shared = { holders: string[]; closing: boolean } const APP_URL = 'https://example.com/app' // exact url of the shared tab const me = `${process.pid}:${randomUUID()}` const alive = (holder: string) => { try { process.kill(Number(holder.split(':')[0]), 0) return true } catch (e) { return (e as NodeJS.ErrnoException).code === 'EPERM' } } // false when the tab is not set up yet (loading, reloaded), closing, or closed const join = (page: Page) => page .evaluate((me) => { const shared = (window as any).__shared as Shared | undefined if (!shared || shared.closing) return false shared.holders.push(me) return true }, me) .catch(() => false) // true when we were the last live holder async function leave(page: Page) { const holders: string[] = await page.evaluate(() => (window as any).__shared?.holders ?? []) const remove = [me, ...holders.filter((h) => !alive(h))] // crashed processes never block the close return page.evaluate((remove) => { const shared = (window as any).__shared as Shared | undefined if (!shared) return false // list wiped by a reload: never close a tab we cannot account for shared.holders = shared.holders.filter((h) => !remove.includes(h)) if (shared.holders.length === 0) shared.closing = true return shared.closing }, remove) } async function claim(connection: PlaywriterBrowserConnection) { const context = connection.browser.contexts()[0] for (const page of context.pages().filter((p) => p.url() === APP_URL)) { if (await join(page)) return page } const page = await context.newPage() let ready = false try { await page.goto(APP_URL, { waitUntil: 'load' }) await page.evaluate((me) => { ;(window as any).__shared = { holders: [me], closing: false } satisfies Shared }, me) ready = true return page } finally { if (!ready) await page.close().catch(() => {}) // never leak a half-set-up tab } } await using connection = await connectViaExtension({ tabGroup: 'app' }) const page = await claim(connection) try { const user = await page.evaluate(() => fetch('/api/me').then((r) => r.json())) } finally { if (await leave(page).catch(() => false)) await page.close().catch(() => {}) }
closing in the same evaluate that empties the list, so a joiner either gets in first or skips that tab and opens a new one.finally does not run when the process is killed by a signal. Handle SIGINT/SIGTERM by running the same leave() first. Holders of crashed processes are dropped by the next leave().window.__shared, and the tab is then never closed. Open your own tab for navigation, and close it yourself.selectBrowser. It gets every connected browser and returns the one to use. Without it, connecting fails when more than one browser is connected.import { connectViaExtension, listBrowsers } from 'playwriter' await using connection = await connectViaExtension({ selectBrowser: (browsers) => { // [{ id, browser: 'Brave', email: 'me@work.com', activeTabs, playwriterVersion }] return browsers.find((b) => b.browser === 'Brave' && b.email === 'me@work.com') }, }) console.log(connection.extensionBrowser.id) // same list, without connecting const browsers = await listBrowsers()
id is stable across restarts, so you can save it and match on it later. email is null when the profile is not signed in./cli/session/new yourself. Do not call chromium.connectOverCDP(getCdpUrl(...)) unless you already have a session from the CLI.# Reset a session (reconnect browser, clear state) playwriter session reset 1 # Delete a session playwriter session delete 1 # List all sessions playwriter session list
| Variable | Description |
state | Persisted object, isolated per session |
context | Browser context, access all pages via context.pages() |
require | Load Node.js modules (path, fs, crypto, etc.) |
fetch | Standard fetch API |
Buffer, URL, URLSearchParams | Standard globals |
setTimeout, setInterval | Timers |
crypto, process | Node.js globals |
page global. Reading page throws. Store your own page in state.page.window.open, OAuth login flows, target=_blank) are auto-relocated to tabs in the main window by the extension. The new tab appears in context.pages():await state.page.locator('button:has-text("Login with Google")').click() await state.page.waitForTimeout(1000) // New tab is the last page const pages = context.pages() const loginPage = pages[pages.length - 1] await loginPage.locator('[data-email]').first().click()
[WARNING] New page opened from current page (index N, initial url: ...) message pointing to the new tab.state.page.removeAllListeners()
browser.close() or context.close(). Only close pages you created yourself.