In Playwright, why can't the storageState option be worker-scoped, and what do you do instead?

## Two scopes, one option Every Playwright fixture is either **test-scoped** — built and torn down around each test — or **worker-scoped**, built once per worker process and reused by every test that worker runs. Scope is declared with the tuple form, `[fn, { scope: 'worker' }]`; the default is test scope. `storageState` looks like a fixture you could re-scope, but it is one of the built-in **test options**: the values a suite supplies through `use` in the config, `use` on a project, or `test.use` in a file or describe block. Since `test.use` is allowed to change an option for a subset of the tests a worker will run, the runner has to resolve options per test. Test scope is therefore not a default someone forgot to change; it is what the option means. ## Why re-declaring it fails Overriding a fixture keeps the original's scope, and registering a name at worker scope that already exists at test scope is refused outright. The rule underneath is the dependency direction: - a **test-scoped** fixture may depend on **worker-scoped** ones — the worker value is already there when the test starts, and it outlives the test; - a **worker-scoped** fixture may **not** depend on test-scoped ones — those are created and destroyed many times inside the worker's lifetime, so there is no single value to capture. If `storageState` were worker-scoped, a `test.use({ storageState })` inside one describe block would have nothing to act on for the other tests running in the same worker. ## The indirection that works Declare a fixture of your own at worker scope that produces the path, and let the test-scoped option read it: ```ts export const test = base.extend<{}, { workerStorageState: string }>({ workerStorageState: [async ({ browser }, use) => { const file = `playwright/.auth/worker-${test.info().parallelIndex}.json`; // sign in once here, write `file` await use(file); }, { scope: 'worker' }], storageState: ({ workerStorageState }, use) => use(workerStorageState), }); ``` Read the generics carefully: in `base.extend<TestFixtures, WorkerFixtures>` the **second** type argument declares worker fixtures. Omitting it is the usual reason TypeScript rejects the tuple form. The override itself is deliberately trivial — it exists only to bridge the two scopes, and it stays a plain function rather than an async one because there is nothing to await. ## What the worker fixture should hand back - **A path, not a parsed object.** The option accepts either, but a path lets a restarted worker detect the file already exists and skip the sign-in. - **An already-verified session.** Assert a role-specific landmark before writing the file; a failed sign-in otherwise produces a valid-looking file full of nothing. - **Its own identity.** Two workers writing the same path race each other; key the file off the worker's own index. - **Nothing that needs per-test teardown.** Worker fixtures are torn down when the worker shuts down, so anything that must be cleaned between tests does not belong here. ## The cost model | Sign-in happens | Where it lives | 200 tests over 4 workers | |---|---|---| | Per test | a beforeEach hook | 200 sign-ins | | Per worker | a worker-scoped fixture | 4 sign-ins | | Once per run | a setup step writing one file | 1 sign-in, one shared identity | The middle row is the reason the indirection is worth the ceremony: it buys per-worker identities at roughly per-run cost. ## Failure modes 1. Declaring the worker fixture and forgetting the `storageState` override — every test quietly keeps using the config-level file, and no error is raised. 2. Writing the sign-in into the fixture but omitting `{ scope: 'worker' }` — it silently becomes a per-test sign-in, which is what you were trying to avoid. 3. Depending on `page` inside the worker fixture — `page` is test-scoped and the runner refuses. Use `browser`, which is worker-scoped.