playwright-auth-state

Playwright Auth State

Overview

Use this skill when tests need to start in a known logged-in session or with a role-specific browser state instead of repeating the login UI in every spec. It keeps the browser state deterministic without making authentication the focus of the test.

Do not use this skill when the login form itself is the feature under test, or when the app is fully local and does not need shared browser state.

When to Use

• When a test requires an already authenticated user.
• When a suite benefits from reusing browser state across many tests.
• When you need separate roles or permissions without redoing the UI login.

When Not to Use

• When the login flow is the feature under test.
• When the app behavior is fully local and does not depend on stored session state.
• When you are diagnosing a flake that should be fixed first in playwright-debugging.

Authenticated State

Create the authenticated state once in a setup project, then load it in the tests that need it.

// tests/auth.setup.ts
import { test as setup, expect } from '@playwright/test';

setup('authenticate', async ({ page }) => {
  await page.goto('/login');
  await page.getByLabel('Email').fill('[email protected]');
  await page.getByLabel('Password').fill('password123');
  await page.getByRole('button', { name: 'Sign in' }).click();

  await expect(page.getByRole('button', { name: 'Sign out' })).toBeVisible();
  await page.context().storageState({ path: 'playwright/.auth/user.json' });
});

Apply the saved state in configuration:

// playwright.config.ts
import { defineConfig } from '@playwright/test';

export default defineConfig({
  projects: [
    {
      name: 'setup',
      testMatch: /.*\.setup\.ts/,
    },
    {
      name: 'chromium',
      dependencies: ['setup'],
      use: {
        storageState: 'playwright/.auth/user.json',
      },
    },
  ],
});

If only some tests need the logged-in session, scope the state to a specific project rather than making it global. For multiple roles, keep one state file per role and give each project a clear name.