When would you pass the object from context.storageState() to browser.newContext instead of a file path?

seniornice to knowfreq 33%

answer

The call returns state; path also writes
Both forms accepted everywhere
Objects do not cross processes
Config names a file, not a variable
Files are what stays inspectable

basics

~20 s

Use the object when one process both mints and consumes the session: context.storageState() with no path returns it, and browser.newContext accepts it directly. Use a file path when another process, run or config must read the state.

solid answer

~50 s

context.storageState() returns the state object; the path option is what additionally writes it to disk. Both browser.newContext({ storageState }) and the runner's option accept either form, so the choice is really about who else needs to read it. Inside a single Node process — a library-API script that signs in once and then opens several contexts against an internal admin console — the object keeps the session in memory: nothing to write, nothing to clean up, no path to get wrong, and no window where a file of live session values sits on disk. A path is what crosses a process boundary: a value named in playwright.config.ts is read from disk when each context is created, and a separate run or a separate process cannot see a variable from yours. In practice the object suits ad-hoc scripts and the path suits anything the configuration has to name.

`context.storageState()` returns the state object; the `path` option is what additionally writes it to disk. Both `browser.newContext({ storageState })` and the runner's option accept either form, so the choice is really about *who else needs to read it*. Inside a single Node process — a library-API script that signs in once and then opens several contexts against an internal admin console — the object keeps the session in memory: nothing to write, nothing to clean up, no path to get wrong, and no window where a file of live session values sits on disk. A path is what crosses a process boundary: a value named in `playwright.config.ts` is read from disk when each context is created, and a separate run or a separate process cannot see a variable from yours. In practice the object suits ad-hoc scripts and the path suits anything the configuration has to name.

code

typescript · 13 lines

typescript

import { chromium } from '@playwright/test';

const browser = await chromium.launch();
const signIn = await browser.newContext();
const page = await signIn.newPage();
await page.goto('https://admin.example.com/sign-in');
// ... drive the console's sign-in form once ...

const state = await signIn.storageState();
await signIn.close();

const reports = await browser.newContext({ storageState: state });
const audits = await browser.newContext({ storageState: state });

go deeper

for a junior

Know that the call returns the state and that path merely also writes it, and that browser.newContext takes either the returned object or a filename.

for a middle

Explain the deciding question — whether another process must read the state — and why a config value has to be a path while a script can pass the object straight along.

for a senior

Show that you pick deliberately: no file for a self-contained script, a file when something downstream consumes it, and that you can say what each choice costs in cleanup and debuggability.

for a principal

Own where sessions are minted and how far they travel across a suite, since that decides whether state lives only in memory or becomes an artefact other runs depend on.

Two return values from one call

context.storageState() always produces the state object. Passing path does not change what is returned; it adds a side effect:

const state = await context.storageState();                        // object only
const same  = await context.storageState({ path: 'admin.json' });  // object and a file

Every consumer of the option accepts both forms — a filename string, or the object a previous call returned. So the real question is never "which does Playwright support" but "who else has to read this".

What the object form buys

Inside one Node process, the object is the simpler artefact:

No file lifecycle. Nothing to create before, or delete after, the run.
No path resolution. A wrong relative path is a whole class of failure that disappears.
No file of live session values on disk. The state exists only for as long as the process does.
Direct reuse. One signed-in context can seed several new ones in the same script: browser.newContext({ storageState: state }), repeated.

That fits the library-API shape well: a script that drives the internal admin console signs in once, captures the state, closes the signing-in context, and opens as many further contexts from the object as the job needs.

What the path form buys

A path is a name that outlives the process that produced it:

playwright.config.ts can point at it, and the value is read when a context is built.
A run that produced the file and a run that consumes it need not be the same process.
The file can be inspected, printed and reasoned about after the fact, which is what makes a signed-out symptom debuggable.

You cannot hand a process a JavaScript object; you can hand it a filename. That single fact explains most of the choice.

Side by side

Consideration	State object	File path
Readable by another process	No	Yes
Nameable in the config	Awkward — must be imported	Yes, directly
Artefact to clean up	None	A file
Inspectable after the run	Only while in memory	Yes, it is JSON
Natural home	A single library-API script	A configured suite

A worked shape

For an admin console script that has to open several browser contexts from one session:

Launch a browser and open a context.
Drive the real sign-in once.
const state = await context.storageState(); — no path.
Close the signing-in context.
await browser.newContext({ storageState: state }) for each context the script needs.

Nothing was written, and each new context begins authenticated. Add path to step 3 only when something outside the script must consume the result — for instance when the configured suite that runs afterwards names that file in its own options.

Nuances worth naming

The object is a plain serialisable value, so it can be turned into JSON yourself if you want a file with different placement or lifetime than path would give you. It can equally be built by hand: the empty session { cookies: [], origins: [] } is the same shape, which is what makes an inline literal a legal value for the option.

And the two forms are not exclusive. A run may capture with path, so the file exists for inspection, while still using the returned object immediately for the contexts it opens next. Passing path costs nothing beyond the write, and the return value is there either way — a point that is easy to miss, because most examples show the file being written and then never mention the value the call handed back.

## Two return values from one call `context.storageState()` always produces the state object. Passing `path` does not change what is returned; it adds a side effect: ```ts const state = await context.storageState(); // object only const same = await context.storageState({ path: 'admin.json' }); // object and a file ``` Every consumer of the option accepts both forms — a filename string, or the object a previous call returned. So the real question is never "which does Playwright support" but "who else has to read this". ## What the object form buys Inside one Node process, the object is the simpler artefact: - **No file lifecycle.** Nothing to create before, or delete after, the run. - **No path resolution.** A wrong relative path is a whole class of failure that disappears. - **No file of live session values on disk.** The state exists only for as long as the process does. - **Direct reuse.** One signed-in context can seed several new ones in the same script: `browser.newContext({ storageState: state })`, repeated. That fits the library-API shape well: a script that drives the internal admin console signs in once, captures the state, closes the signing-in context, and opens as many further contexts from the object as the job needs. ## What the path form buys A path is a name that outlives the process that produced it: - `playwright.config.ts` can point at it, and the value is read when a context is built. - A run that produced the file and a run that consumes it need not be the same process. - The file can be inspected, printed and reasoned about after the fact, which is what makes a signed-out symptom debuggable. You cannot hand a process a JavaScript object; you can hand it a filename. That single fact explains most of the choice. ## Side by side | Consideration | State object | File path | |---|---|---| | Readable by another process | No | Yes | | Nameable in the config | Awkward — must be imported | Yes, directly | | Artefact to clean up | None | A file | | Inspectable after the run | Only while in memory | Yes, it is JSON | | Natural home | A single library-API script | A configured suite | ## A worked shape For an admin console script that has to open several browser contexts from one session: 1. Launch a browser and open a context. 2. Drive the real sign-in once. 3. `const state = await context.storageState();` — no `path`. 4. Close the signing-in context. 5. `await browser.newContext({ storageState: state })` for each context the script needs. Nothing was written, and each new context begins authenticated. Add `path` to step 3 only when something outside the script must consume the result — for instance when the configured suite that runs afterwards names that file in its own options. ## Nuances worth naming The object is a plain serialisable value, so it can be turned into JSON yourself if you want a file with different placement or lifetime than `path` would give you. It can equally be built by hand: the empty session `{ cookies: [], origins: [] }` is the same shape, which is what makes an inline literal a legal value for the option. And the two forms are not exclusive. A run may capture with `path`, so the file exists for inspection, while still using the returned object immediately for the contexts it opens next. Passing `path` costs nothing beyond the write, and the return value is there either way — a point that is easy to miss, because most examples show the file being written and then never mention the value the call handed back.

Can the runner's storageState option take an object rather than a filename?
Yes — both `test.use` and a project's `use` accept a state object as well as a path. An inline `{ cookies: [], origins: [] }` is the common case. A real session usually still travels as a file, because a config value has to be resolvable without the process that produced the session.
Does passing path mean you lose the object?
No. `context.storageState({ path })` still resolves to the state object; the `path` option only adds the write. A script may keep the returned value for the contexts it opens next while leaving the file behind for something else to consume.

saying these in an interview costs you the question

Believing browser.newContext only accepts a filename
Thinking storageState returns nothing when path is given
Expecting another process to read an in-memory state object
Writing a file when one script both makes and uses the session
Assuming the object form drops cookies and keeps storage

When would you pass the object from context.storageState() to browser.newContext instead of a file path?

§ answer

basics

solid answer

code

§ go deeper

▾level notes4 levels

▾deep dive~3 min

Two return values from one call

What the object form buys

What the path form buys

Side by side

A worked shape

Nuances worth naming

▾common follow-ups2 questions

▾red flags5 flags

Two return values from one call

What the object form buys

What the path form buys

Side by side

A worked shape

Nuances worth naming

answer

go deeper