1# Complex Authentication Flow Patterns
2 
3## Table of Contents
4 
51. [Email Verification Flows](#email-verification-flows)
62. [Password Reset](#password-reset)
73. [Session Timeout](#session-timeout)
84. [Remember Me Persistence](#remember-me-persistence)
95. [Logout Patterns](#logout-patterns)
106. [Tips](#tips)
117. [Related](#related)
12 
13> **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).
14 
15---
16 
17## Email Verification Flows
18 
19### Capturing Verification Tokens
20 
21Intercept API responses to capture verification tokens for testing:
22 
23```typescript
24test('completes registration with email verification', async ({ page }) => {
25  let capturedToken = '';
26 
27  await page.route('**/api/auth/register', async (route) => {
28    const response = await route.fetch();
29    const body = await response.json();
30    capturedToken = body.verificationToken;
31    await route.fulfill({ response });
32  });
33 
34  await page.goto('/register');
35  await page.getByLabel('Name').fill('New User');
36  await page.getByLabel('Email').fill('[email protected]');
37  await page.getByLabel('Password', { exact: true }).fill('SecurePass!');
38  await page.getByLabel('Confirm password').fill('SecurePass!');
39  await page.getByRole('button', { name: 'Create account' }).click();
40 
41  await expect(page.getByText('Check your inbox')).toBeVisible();
42 
43  expect(capturedToken).toBeTruthy();
44  await page.goto(`/verify?token=${capturedToken}`);
45 
46  await expect(page.getByText('Email confirmed')).toBeVisible();
47});
48```
49 
50### Fully Mocked Verification
51 
52```typescript
53test('verifies email with mocked endpoints', async ({ page }) => {
54  const mockToken = 'test-verification-abc123';
55 
56  await page.route('**/api/auth/register', async (route) => {
57    await route.fulfill({
58      status: 200,
59      contentType: 'application/json',
60      body: JSON.stringify({ message: 'Verification sent', verificationToken: mockToken }),
61    });
62  });
63 
64  await page.route(`**/api/auth/verify?token=${mockToken}`, async (route) => {
65    await route.fulfill({
66      status: 200,
67      contentType: 'application/json',
68      body: JSON.stringify({ verified: true }),
69    });
70  });
71 
72  await page.goto('/register');
73  await page.getByLabel('Email').fill('[email protected]');
74  await page.getByLabel('Password', { exact: true }).fill('Password123!');
75  await page.getByRole('button', { name: 'Sign up' }).click();
76 
77  await expect(page.getByText('Check your inbox')).toBeVisible();
78 
79  await page.goto(`/verify?token=${mockToken}`);
80  await expect(page.getByText('Email confirmed')).toBeVisible();
81});
82```
83 
84---
85 
86## Password Reset
87 
88### Complete Reset Flow
89 
90```typescript
91test('resets password through email link', async ({ page }) => {
92  let resetToken = '';
93 
94  await page.route('**/api/auth/forgot-password', async (route) => {
95    const response = await route.fetch();
96    const body = await response.json();
97    resetToken = body.resetToken;
98    await route.fulfill({ response });
99  });
100 
101  await page.goto('/forgot-password');
102  await page.getByLabel('Email').fill('[email protected]');
103  await page.getByRole('button', { name: 'Send link' }).click();
104 
105  await expect(page.getByText('Reset email sent')).toBeVisible();
106 
107  expect(resetToken).toBeTruthy();
108  await page.goto(`/reset-password?token=${resetToken}`);
109 
110  await page.getByLabel('New password', { exact: true }).fill('NewPassword456!');
111  await page.getByLabel('Confirm password').fill('NewPassword456!');
112  await page.getByRole('button', { name: 'Update password' }).click();
113 
114  await expect(page.getByText('Password updated')).toBeVisible();
115});
116```
117 
118### Expired Token Handling
119 
120```typescript
121test('shows error for expired reset token', async ({ page }) => {
122  await page.goto('/reset-password?token=expired-token');
123 
124  await page.getByLabel('New password', { exact: true }).fill('NewPass!');
125  await page.getByLabel('Confirm password').fill('NewPass!');
126  await page.getByRole('button', { name: 'Update password' }).click();
127 
128  await expect(page.getByRole('alert')).toContainText(/expired|invalid/i);
129});
130```
131 
132### Password Strength Validation
133 
134```typescript
135test('enforces password requirements on reset', async ({ page }) => {
136  await page.goto('/reset-password?token=valid-token');
137 
138  await page.getByLabel('New password', { exact: true }).fill('weak');
139  await page.getByLabel('Confirm password').fill('weak');
140  await page.getByRole('button', { name: 'Update password' }).click();
141 
142  await expect(page.getByText(/at least 8 characters/i)).toBeVisible();
143});
144```
145 
146---
147 
148## Session Timeout
149 
150### Detecting Expired Sessions
151 
152```typescript
153test('redirects to signin after session expires', async ({ page, context }) => {
154  await page.goto('/signin');
155  await page.getByLabel('Email').fill('[email protected]');
156  await page.getByLabel('Password').fill('Password!');
157  await page.getByRole('button', { name: 'Sign in' }).click();
158  await expect(page).toHaveURL('/home');
159 
160  const cookies = await context.cookies();
161  const sessionCookie = cookies.find((c) => c.name.includes('session'));
162 
163  if (sessionCookie) {
164    await context.clearCookies({ name: sessionCookie.name });
165  }
166 
167  await page.goto('/profile');
168  await expect(page).toHaveURL(/\/signin/);
169  await expect(page.getByText(/session.*expired|sign in again/i)).toBeVisible();
170});
171```
172 
173### Session Extension Warning
174 
175```typescript
176test('shows warning before session expires', async ({ page }) => {
177  await page.route('**/api/auth/session', async (route) => {
178    await route.fulfill({
179      status: 200,
180      contentType: 'application/json',
181      body: JSON.stringify({ valid: true, expiresIn: 60 }),
182    });
183  });
184 
185  await page.goto('/home');
186 
187  await expect(page.getByText(/session.*expir/i)).toBeVisible({ timeout: 10000 });
188  await expect(page.getByRole('button', { name: /extend|stay signed in/i })).toBeVisible();
189});
190```
191 
192### Session Extension Action
193 
194```typescript
195test('extends session when user clicks extend', async ({ page }) => {
196  let sessionExtended = false;
197 
198  await page.route('**/api/auth/session', async (route) => {
199    await route.fulfill({
200      status: 200,
201      contentType: 'application/json',
202      body: JSON.stringify({ valid: true, expiresIn: 60 }),
203    });
204  });
205 
206  await page.route('**/api/auth/refresh', async (route) => {
207    sessionExtended = true;
208    await route.fulfill({
209      status: 200,
210      contentType: 'application/json',
211      body: JSON.stringify({ valid: true, expiresIn: 3600 }),
212    });
213  });
214 
215  await page.goto('/home');
216 
217  await expect(page.getByRole('button', { name: /extend|stay signed in/i })).toBeVisible({
218    timeout: 10000,
219  });
220  await page.getByRole('button', { name: /extend|stay signed in/i }).click();
221 
222  expect(sessionExtended).toBe(true);
223  await expect(page.getByText(/session.*expir/i)).not.toBeVisible();
224});
225```
226 
227---
228 
229## Remember Me Persistence
230 
231### Persistent Session
232 
233```typescript
234test('persists session with remember me enabled', async ({ browser }) => {
235  const ctx1 = await browser.newContext();
236  const page1 = await ctx1.newPage();
237 
238  await page1.goto('/signin');
239  await page1.getByLabel('Email').fill('[email protected]');
240  await page1.getByLabel('Password').fill('Password!');
241  await page1.getByLabel('Keep me signed in').check();
242  await page1.getByRole('button', { name: 'Sign in' }).click();
243 
244  await expect(page1).toHaveURL('/home');
245 
246  const state = await ctx1.storageState();
247  await ctx1.close();
248 
249  const ctx2 = await browser.newContext({ storageState: state });
250  const page2 = await ctx2.newPage();
251 
252  await page2.goto('/home');
253  await expect(page2).toHaveURL('/home');
254  await expect(page2.getByText('Welcome')).toBeVisible();
255 
256  await ctx2.close();
257});
258```
259 
260### Session-Only Login
261 
262```typescript
263test('session-only login does not persist across browser restarts', async ({ browser }) => {
264  const ctx1 = await browser.newContext();
265  const page1 = await ctx1.newPage();
266 
267  await page1.goto('/signin');
268  await page1.getByLabel('Email').fill('[email protected]');
269  await page1.getByLabel('Password').fill('Password!');
270  // Leave "Remember me" unchecked
271  await expect(page1.getByLabel('Keep me signed in')).not.toBeChecked();
272  await page1.getByRole('button', { name: 'Sign in' }).click();
273 
274  await expect(page1).toHaveURL('/home');
275 
276  // Only keep persistent cookies (filter out session cookies)
277  const cookies = await ctx1.cookies();
278  await ctx1.close();
279 
280  const persistentCookies = cookies.filter((c) => c.expires > 0);
281  const ctx2 = await browser.newContext();
282  await ctx2.addCookies(persistentCookies);
283  const page2 = await ctx2.newPage();
284 
285  await page2.goto('/home');
286 
287  // Should redirect to login since session was not persisted
288  await expect(page2).toHaveURL(/\/signin/);
289 
290  await ctx2.close();
291});
292```
293 
294---
295 
296## Logout Patterns
297 
298### Standard Logout with Session Cleanup
299 
300```typescript
301test.use({ storageState: '.auth/user.json' });
302 
303test('logs out and clears session', async ({ page, context }) => {
304  await page.goto('/home');
305 
306  await page.getByRole('button', { name: /account|menu/i }).click();
307  await page.getByRole('menuitem', { name: 'Sign out' }).click();
308 
309  await expect(page).toHaveURL('/signin');
310 
311  const cookies = await context.cookies();
312  const sessionCookies = cookies.filter((c) => c.name.includes('session') || c.name.includes('token'));
313  expect(sessionCookies).toHaveLength(0);
314 
315  await page.goto('/home');
316  await expect(page).toHaveURL(/\/signin/);
317});
318```
319 
320### Logout from All Devices
321 
322```typescript
323test('logs out from all devices', async ({ page }) => {
324  let logoutAllCalled = false;
325 
326  await page.route('**/api/auth/logout-all', async (route) => {
327    logoutAllCalled = true;
328    await route.fulfill({
329      status: 200,
330      contentType: 'application/json',
331      body: JSON.stringify({ message: 'Logged out everywhere' }),
332    });
333  });
334 
335  await page.goto('/settings/security');
336 
337  await page.getByRole('button', { name: 'Sign out everywhere' }).click();
338  await page.getByRole('dialog').getByRole('button', { name: 'Confirm' }).click();
339 
340  expect(logoutAllCalled).toBe(true);
341  await expect(page).toHaveURL(/\/signin/);
342});
343```
344 
345---
346 
347## Tips
348 
3491. **Configure shorter session timeouts in test environments** — Enables testing timeout behavior without slow tests
3502. **Test token expiration edge cases** — Expired tokens, invalid tokens, already-used tokens
3513. **Verify cleanup on logout** — Check both cookies and localStorage are cleared
3524. **Test the full flow end-to-end** — Password reset should verify login with new password works
353 
354---
355 
356## Related
357 
358- [authentication.md](authentication.md) — Storage state, OAuth mocking, MFA, role-based access, API login
359- [fixtures-hooks.md](../core/fixtures-hooks.md) — Creating auth fixtures
360- [third-party.md](./third-party.md) — Mocking external auth providers
361