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-flows.md

View on GitHub
# Complex Authentication Flow Patterns

## Table of Contents

1. [Email Verification Flows](#email-verification-flows)
2. [Password Reset](#password-reset)
3. [Session Timeout](#session-timeout)
4. [Remember Me Persistence](#remember-me-persistence)
5. [Logout Patterns](#logout-patterns)
6. [Tips](#tips)
7. [Related](#related)

> **When to use**: Testing email verification, password reset, session timeout/expiration, or remember-me functionality. For basic auth setup (storage state, OAuth mocking, MFA, role-based access), see [authentication.md](authentication.md).

---

## Email Verification Flows

### Capturing Verification Tokens

Intercept API responses to capture verification tokens for testing:

```typescript
test('completes registration with email verification', async ({ page }) => {
	let capturedToken = '';

	await page.route('**/api/auth/register', async (route) => {
		const response = await route.fetch();
		const body = await response.json();
		capturedToken = body.verificationToken;
		await route.fulfill({ response });
	});

	await page.goto('/register');
	await page.getByLabel('Name').fill('New User');
	await page.getByLabel('Email').fill('newuser@test.com');
	await page.getByLabel('Password', { exact: true }).fill('SecurePass!');
	await page.getByLabel('Confirm password').fill('SecurePass!');
	await page.getByRole('button', { name: 'Create account' }).click();

	await expect(page.getByText('Check your inbox')).toBeVisible();

	expect(capturedToken).toBeTruthy();
	await page.goto(`/verify?token=${capturedToken}`);

	await expect(page.getByText('Email confirmed')).toBeVisible();
});
```

### Fully Mocked Verification

```typescript
test('verifies email with mocked endpoints', async ({ page }) => {
	const mockToken = 'test-verification-abc123';

	await page.route('**/api/auth/register', async (route) => {
		await route.fulfill({
			status: 200,
			contentType: 'application/json',
			body: JSON.stringify({ message: 'Verification sent', verificationToken: mockToken })
		});
	});

	await page.route(`**/api/auth/verify?token=${mockToken}`, async (route) => {
		await route.fulfill({
			status: 200,
			contentType: 'application/json',
			body: JSON.stringify({ verified: true })
		});
	});

	await page.goto('/register');
	await page.getByLabel('Email').fill('test@example.com');
	await page.getByLabel('Password', { exact: true }).fill('Password123!');
	await page.getByRole('button', { name: 'Sign up' }).click();

	await expect(page.getByText('Check your inbox')).toBeVisible();

	await page.goto(`/verify?token=${mockToken}`);
	await expect(page.getByText('Email confirmed')).toBeVisible();
});
```

---

## Password Reset

### Complete Reset Flow

```typescript
test('resets password through email link', async ({ page }) => {
	let resetToken = '';

	await page.route('**/api/auth/forgot-password', async (route) => {
		const response = await route.fetch();
		const body = await response.json();
		resetToken = body.resetToken;
		await route.fulfill({ response });
	});

	await page.goto('/forgot-password');
	await page.getByLabel('Email').fill('user@test.com');
	await page.getByRole('button', { name: 'Send link' }).click();

	await expect(page.getByText('Reset email sent')).toBeVisible();

	expect(resetToken).toBeTruthy();
	await page.goto(`/reset-password?token=${resetToken}`);

	await page.getByLabel('New password', { exact: true }).fill('NewPassword456!');
	await page.getByLabel('Confirm password').fill('NewPassword456!');
	await page.getByRole('button', { name: 'Update password' }).click();

	await expect(page.getByText('Password updated')).toBeVisible();
});
```

### Expired Token Handling

```typescript
test('shows error for expired reset token', async ({ page }) => {
	await page.goto('/reset-password?token=expired-token');

	await page.getByLabel('New password', { exact: true }).fill('NewPass!');
	await page.getByLabel('Confirm password').fill('NewPass!');
	await page.getByRole('button', { name: 'Update password' }).click();

	await expect(page.getByRole('alert')).toContainText(/expired|invalid/i);
});
```

### Password Strength Validation

```typescript
test('enforces password requirements on reset', async ({ page }) => {
	await page.goto('/reset-password?token=valid-token');

	await page.getByLabel('New password', { exact: true }).fill('weak');
	await page.getByLabel('Confirm password').fill('weak');
	await page.getByRole('button', { name: 'Update password' }).click();

	await expect(page.getByText(/at least 8 characters/i)).toBeVisible();
});
```

---

## Session Timeout

### Detecting Expired Sessions

```typescript
test('redirects to signin after session expires', async ({ page, context }) => {
	await page.goto('/signin');
	await page.getByLabel('Email').fill('user@test.com');
	await page.getByLabel('Password').fill('Password!');
	await page.getByRole('button', { name: 'Sign in' }).click();
	await expect(page).toHaveURL('/home');

	const cookies = await context.cookies();
	const sessionCookie = cookies.find((c) => c.name.includes('session'));

	if (sessionCookie) {
		await context.clearCookies({ name: sessionCookie.name });
	}

	await page.goto('/profile');
	await expect(page).toHaveURL(/\/signin/);
	await expect(page.getByText(/session.*expired|sign in again/i)).toBeVisible();
});
```

### Session Extension Warning

```typescript
test('shows warning before session expires', async ({ page }) => {
	await page.route('**/api/auth/session', async (route) => {
		await route.fulfill({
			status: 200,
			contentType: 'application/json',
			body: JSON.stringify({ valid: true, expiresIn: 60 })
		});
	});

	await page.goto('/home');

	await expect(page.getByText(/session.*expir/i)).toBeVisible({ timeout: 10000 });
	await expect(page.getByRole('button', { name: /extend|stay signed in/i })).toBeVisible();
});
```

### Session Extension Action

```typescript
test('extends session when user clicks extend', async ({ page }) => {
	let sessionExtended = false;

	await page.route('**/api/auth/session', async (route) => {
		await route.fulfill({
			status: 200,
			contentType: 'application/json',
			body: JSON.stringify({ valid: true, expiresIn: 60 })
		});
	});

	await page.route('**/api/auth/refresh', async (route) => {
		sessionExtended = true;
		await route.fulfill({
			status: 200,
			contentType: 'application/json',
			body: JSON.stringify({ valid: true, expiresIn: 3600 })
		});
	});

	await page.goto('/home');

	await expect(page.getByRole('button', { name: /extend|stay signed in/i })).toBeVisible({
		timeout: 10000
	});
	await page.getByRole('button', { name: /extend|stay signed in/i }).click();

	expect(sessionExtended).toBe(true);
	await expect(page.getByText(/session.*expir/i)).not.toBeVisible();
});
```

---

## Remember Me Persistence

### Persistent Session

```typescript
test('persists session with remember me enabled', async ({ browser }) => {
	const ctx1 = await browser.newContext();
	const page1 = await ctx1.newPage();

	await page1.goto('/signin');
	await page1.getByLabel('Email').fill('user@test.com');
	await page1.getByLabel('Password').fill('Password!');
	await page1.getByLabel('Keep me signed in').check();
	await page1.getByRole('button', { name: 'Sign in' }).click();

	await expect(page1).toHaveURL('/home');

	const state = await ctx1.storageState();
	await ctx1.close();

	const ctx2 = await browser.newContext({ storageState: state });
	const page2 = await ctx2.newPage();

	await page2.goto('/home');
	await expect(page2).toHaveURL('/home');
	await expect(page2.getByText('Welcome')).toBeVisible();

	await ctx2.close();
});
```

### Session-Only Login

```typescript
test('session-only login does not persist across browser restarts', async ({ browser }) => {
	const ctx1 = await browser.newContext();
	const page1 = await ctx1.newPage();

	await page1.goto('/signin');
	await page1.getByLabel('Email').fill('user@test.com');
	await page1.getByLabel('Password').fill('Password!');
	// Leave "Remember me" unchecked
	await expect(page1.getByLabel('Keep me signed in')).not.toBeChecked();
	await page1.getByRole('button', { name: 'Sign in' }).click();

	await expect(page1).toHaveURL('/home');

	// Only keep persistent cookies (filter out session cookies)
	const cookies = await ctx1.cookies();
	await ctx1.close();

	const persistentCookies = cookies.filter((c) => c.expires > 0);
	const ctx2 = await browser.newContext();
	await ctx2.addCookies(persistentCookies);
	const page2 = await ctx2.newPage();

	await page2.goto('/home');

	// Should redirect to login since session was not persisted
	await expect(page2).toHaveURL(/\/signin/);

	await ctx2.close();
});
```

---

## Logout Patterns

### Standard Logout with Session Cleanup

```typescript
test.use({ storageState: '.auth/user.json' });

test('logs out and clears session', async ({ page, context }) => {
	await page.goto('/home');

	await page.getByRole('button', { name: /account|menu/i }).click();
	await page.getByRole('menuitem', { name: 'Sign out' }).click();

	await expect(page).toHaveURL('/signin');

	const cookies = await context.cookies();
	const sessionCookies = cookies.filter((c) => c.name.includes('session') || c.name.includes('token'));
	expect(sessionCookies).toHaveLength(0);

	await page.goto('/home');
	await expect(page).toHaveURL(/\/signin/);
});
```

### Logout from All Devices

```typescript
test('logs out from all devices', async ({ page }) => {
	let logoutAllCalled = false;

	await page.route('**/api/auth/logout-all', async (route) => {
		logoutAllCalled = true;
		await route.fulfill({
			status: 200,
			contentType: 'application/json',
			body: JSON.stringify({ message: 'Logged out everywhere' })
		});
	});

	await page.goto('/settings/security');

	await page.getByRole('button', { name: 'Sign out everywhere' }).click();
	await page.getByRole('dialog').getByRole('button', { name: 'Confirm' }).click();

	expect(logoutAllCalled).toBe(true);
	await expect(page).toHaveURL(/\/signin/);
});
```

---

## Tips

1. **Configure shorter session timeouts in test environments** — Enables testing timeout behavior without slow tests
2. **Test token expiration edge cases** — Expired tokens, invalid tokens, already-used tokens
3. **Verify cleanup on logout** — Check both cookies and localStorage are cleared
4. **Test the full flow end-to-end** — Password reset should verify login with new password works

---

## Related

- [authentication.md](authentication.md) — Storage state, OAuth mocking, MFA, role-based access, API login
- [fixtures-hooks.md](../core/fixtures-hooks.md) — Creating auth fixtures
- [third-party.md](./third-party.md) — Mocking external auth providers
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