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('user@example.com');
  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.

Treat the generated storage state as a build artifact, not source code. Keep it out of version control unless your project has a specific reason to commit it.

Recommended Project Shape

Keep the setup file and the auth state file in a predictable location:

• tests/auth.setup.ts
• playwright/.auth/user.json
• playwright.config.ts

Keep the setup test focused on creating state, not on exercising the full product flow. The setup project should end as soon as the authenticated signal is visible and the storage state has been written.

Verification

Verify the state file was created and loaded correctly.

Typical checks:

npx playwright test --project=setup
npx playwright test tests/dashboard.spec.ts

For debugging, use trace viewer or UI mode to confirm the login state is present in the resulting session.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: hzijad
• Source: hzijad/playwright-agent-skills
• License: MIT

Install and usage instructions live in the source repository linked above.