The word “isolated” in Playwright testing is doing too much work.

The four state layers, in scope order

Each layer is a different scope at which two tests can share state. The first two are addressed by Playwright's defaults. The third is what most teams miss. The fourth is its own discipline.

What Playwright handles for free, and where the docs stop

Workers and per-test contexts have been the default since v1.10. If you write test("...", async ({ page }) => {}) and never touch the config, you already get OS-process isolation between groups of tests and a fresh BrowserContext for every test inside a group. That is the half of the “isolated Playwright testing” story that almost every guide covers and most readers take away.

The thing the typical guide does not say: Layer 3 is not addressed by either of those. The BrowserContext is a logical partition inside one Chromium process. Underneath, the process is still using one user-data-dir. If a test installs a service worker, the registration goes into the user-data-dir. If a test caches a 200 response on a CDN URL, that goes into the HTTP cache in the user-data-dir. Both can survive a context tear-down and show up in the next test's context if the URL matches.

// playwright.config.ts — what 'isolated' means by default

import { defineConfig } from "@playwright/test";

export default defineConfig({
  // Layer 1 (process): one OS process per worker.
  // Crashes in one worker do not affect others.
  workers: process.env.CI ? 4 : undefined,

  use: {
    // Layer 2 (context): every test() call gets a brand new
    // BrowserContext. Cookies, localStorage, IndexedDB created
    // by one test cannot be read by the next.
    //
    // Layer 3 (profile): NOT addressed here. Chromium writes
    // service workers, the HTTP cache, the safe-browsing list,
    // and the GPU shader cache to user-data-dir, which by
    // default is shared across all contexts in the same launch.
    //
    // Layer 4 (network): NOT addressed here. The staging API
    // is the same for every test in every worker. If two tests
    // mutate the same row, order matters.
  },
});

The fix at Layer 3 is to either (a) launch a fresh user-data-dir per test (slow, because Chromium cold-starts each time), or (b) launch a fresh user-data-dir per run and accept that within one run Chromium shares state below the context level. Most teams pick (b) without realising they picked it. Assrt's --isolated flag is option (b) wired up explicitly: an in-memory user-data-dir per run, no persistence, fresh cache.

One flag, three modes, the exact line of code that flips them

The whole profile-layer decision in Assrt happens in one branch of one function. It is short enough to read in full. The branch is inside launchLocal() in src/core/browser.ts (lines 296 to 347 in the open-source repo). The three log lines you see on stderr are the three modes:

// node_modules/@m13v/assrt/dist/core/browser.ts
// (matches src/core/browser.ts:296-347 in the open-source repo)

const args = [
  cliPath,
  "--viewport-size", "1600x900",
  "--output-mode", "file",
  "--output-dir", outputDir,
  "--caps", "devtools",
];

if (extension) {
  // Mode 1: skip profile entirely; attach to your real Chrome
  args.push("--extension");
  console.error("[browser] launch mode: extension (connecting to existing Chrome)");
} else if (isolated) {
  // Mode 2: in-memory user-data-dir; nothing survives the run
  args.push("--isolated");
  console.error("[browser] profile mode: isolated (in-memory, no persistence)");
} else {
  // Mode 3 (default): shared profile at ~/.assrt/browser-profile
  const userDataDir = join(homedir(), ".assrt", "browser-profile");
  mkdirSync(userDataDir, { recursive: true });
  await McpBrowserManager.killOrphanChromeProcesses(userDataDir);
  // ... SingletonLock/SingletonSocket/SingletonCookie scrub ...
  args.push("--user-data-dir", userDataDir);
  console.error(`[browser] profile mode: persistent (${userDataDir})`);
}

Three log lines, three Layer-3 stances. The default is persistent because that is what you want for a long-lived dev session that wants to keep your login. The --isolated flag (or ASSRT_ISOLATED=1 in the env, parsed at cli.ts:114 and server.ts:501) is the fast switch to a clean profile every time. The --extension mode is the explicit anti-isolation mode for when you need to drive your real Chrome.

The same command, three different runs

The plan file is the same. The URL is the same. The thing that changes is what state the browser carries into the run.

// What flipping the profile dial actually does

// Persistent (default) — inherits ~/.assrt/browser-profile
npx @m13v/assrt run --url http://localhost:3000 --plan-file login.md
// stderr: [browser] profile mode: persistent (~/.assrt/browser-profile)
// Effect: cookies, localStorage, service workers from previous
// runs are still in the user-data-dir.

// Isolated — fresh in-memory user-data-dir per run
npx @m13v/assrt run --url http://localhost:3000 --plan-file login.md --isolated
// stderr: [browser] profile mode: isolated (in-memory, no persistence)
// Effect: clean Chromium, no carryover from previous runs.
// Equivalent: ASSRT_ISOLATED=1 npx @m13v/assrt run ...

// Extension — attach to your real Chrome (no isolation by design)
npx @m13v/assrt run --url http://localhost:3000 --plan-file login.md --extension
// stderr: [browser] launch mode: extension (connecting to existing Chrome)
// Effect: drives the Chrome window already on your taskbar.

Why storageState alone is not Layer 3

The closest thing in vanilla Playwright to a profile dial is the storageState fixture. It is a real solution, but it lives at Layer 2: it dumps and restores cookies and localStorage. It does not touch the user-data-dir, which means service workers, HTTP cache, and IndexedDB state below the context can still leak.

// Layer-2 approach: persist cookies + localStorage
// only. user-data-dir is shared across the entire run.

// global-setup.ts
import { chromium } from "@playwright/test";

async function globalSetup() {
  const browser = await chromium.launch();
  const ctx = await browser.newContext();
  const page = await ctx.newPage();
  await page.goto("http://localhost:3000/login");
  await page.fill("#email", "test@example.com");
  await page.fill("#password", "secret");
  await page.click("button[type=submit]");
  await ctx.storageState({ path: "auth.json" });
  await browser.close();
}

// playwright.config.ts
export default defineConfig({
  globalSetup: require.resolve("./global-setup"),
  use: { storageState: "auth.json" },
});

// Pro: tests start logged in.
// Con: service worker installed by test 4 is still
// registered when test 12 runs.

They are not competing solutions. They are tools at different scopes. Use storageState when you want to skip the login form per test in a long suite. Use --isolated when you want a clean Chromium under the contexts. Use both when you have a long suite that touches a service worker.

What two concurrent runs against the persistent profile look like

One detail that surprises people: if two runs both try to launch against the persistent profile within the same second, only one wins. The other is automatically demoted to --isolated for that single run. No error, no thrown exception, no failed test; just a different log line on stderr. This is the catch block at browser.ts:336 firing.

The takeaway: if you genuinely run two test sessions in parallel, you do not actually have to opt into --isolated for the second one. The runner detects the collision and demotes itself. You will see one persistent run line and one isolated run line in the logs.

What the disk looks like in each mode

Toggle the panel to see the difference. In persistent mode the profile lives at a stable path and grows over time. In isolated mode it is a temp dir that disappears with the process.

Which dial for which test

A few opinions, in order of how often they come up.

• CI runs: isolated, always. There is no reason to share Chromium state between CI builds. Persistent state on a CI runner is either a security issue (auth cookies leaking between PRs on the same shared runner) or a flakiness source (a service worker registered by an earlier build still cached). Set ASSRT_ISOLATED=1 in the workflow env and forget about it.
• Local dev runs against your own app: persistent. You log in once, the cookie is in the user-data-dir, every subsequent assrt_test call against localhost:3000 inherits it. This is the “sit on top of an already-set-up session” case the persistent default exists for.
• Debugging a flake nobody can reproduce: try isolated first. If a test fails on CI but passes locally, the most common root cause is layer-3 state your local profile is silently providing. A single --isolated run on your own machine reproduces the fresh-Chromium reality CI sees, often in seconds.
• PWA, push, or service-worker tests: isolated. Service worker registrations live in the user-data-dir. If your test installs one, an isolated run guarantees a clean slate. A persistent run will silently inherit the previous registration and quietly invalidate your test's assumptions.
• MFA, anti-bot, or anything Cloudflare touches: extension. Both isolated and persistent modes look like a fresh Chromium to Cloudflare Turnstile, which is a fingerprint Turnstile dislikes. Run with --extension to drive your real Chrome and bypass the gate. Not an isolation mode; the explicit anti-isolation escape hatch.

Frequently asked questions