@arcadialdev/arcality 2.2.0

package/.agents/skills/playwright-best-practices/SKILL.md

@@ -0,0 +1,303 @@
+---
+name: playwright-best-practices
+description: 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.
+license: MIT
+metadata:
+  author: currents.dev
+  version: "1.1"
+---
+
+# Playwright Best Practices
+
+This skill provides comprehensive guidance for all aspects of Playwright test development, from writing new tests to debugging and maintaining existing test suites.
+
+## Activity-Based Reference Guide
+
+Consult these references based on what you're doing:
+
+### Writing New Tests
+
+**When to use**: Creating new test files, writing test cases, implementing test scenarios
+
+| Activity                            | Reference Files                                                                                                                               |
+| ----------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Writing E2E tests**               | [test-suite-structure.md](core/test-suite-structure.md), [locators.md](core/locators.md), [assertions-waiting.md](core/assertions-waiting.md) |
+| **Writing component tests**         | [component-testing.md](testing-patterns/component-testing.md), [test-suite-structure.md](core/test-suite-structure.md)                        |
+| **Writing API tests**               | [api-testing.md](testing-patterns/api-testing.md), [test-suite-structure.md](core/test-suite-structure.md)                                    |
+| **Writing GraphQL tests**           | [graphql-testing.md](testing-patterns/graphql-testing.md), [api-testing.md](testing-patterns/api-testing.md)                                  |
+| **Writing visual regression tests** | [visual-regression.md](testing-patterns/visual-regression.md), [canvas-webgl.md](testing-patterns/canvas-webgl.md)                            |
+| **Structuring test code with POM**  | [page-object-model.md](core/page-object-model.md), [test-suite-structure.md](core/test-suite-structure.md)                                    |
+| **Setting up test data/fixtures**   | [fixtures-hooks.md](core/fixtures-hooks.md), [test-data.md](core/test-data.md)                                                                |
+| **Handling authentication**         | [authentication.md](advanced/authentication.md), [authentication-flows.md](advanced/authentication-flows.md)                                  |
+| **Testing date/time features**      | [clock-mocking.md](advanced/clock-mocking.md)                                                                                                 |
+| **Testing file upload/download**    | [file-operations.md](testing-patterns/file-operations.md), [file-upload-download.md](testing-patterns/file-upload-download.md)                |
+| **Testing forms/validation**        | [forms-validation.md](testing-patterns/forms-validation.md)                                                                                   |
+| **Testing drag and drop**           | [drag-drop.md](testing-patterns/drag-drop.md)                                                                                                 |
+| **Testing accessibility**           | [accessibility.md](testing-patterns/accessibility.md)                                                                                         |
+| **Testing security (XSS, CSRF)**    | [security-testing.md](testing-patterns/security-testing.md)                                                                                   |
+| **Using test annotations**          | [annotations.md](core/annotations.md)                                                                                                         |
+| **Using test tags**                 | [test-tags.md](core/test-tags.md)                                                                                                             |
+| **Testing iframes**                 | [iframes.md](browser-apis/iframes.md)                                                                                                         |
+| **Testing canvas/WebGL**            | [canvas-webgl.md](testing-patterns/canvas-webgl.md)                                                                                           |
+| **Internationalization (i18n)**     | [i18n.md](testing-patterns/i18n.md)                                                                                                           |
+| **Testing Electron apps**           | [electron.md](testing-patterns/electron.md)                                                                                                   |
+| **Testing browser extensions**      | [browser-extensions.md](testing-patterns/browser-extensions.md)                                                                               |
+
+### Mobile & Responsive Testing
+
+**When to use**: Testing mobile devices, touch interactions, responsive layouts
+
+| Activity                        | Reference Files                                                                  |
+| ------------------------------- | -------------------------------------------------------------------------------- |
+| **Device emulation**            | [mobile-testing.md](advanced/mobile-testing.md)                                  |
+| **Touch gestures (swipe, tap)** | [mobile-testing.md](advanced/mobile-testing.md)                                  |
+| **Viewport/breakpoint testing** | [mobile-testing.md](advanced/mobile-testing.md)                                  |
+| **Mobile-specific UI**          | [mobile-testing.md](advanced/mobile-testing.md), [locators.md](core/locators.md) |
+
+### Real-Time & Browser APIs
+
+**When to use**: Testing WebSockets, geolocation, permissions, multi-tab flows
+
+| Activity                        | Reference Files                                                                          |
+| ------------------------------- | ---------------------------------------------------------------------------------------- |
+| **WebSocket/real-time testing** | [websockets.md](browser-apis/websockets.md)                                              |
+| **Geolocation mocking**         | [browser-apis.md](browser-apis/browser-apis.md)                                          |
+| **Permission handling**         | [browser-apis.md](browser-apis/browser-apis.md)                                          |
+| **Clipboard testing**           | [browser-apis.md](browser-apis/browser-apis.md)                                          |
+| **Camera/microphone mocking**   | [browser-apis.md](browser-apis/browser-apis.md)                                          |
+| **Multi-tab/popup flows**       | [multi-context.md](advanced/multi-context.md)                                            |
+| **OAuth popup handling**        | [third-party.md](advanced/third-party.md), [multi-context.md](advanced/multi-context.md) |
+
+### Debugging & Troubleshooting
+
+**When to use**: Test failures, element not found, timeouts, unexpected behavior
+
+| Activity                                          | Reference Files                                                                                                                                |
+| ------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Debugging test failures**                       | [debugging.md](debugging/debugging.md), [assertions-waiting.md](core/assertions-waiting.md)                                                    |
+| **Fixing flaky tests**                            | [flaky-tests.md](debugging/flaky-tests.md), [debugging.md](debugging/debugging.md), [assertions-waiting.md](core/assertions-waiting.md)        |
+| **Debugging flaky parallel runs**                 | [flaky-tests.md](debugging/flaky-tests.md), [performance.md](infrastructure-ci-cd/performance.md), [fixtures-hooks.md](core/fixtures-hooks.md) |
+| **Ensuring test isolation / avoiding state leak** | [flaky-tests.md](debugging/flaky-tests.md), [fixtures-hooks.md](core/fixtures-hooks.md), [performance.md](infrastructure-ci-cd/performance.md) |
+| **Fixing selector issues**                        | [locators.md](core/locators.md), [debugging.md](debugging/debugging.md)                                                                        |
+| **Investigating timeout issues**                  | [assertions-waiting.md](core/assertions-waiting.md), [debugging.md](debugging/debugging.md)                                                    |
+| **Using trace viewer**                            | [debugging.md](debugging/debugging.md)                                                                                                         |
+| **Debugging race conditions**                     | [flaky-tests.md](debugging/flaky-tests.md), [debugging.md](debugging/debugging.md), [assertions-waiting.md](core/assertions-waiting.md)        |
+| **Debugging console/JS errors**                   | [console-errors.md](debugging/console-errors.md), [debugging.md](debugging/debugging.md)                                                       |
+
+### Error & Edge Case Testing
+
+**When to use**: Testing error states, offline mode, network failures, validation
+
+| Activity                       | Reference Files                                                                                       |
+| ------------------------------ | ----------------------------------------------------------------------------------------------------- |
+| **Error boundary testing**     | [error-testing.md](debugging/error-testing.md)                                                        |
+| **Network failure simulation** | [error-testing.md](debugging/error-testing.md), [network-advanced.md](advanced/network-advanced.md)   |
+| **Offline mode testing**       | [error-testing.md](debugging/error-testing.md), [service-workers.md](browser-apis/service-workers.md) |
+| **Service worker testing**     | [service-workers.md](browser-apis/service-workers.md)                                                 |
+| **Loading state testing**      | [error-testing.md](debugging/error-testing.md)                                                        |
+| **Form validation testing**    | [error-testing.md](debugging/error-testing.md)                                                        |
+
+### Multi-User & Collaboration Testing
+
+**When to use**: Testing features involving multiple users, roles, or real-time collaboration
+
+| Activity                       | Reference Files                                                                      |
+| ------------------------------ | ------------------------------------------------------------------------------------ |
+| **Multiple users in one test** | [multi-user.md](advanced/multi-user.md)                                              |
+| **Real-time collaboration**    | [multi-user.md](advanced/multi-user.md), [websockets.md](browser-apis/websockets.md) |
+| **Role-based access testing**  | [multi-user.md](advanced/multi-user.md)                                              |
+| **Concurrent action testing**  | [multi-user.md](advanced/multi-user.md)                                              |
+
+### Architecture Decisions
+
+**When to use**: Choosing test patterns, deciding between approaches, planning test architecture
+
+| Activity                     | Reference Files                                           |
+| ---------------------------- | --------------------------------------------------------- |
+| **POM vs fixtures decision** | [pom-vs-fixtures.md](architecture/pom-vs-fixtures.md)     |
+| **Test type selection**      | [test-architecture.md](architecture/test-architecture.md) |
+| **Mock vs real services**    | [when-to-mock.md](architecture/when-to-mock.md)           |
+| **Test suite structure**     | [test-suite-structure.md](core/test-suite-structure.md)   |
+
+### Framework-Specific Testing
+
+**When to use**: Testing React, Angular, Vue, or Next.js applications
+
+| Activity                  | Reference Files                     |
+| ------------------------- | ----------------------------------- |
+| **Testing React apps**    | [react.md](frameworks/react.md)     |
+| **Testing Angular apps**  | [angular.md](frameworks/angular.md) |
+| **Testing Vue/Nuxt apps** | [vue.md](frameworks/vue.md)         |
+| **Testing Next.js apps**  | [nextjs.md](frameworks/nextjs.md)   |
+
+### Refactoring & Maintenance
+
+**When to use**: Improving existing tests, code review, reducing duplication
+
+| Activity                             | Reference Files                                                                                            |
+| ------------------------------------ | ---------------------------------------------------------------------------------------------------------- |
+| **Refactoring to Page Object Model** | [page-object-model.md](core/page-object-model.md), [test-suite-structure.md](core/test-suite-structure.md) |
+| **Improving test organization**      | [test-suite-structure.md](core/test-suite-structure.md), [page-object-model.md](core/page-object-model.md) |
+| **Extracting common setup/teardown** | [fixtures-hooks.md](core/fixtures-hooks.md)                                                                |
+| **Replacing brittle selectors**      | [locators.md](core/locators.md)                                                                            |
+| **Removing explicit waits**          | [assertions-waiting.md](core/assertions-waiting.md)                                                        |
+| **Creating test data factories**     | [test-data.md](core/test-data.md)                                                                          |
+| **Configuration setup**              | [configuration.md](core/configuration.md)                                                                  |
+
+### Infrastructure & Configuration
+
+**When to use**: Setting up projects, configuring CI/CD, optimizing performance
+
+| Activity                                | Reference Files                                                                                                          |
+| --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
+| **Configuring Playwright project**      | [configuration.md](core/configuration.md), [projects-dependencies.md](core/projects-dependencies.md)                     |
+| **Setting up CI/CD pipelines**          | [ci-cd.md](infrastructure-ci-cd/ci-cd.md), [github-actions.md](infrastructure-ci-cd/github-actions.md)                   |
+| **GitHub Actions setup**                | [github-actions.md](infrastructure-ci-cd/github-actions.md)                                                              |
+| **GitLab CI setup**                     | [gitlab.md](infrastructure-ci-cd/gitlab.md)                                                                              |
+| **Other CI providers**                  | [other-providers.md](infrastructure-ci-cd/other-providers.md)                                                            |
+| **Docker/container setup**              | [docker.md](infrastructure-ci-cd/docker.md)                                                                              |
+| **Global setup & teardown**             | [global-setup.md](core/global-setup.md)                                                                                  |
+| **Project dependencies**                | [projects-dependencies.md](core/projects-dependencies.md)                                                                |
+| **Optimizing test performance**         | [performance.md](infrastructure-ci-cd/performance.md), [test-suite-structure.md](core/test-suite-structure.md)           |
+| **Configuring parallel execution**      | [parallel-sharding.md](infrastructure-ci-cd/parallel-sharding.md), [performance.md](infrastructure-ci-cd/performance.md) |
+| **Isolating test data between workers** | [fixtures-hooks.md](core/fixtures-hooks.md), [performance.md](infrastructure-ci-cd/performance.md)                       |
+| **Test coverage**                       | [test-coverage.md](infrastructure-ci-cd/test-coverage.md)                                                                |
+| **Test reporting/artifacts**            | [reporting.md](infrastructure-ci-cd/reporting.md)                                                                        |
+
+### Advanced Patterns
+
+**When to use**: Complex scenarios, API mocking, network interception
+
+| Activity                             | Reference Files                                                                                              |
+| ------------------------------------ | ------------------------------------------------------------------------------------------------------------ |
+| **Mocking API responses**            | [test-suite-structure.md](core/test-suite-structure.md), [network-advanced.md](advanced/network-advanced.md) |
+| **Network interception**             | [network-advanced.md](advanced/network-advanced.md), [assertions-waiting.md](core/assertions-waiting.md)     |
+| **GraphQL mocking**                  | [network-advanced.md](advanced/network-advanced.md)                                                          |
+| **HAR recording/playback**           | [network-advanced.md](advanced/network-advanced.md)                                                          |
+| **Custom fixtures**                  | [fixtures-hooks.md](core/fixtures-hooks.md)                                                                  |
+| **Advanced waiting strategies**      | [assertions-waiting.md](core/assertions-waiting.md)                                                          |
+| **OAuth/SSO mocking**                | [third-party.md](advanced/third-party.md), [multi-context.md](advanced/multi-context.md)                     |
+| **Payment gateway mocking**          | [third-party.md](advanced/third-party.md)                                                                    |
+| **Email/SMS verification mocking**   | [third-party.md](advanced/third-party.md)                                                                    |
+| **Failing on console errors**        | [console-errors.md](debugging/console-errors.md)                                                             |
+| **Security testing (XSS, CSRF)**     | [security-testing.md](testing-patterns/security-testing.md)                                                  |
+| **Performance budgets & Web Vitals** | [performance-testing.md](testing-patterns/performance-testing.md)                                            |
+| **Lighthouse integration**           | [performance-testing.md](testing-patterns/performance-testing.md)                                            |
+| **Test annotations (skip, fixme)**   | [annotations.md](core/annotations.md)                                                                        |
+| **Test tags (@smoke, @fast)**        | [test-tags.md](core/test-tags.md)                                                                            |
+| **Test steps for reporting**         | [annotations.md](core/annotations.md)                                                                        |
+
+## Quick Decision Tree
+
+```
+What are you doing?
+│
+├─ Writing a new test?
+│  ├─ E2E test → core/test-suite-structure.md, core/locators.md, core/assertions-waiting.md
+│  ├─ Component test → testing-patterns/component-testing.md
+│  ├─ API test → testing-patterns/api-testing.md, core/test-suite-structure.md
+│  ├─ GraphQL test → testing-patterns/graphql-testing.md
+│  ├─ Visual regression → testing-patterns/visual-regression.md
+│  ├─ Visual/canvas test → testing-patterns/canvas-webgl.md, core/test-suite-structure.md
+│  ├─ Accessibility test → testing-patterns/accessibility.md
+│  ├─ Mobile/responsive test → advanced/mobile-testing.md
+│  ├─ i18n/locale test → testing-patterns/i18n.md
+│  ├─ Electron app test → testing-patterns/electron.md
+│  ├─ Browser extension test → testing-patterns/browser-extensions.md
+│  ├─ Multi-user test → advanced/multi-user.md
+│  ├─ Form validation test → testing-patterns/forms-validation.md
+│  └─ Drag and drop test → testing-patterns/drag-drop.md
+│
+├─ Testing specific features?
+│  ├─ File upload/download → testing-patterns/file-operations.md, testing-patterns/file-upload-download.md
+│  ├─ Date/time dependent → advanced/clock-mocking.md
+│  ├─ WebSocket/real-time → browser-apis/websockets.md
+│  ├─ Geolocation/permissions → browser-apis/browser-apis.md
+│  ├─ OAuth/SSO mocking → advanced/third-party.md, advanced/multi-context.md
+│  ├─ Payments/email/SMS → advanced/third-party.md
+│  ├─ iFrames → browser-apis/iframes.md
+│  ├─ Canvas/WebGL/charts → testing-patterns/canvas-webgl.md
+│  ├─ Service workers/PWA → browser-apis/service-workers.md
+│  ├─ i18n/localization → testing-patterns/i18n.md
+│  ├─ Security (XSS, CSRF) → testing-patterns/security-testing.md
+│  └─ Performance/Web Vitals → testing-patterns/performance-testing.md
+│
+├─ Architecture decisions?
+│  ├─ POM vs fixtures → architecture/pom-vs-fixtures.md
+│  ├─ Test type selection → architecture/test-architecture.md
+│  ├─ Mock vs real services → architecture/when-to-mock.md
+│  └─ Test suite structure → core/test-suite-structure.md
+│
+├─ Framework-specific testing?
+│  ├─ React app → frameworks/react.md
+│  ├─ Angular app → frameworks/angular.md
+│  ├─ Vue/Nuxt app → frameworks/vue.md
+│  └─ Next.js app → frameworks/nextjs.md
+│
+├─ Authentication testing?
+│  ├─ Basic auth patterns → advanced/authentication.md
+│  └─ Complex flows (MFA, reset) → advanced/authentication-flows.md
+│
+├─ Test is failing/flaky?
+│  ├─ Flaky test investigation → debugging/flaky-tests.md
+│  ├─ Element not found → core/locators.md, debugging/debugging.md
+│  ├─ Timeout issues → core/assertions-waiting.md, debugging/debugging.md
+│  ├─ Race conditions → debugging/flaky-tests.md, debugging/debugging.md
+│  ├─ Flaky only with multiple workers → debugging/flaky-tests.md, infrastructure-ci-cd/performance.md
+│  ├─ State leak / isolation → debugging/flaky-tests.md, core/fixtures-hooks.md
+│  ├─ Console/JS errors → debugging/console-errors.md, debugging/debugging.md
+│  └─ General debugging → debugging/debugging.md
+│
+├─ Testing error scenarios?
+│  ├─ Network failures → debugging/error-testing.md, advanced/network-advanced.md
+│  ├─ Offline (unexpected) → debugging/error-testing.md
+│  ├─ Offline-first/PWA → browser-apis/service-workers.md
+│  ├─ Error boundaries → debugging/error-testing.md
+│  └─ Form validation → testing-patterns/forms-validation.md, debugging/error-testing.md
+│
+├─ Refactoring existing code?
+│  ├─ Implementing POM → core/page-object-model.md
+│  ├─ Improving selectors → core/locators.md
+│  ├─ Extracting fixtures → core/fixtures-hooks.md
+│  ├─ Creating data factories → core/test-data.md
+│  └─ Configuration setup → core/configuration.md
+│
+├─ Setting up infrastructure?
+│  ├─ CI/CD → infrastructure-ci-cd/ci-cd.md
+│  ├─ GitHub Actions → infrastructure-ci-cd/github-actions.md
+│  ├─ GitLab CI → infrastructure-ci-cd/gitlab.md
+│  ├─ Other CI providers → infrastructure-ci-cd/other-providers.md
+│  ├─ Docker/containers → infrastructure-ci-cd/docker.md
+│  ├─ Sharding/parallel → infrastructure-ci-cd/parallel-sharding.md
+│  ├─ Reporting/artifacts → infrastructure-ci-cd/reporting.md
+│  ├─ Global setup/teardown → core/global-setup.md
+│  ├─ Project dependencies → core/projects-dependencies.md
+│  ├─ Test performance → infrastructure-ci-cd/performance.md
+│  ├─ Test coverage → infrastructure-ci-cd/test-coverage.md
+│  └─ Project config → core/configuration.md, core/projects-dependencies.md
+│
+├─ Organizing tests?
+│  ├─ Skip/fixme/slow tests → core/annotations.md
+│  ├─ Test tags (@smoke, @fast) → core/test-tags.md
+│  ├─ Filtering tests (--grep) → core/test-tags.md
+│  ├─ Test steps → core/annotations.md
+│  └─ Conditional execution → core/annotations.md
+│
+└─ Running subset of tests?
+   ├─ By tag (@smoke, @critical) → core/test-tags.md
+   ├─ Exclude slow/flaky tests → core/test-tags.md
+   ├─ PR vs nightly tests → core/test-tags.md, infrastructure-ci-cd/ci-cd.md
+   └─ Project-specific filtering → core/test-tags.md, core/configuration.md
+```
+
+## Test Validation Loop
+
+After writing or modifying tests:
+
+1. **Run tests**: `npx playwright test --reporter=list`
+2. **If tests fail**:
+   - Review error output and trace (`npx playwright show-trace`)
+   - Fix locators, waits, or assertions
+   - Re-run tests
+3. **Only proceed when all tests pass**
+4. **Run multiple times** for critical tests: `npx playwright test --repeat-each=5`

package/.agents/skills/playwright-best-practices/advanced/authentication-flows.md

@@ -0,0 +1,360 @@
+# 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