@assertrx/dino 1.0.0

package/skills/playwright-core/auth-flows.md

@@ -0,0 +1,1081 @@
+# Authentication Flow Recipes
+
+> **When to use**: You need to test login, signup, logout, session management, or any authentication-related user flow.
+
+---
+
+## Recipe 1: Basic Login
+
+### Complete Example
+
+**TypeScript**
+
+```typescript
+import { test, expect } from '@playwright/test';
+
+test('logs in with valid credentials', async ({ page }) => {
+  await page.goto('/login');
+
+  await page.getByLabel('Email').fill('user@example.com');
+  await page.getByLabel('Password').fill('SecurePass123!');
+  await page.getByRole('button', { name: 'Sign in' }).click();
+
+  // Wait for navigation to complete after login
+  await expect(page).toHaveURL('/dashboard');
+  await expect(page.getByRole('heading', { name: 'Dashboard' })).toBeVisible();
+  await expect(page.getByText('Welcome, user@example.com')).toBeVisible();
+});
+
+test('shows error for invalid credentials', async ({ page }) => {
+  await page.goto('/login');
+
+  await page.getByLabel('Email').fill('user@example.com');
+  await page.getByLabel('Password').fill('WrongPassword');
+  await page.getByRole('button', { name: 'Sign in' }).click();
+
+  await expect(page.getByRole('alert')).toContainText('Invalid email or password');
+  // Should remain on login page
+  await expect(page).toHaveURL('/login');
+});
+
+test('shows validation errors for empty fields', async ({ page }) => {
+  await page.goto('/login');
+
+  await page.getByRole('button', { name: 'Sign in' }).click();
+
+  await expect(page.getByText('Email is required')).toBeVisible();
+  await expect(page.getByText('Password is required')).toBeVisible();
+});
+```
+
+**JavaScript**
+
+```javascript
+const { test, expect } = require('@playwright/test');
+
+test('logs in with valid credentials', async ({ page }) => {
+  await page.goto('/login');
+
+  await page.getByLabel('Email').fill('user@example.com');
+  await page.getByLabel('Password').fill('SecurePass123!');
+  await page.getByRole('button', { name: 'Sign in' }).click();
+
+  await expect(page).toHaveURL('/dashboard');
+  await expect(page.getByRole('heading', { name: 'Dashboard' })).toBeVisible();
+  await expect(page.getByText('Welcome, user@example.com')).toBeVisible();
+});
+
+test('shows error for invalid credentials', async ({ page }) => {
+  await page.goto('/login');
+
+  await page.getByLabel('Email').fill('user@example.com');
+  await page.getByLabel('Password').fill('WrongPassword');
+  await page.getByRole('button', { name: 'Sign in' }).click();
+
+  await expect(page.getByRole('alert')).toContainText('Invalid email or password');
+  await expect(page).toHaveURL('/login');
+});
+
+test('shows validation errors for empty fields', async ({ page }) => {
+  await page.goto('/login');
+
+  await page.getByRole('button', { name: 'Sign in' }).click();
+
+  await expect(page.getByText('Email is required')).toBeVisible();
+  await expect(page.getByText('Password is required')).toBeVisible();
+});
+```
+
+---
+
+## Recipe 2: Login with "Remember Me"
+
+### Complete Example
+
+**TypeScript**
+
+```typescript
+import { test, expect, type BrowserContext } from '@playwright/test';
+
+test('remember me persists session across browser restarts', async ({ browser }) => {
+  // First session: log in with "remember me" checked
+  const context1 = await browser.newContext();
+  const page1 = await context1.newPage();
+
+  await page1.goto('/login');
+  await page1.getByLabel('Email').fill('user@example.com');
+  await page1.getByLabel('Password').fill('SecurePass123!');
+  await page1.getByLabel('Remember me').check();
+  await page1.getByRole('button', { name: 'Sign in' }).click();
+
+  await expect(page1).toHaveURL('/dashboard');
+
+  // Save storage state (cookies + localStorage)
+  const storageState = await context1.storageState();
+  await context1.close();
+
+  // Second session: restore state to simulate browser restart
+  const context2 = await browser.newContext({ storageState });
+  const page2 = await context2.newPage();
+
+  await page2.goto('/dashboard');
+
+  // Should still be logged in without re-authenticating
+  await expect(page2).toHaveURL('/dashboard');
+  await expect(page2.getByText('Welcome, user@example.com')).toBeVisible();
+
+  await context2.close();
+});
+
+test('no remember me does not persist session', async ({ browser }) => {
+  const context1 = await browser.newContext();
+  const page1 = await context1.newPage();
+
+  await page1.goto('/login');
+  await page1.getByLabel('Email').fill('user@example.com');
+  await page1.getByLabel('Password').fill('SecurePass123!');
+  // Explicitly leave "Remember me" unchecked
+  await expect(page1.getByLabel('Remember me')).not.toBeChecked();
+  await page1.getByRole('button', { name: 'Sign in' }).click();
+
+  await expect(page1).toHaveURL('/dashboard');
+
+  // Capture only cookies (not sessionStorage) to simulate new tab/window
+  const cookies = await context1.cookies();
+  await context1.close();
+
+  // New context with only persistent cookies (session cookies are excluded)
+  const persistentCookies = cookies.filter(c => c.expires > 0);
+  const context2 = await browser.newContext();
+  await context2.addCookies(persistentCookies);
+  const page2 = await context2.newPage();
+
+  await page2.goto('/dashboard');
+
+  // Should redirect to login since session was not persisted
+  await expect(page2).toHaveURL(/\/login/);
+
+  await context2.close();
+});
+```
+
+**JavaScript**
+
+```javascript
+const { test, expect } = require('@playwright/test');
+
+test('remember me persists session across browser restarts', async ({ browser }) => {
+  const context1 = await browser.newContext();
+  const page1 = await context1.newPage();
+
+  await page1.goto('/login');
+  await page1.getByLabel('Email').fill('user@example.com');
+  await page1.getByLabel('Password').fill('SecurePass123!');
+  await page1.getByLabel('Remember me').check();
+  await page1.getByRole('button', { name: 'Sign in' }).click();
+
+  await expect(page1).toHaveURL('/dashboard');
+
+  const storageState = await context1.storageState();
+  await context1.close();
+
+  const context2 = await browser.newContext({ storageState });
+  const page2 = await context2.newPage();
+
+  await page2.goto('/dashboard');
+
+  await expect(page2).toHaveURL('/dashboard');
+  await expect(page2.getByText('Welcome, user@example.com')).toBeVisible();
+
+  await context2.close();
+});
+```
+
+---
+
+## Recipe 3: Signup with Email Verification (Mocked)
+
+### Complete Example
+
+**TypeScript**
+
+```typescript
+import { test, expect } from '@playwright/test';
+
+test('completes signup flow with mocked email verification', async ({ page }) => {
+  // Intercept the verification email API so we can capture the token
+  let verificationToken = '';
+  await page.route('**/api/auth/send-verification', async (route) => {
+    // Let the request go through to the server
+    const response = await route.fetch();
+    const body = await response.json();
+
+    // Capture the token from the API response (test environments expose this)
+    verificationToken = body.verificationToken;
+
+    await route.fulfill({ response });
+  });
+
+  // Step 1: Fill out signup form
+  await page.goto('/signup');
+
+  await page.getByLabel('Full name').fill('Jane Tester');
+  await page.getByLabel('Email').fill('jane@example.com');
+  await page.getByLabel('Password', { exact: true }).fill('SecurePass123!');
+  await page.getByLabel('Confirm password').fill('SecurePass123!');
+  await page.getByLabel('I agree to the Terms of Service').check();
+  await page.getByRole('button', { name: 'Create account' }).click();
+
+  // Step 2: Verify "check your email" screen appears
+  await expect(page.getByText('Check your email')).toBeVisible();
+  await expect(page.getByText('jane@example.com')).toBeVisible();
+
+  // Step 3: Navigate directly to verification URL using captured token
+  expect(verificationToken).toBeTruthy();
+  await page.goto(`/verify-email?token=${verificationToken}`);
+
+  // Step 4: Verify account is now active
+  await expect(page.getByText('Email verified successfully')).toBeVisible();
+  await expect(page).toHaveURL('/login');
+
+  // Step 5: Log in with the new account
+  await page.getByLabel('Email').fill('jane@example.com');
+  await page.getByLabel('Password').fill('SecurePass123!');
+  await page.getByRole('button', { name: 'Sign in' }).click();
+
+  await expect(page).toHaveURL('/dashboard');
+  await expect(page.getByText('Welcome, Jane Tester')).toBeVisible();
+});
+
+test('signup with fully mocked email API (no server dependency)', async ({ page }) => {
+  const fakeToken = 'test-verification-token-12345';
+
+  // Mock the signup API endpoint
+  await page.route('**/api/auth/signup', async (route) => {
+    await route.fulfill({
+      status: 200,
+      contentType: 'application/json',
+      body: JSON.stringify({
+        message: 'Verification email sent',
+        verificationToken: fakeToken,
+      }),
+    });
+  });
+
+  // Mock the verification endpoint
+  await page.route(`**/api/auth/verify-email?token=${fakeToken}`, async (route) => {
+    await route.fulfill({
+      status: 200,
+      contentType: 'application/json',
+      body: JSON.stringify({ message: 'Email verified', redirectTo: '/login' }),
+    });
+  });
+
+  await page.goto('/signup');
+
+  await page.getByLabel('Full name').fill('Jane Tester');
+  await page.getByLabel('Email').fill('jane@example.com');
+  await page.getByLabel('Password', { exact: true }).fill('SecurePass123!');
+  await page.getByLabel('Confirm password').fill('SecurePass123!');
+  await page.getByLabel('I agree to the Terms of Service').check();
+  await page.getByRole('button', { name: 'Create account' }).click();
+
+  await expect(page.getByText('Check your email')).toBeVisible();
+
+  // Simulate clicking the verification link from the email
+  await page.goto(`/verify-email?token=${fakeToken}`);
+
+  await expect(page.getByText('Email verified successfully')).toBeVisible();
+});
+```
+
+**JavaScript**
+
+```javascript
+const { test, expect } = require('@playwright/test');
+
+test('completes signup flow with mocked email verification', async ({ page }) => {
+  let verificationToken = '';
+  await page.route('**/api/auth/send-verification', async (route) => {
+    const response = await route.fetch();
+    const body = await response.json();
+    verificationToken = body.verificationToken;
+    await route.fulfill({ response });
+  });
+
+  await page.goto('/signup');
+
+  await page.getByLabel('Full name').fill('Jane Tester');
+  await page.getByLabel('Email').fill('jane@example.com');
+  await page.getByLabel('Password', { exact: true }).fill('SecurePass123!');
+  await page.getByLabel('Confirm password').fill('SecurePass123!');
+  await page.getByLabel('I agree to the Terms of Service').check();
+  await page.getByRole('button', { name: 'Create account' }).click();
+
+  await expect(page.getByText('Check your email')).toBeVisible();
+
+  expect(verificationToken).toBeTruthy();
+  await page.goto(`/verify-email?token=${verificationToken}`);
+
+  await expect(page.getByText('Email verified successfully')).toBeVisible();
+  await expect(page).toHaveURL('/login');
+});
+```
+
+---
+
+## Recipe 4: Password Reset Flow
+
+### Complete Example
+
+**TypeScript**
+
+```typescript
+import { test, expect } from '@playwright/test';
+
+test('completes password reset flow', async ({ page }) => {
+  let resetToken = '';
+
+  // Intercept the password reset API to capture the reset token
+  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 });
+  });
+
+  // Step 1: Request password reset
+  await page.goto('/forgot-password');
+
+  await page.getByLabel('Email').fill('user@example.com');
+  await page.getByRole('button', { name: 'Send reset link' }).click();
+
+  await expect(page.getByText('Reset link sent')).toBeVisible();
+  await expect(page.getByText('user@example.com')).toBeVisible();
+
+  // Step 2: Navigate to the reset page with token
+  expect(resetToken).toBeTruthy();
+  await page.goto(`/reset-password?token=${resetToken}`);
+
+  // Step 3: Set new password
+  await page.getByLabel('New password', { exact: true }).fill('NewSecurePass456!');
+  await page.getByLabel('Confirm new password').fill('NewSecurePass456!');
+  await page.getByRole('button', { name: 'Reset password' }).click();
+
+  await expect(page.getByText('Password reset successfully')).toBeVisible();
+
+  // Step 4: Log in with new password
+  await page.goto('/login');
+  await page.getByLabel('Email').fill('user@example.com');
+  await page.getByLabel('Password').fill('NewSecurePass456!');
+  await page.getByRole('button', { name: 'Sign in' }).click();
+
+  await expect(page).toHaveURL('/dashboard');
+});
+
+test('password reset with expired token shows error', async ({ page }) => {
+  await page.goto('/reset-password?token=expired-token-123');
+
+  await page.getByLabel('New password', { exact: true }).fill('NewSecurePass456!');
+  await page.getByLabel('Confirm new password').fill('NewSecurePass456!');
+  await page.getByRole('button', { name: 'Reset password' }).click();
+
+  await expect(page.getByRole('alert')).toContainText(
+    /token has expired|link is no longer valid/i
+  );
+  await expect(page.getByRole('link', { name: 'Request a new reset link' })).toBeVisible();
+});
+
+test('password reset enforces password strength requirements', async ({ page }) => {
+  await page.goto('/reset-password?token=valid-token');
+
+  // Try a weak password
+  await page.getByLabel('New password', { exact: true }).fill('123');
+  await page.getByLabel('Confirm new password').fill('123');
+  await page.getByRole('button', { name: 'Reset password' }).click();
+
+  await expect(page.getByText(/at least 8 characters/i)).toBeVisible();
+});
+```
+
+**JavaScript**
+
+```javascript
+const { test, expect } = require('@playwright/test');
+
+test('completes password reset flow', 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@example.com');
+  await page.getByRole('button', { name: 'Send reset link' }).click();
+
+  await expect(page.getByText('Reset link sent')).toBeVisible();
+
+  expect(resetToken).toBeTruthy();
+  await page.goto(`/reset-password?token=${resetToken}`);
+
+  await page.getByLabel('New password', { exact: true }).fill('NewSecurePass456!');
+  await page.getByLabel('Confirm new password').fill('NewSecurePass456!');
+  await page.getByRole('button', { name: 'Reset password' }).click();
+
+  await expect(page.getByText('Password reset successfully')).toBeVisible();
+
+  await page.goto('/login');
+  await page.getByLabel('Email').fill('user@example.com');
+  await page.getByLabel('Password').fill('NewSecurePass456!');
+  await page.getByRole('button', { name: 'Sign in' }).click();
+
+  await expect(page).toHaveURL('/dashboard');
+});
+```
+
+---
+
+## Recipe 5: OAuth Login (Mocked Callback)
+
+### Complete Example
+
+**TypeScript**
+
+```typescript
+import { test, expect } from '@playwright/test';
+
+test('logs in via mocked Google OAuth callback', async ({ page }) => {
+  // Intercept the OAuth redirect to Google and simulate the callback
+  await page.route('**/accounts.google.com/**', async (route) => {
+    // Instead of actually going to Google, redirect back to our callback URL
+    // with a mock authorization code
+    const callbackUrl = new URL('/auth/callback/google', 'http://localhost:3000');
+    callbackUrl.searchParams.set('code', 'mock-auth-code-12345');
+    callbackUrl.searchParams.set('state', route.request().url().match(/state=([^&]+)/)?.[1] || '');
+
+    await route.fulfill({
+      status: 302,
+      headers: { location: callbackUrl.toString() },
+    });
+  });
+
+  // Mock the token exchange on our backend
+  await page.route('**/api/auth/callback/google**', async (route) => {
+    await route.fulfill({
+      status: 200,
+      contentType: 'application/json',
+      body: JSON.stringify({
+        user: {
+          id: '1',
+          email: 'googleuser@gmail.com',
+          name: 'Google User',
+          avatar: 'https://example.com/avatar.jpg',
+        },
+        token: 'mock-jwt-token',
+      }),
+    });
+  });
+
+  await page.goto('/login');
+
+  // Click the OAuth button
+  await page.getByRole('button', { name: /Sign in with Google/i }).click();
+
+  // After the mocked OAuth flow, we should land on the dashboard
+  await expect(page).toHaveURL('/dashboard');
+  await expect(page.getByText('Google User')).toBeVisible();
+});
+
+test('handles OAuth login failure gracefully', async ({ page }) => {
+  // Simulate OAuth provider returning an error
+  await page.route('**/accounts.google.com/**', async (route) => {
+    const callbackUrl = new URL('/auth/callback/google', 'http://localhost:3000');
+    callbackUrl.searchParams.set('error', 'access_denied');
+    callbackUrl.searchParams.set('error_description', 'User denied access');
+
+    await route.fulfill({
+      status: 302,
+      headers: { location: callbackUrl.toString() },
+    });
+  });
+
+  await page.goto('/login');
+  await page.getByRole('button', { name: /Sign in with Google/i }).click();
+
+  await expect(page.getByRole('alert')).toContainText(/authentication failed|access denied/i);
+  await expect(page).toHaveURL(/\/login/);
+});
+```
+
+**JavaScript**
+
+```javascript
+const { test, expect } = require('@playwright/test');
+
+test('logs in via mocked Google OAuth callback', async ({ page }) => {
+  await page.route('**/accounts.google.com/**', async (route) => {
+    const callbackUrl = new URL('/auth/callback/google', 'http://localhost:3000');
+    callbackUrl.searchParams.set('code', 'mock-auth-code-12345');
+    callbackUrl.searchParams.set('state', route.request().url().match(/state=([^&]+)/)?.[1] || '');
+
+    await route.fulfill({
+      status: 302,
+      headers: { location: callbackUrl.toString() },
+    });
+  });
+
+  await page.route('**/api/auth/callback/google**', async (route) => {
+    await route.fulfill({
+      status: 200,
+      contentType: 'application/json',
+      body: JSON.stringify({
+        user: { id: '1', email: 'googleuser@gmail.com', name: 'Google User' },
+        token: 'mock-jwt-token',
+      }),
+    });
+  });
+
+  await page.goto('/login');
+  await page.getByRole('button', { name: /Sign in with Google/i }).click();
+
+  await expect(page).toHaveURL('/dashboard');
+  await expect(page.getByText('Google User')).toBeVisible();
+});
+```
+
+---
+
+## Recipe 6: Role-Based Access Testing
+
+### Complete Example
+
+**TypeScript**
+
+```typescript
+import { test, expect, type Page } from '@playwright/test';
+import path from 'path';
+
+// Store auth state for each role in separate files
+const authDir = path.resolve(__dirname, '../.auth');
+
+// Setup: create auth state files for each role (run in globalSetup or auth.setup)
+// This pattern uses Playwright's storage state for efficient role switching
+const roles = ['admin', 'editor', 'viewer'] as const;
+type Role = typeof roles[number];
+
+function authFile(role: Role): string {
+  return path.join(authDir, `${role}.json`);
+}
+
+// Auth setup project — runs before all tests
+test.describe('auth setup', () => {
+  const credentials: Record<Role, { email: string; password: string }> = {
+    admin: { email: 'admin@example.com', password: 'AdminPass123!' },
+    editor: { email: 'editor@example.com', password: 'EditorPass123!' },
+    viewer: { email: 'viewer@example.com', password: 'ViewerPass123!' },
+  };
+
+  for (const role of roles) {
+    test(`authenticate as ${role}`, async ({ page }) => {
+      await page.goto('/login');
+      await page.getByLabel('Email').fill(credentials[role].email);
+      await page.getByLabel('Password').fill(credentials[role].password);
+      await page.getByRole('button', { name: 'Sign in' }).click();
+      await expect(page).toHaveURL('/dashboard');
+
+      await page.context().storageState({ path: authFile(role) });
+    });
+  }
+});
+
+// Admin tests
+test.describe('admin access', () => {
+  test.use({ storageState: authFile('admin') });
+
+  test('admin can access user management', async ({ page }) => {
+    await page.goto('/admin/users');
+    await expect(page).toHaveURL('/admin/users');
+    await expect(page.getByRole('heading', { name: 'User Management' })).toBeVisible();
+    await expect(page.getByRole('button', { name: 'Add user' })).toBeVisible();
+    await expect(page.getByRole('button', { name: 'Delete' }).first()).toBeVisible();
+  });
+
+  test('admin can access system settings', async ({ page }) => {
+    await page.goto('/admin/settings');
+    await expect(page).toHaveURL('/admin/settings');
+    await expect(page.getByRole('heading', { name: 'System Settings' })).toBeVisible();
+  });
+});
+
+// Editor tests
+test.describe('editor access', () => {
+  test.use({ storageState: authFile('editor') });
+
+  test('editor can create and edit content', async ({ page }) => {
+    await page.goto('/content');
+    await expect(page.getByRole('button', { name: 'New post' })).toBeVisible();
+    await expect(page.getByRole('button', { name: 'Edit' }).first()).toBeVisible();
+  });
+
+  test('editor cannot access admin area', async ({ page }) => {
+    await page.goto('/admin/users');
+    // Should be redirected or shown forbidden
+    await expect(page).toHaveURL(/\/(403|dashboard|login)/);
+  });
+});
+
+// Viewer tests
+test.describe('viewer access', () => {
+  test.use({ storageState: authFile('viewer') });
+
+  test('viewer can read content', async ({ page }) => {
+    await page.goto('/content');
+    await expect(page.getByRole('article').first()).toBeVisible();
+  });
+
+  test('viewer cannot create content', async ({ page }) => {
+    await page.goto('/content');
+    await expect(page.getByRole('button', { name: 'New post' })).not.toBeVisible();
+  });
+
+  test('viewer cannot access admin area', async ({ page }) => {
+    await page.goto('/admin/users');
+    await expect(page).toHaveURL(/\/(403|dashboard|login)/);
+  });
+});
+```
+
+**JavaScript**
+
+```javascript
+const { test, expect } = require('@playwright/test');
+const path = require('path');
+
+const authDir = path.resolve(__dirname, '../.auth');
+
+function authFile(role) {
+  return path.join(authDir, `${role}.json`);
+}
+
+// Admin tests
+test.describe('admin access', () => {
+  test.use({ storageState: authFile('admin') });
+
+  test('admin can access user management', async ({ page }) => {
+    await page.goto('/admin/users');
+    await expect(page).toHaveURL('/admin/users');
+    await expect(page.getByRole('heading', { name: 'User Management' })).toBeVisible();
+    await expect(page.getByRole('button', { name: 'Add user' })).toBeVisible();
+  });
+
+  test('admin can access system settings', async ({ page }) => {
+    await page.goto('/admin/settings');
+    await expect(page).toHaveURL('/admin/settings');
+  });
+});
+
+// Viewer tests
+test.describe('viewer access', () => {
+  test.use({ storageState: authFile('viewer') });
+
+  test('viewer cannot create content', async ({ page }) => {
+    await page.goto('/content');
+    await expect(page.getByRole('button', { name: 'New post' })).not.toBeVisible();
+  });
+
+  test('viewer cannot access admin area', async ({ page }) => {
+    await page.goto('/admin/users');
+    await expect(page).toHaveURL(/\/(403|dashboard|login)/);
+  });
+});
+```
+
+---
+
+## Recipe 7: Session Timeout Handling
+
+### Complete Example
+
+**TypeScript**
+
+```typescript
+import { test, expect } from '@playwright/test';
+
+test('redirects to login after session timeout', async ({ page, context }) => {
+  // Log in first
+  await page.goto('/login');
+  await page.getByLabel('Email').fill('user@example.com');
+  await page.getByLabel('Password').fill('SecurePass123!');
+  await page.getByRole('button', { name: 'Sign in' }).click();
+  await expect(page).toHaveURL('/dashboard');
+
+  // Simulate session expiration by clearing the session cookie
+  const cookies = await context.cookies();
+  const sessionCookie = cookies.find(
+    (c) => c.name === 'session' || c.name === 'sid' || c.name === 'connect.sid'
+  );
+
+  if (sessionCookie) {
+    await context.clearCookies({ name: sessionCookie.name });
+  }
+
+  // Try to navigate to a protected page
+  await page.goto('/settings');
+
+  // Should redirect to login with a return URL
+  await expect(page).toHaveURL(/\/login/);
+  await expect(page.getByText(/session.*expired|please.*log in again/i)).toBeVisible();
+});
+
+test('shows session expiry warning before timeout', async ({ page }) => {
+  // Mock the session check endpoint to return "expiring soon"
+  await page.route('**/api/auth/session', async (route) => {
+    await route.fulfill({
+      status: 200,
+      contentType: 'application/json',
+      body: JSON.stringify({
+        valid: true,
+        expiresIn: 120, // 2 minutes remaining
+      }),
+    });
+  });
+
+  await page.goto('/dashboard');
+
+  // The app should show a warning when session is about to expire
+  await expect(page.getByText(/session.*expir/i)).toBeVisible({ timeout: 10000 });
+  await expect(page.getByRole('button', { name: /extend|stay logged in/i })).toBeVisible();
+});
+
+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: 120 }),
+    });
+  });
+
+  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('/dashboard');
+
+  await expect(page.getByRole('button', { name: /extend|stay logged in/i })).toBeVisible({
+    timeout: 10000,
+  });
+  await page.getByRole('button', { name: /extend|stay logged in/i }).click();
+
+  expect(sessionExtended).toBe(true);
+  await expect(page.getByText(/session.*expir/i)).not.toBeVisible();
+});
+```
+
+**JavaScript**
+
+```javascript
+const { test, expect } = require('@playwright/test');
+
+test('redirects to login after session timeout', async ({ page, context }) => {
+  await page.goto('/login');
+  await page.getByLabel('Email').fill('user@example.com');
+  await page.getByLabel('Password').fill('SecurePass123!');
+  await page.getByRole('button', { name: 'Sign in' }).click();
+  await expect(page).toHaveURL('/dashboard');
+
+  const cookies = await context.cookies();
+  const sessionCookie = cookies.find(
+    (c) => c.name === 'session' || c.name === 'sid' || c.name === 'connect.sid'
+  );
+
+  if (sessionCookie) {
+    await context.clearCookies({ name: sessionCookie.name });
+  }
+
+  await page.goto('/settings');
+
+  await expect(page).toHaveURL(/\/login/);
+  await expect(page.getByText(/session.*expired|please.*log in again/i)).toBeVisible();
+});
+```
+
+---
+
+## Recipe 8: Logout
+
+### Complete Example
+
+**TypeScript**
+
+```typescript
+import { test, expect } from '@playwright/test';
+
+// Use a logged-in state
+test.use({ storageState: '.auth/user.json' });
+
+test('logs out and redirects to login page', async ({ page }) => {
+  await page.goto('/dashboard');
+  await expect(page.getByText('Welcome')).toBeVisible();
+
+  // Open user menu and click logout
+  await page.getByRole('button', { name: /user menu|account|profile/i }).click();
+  await page.getByRole('menuitem', { name: 'Log out' }).click();
+
+  // Should redirect to login
+  await expect(page).toHaveURL('/login');
+
+  // Verify we can no longer access protected pages
+  await page.goto('/dashboard');
+  await expect(page).toHaveURL(/\/login/);
+});
+
+test('logout clears all session data', async ({ page, context }) => {
+  await page.goto('/dashboard');
+
+  await page.getByRole('button', { name: /user menu|account|profile/i }).click();
+  await page.getByRole('menuitem', { name: 'Log out' }).click();
+
+  await expect(page).toHaveURL('/login');
+
+  // Verify cookies are cleared
+  const cookies = await context.cookies();
+  const sessionCookies = cookies.filter(
+    (c) => c.name === 'session' || c.name === 'sid' || c.name === 'token'
+  );
+  expect(sessionCookies).toHaveLength(0);
+
+  // Verify localStorage is cleared
+  const token = await page.evaluate(() => localStorage.getItem('authToken'));
+  expect(token).toBeNull();
+});
+
+test('logout 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 from all devices' }),
+    });
+  });
+
+  await page.goto('/settings/security');
+
+  await page.getByRole('button', { name: 'Log out of all devices' }).click();
+
+  // Confirm the action in the dialog
+  await page.getByRole('dialog').getByRole('button', { name: 'Confirm' }).click();
+
+  expect(logoutAllCalled).toBe(true);
+  await expect(page).toHaveURL(/\/login/);
+});
+```
+
+**JavaScript**
+
+```javascript
+const { test, expect } = require('@playwright/test');
+
+test.use({ storageState: '.auth/user.json' });
+
+test('logs out and redirects to login page', async ({ page }) => {
+  await page.goto('/dashboard');
+
+  await page.getByRole('button', { name: /user menu|account|profile/i }).click();
+  await page.getByRole('menuitem', { name: 'Log out' }).click();
+
+  await expect(page).toHaveURL('/login');
+
+  await page.goto('/dashboard');
+  await expect(page).toHaveURL(/\/login/);
+});
+
+test('logout clears all session data', async ({ page, context }) => {
+  await page.goto('/dashboard');
+
+  await page.getByRole('button', { name: /user menu|account|profile/i }).click();
+  await page.getByRole('menuitem', { name: 'Log out' }).click();
+
+  await expect(page).toHaveURL('/login');
+
+  const cookies = await context.cookies();
+  const sessionCookies = cookies.filter(
+    (c) => c.name === 'session' || c.name === 'sid' || c.name === 'token'
+  );
+  expect(sessionCookies).toHaveLength(0);
+});
+```
+
+---
+
+## Variations
+
+### Login via API for Speed
+
+Skip the UI for login when testing non-auth features. Use `request` context to get tokens faster.
+
+**TypeScript**
+
+```typescript
+import { test as setup } from '@playwright/test';
+
+setup('authenticate via API', async ({ request }) => {
+  const response = await request.post('/api/auth/login', {
+    data: {
+      email: 'user@example.com',
+      password: 'SecurePass123!',
+    },
+  });
+
+  expect(response.ok()).toBeTruthy();
+
+  // Save the auth state
+  await request.storageState({ path: '.auth/user.json' });
+});
+```
+
+### Multi-Factor Authentication
+
+```typescript
+test('logs in with MFA (TOTP)', async ({ page }) => {
+  await page.goto('/login');
+  await page.getByLabel('Email').fill('mfa-user@example.com');
+  await page.getByLabel('Password').fill('SecurePass123!');
+  await page.getByRole('button', { name: 'Sign in' }).click();
+
+  // MFA challenge screen appears
+  await expect(page.getByText('Enter verification code')).toBeVisible();
+
+  // In test environments, use a predictable TOTP code or mock the verification
+  await page.route('**/api/auth/verify-mfa', async (route) => {
+    await route.fulfill({
+      status: 200,
+      contentType: 'application/json',
+      body: JSON.stringify({ success: true, token: 'jwt-token' }),
+    });
+  });
+
+  await page.getByLabel('Verification code').fill('123456');
+  await page.getByRole('button', { name: 'Verify' }).click();
+
+  await expect(page).toHaveURL('/dashboard');
+});
+```
+
+### Passkeys / WebAuthn (Playwright 1.61+)
+
+Playwright 1.61 ships a virtual WebAuthn authenticator scoped to the browser context: `context.credentials`. Tests can register passkeys and answer `navigator.credentials.create()` / `navigator.credentials.get()` ceremonies without a hardware security key. Call `credentials.install()` before any page in the context starts a WebAuthn ceremony.
+
+**Pattern A: let the app register a passkey, then sign in with it**
+
+```typescript
+test('registers a passkey and signs in with it', async ({ browser }) => {
+  const context = await browser.newContext();
+  await context.credentials.install(); // override navigator.credentials in this context
+
+  const page = await context.newPage();
+
+  // Register: the app's "Create a passkey" flow now talks to the virtual authenticator
+  await page.goto('/settings/security');
+  await page.getByRole('button', { name: 'Create a passkey' }).click();
+  await expect(page.getByText('Passkey added')).toBeVisible();
+
+  // Sign out, then sign back in with the passkey
+  await page.goto('/logout');
+  await page.goto('/login');
+  await page.getByRole('button', { name: 'Sign in with a passkey' }).click();
+  // navigator.credentials.get() is answered with the registered passkey
+  await expect(page).toHaveURL('/dashboard');
+
+  await context.close();
+});
+```
+
+**Pattern B: capture once, seed everywhere (the storageState pattern for passkeys)**
+
+```typescript
+// setup project: register a passkey once and save it (it includes the private key)
+const [credential] = await context.credentials.get({ rpId: 'example.com' });
+fs.writeFileSync('playwright/.auth/passkey.json', JSON.stringify(credential));
+
+// later tests: seed the captured passkey so the user is already enrolled
+const credential = JSON.parse(fs.readFileSync('playwright/.auth/passkey.json', 'utf8'));
+const context = await browser.newContext();
+await context.credentials.create(credential.rpId, credential);
+await context.credentials.install();
+// navigator.credentials.get() now resolves the seeded passkey — no registration UI needed
+```
+
+You can also seed a credential your backend already provisioned for a test user by passing `id`, `userHandle`, `privateKey` (base64url PKCS#8), and `publicKey` (base64url SPKI) to `credentials.create(rpId, …)`, and remove one with `credentials.delete(id)`.
+
+**Tips:**
+- Treat saved passkey JSON like a saved `storageState` — it contains a private key, so keep it out of version control (`.gitignore` the `.auth/` directory).
+- Combine with a setup project (see Recipe 1) so passkey enrollment happens once per run, not per test.
+- Test the fallback path too: what happens when the user cancels the ceremony or has no passkey.
+
+### Testing Auth with Different Browser Contexts
+
+```typescript
+test('two users interact simultaneously', async ({ browser }) => {
+  const adminContext = await browser.newContext({
+    storageState: '.auth/admin.json',
+  });
+  const userContext = await browser.newContext({
+    storageState: '.auth/viewer.json',
+  });
+
+  const adminPage = await adminContext.newPage();
+  const userPage = await userContext.newPage();
+
+  // Admin bans a user
+  await adminPage.goto('/admin/users');
+  await adminPage.getByRole('row', { name: 'viewer@example.com' })
+    .getByRole('button', { name: 'Ban' }).click();
+  await adminPage.getByRole('dialog').getByRole('button', { name: 'Confirm' }).click();
+
+  // User tries to navigate and should be blocked
+  await userPage.goto('/dashboard');
+  await expect(userPage.getByText(/account.*banned|access.*revoked/i)).toBeVisible();
+
+  await adminContext.close();
+  await userContext.close();
+});
+```
+
+---
+
+## Tips
+
+1. **Use `storageState` for reusable auth**. Run login once in a setup project, save the state to a JSON file, and reuse it across all tests. This dramatically speeds up your test suite since you only log in once per role.
+
+2. **Never hard-code credentials in test files**. Use environment variables or a `.env` file loaded via `dotenv`. In `playwright.config.ts`, set `process.env` values or use the `env` option in `use`.
+
+3. **Prefer API-based login for non-auth tests**. Only test the login UI in your auth-specific tests. For everything else, authenticate via the API or by restoring `storageState`. This makes tests faster and less brittle.
+
+4. **Test the negative paths too**. Invalid credentials, expired tokens, locked accounts, rate limiting. These are the scenarios users actually encounter in production and are frequently undertested.
+
+5. **Set a shorter session timeout in your test environment**. If your app has a 30-minute session timeout, configure it to 30 seconds in the test environment so you can test timeout behavior without slow tests.
+
+---
+
+## Related
+
+- [Playwright Authentication Docs](https://playwright.dev/docs/auth)
+- `patterns/page-objects.md` -- Encapsulate login flows in page objects
+- `foundations/assertions.md` -- Assertion patterns for auth states
+- `recipes/crud-testing.md` -- Test CRUD operations once authenticated