ever-co/ever-works / .agents/skills/playwright-best-practices
playwright-best-practices
VerifiedUse when writing Playwright tests, fixing flaky tests, debugging failures, implementing Page Object Model, configuring CI/CD, optimizing performance, mocking APIs, handling authentication or OAuth, testing accessibility (axe-core), file uploads/downloads, date/time mocking, WebSockets, geolocation, permissions, multi-tab/popup flows, mobile/responsive layouts, touch gestures, GraphQL, error handling, offline mode, multi-user collaboration, third-party services (payments, email verification), console error monitoring, global setup/teardown, test annotations (skip, fixme, slow), test tags (@smoke, @fast, @critical, filtering with --grep), project dependencies, security testing (XSS, CSRF, auth), performance budgets (Web Vitals, Lighthouse), iframes, component testing, canvas/WebGL, service workers/PWA, test coverage, i18n/localization, Electron apps, or browser extension testing. Covers E2E, component, API, visual, accessibility, security, Electron, and extension testing.
advanced/authentication.md
View on GitHub# Authentication Testing
## Table of Contents
1. [Quick Reference](#quick-reference)
2. [Patterns](#patterns)
3. [Decision Guide](#decision-guide)
4. [Anti-Patterns](#anti-patterns)
5. [Troubleshooting](#troubleshooting)
6. [Related](#related)
> **When to use**: Apps with login, session management, or protected routes. Authentication is the most common source of slow test suites.
## Quick Reference
```typescript
// Storage state reuse — the #1 pattern for fast auth
await page.goto('/login');
await page.getByLabel('Username').fill('testuser@example.com');
await page.getByLabel('Password').fill('secretPass123');
await page.getByRole('button', { name: 'Log in' }).click();
await page.context().storageState({ path: '.auth/session.json' });
// Reuse in config — every test starts authenticated
{
use: {
storageState: '.auth/session.json';
}
}
// API login — skip the UI entirely
const context = await browser.newContext();
const response = await context.request.post('/api/auth/login', {
data: { email: 'testuser@example.com', password: 'secretPass123' }
});
await context.storageState({ path: '.auth/session.json' });
```
## Patterns
### Storage State Reuse
**Use when**: You need authenticated tests and want to avoid logging in before every test.
**Avoid when**: Tests require completely fresh sessions, or you are testing the login flow itself.
`storageState` serializes cookies and localStorage to a JSON file. Load it in any browser context to start authenticated instantly.
```typescript
// scripts/generate-auth.ts — run once to generate the state file
import { chromium } from '@playwright/test';
async function generateAuthState() {
const browser = await chromium.launch();
const context = await browser.newContext();
const page = await context.newPage();
await page.goto('http://localhost:4000/login');
await page.getByLabel('Username').fill('testuser@example.com');
await page.getByLabel('Password').fill('secretPass123');
await page.getByRole('button', { name: 'Log in' }).click();
await page.waitForURL('/home');
await context.storageState({ path: '.auth/session.json' });
await browser.close();
}
generateAuthState();
```
```typescript
// playwright.config.ts — load saved state for all tests
import { defineConfig } from '@playwright/test';
export default defineConfig({
use: {
baseURL: 'http://localhost:4000',
storageState: '.auth/session.json'
}
});
```
```typescript
// tests/home.spec.ts — test starts already logged in
import { test, expect } from '@playwright/test';
test('authenticated user sees home page', async ({ page }) => {
await page.goto('/home');
await expect(page.getByRole('heading', { name: 'Home' })).toBeVisible();
});
```
### Global Setup Authentication
**Use when**: You want to authenticate once before the entire test suite runs.
**Avoid when**: Different tests need different users, or your tokens expire faster than your suite runs.
```typescript
// global-setup.ts
import { chromium, type FullConfig } from '@playwright/test';
async function globalSetup(config: FullConfig) {
const { baseURL } = config.projects[0].use;
const browser = await chromium.launch();
const context = await browser.newContext();
const page = await context.newPage();
await page.goto(`${baseURL}/login`);
await page.getByLabel('Username').fill(process.env.TEST_USER_EMAIL!);
await page.getByLabel('Password').fill(process.env.TEST_USER_PASSWORD!);
await page.getByRole('button', { name: 'Log in' }).click();
await page.waitForURL('**/home');
await context.storageState({ path: '.auth/session.json' });
await browser.close();
}
export default globalSetup;
```
```typescript
// playwright.config.ts
import { defineConfig } from '@playwright/test';
export default defineConfig({
globalSetup: require.resolve('./global-setup'),
use: {
baseURL: 'http://localhost:4000',
storageState: '.auth/session.json'
}
});
```
Add `.auth/` to `.gitignore`. Auth state files contain session tokens and should never be committed.
### Per-Worker Authentication
**Use when**: Each parallel worker needs its own authenticated session to avoid race conditions for tests that modify server-side state.
**Avoid when**: Tests are read-only and a modifying shared session is safe, you can use a single shared account.
> **Sharded runs**: `parallelIndex` resets per shard, so different shards can have workers with the same index. To avoid collisions, include the shard identifier in the username (e.g., `worker-${SHARD_INDEX}-${parallelIndex}@example.com`) by passing a `SHARD_INDEX` environment variable from your CI matrix.
```typescript
// fixtures/auth.ts
import { test as base, type BrowserContext } from '@playwright/test';
type AuthFixtures = {
authenticatedContext: BrowserContext;
};
export const test = base.extend<{}, AuthFixtures>({
authenticatedContext: [
async ({ browser }, use) => {
const context = await browser.newContext();
const page = await context.newPage();
await page.goto('/login');
await page.getByLabel('Username').fill(`worker-${test.info().parallelIndex}@example.com`);
await page.getByLabel('Password').fill('secretPass123');
await page.getByRole('button', { name: 'Log in' }).click();
await page.waitForURL('/home');
await page.close();
await use(context);
await context.close();
},
{ scope: 'worker' }
]
});
export { expect } from '@playwright/test';
```
```typescript
// tests/settings.spec.ts
import { test, expect } from '../fixtures/auth';
test('update display name', async ({ authenticatedContext }) => {
const page = await authenticatedContext.newPage();
await page.goto('/settings/profile');
await page.getByLabel('Display name').fill('Updated Name');
await page.getByRole('button', { name: 'Save' }).click();
await expect(page.getByText('Profile saved')).toBeVisible();
});
```
### Multiple Roles
**Use when**: Your app has role-based access control and you need to test different permission levels.
**Avoid when**: Your app has a single user role.
```typescript
// global-setup.ts — authenticate all roles
import { chromium, type FullConfig } from '@playwright/test';
const accounts = [
{
role: 'admin',
email: 'admin@example.com',
password: process.env.ADMIN_PASSWORD!
},
{
role: 'member',
email: 'member@example.com',
password: process.env.MEMBER_PASSWORD!
},
{
role: 'guest',
email: 'guest@example.com',
password: process.env.GUEST_PASSWORD!
}
];
async function globalSetup(config: FullConfig) {
const { baseURL } = config.projects[0].use;
for (const { role, email, password } of accounts) {
const browser = await chromium.launch();
const context = await browser.newContext();
const page = await context.newPage();
await page.goto(`${baseURL}/login`);
await page.getByLabel('Username').fill(email);
await page.getByLabel('Password').fill(password);
await page.getByRole('button', { name: 'Log in' }).click();
await page.waitForURL('**/home');
await context.storageState({ path: `.auth/${role}.json` });
await browser.close();
}
}
export default globalSetup;
```
```typescript
// playwright.config.ts — one project per role
import { defineConfig } from '@playwright/test';
export default defineConfig({
globalSetup: require.resolve('./global-setup'),
projects: [
{
name: 'admin',
use: { storageState: '.auth/admin.json' },
testMatch: '**/*.admin.spec.ts'
},
{
name: 'member',
use: { storageState: '.auth/member.json' },
testMatch: '**/*.member.spec.ts'
},
{
name: 'guest',
use: { storageState: '.auth/guest.json' },
testMatch: '**/*.guest.spec.ts'
},
{
name: 'anonymous',
use: { storageState: { cookies: [], origins: [] } },
testMatch: '**/*.anon.spec.ts'
}
]
});
```
```typescript
// tests/admin-panel.admin.spec.ts
import { test, expect } from '@playwright/test';
test('admin can access user management', async ({ page }) => {
await page.goto('/admin/users');
await expect(page.getByRole('heading', { name: 'User Management' })).toBeVisible();
await expect(page.getByRole('button', { name: 'Remove user' })).toBeEnabled();
});
```
```typescript
// tests/admin-panel.guest.spec.ts
import { test, expect } from '@playwright/test';
test('guest cannot access admin panel', async ({ page }) => {
await page.goto('/admin/users');
await expect(page.getByText('Access denied')).toBeVisible();
});
```
**Alternative**: Use a fixture that accepts a role parameter when you need role switching within a single spec file.
```typescript
// fixtures/auth.ts — role-based fixture
import { test as base, type Page } from '@playwright/test';
import fs from 'fs';
type RoleFixtures = {
loginAs: (role: 'admin' | 'member' | 'guest') => Promise<Page>;
};
export const test = base.extend<RoleFixtures>({
loginAs: async ({ browser }, use) => {
const pages: Page[] = [];
await use(async (role) => {
const statePath = `.auth/${role}.json`;
if (!fs.existsSync(statePath)) {
throw new Error(`Auth state for role "${role}" not found at ${statePath}`);
}
const context = await browser.newContext({ storageState: statePath });
const page = await context.newPage();
pages.push(page);
return page;
});
for (const page of pages) {
await page.context().close();
}
}
});
export { expect } from '@playwright/test';
```
```typescript
// tests/role-comparison.spec.ts
import { test, expect } from '../fixtures/auth';
test('admin sees remove button, guest does not', async ({ loginAs }) => {
const adminPage = await loginAs('admin');
await adminPage.goto('/admin/users');
await expect(adminPage.getByRole('button', { name: 'Remove user' })).toBeVisible();
const guestPage = await loginAs('guest');
await guestPage.goto('/admin/users');
await expect(guestPage.getByText('Access denied')).toBeVisible();
});
```
### OAuth/SSO Mocking
**Use when**: Your app authenticates via a third-party OAuth provider and you cannot hit the real provider in tests.
**Avoid when**: You have a dedicated test tenant on the OAuth provider.
A typical OAuth flow works like this:
1. User clicks "Sign in with Provider" → browser navigates to `https://accounts.provider.com/authorize?...`
2. User authenticates on the provider's page → provider redirects back to your app's **callback route** (e.g. `http://localhost:4000/auth/callback?code=ABC&state=XYZ`)
3. Your backend exchanges the `code` for an access token, creates a session, and redirects the user to a logged-in page
In tests you can short-circuit step 2 with `page.route()`: intercept the outbound request to the provider and respond with a `302` redirect straight to your callback route, supplying a mock `code` and `state`. Your backend still executes its normal callback handler — the only part that's mocked is the provider's authorization page.
For cases where you want to skip the browser redirect entirely, a second approach calls a **test-only API endpoint** that creates the session server-side and returns the session cookie directly.
```typescript
// tests/oauth-login.spec.ts — mock the callback route
import { test, expect } from '@playwright/test';
test('login via mocked OAuth flow', async ({ page }) => {
await page.route('https://accounts.provider.com/**', async (route) => {
const callbackUrl = new URL('http://localhost:4000/auth/callback');
callbackUrl.searchParams.set('code', 'mock-auth-code-xyz');
callbackUrl.searchParams.set('state', 'expected-state-value');
await route.fulfill({
status: 302,
headers: { location: callbackUrl.toString() }
});
});
await page.goto('/login');
await page.getByRole('button', { name: 'Sign in with Provider' }).click();
await page.waitForURL('/home');
await expect(page.getByRole('heading', { name: 'Home' })).toBeVisible();
});
```
```typescript
// tests/oauth-login.spec.ts — API-based session injection
import { test, expect } from '@playwright/test';
test('bypass OAuth entirely via API session injection', async ({ page }) => {
// Call a test-only endpoint that creates a session without OAuth
const response = await page.request.post('/api/test/create-session', {
data: {
email: 'oauth-user@example.com',
provider: 'provider',
role: 'member'
}
});
expect(response.ok()).toBeTruthy();
await page.context().storageState({ path: '.auth/oauth-user.json' });
await page.goto('/home');
await expect(page.getByRole('heading', { name: 'Home' })).toBeVisible();
});
```
**Backend requirement**: Your backend must expose a test-only session creation endpoint (guarded by `NODE_ENV=test`) or accept a known test OAuth code.
### MFA Handling
**Use when**: Your app requires two-factor authentication (TOTP, SMS, email codes).
**Avoid when**: MFA is optional and you can disable it for test accounts.
**Strategy 1**: Generate real TOTP codes from a shared secret.
```typescript
// helpers/totp.ts
import * as OTPAuth from 'otpauth';
export function generateTOTP(secret: string): string {
const totp = new OTPAuth.TOTP({
secret: OTPAuth.Secret.fromBase32(secret),
digits: 6,
period: 30,
algorithm: 'SHA1'
});
return totp.generate();
}
```
```typescript
// tests/mfa-login.spec.ts
import { test, expect } from '@playwright/test';
import { generateTOTP } from '../helpers/totp';
test('login with TOTP two-factor auth', async ({ page }) => {
await page.goto('/login');
await page.getByLabel('Username').fill('mfa-user@example.com');
await page.getByLabel('Password').fill('secretPass123');
await page.getByRole('button', { name: 'Log in' }).click();
await expect(page.getByText('Enter your authentication code')).toBeVisible();
const code = generateTOTP(process.env.MFA_TOTP_SECRET!);
await page.getByLabel('Authentication code').fill(code);
await page.getByRole('button', { name: 'Verify' }).click();
await page.waitForURL('/home');
await expect(page.getByRole('heading', { name: 'Home' })).toBeVisible();
});
```
**Strategy 2**: Mock MFA at the backend level. Have your backend accept a known bypass code (e.g., `000000`) when `NODE_ENV=test`.
**Strategy 3**: Disable MFA for test accounts at the infrastructure level.
### Session Refresh
**Use when**: Your tokens expire during long test runs.
**Avoid when**: Your test suite runs quickly and tokens outlast the entire run.
```typescript
// fixtures/auth-with-refresh.ts
import { test as base, type BrowserContext } from '@playwright/test';
import fs from 'fs';
type AuthFixtures = {
authenticatedPage: import('@playwright/test').Page;
};
export const test = base.extend<AuthFixtures>({
authenticatedPage: async ({ browser }, use) => {
const statePath = '.auth/session.json';
let context: BrowserContext;
if (fs.existsSync(statePath)) {
context = await browser.newContext({ storageState: statePath });
const page = await context.newPage();
const response = await page.request.get('/api/auth/me');
if (response.ok()) {
await use(page);
await context.close();
return;
}
await context.close();
}
context = await browser.newContext();
const page = await context.newPage();
await page.goto('/login');
await page.getByLabel('Username').fill(process.env.TEST_USER_EMAIL!);
await page.getByLabel('Password').fill(process.env.TEST_USER_PASSWORD!);
await page.getByRole('button', { name: 'Log in' }).click();
await page.waitForURL('/home');
await context.storageState({ path: statePath });
await use(page);
await context.close();
}
});
export { expect } from '@playwright/test';
```
### Login Page Object
**Use when**: Multiple test files need to log in and you want consistent, maintainable login logic.
**Avoid when**: You use `storageState` everywhere and never navigate through the login UI in tests.
```typescript
// page-objects/LoginPage.ts
import { type Page, type Locator, expect } from '@playwright/test';
export class LoginPage {
readonly page: Page;
readonly usernameInput: Locator;
readonly passwordInput: Locator;
readonly loginButton: Locator;
readonly errorMessage: Locator;
readonly forgotPasswordLink: Locator;
constructor(page: Page) {
this.page = page;
this.usernameInput = page.getByLabel('Username');
this.passwordInput = page.getByLabel('Password');
this.loginButton = page.getByRole('button', { name: 'Log in' });
this.errorMessage = page.getByRole('alert');
this.forgotPasswordLink = page.getByRole('link', {
name: 'Forgot password'
});
}
async goto() {
await this.page.goto('/login');
await expect(this.loginButton).toBeVisible();
}
async login(username: string, password: string) {
await this.usernameInput.fill(username);
await this.passwordInput.fill(password);
await this.loginButton.click();
}
async loginAndWaitForHome(username: string, password: string) {
await this.login(username, password);
await this.page.waitForURL('/home');
}
async expectError(message: string | RegExp) {
await expect(this.errorMessage).toContainText(message);
}
async expectFieldError(field: 'username' | 'password', message: string) {
const input = field === 'username' ? this.usernameInput : this.passwordInput;
await expect(input).toHaveAttribute('aria-invalid', 'true');
const errorId = await input.getAttribute('aria-describedby');
if (errorId) {
await expect(this.page.locator(`#${errorId}`)).toContainText(message);
}
}
}
```
```typescript
// tests/login.spec.ts
import { test, expect } from '@playwright/test';
import { LoginPage } from '../page-objects/LoginPage';
test.use({ storageState: { cookies: [], origins: [] } });
test.describe('login page', () => {
let loginPage: LoginPage;
test.beforeEach(async ({ page }) => {
loginPage = new LoginPage(page);
await loginPage.goto();
});
test('successful login redirects to home', async ({ page }) => {
await loginPage.loginAndWaitForHome('testuser@example.com', 'secretPass123');
await expect(page.getByRole('heading', { name: 'Home' })).toBeVisible();
});
test('wrong password shows error', async () => {
await loginPage.login('testuser@example.com', 'wrong-password');
await loginPage.expectError('Invalid username or password');
});
test('empty fields show validation errors', async () => {
await loginPage.loginButton.click();
await loginPage.expectFieldError('username', 'Username is required');
});
test('forgot password link navigates correctly', async ({ page }) => {
await loginPage.forgotPasswordLink.click();
await page.waitForURL('/forgot-password');
await expect(page.getByRole('heading', { name: 'Reset password' })).toBeVisible();
});
});
```
### API-Based Login
**Use when**: You want the fastest possible authentication without any browser interaction.
**Avoid when**: You are specifically testing the login UI.
API login is typically 5-10x faster than UI login.
```typescript
// global-setup.ts — API-based login (fastest)
import { request, type FullConfig } from '@playwright/test';
async function globalSetup(config: FullConfig) {
const { baseURL } = config.projects[0].use;
const requestContext = await request.newContext({ baseURL });
const response = await requestContext.post('/api/auth/login', {
data: {
email: process.env.TEST_USER_EMAIL!,
password: process.env.TEST_USER_PASSWORD!
}
});
if (!response.ok()) {
throw new Error(`API login failed: ${response.status()} ${await response.text()}`);
}
await requestContext.storageState({ path: '.auth/session.json' });
await requestContext.dispose();
}
export default globalSetup;
```
```typescript
// fixtures/api-auth.ts — fixture version for per-test authentication
import { test as base } from '@playwright/test';
export const test = base.extend({
authenticatedPage: async ({ browser, playwright }, use) => {
const apiContext = await playwright.request.newContext({
baseURL: 'http://localhost:4000'
});
await apiContext.post('/api/auth/login', {
data: {
email: 'testuser@example.com',
password: 'secretPass123'
}
});
const state = await apiContext.storageState();
const context = await browser.newContext({ storageState: state });
const page = await context.newPage();
await use(page);
await context.close();
await apiContext.dispose();
}
});
export { expect } from '@playwright/test';
```
### Unauthenticated Tests
**Use when**: Testing the login page, signup flow, password reset, public pages, or redirect behavior for unauthenticated users.
**Avoid when**: The test requires a logged-in user.
When your config sets a default `storageState`, you must explicitly clear it for unauthenticated tests.
```typescript
// tests/public-pages.spec.ts
import { test, expect } from '@playwright/test';
test.use({ storageState: { cookies: [], origins: [] } });
test.describe('unauthenticated access', () => {
test('homepage is accessible without login', async ({ page }) => {
await page.goto('/');
await expect(page.getByRole('heading', { name: 'Welcome' })).toBeVisible();
await expect(page.getByRole('link', { name: 'Log in' })).toBeVisible();
});
test('protected route redirects to login', async ({ page }) => {
await page.goto('/home');
await page.waitForURL('**/login**');
expect(page.url()).toContain('redirect=%2Fhome');
});
test('expired session shows re-login prompt', async ({ page, context }) => {
await page.goto('/home');
await context.clearCookies();
await page.goto('/settings');
await page.waitForURL('**/login**');
await expect(page.getByText('Your session has expired')).toBeVisible();
});
test('signup flow creates account', async ({ page }) => {
await page.goto('/signup');
await page.getByLabel('Name').fill('New User');
await page.getByLabel('Email').fill(`test-${Date.now()}@example.com`);
await page.getByLabel('Password', { exact: true }).fill('secretPass123');
await page.getByLabel('Confirm password').fill('secretPass123');
await page.getByRole('button', { name: 'Create account' }).click();
await page.waitForURL('/onboarding');
await expect(page.getByText('Welcome, New User')).toBeVisible();
});
});
```
## Decision Guide
| Scenario | Approach | Speed | Isolation | When to Choose |
| -------------------------------- | ------------------------------ | -------- | -------------- | -------------------------------------------------------------- |
| Most tests need auth | Global setup + `storageState` | Fastest | Shared session | Default for nearly every project |
| Tests modify user state | Per-worker fixture | Fast | Per worker | Tests update profile, change settings, or mutate data |
| Multiple user roles | Per-project `storageState` | Fastest | Per role | App has admin/member/guest roles |
| Testing the login page | No `storageState` | N/A | Full | Use `test.use({ storageState: { cookies: [], origins: [] } })` |
| OAuth/SSO provider | Mock the callback | Fast | Per test | Never hit real OAuth providers in CI |
| MFA is required | TOTP generation or bypass | Moderate | Per test | Generate real TOTP codes or use a test-mode bypass |
| Token expires mid-suite | Session refresh fixture | Fast | Per check | Fixture validates the session before use |
| Single test needs different user | `loginAs(role)` fixture | Moderate | Per call | Rare: prefer per-project roles |
| API-first app (no login UI) | API login via `request.post()` | Fastest | Per test | No browser needed for auth |
### UI Login vs API Login vs Storage State
```text
Need to test the login page itself?
├── Yes → UI login with LoginPage POM, no storageState
└── No → Do you have a login API endpoint?
├── Yes → API login in global setup, save storageState (fastest)
└── No → UI login in global setup, save storageState
└── Tokens expire quickly?
├── Yes → Add session refresh fixture
└── No → Standard storageState reuse is fine
```
## Anti-Patterns
| Don't Do This | Problem | Do This Instead |
| ------------------------------------------------------------------------- | ------------------------------------------- | ------------------------------------------------------------------------- |
| Log in via UI before every test | Adds 2-5 seconds per test | Use `storageState` to skip login entirely |
| Share a single auth state file across parallel workers that mutate state | Race conditions | Use per-worker fixtures with `{ scope: 'worker' }` |
| Hardcode credentials in test files | Security risk | Use environment variables and `.env` files |
| Ignore token expiration | Tests fail intermittently with 401 errors | Add a session validity check in your auth fixture |
| Hit real OAuth providers in CI | Flaky: rate limits, CAPTCHA, network issues | Mock the OAuth callback or use API session injection |
| Use `page.waitForTimeout(2000)` after login | Arbitrary delay | `await page.waitForURL('/home')` or `await expect(heading).toBeVisible()` |
| Store `.auth/*.json` files in git | Tokens in version control | Add `.auth/` to `.gitignore` |
| Create one "god" test account with all permissions | Cannot test role-based access control | Create separate accounts per role |
| Use `browser.newContext()` without `storageState` for authenticated tests | Every context starts unauthenticated | Pass `storageState` when creating the context |
| Test MFA by disabling it everywhere | You never test the MFA flow | Use TOTP generation for at least one test |
## Troubleshooting
### Global setup fails with "Target page, context or browser has been closed"
**Cause**: The login page redirected unexpectedly, or the browser closed before `storageState()` was called.
**Fix**:
- Add `await page.waitForURL()` after the login action
- Check that `baseURL` in your config matches the actual server URL and protocol
- Add error handling to global setup:
```typescript
const response = await page.waitForResponse('**/api/auth/**');
if (!response.ok()) {
throw new Error(`Login failed in global setup: ${response.status()} ${await response.text()}`);
}
```
### Tests fail with 401 Unauthorized after running for a while
**Cause**: The session token saved in `storageState` has expired.
**Fix**:
- Use the session refresh fixture pattern
- Increase token expiry in test environment configuration
- Switch to API-based login in a worker-scoped fixture
### `storageState` file is empty or contains no cookies
**Cause**: `storageState()` was called before the login response set cookies.
**Fix**:
- Wait for the post-login page to load: `await page.waitForURL('/home')`
- Verify cookies exist before saving:
```typescript
const cookies = await context.cookies();
if (cookies.length === 0) {
throw new Error('No cookies found after login');
}
await context.storageState({ path: '.auth/session.json' });
```
### Different browsers get different cookies
**Cause**: Some auth flows set cookies with `SameSite=Strict` or use browser-specific cookie behavior.
**Fix**:
- Generate separate auth state files per browser project
- Check if your auth uses `SameSite=None; Secure` cookies that require HTTPS:
```typescript
projects: [
{
name: 'chromium',
use: { ...devices['Desktop Chrome'], storageState: '.auth/chromium-session.json' },
},
{
name: 'firefox',
use: { ...devices['Desktop Firefox'], storageState: '.auth/firefox-session.json' },
},
],
```
### Parallel tests interfere with each other's sessions
**Cause**: Multiple workers share the same test account and one worker's actions affect others.
**Fix**:
- Use per-worker test accounts: `worker-${test.info().parallelIndex}@example.com`
- Use the per-worker authentication fixture pattern
- Make tests idempotent
### OAuth mock does not work — still redirects to real provider
**Cause**: `page.route()` was registered after the navigation that triggers the OAuth redirect.
**Fix**:
- Register route handlers before any navigation: call `page.route()` before `page.goto()`
- Log the actual redirect URL to verify the pattern:
```typescript
page.on('request', (req) => {
if (req.url().includes('oauth') || req.url().includes('accounts.provider')) {
console.log('OAuth request:', req.url());
}
});
```
## Related
- [fixtures-hooks.md](../core/fixtures-hooks.md) — custom fixtures for auth setup and teardown
- [configuration.md](../core/configuration.md) — `storageState`, projects, and global setup configuration
- [global-setup.md](../core/global-setup.md) — global setup patterns and project dependencies
- [network-advanced.md](network-advanced.md) — route interception patterns used in OAuth mocking
- [api-testing.md](../testing-patterns/api-testing.md) — API request context used in API-based login
- [flaky-tests.md](../debugging/flaky-tests.md) — diagnosing auth-related flakiness
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit. | Stars: 471k | Updated | Claude CodeCodex | Verified | Install |
| rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure. | Stars: 471k | Updated | Claude CodeCodex | Verified | Install |
| rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics. | Stars: 471k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |