Skip to content

ever-co/ever-works / .agents/skills/playwright-best-practices

playwright-best-practices

Verified

Use 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.

FileKindSize
LICENSE.mdmarkdown1.0 KB
README.mdmarkdown9.9 KB
SKILL.mdskill md25.7 KB
advanced/authentication-flows.mdmarkdown10.4 KB
advanced/authentication.mdmarkdown29.4 KB
advanced/clock-mocking.mdmarkdown9.4 KB
advanced/mobile-testing.mdmarkdown10.3 KB
advanced/multi-context.mdmarkdown8.2 KB
advanced/multi-user.mdmarkdown10.9 KB
advanced/network-advanced.mdmarkdown10.1 KB
advanced/third-party.mdmarkdown11.1 KB
architecture/pom-vs-fixtures.mdmarkdown11.4 KB
architecture/test-architecture.mdmarkdown14.3 KB
architecture/when-to-mock.mdmarkdown11.9 KB
browser-apis/browser-apis.mdmarkdown10.1 KB
browser-apis/iframes.mdmarkdown11.1 KB
browser-apis/service-workers.mdmarkdown13.1 KB
browser-apis/websockets.mdmarkdown9.9 KB
core/annotations.mdmarkdown10.4 KB
core/assertions-waiting.mdmarkdown9.1 KB
core/configuration.mdmarkdown13.7 KB
core/fixtures-hooks.mdmarkdown11.2 KB
core/global-setup.mdmarkdown12.4 KB
core/locators.mdmarkdown6.4 KB
core/page-object-model.mdmarkdown7.7 KB
core/projects-dependencies.mdmarkdown8.1 KB
core/test-data.mdmarkdown11.3 KB
core/test-suite-structure.mdmarkdown9.1 KB
core/test-tags.mdmarkdown6.7 KB
debugging/console-errors.mdmarkdown9.3 KB
debugging/debugging.mdmarkdown14.7 KB
debugging/error-testing.mdmarkdown9.2 KB
debugging/flaky-tests.mdmarkdown14.5 KB
frameworks/angular.mdmarkdown18.9 KB
frameworks/nextjs.mdmarkdown13.4 KB
frameworks/react.mdmarkdown17.5 KB
frameworks/vue.mdmarkdown17.3 KB
infrastructure-ci-cd/ci-cd.mdmarkdown10.4 KB
infrastructure-ci-cd/docker.mdmarkdown7.0 KB
infrastructure-ci-cd/github-actions.mdmarkdown15.1 KB
infrastructure-ci-cd/gitlab.mdmarkdown10.9 KB
infrastructure-ci-cd/other-providers.mdmarkdown14.2 KB
infrastructure-ci-cd/parallel-sharding.mdmarkdown11.6 KB
infrastructure-ci-cd/performance.mdmarkdown11.3 KB
infrastructure-ci-cd/reporting.mdmarkdown11.4 KB
infrastructure-ci-cd/test-coverage.mdmarkdown12.0 KB
testing-patterns/accessibility.mdmarkdown8.7 KB
testing-patterns/api-testing.mdmarkdown23.5 KB
testing-patterns/browser-extensions.mdmarkdown13.0 KB
testing-patterns/canvas-webgl.mdmarkdown12.3 KB
testing-patterns/component-testing.mdmarkdown11.0 KB
testing-patterns/drag-drop.mdmarkdown17.4 KB
testing-patterns/electron.mdmarkdown12.8 KB
testing-patterns/file-operations.mdmarkdown10.0 KB
testing-patterns/file-upload-download.mdmarkdown16.5 KB
testing-patterns/forms-validation.mdmarkdown21.3 KB
testing-patterns/graphql-testing.mdmarkdown8.6 KB
testing-patterns/i18n.mdmarkdown12.3 KB
testing-patterns/performance-testing.mdmarkdown11.5 KB
testing-patterns/security-testing.mdmarkdown11.5 KB
testing-patterns/visual-regression.mdmarkdown18.4 KB

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
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: 471kUpdated Claude CodeCodexVerifiedInstall
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: 471kUpdated Claude CodeCodexVerifiedInstall
rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first.Stars: 194kUpdated Claude CodeCodexVerifiedInstall