Implementation:Microsoft Playwright StorageState
| Knowledge Sources | |
|---|---|
| Domains | Browser_Automation, CLI |
| Last Updated | 2026-02-11 00:00 GMT |
Overview
Concrete tool for persisting and restoring browser authentication state (cookies, local storage) across automation sessions, provided by the Playwright library.
Description
The StorageState implementation in Playwright provides a complete save-and-load cycle for browser authentication state, accessible both through the CLI and the programmatic API.
CLI integration (save): When the --save-storage <filename> flag is passed to any browser-opening CLI command (open, codegen, cr, ff, wk), the launchContext() function registers a cleanup handler. When the browser closes (either by the user closing the last page or by Ctrl+C), the handler calls context.storageState({ path: options.saveStorage }) to serialize all cookies and local storage to the specified JSON file.
CLI integration (load): When the --load-storage <filename> flag is passed, launchContext() sets contextOptions.storageState = options.loadStorage before creating the browser context. Playwright reads the JSON file and pre-populates the context with the saved cookies and local storage entries.
Programmatic API: The context.storageState() method on BrowserContext can be called at any point during a session. It accepts an optional path parameter to write directly to a file, and an optional indexedDB boolean to include IndexedDB data. It returns a StorageState object containing cookies and origins arrays.
The method implementation sends the serialization request over the Playwright channel protocol, receives the serialized state from the browser server, and writes it to disk using fs.promises.writeFile with pretty-printed JSON (2-space indent, UTF-8 encoding). The directory for the output file is created automatically via mkdirIfNeeded().
Usage
Use this implementation when:
- Saving authentication state after an interactive login for reuse in later automation runs.
- Loading pre-saved authentication state to skip the login flow in tests.
- Building a global setup script that authenticates once and exports state for parallel test workers.
- Chaining CLI commands where one session logs in and the next session reuses the credentials.
Code Reference
Source Location
- Repository: playwright
- CLI load-storage:
packages/playwright-core/src/cli/program.ts(line 472-473) - CLI save-storage:
packages/playwright-core/src/cli/program.ts(lines 499-510) - CLI option registration:
packages/playwright-core/src/cli/program.ts(lines 717, 723) - storageState() method:
packages/playwright-core/src/client/browserContext.ts(lines 465-472)
Signature
// BrowserContext.storageState() -- programmatic API
async storageState(options?: {
path?: string;
indexedDB?: boolean;
}): Promise<StorageState>;
// StorageState type (returned object / JSON file structure)
type StorageState = {
cookies: Array<{
name: string;
value: string;
domain: string;
path: string;
expires: number;
httpOnly: boolean;
secure: boolean;
sameSite: 'Strict' | 'Lax' | 'None';
}>;
origins: Array<{
origin: string;
localStorage: Array<{
name: string;
value: string;
}>;
}>;
};
// CLI option handling in launchContext()
// Load: sets contextOptions.storageState = options.loadStorage (line 472-473)
if (options.loadStorage)
contextOptions.storageState = options.loadStorage;
// Save: calls context.storageState() in closeBrowser() (lines 505-506)
if (options.saveStorage)
await context.storageState({ path: options.saveStorage });
Import
# CLI usage -- save authentication state after interactive login
npx playwright open --save-storage auth.json https://example.com/login
# CLI usage -- load saved state into a new session
npx playwright open --load-storage auth.json https://example.com/dashboard
# CLI usage -- chain save and load across commands
npx playwright codegen --save-storage auth.json https://example.com/login
npx playwright screenshot --load-storage auth.json https://example.com/dashboard dashboard.png
// Programmatic usage in a test or script
import { chromium } from 'playwright';
// Save
const browser = await chromium.launch();
const context = await browser.newContext();
// ... perform login ...
await context.storageState({ path: 'auth.json' });
await browser.close();
// Load
const browser2 = await chromium.launch();
const context2 = await browser2.newContext({ storageState: 'auth.json' });
// context2 is now authenticated
I/O Contract
Inputs
| Name | Type | Required | Description |
|---|---|---|---|
| --load-storage | string (file path) | No | Path to a JSON file containing previously saved cookies and localStorage. The file is read and its contents are applied to the browser context at creation time via contextOptions.storageState.
|
| --save-storage | string (file path) | No | Path where cookies and localStorage will be written as JSON when the browser closes. The file is created or overwritten. |
| options.path | string | No (programmatic API) | When calling context.storageState() directly, the path to write the JSON file. If omitted, the state is returned as an in-memory object only.
|
| options.indexedDB | boolean | No (programmatic API) | When true, IndexedDB data is included in the serialized state in addition to cookies and localStorage. |
Outputs
| Name | Type | Description |
|---|---|---|
| JSON state file | File | A JSON file containing cookies and origins arrays. Each cookie includes name, value, domain, path, expires, httpOnly, secure, and sameSite. Each origin includes its URL and an array of localStorage key-value pairs.
|
| StorageState object | Object | When using the programmatic API without a path, the method returns the state as a JavaScript object. |
| Pre-populated context | BrowserContext | When --load-storage is used, the created BrowserContext has all cookies and localStorage entries from the file already set.
|
Usage Examples
Basic Example
# Step 1: Log in interactively and save the authentication state
npx playwright open --save-storage auth.json https://myapp.com/login
# Step 2: Use the saved state to skip login in future sessions
npx playwright open --load-storage auth.json https://myapp.com/dashboard
Screenshot with Saved Auth
# Capture a screenshot of an authenticated page
npx playwright screenshot --load-storage auth.json https://myapp.com/profile profile.png
Code Generation with Auth
# Generate test code while authenticated
npx playwright codegen --load-storage auth.json https://myapp.com/settings
Programmatic Save and Load
import { chromium } from 'playwright';
// Global setup: authenticate once
async function globalSetup() {
const browser = await chromium.launch();
const context = await browser.newContext();
const page = await context.newPage();
await page.goto('https://myapp.com/login');
await page.fill('#username', 'testuser');
await page.fill('#password', 'password');
await page.click('#login-button');
await page.waitForURL('**/dashboard');
// Save the authenticated state
await context.storageState({ path: 'auth.json' });
await browser.close();
}
// Test: reuse the authenticated state
async function test() {
const browser = await chromium.launch();
const context = await browser.newContext({ storageState: 'auth.json' });
const page = await context.newPage();
await page.goto('https://myapp.com/dashboard');
// Already authenticated -- no login required
}