The Complete Guide to Playwright storage_state — Saving, Reusing, and Managing Multiple Roles

If your Playwright tests feel slow because every one of them logs in from scratch, storage_state is the answer. By saving cookies and localStorage after login to a file and loading it in later tests, you can skip the login flow entirely. This article covers everything from the basics of saving and loading, to wiring it into pytest-playwright, managing multiple roles, and the practical pitfalls around expiry, parallel execution, and sensitive data.

storage_state isn’t a “login shortcut” — it’s a way of managing authentication state as a file. Understanding what gets saved, and what doesn’t, cuts down on mysterious authentication errors.

When testing apps that require login, these problems tend to come up:

• Every test drives the login screen, adding a few seconds apiece
• A change to the login screen takes down unrelated tests all at once
• Tests for different roles, like admin and regular user, aren’t well organized
• Things got unstable once you turned on parallel execution

Designing your storage_state usage properly goes a long way toward easing all of them.

Where This Article Fits

Our advanced Page Object Model article introduces the idea of “create authentication state once in a session-scoped fixture and reuse it” as one part of POM design. This article pulls that piece out and goes deeper, focusing on the operational side: saving to a file, multiple roles, expiry, CI, and parallel execution. If you want to see how it fits together with POM, read the advanced article as well.

What Is storage_state, and What Gets Saved?

storage_state is a feature for saving the state of a browser context — cookies, localStorage, and so on — and carrying it over to another context. Reusing a logged-in state is its most common use.

① Saving Authentication State to a File

Here’s the basic form: log in, then write storage_state out to a file.

from playwright.sync_api import Browser

def save_auth_state(browser: Browser, base_url: str, path: str) -> None:
    context = browser.new_context()
    page = context.new_page()

    page.goto(f"{base_url}/login")
    page.get_by_label("Email").fill("test@example.com")
    page.get_by_label("Password").fill("Password123")
    page.get_by_role("button", name="Log in").click()
    page.wait_for_url("**/dashboard")  # confirm login finished before saving

    context.storage_state(path=path)  # write out as a JSON file
    context.close()

If your app keeps authentication data in IndexedDB (Firebase Authentication, for example), pass indexed_db=True when saving.

# Include IndexedDB in the saved state (v1.51 and later)
context.storage_state(path=path, indexed_db=True)

② Applying It to pytest-playwright’s Default page

With pytest-playwright, overriding the browser_context_args fixture applies the saved state to any test that uses the default context and page fixtures.

# conftest.py
import os
import pytest

AUTH_FILE = "auth/user.json"

@pytest.fixture(scope="session", autouse=True)
def prepare_auth(browser, base_url):
    """Log in once before the tests start, and save the auth state."""
    os.makedirs("auth", exist_ok=True)
    save_auth_state(browser, base_url, AUTH_FILE)

@pytest.fixture(scope="session")
def browser_context_args(browser_context_args):
    """Apply the saved auth state to the default context."""
    return {**browser_context_args, "storage_state": AUTH_FILE}

# The test starts already logged in
def test_dashboard(page):
    page.goto("/dashboard")
    assert page.get_by_text("Welcome").is_visible()

③ Switching Between Multiple Roles

If you keep a separate file per role — admin and regular user, say — each test can pick the role it needs.

# conftest.py
import pytest

ROLE_FILES = {
    "admin": "auth/admin.json",
    "user": "auth/user.json",
}

@pytest.fixture
def page_as(browser):
    """A factory fixture that returns a page already logged in as the given role."""
    contexts = []

    def _page_as(role: str):
        context = browser.new_context(storage_state=ROLE_FILES[role])
        contexts.append(context)
        return context.new_page()

    yield _page_as

    for context in contexts:
        context.close()  # don't forget the cleanup

def test_admin_can_see_user_list(page_as):
    page = page_as("admin")
    page.goto("/admin/users")
    assert page.get_by_role("heading", name="User Management").is_visible()

def test_user_cannot_access_admin_page(page_as):
    page = page_as("user")
    page.goto("/admin/users")
    assert page.get_by_text("You do not have permission").is_visible()

④ Planning for Expiry

A saved file doesn’t last forever. Once the session expires, tests start failing with “mysterious authentication errors.”

import os
import time

MAX_AGE_SECONDS = 30 * 60  # example: only reuse files modified within 30 minutes

def is_auth_file_fresh(path: str) -> bool:
    """True if the file exists and was modified recently enough."""
    if not os.path.exists(path):
        return False
    age = time.time() - os.path.getmtime(path)
    return age < MAX_AGE_SECONDS

@pytest.fixture(scope="session", autouse=True)
def prepare_auth(browser, base_url):
    if not is_auth_file_fresh(AUTH_FILE):
        os.makedirs("auth", exist_ok=True)
        save_auth_state(browser, base_url, AUTH_FILE)

⑤ CI, Parallel Execution, and Sensitive Data

To split files per worker, use the worker_id fixture provided by pytest-xdist. The official Playwright authentication guide also describes splitting auth state files per worker for parallel runs (using parallelIndex on the Node side). Don’t just rename the file — make both the save step and the load step use the same auth_file.

# conftest.py (the fixed-AUTH_FILE version from ②, rewritten for parallel runs)
@pytest.fixture(scope="session")
def auth_file(worker_id):
    # without xdist: user_master.json / with it: user_gw0.json, user_gw1.json ...
    os.makedirs("auth", exist_ok=True)
    return f"auth/user_{worker_id}.json"

@pytest.fixture(scope="session", autouse=True)
def prepare_auth(browser, base_url, auth_file):
    save_auth_state(browser, base_url, auth_file)  # the save path is now per-worker

@pytest.fixture(scope="session")
def browser_context_args(browser_context_args, auth_file):
    return {**browser_context_args, "storage_state": auth_file}  # same file when loading

Common Mistakes Seen in Practice

FAQ

📋 Summary

Repeating the login flow quietly pushes up your suite’s runtime. Start by trying save-and-load with a single role, and once that works, expand to more roles and the operational rules above.