testeiya 0.2.0 → 0.3.9

package/skills/playwright-best-practices-skill/advanced/authentication.md

@@ -1,871 +0,0 @@
-# Authentication Testing
-
-## Table of Contents
-
-1. [Quick Reference](#quick-reference)
-2. [Patterns](#patterns)
-3. [Decision Guide](#decision-guide)
-4. [Anti-Patterns](#anti-patterns)
-5. [Troubleshooting](#troubleshooting)
-6. [Related](#related)
-
-> **When to use**: Apps with login, session management, or protected routes. Authentication is the most common source of slow test suites.
-
-## Quick Reference
-
-```typescript
-// Storage state reuse — the #1 pattern for fast auth
-await page.goto("/login");
-await page.getByLabel("Username").fill("testuser@example.com");
-await page.getByLabel("Password").fill("secretPass123");
-await page.getByRole("button", { name: "Log in" }).click();
-await page.context().storageState({ path: ".auth/session.json" });
-
-// Reuse in config — every test starts authenticated
-{
-  use: {
-    storageState: ".auth/session.json"
-  }
-}
-
-// API login — skip the UI entirely
-const context = await browser.newContext();
-const response = await context.request.post("/api/auth/login", {
-  data: { email: "testuser@example.com", password: "secretPass123" },
-});
-await context.storageState({ path: ".auth/session.json" });
-```
-
-## Patterns
-
-### Storage State Reuse
-
-**Use when**: You need authenticated tests and want to avoid logging in before every test.
-**Avoid when**: Tests require completely fresh sessions, or you are testing the login flow itself.
-
-`storageState` serializes cookies and localStorage to a JSON file. Load it in any browser context to start authenticated instantly.
-
-```typescript
-// scripts/generate-auth.ts — run once to generate the state file
-import { chromium } from "@playwright/test";
-
-async function generateAuthState() {
-  const browser = await chromium.launch();
-  const context = await browser.newContext();
-  const page = await context.newPage();
-
-  await page.goto("http://localhost:4000/login");
-  await page.getByLabel("Username").fill("testuser@example.com");
-  await page.getByLabel("Password").fill("secretPass123");
-  await page.getByRole("button", { name: "Log in" }).click();
-  await page.waitForURL("/home");
-
-  await context.storageState({ path: ".auth/session.json" });
-  await browser.close();
-}
-
-generateAuthState();
-```
-
-```typescript
-// playwright.config.ts — load saved state for all tests
-import { defineConfig } from "@playwright/test";
-
-export default defineConfig({
-  use: {
-    baseURL: "http://localhost:4000",
-    storageState: ".auth/session.json",
-  },
-});
-```
-
-```typescript
-// tests/home.spec.ts — test starts already logged in
-import { test, expect } from "@playwright/test";
-
-test("authenticated user sees home page", async ({ page }) => {
-  await page.goto("/home");
-  await expect(page.getByRole("heading", { name: "Home" })).toBeVisible();
-});
-```
-
-### Global Setup Authentication
-
-**Use when**: You want to authenticate once before the entire test suite runs.
-**Avoid when**: Different tests need different users, or your tokens expire faster than your suite runs.
-
-```typescript
-// global-setup.ts
-import { chromium, type FullConfig } from "@playwright/test";
-
-async function globalSetup(config: FullConfig) {
-  const { baseURL } = config.projects[0].use;
-  const browser = await chromium.launch();
-  const context = await browser.newContext();
-  const page = await context.newPage();
-
-  await page.goto(`${baseURL}/login`);
-  await page.getByLabel("Username").fill(process.env.TEST_USER_EMAIL!);
-  await page.getByLabel("Password").fill(process.env.TEST_USER_PASSWORD!);
-  await page.getByRole("button", { name: "Log in" }).click();
-  await page.waitForURL("**/home");
-
-  await context.storageState({ path: ".auth/session.json" });
-  await browser.close();
-}
-
-export default globalSetup;
-```
-
-```typescript
-// playwright.config.ts
-import { defineConfig } from "@playwright/test";
-
-export default defineConfig({
-  globalSetup: require.resolve("./global-setup"),
-  use: {
-    baseURL: "http://localhost:4000",
-    storageState: ".auth/session.json",
-  },
-});
-```
-
-Add `.auth/` to `.gitignore`. Auth state files contain session tokens and should never be committed.
-
-### Per-Worker Authentication
-
-**Use when**: Each parallel worker needs its own authenticated session to avoid race conditions for tests that modify server-side state.
-**Avoid when**: Tests are read-only and a modifying shared session is safe, you can use a single shared account.
-
-> **Sharded runs**: `parallelIndex` resets per shard, so different shards can have workers with the same index. To avoid collisions, include the shard identifier in the username (e.g., `worker-${SHARD_INDEX}-${parallelIndex}@example.com`) by passing a `SHARD_INDEX` environment variable from your CI matrix.
-
-```typescript
-// fixtures/auth.ts
-import { test as base, type BrowserContext } from "@playwright/test";
-
-type AuthFixtures = {
-  authenticatedContext: BrowserContext;
-};
-
-export const test = base.extend<{}, AuthFixtures>({
-  authenticatedContext: [
-    async ({ browser }, use) => {
-      const context = await browser.newContext();
-      const page = await context.newPage();
-
-      await page.goto("/login");
-      await page
-        .getByLabel("Username")
-        .fill(`worker-${test.info().parallelIndex}@example.com`);
-      await page.getByLabel("Password").fill("secretPass123");
-      await page.getByRole("button", { name: "Log in" }).click();
-      await page.waitForURL("/home");
-      await page.close();
-
-      await use(context);
-      await context.close();
-    },
-    { scope: "worker" },
-  ],
-});
-
-export { expect } from "@playwright/test";
-```
-
-```typescript
-// tests/settings.spec.ts
-import { test, expect } from "../fixtures/auth";
-
-test("update display name", async ({ authenticatedContext }) => {
-  const page = await authenticatedContext.newPage();
-  await page.goto("/settings/profile");
-  await page.getByLabel("Display name").fill("Updated Name");
-  await page.getByRole("button", { name: "Save" }).click();
-  await expect(page.getByText("Profile saved")).toBeVisible();
-});
-```
-
-### Multiple Roles
-
-**Use when**: Your app has role-based access control and you need to test different permission levels.
-**Avoid when**: Your app has a single user role.
-
-```typescript
-// global-setup.ts — authenticate all roles
-import { chromium, type FullConfig } from "@playwright/test";
-
-const accounts = [
-  {
-    role: "admin",
-    email: "admin@example.com",
-    password: process.env.ADMIN_PASSWORD!,
-  },
-  {
-    role: "member",
-    email: "member@example.com",
-    password: process.env.MEMBER_PASSWORD!,
-  },
-  {
-    role: "guest",
-    email: "guest@example.com",
-    password: process.env.GUEST_PASSWORD!,
-  },
-];
-
-async function globalSetup(config: FullConfig) {
-  const { baseURL } = config.projects[0].use;
-
-  for (const { role, email, password } of accounts) {
-    const browser = await chromium.launch();
-    const context = await browser.newContext();
-    const page = await context.newPage();
-
-    await page.goto(`${baseURL}/login`);
-    await page.getByLabel("Username").fill(email);
-    await page.getByLabel("Password").fill(password);
-    await page.getByRole("button", { name: "Log in" }).click();
-    await page.waitForURL("**/home");
-
-    await context.storageState({ path: `.auth/${role}.json` });
-    await browser.close();
-  }
-}
-
-export default globalSetup;
-```
-
-```typescript
-// playwright.config.ts — one project per role
-import { defineConfig } from "@playwright/test";
-
-export default defineConfig({
-  globalSetup: require.resolve("./global-setup"),
-  projects: [
-    {
-      name: "admin",
-      use: { storageState: ".auth/admin.json" },
-      testMatch: "**/*.admin.spec.ts",
-    },
-    {
-      name: "member",
-      use: { storageState: ".auth/member.json" },
-      testMatch: "**/*.member.spec.ts",
-    },
-    {
-      name: "guest",
-      use: { storageState: ".auth/guest.json" },
-      testMatch: "**/*.guest.spec.ts",
-    },
-    {
-      name: "anonymous",
-      use: { storageState: { cookies: [], origins: [] } },
-      testMatch: "**/*.anon.spec.ts",
-    },
-  ],
-});
-```
-
-```typescript
-// tests/admin-panel.admin.spec.ts
-import { test, expect } from "@playwright/test";
-
-test("admin can access user management", async ({ page }) => {
-  await page.goto("/admin/users");
-  await expect(
-    page.getByRole("heading", { name: "User Management" })
-  ).toBeVisible();
-  await expect(page.getByRole("button", { name: "Remove user" })).toBeEnabled();
-});
-```
-
-```typescript
-// tests/admin-panel.guest.spec.ts
-import { test, expect } from "@playwright/test";
-
-test("guest cannot access admin panel", async ({ page }) => {
-  await page.goto("/admin/users");
-  await expect(page.getByText("Access denied")).toBeVisible();
-});
-```
-
-**Alternative**: Use a fixture that accepts a role parameter when you need role switching within a single spec file.
-
-```typescript
-// fixtures/auth.ts — role-based fixture
-import { test as base, type Page } from "@playwright/test";
-import fs from "fs";
-
-type RoleFixtures = {
-  loginAs: (role: "admin" | "member" | "guest") => Promise<Page>;
-};
-
-export const test = base.extend<RoleFixtures>({
-  loginAs: async ({ browser }, use) => {
-    const pages: Page[] = [];
-
-    await use(async (role) => {
-      const statePath = `.auth/${role}.json`;
-      if (!fs.existsSync(statePath)) {
-        throw new Error(
-          `Auth state for role "${role}" not found at ${statePath}`
-        );
-      }
-      const context = await browser.newContext({ storageState: statePath });
-      const page = await context.newPage();
-      pages.push(page);
-      return page;
-    });
-
-    for (const page of pages) {
-      await page.context().close();
-    }
-  },
-});
-
-export { expect } from "@playwright/test";
-```
-
-```typescript
-// tests/role-comparison.spec.ts
-import { test, expect } from "../fixtures/auth";
-
-test("admin sees remove button, guest does not", async ({ loginAs }) => {
-  const adminPage = await loginAs("admin");
-  await adminPage.goto("/admin/users");
-  await expect(
-    adminPage.getByRole("button", { name: "Remove user" })
-  ).toBeVisible();
-
-  const guestPage = await loginAs("guest");
-  await guestPage.goto("/admin/users");
-  await expect(guestPage.getByText("Access denied")).toBeVisible();
-});
-```
-
-### OAuth/SSO Mocking
-
-**Use when**: Your app authenticates via a third-party OAuth provider and you cannot hit the real provider in tests.
-**Avoid when**: You have a dedicated test tenant on the OAuth provider.
-
-A typical OAuth flow works like this:
-
-1. User clicks "Sign in with Provider" → browser navigates to `https://accounts.provider.com/authorize?...`
-2. User authenticates on the provider's page → provider redirects back to your app's **callback route** (e.g. `http://localhost:4000/auth/callback?code=ABC&state=XYZ`)
-3. Your backend exchanges the `code` for an access token, creates a session, and redirects the user to a logged-in page
-
-In tests you can short-circuit step 2 with `page.route()`: intercept the outbound request to the provider and respond with a `302` redirect straight to your callback route, supplying a mock `code` and `state`. Your backend still executes its normal callback handler — the only part that's mocked is the provider's authorization page.
-
-For cases where you want to skip the browser redirect entirely, a second approach calls a **test-only API endpoint** that creates the session server-side and returns the session cookie directly.
-
-```typescript
-// tests/oauth-login.spec.ts — mock the callback route
-import { test, expect } from "@playwright/test";
-
-test("login via mocked OAuth flow", async ({ page }) => {
-  await page.route("https://accounts.provider.com/**", async (route) => {
-    const callbackUrl = new URL("http://localhost:4000/auth/callback");
-    callbackUrl.searchParams.set("code", "mock-auth-code-xyz");
-    callbackUrl.searchParams.set("state", "expected-state-value");
-    await route.fulfill({
-      status: 302,
-      headers: { location: callbackUrl.toString() },
-    });
-  });
-
-  await page.goto("/login");
-  await page.getByRole("button", { name: "Sign in with Provider" }).click();
-
-  await page.waitForURL("/home");
-  await expect(page.getByRole("heading", { name: "Home" })).toBeVisible();
-});
-```
-
-```typescript
-// tests/oauth-login.spec.ts — API-based session injection
-import { test, expect } from "@playwright/test";
-
-test("bypass OAuth entirely via API session injection", async ({
-  page,
-}) => {
-  // Call a test-only endpoint that creates a session without OAuth
-  const response = await page.request.post("/api/test/create-session", {
-    data: {
-      email: "oauth-user@example.com",
-      provider: "provider",
-      role: "member",
-    },
-  });
-  expect(response.ok()).toBeTruthy();
-
-  await page.context().storageState({ path: ".auth/oauth-user.json" });
-  await page.goto("/home");
-  await expect(page.getByRole("heading", { name: "Home" })).toBeVisible();
-});
-```
-
-**Backend requirement**: Your backend must expose a test-only session creation endpoint (guarded by `NODE_ENV=test`) or accept a known test OAuth code.
-
-### MFA Handling
-
-**Use when**: Your app requires two-factor authentication (TOTP, SMS, email codes).
-**Avoid when**: MFA is optional and you can disable it for test accounts.
-
-**Strategy 1**: Generate real TOTP codes from a shared secret.
-
-```typescript
-// helpers/totp.ts
-import * as OTPAuth from "otpauth";
-
-export function generateTOTP(secret: string): string {
-  const totp = new OTPAuth.TOTP({
-    secret: OTPAuth.Secret.fromBase32(secret),
-    digits: 6,
-    period: 30,
-    algorithm: "SHA1",
-  });
-  return totp.generate();
-}
-```
-
-```typescript
-// tests/mfa-login.spec.ts
-import { test, expect } from "@playwright/test";
-import { generateTOTP } from "../helpers/totp";
-
-test("login with TOTP two-factor auth", async ({ page }) => {
-  await page.goto("/login");
-  await page.getByLabel("Username").fill("mfa-user@example.com");
-  await page.getByLabel("Password").fill("secretPass123");
-  await page.getByRole("button", { name: "Log in" }).click();
-
-  await expect(page.getByText("Enter your authentication code")).toBeVisible();
-
-  const code = generateTOTP(process.env.MFA_TOTP_SECRET!);
-  await page.getByLabel("Authentication code").fill(code);
-  await page.getByRole("button", { name: "Verify" }).click();
-
-  await page.waitForURL("/home");
-  await expect(page.getByRole("heading", { name: "Home" })).toBeVisible();
-});
-```
-
-**Strategy 2**: Mock MFA at the backend level. Have your backend accept a known bypass code (e.g., `000000`) when `NODE_ENV=test`.
-
-**Strategy 3**: Disable MFA for test accounts at the infrastructure level.
-
-### Session Refresh
-
-**Use when**: Your tokens expire during long test runs.
-**Avoid when**: Your test suite runs quickly and tokens outlast the entire run.
-
-```typescript
-// fixtures/auth-with-refresh.ts
-import { test as base, type BrowserContext } from "@playwright/test";
-import fs from "fs";
-
-type AuthFixtures = {
-  authenticatedPage: import("@playwright/test").Page;
-};
-
-export const test = base.extend<AuthFixtures>({
-  authenticatedPage: async ({ browser }, use) => {
-    const statePath = ".auth/session.json";
-
-    let context: BrowserContext;
-    if (fs.existsSync(statePath)) {
-      context = await browser.newContext({ storageState: statePath });
-      const page = await context.newPage();
-
-      const response = await page.request.get("/api/auth/me");
-      if (response.ok()) {
-        await use(page);
-        await context.close();
-        return;
-      }
-      await context.close();
-    }
-
-    context = await browser.newContext();
-    const page = await context.newPage();
-    await page.goto("/login");
-    await page.getByLabel("Username").fill(process.env.TEST_USER_EMAIL!);
-    await page.getByLabel("Password").fill(process.env.TEST_USER_PASSWORD!);
-    await page.getByRole("button", { name: "Log in" }).click();
-    await page.waitForURL("/home");
-
-    await context.storageState({ path: statePath });
-
-    await use(page);
-    await context.close();
-  },
-});
-
-export { expect } from "@playwright/test";
-```
-
-### Login Page Object
-
-**Use when**: Multiple test files need to log in and you want consistent, maintainable login logic.
-**Avoid when**: You use `storageState` everywhere and never navigate through the login UI in tests.
-
-```typescript
-// page-objects/LoginPage.ts
-import { type Page, type Locator, expect } from "@playwright/test";
-
-export class LoginPage {
-  readonly page: Page;
-  readonly usernameInput: Locator;
-  readonly passwordInput: Locator;
-  readonly loginButton: Locator;
-  readonly errorMessage: Locator;
-  readonly forgotPasswordLink: Locator;
-
-  constructor(page: Page) {
-    this.page = page;
-    this.usernameInput = page.getByLabel("Username");
-    this.passwordInput = page.getByLabel("Password");
-    this.loginButton = page.getByRole("button", { name: "Log in" });
-    this.errorMessage = page.getByRole("alert");
-    this.forgotPasswordLink = page.getByRole("link", {
-      name: "Forgot password",
-    });
-  }
-
-  async goto() {
-    await this.page.goto("/login");
-    await expect(this.loginButton).toBeVisible();
-  }
-
-  async login(username: string, password: string) {
-    await this.usernameInput.fill(username);
-    await this.passwordInput.fill(password);
-    await this.loginButton.click();
-  }
-
-  async loginAndWaitForHome(username: string, password: string) {
-    await this.login(username, password);
-    await this.page.waitForURL("/home");
-  }
-
-  async expectError(message: string | RegExp) {
-    await expect(this.errorMessage).toContainText(message);
-  }
-
-  async expectFieldError(field: "username" | "password", message: string) {
-    const input =
-      field === "username" ? this.usernameInput : this.passwordInput;
-    await expect(input).toHaveAttribute("aria-invalid", "true");
-    const errorId = await input.getAttribute("aria-describedby");
-    if (errorId) {
-      await expect(this.page.locator(`#${errorId}`)).toContainText(message);
-    }
-  }
-}
-```
-
-```typescript
-// tests/login.spec.ts
-import { test, expect } from "@playwright/test";
-import { LoginPage } from "../page-objects/LoginPage";
-
-test.use({ storageState: { cookies: [], origins: [] } });
-
-test.describe("login page", () => {
-  let loginPage: LoginPage;
-
-  test.beforeEach(async ({ page }) => {
-    loginPage = new LoginPage(page);
-    await loginPage.goto();
-  });
-
-  test("successful login redirects to home", async ({ page }) => {
-    await loginPage.loginAndWaitForHome(
-      "testuser@example.com",
-      "secretPass123"
-    );
-    await expect(page.getByRole("heading", { name: "Home" })).toBeVisible();
-  });
-
-  test("wrong password shows error", async () => {
-    await loginPage.login("testuser@example.com", "wrong-password");
-    await loginPage.expectError("Invalid username or password");
-  });
-
-  test("empty fields show validation errors", async () => {
-    await loginPage.loginButton.click();
-    await loginPage.expectFieldError("username", "Username is required");
-  });
-
-  test("forgot password link navigates correctly", async ({ page }) => {
-    await loginPage.forgotPasswordLink.click();
-    await page.waitForURL("/forgot-password");
-    await expect(
-      page.getByRole("heading", { name: "Reset password" })
-    ).toBeVisible();
-  });
-});
-```
-
-### API-Based Login
-
-**Use when**: You want the fastest possible authentication without any browser interaction.
-**Avoid when**: You are specifically testing the login UI.
-
-API login is typically 5-10x faster than UI login.
-
-```typescript
-// global-setup.ts — API-based login (fastest)
-import { request, type FullConfig } from "@playwright/test";
-
-async function globalSetup(config: FullConfig) {
-  const { baseURL } = config.projects[0].use;
-
-  const requestContext = await request.newContext({ baseURL });
-
-  const response = await requestContext.post("/api/auth/login", {
-    data: {
-      email: process.env.TEST_USER_EMAIL!,
-      password: process.env.TEST_USER_PASSWORD!,
-    },
-  });
-
-  if (!response.ok()) {
-    throw new Error(
-      `API login failed: ${response.status()} ${await response.text()}`
-    );
-  }
-
-  await requestContext.storageState({ path: ".auth/session.json" });
-  await requestContext.dispose();
-}
-
-export default globalSetup;
-```
-
-```typescript
-// fixtures/api-auth.ts — fixture version for per-test authentication
-import { test as base } from "@playwright/test";
-
-export const test = base.extend({
-  authenticatedPage: async ({ browser, playwright }, use) => {
-    const apiContext = await playwright.request.newContext({
-      baseURL: "http://localhost:4000",
-    });
-
-    await apiContext.post("/api/auth/login", {
-      data: {
-        email: "testuser@example.com",
-        password: "secretPass123",
-      },
-    });
-
-    const state = await apiContext.storageState();
-    const context = await browser.newContext({ storageState: state });
-    const page = await context.newPage();
-
-    await use(page);
-
-    await context.close();
-    await apiContext.dispose();
-  },
-});
-
-export { expect } from "@playwright/test";
-```
-
-### Unauthenticated Tests
-
-**Use when**: Testing the login page, signup flow, password reset, public pages, or redirect behavior for unauthenticated users.
-**Avoid when**: The test requires a logged-in user.
-
-When your config sets a default `storageState`, you must explicitly clear it for unauthenticated tests.
-
-```typescript
-// tests/public-pages.spec.ts
-import { test, expect } from "@playwright/test";
-
-test.use({ storageState: { cookies: [], origins: [] } });
-
-test.describe("unauthenticated access", () => {
-  test("homepage is accessible without login", async ({ page }) => {
-    await page.goto("/");
-    await expect(page.getByRole("heading", { name: "Welcome" })).toBeVisible();
-    await expect(page.getByRole("link", { name: "Log in" })).toBeVisible();
-  });
-
-  test("protected route redirects to login", async ({ page }) => {
-    await page.goto("/home");
-    await page.waitForURL("**/login**");
-    expect(page.url()).toContain("redirect=%2Fhome");
-  });
-
-  test("expired session shows re-login prompt", async ({ page, context }) => {
-    await page.goto("/home");
-    await context.clearCookies();
-
-    await page.goto("/settings");
-    await page.waitForURL("**/login**");
-    await expect(page.getByText("Your session has expired")).toBeVisible();
-  });
-
-  test("signup flow creates account", async ({ page }) => {
-    await page.goto("/signup");
-    await page.getByLabel("Name").fill("New User");
-    await page.getByLabel("Email").fill(`test-${Date.now()}@example.com`);
-    await page.getByLabel("Password", { exact: true }).fill("secretPass123");
-    await page.getByLabel("Confirm password").fill("secretPass123");
-    await page.getByRole("button", { name: "Create account" }).click();
-
-    await page.waitForURL("/onboarding");
-    await expect(page.getByText("Welcome, New User")).toBeVisible();
-  });
-});
-```
-
-## Decision Guide
-
-| Scenario                         | Approach                       | Speed    | Isolation      | When to Choose                                                 |
-| -------------------------------- | ------------------------------ | -------- | -------------- | -------------------------------------------------------------- |
-| Most tests need auth             | Global setup + `storageState`  | Fastest  | Shared session | Default for nearly every project                               |
-| Tests modify user state          | Per-worker fixture             | Fast     | Per worker     | Tests update profile, change settings, or mutate data          |
-| Multiple user roles              | Per-project `storageState`     | Fastest  | Per role       | App has admin/member/guest roles                               |
-| Testing the login page           | No `storageState`              | N/A      | Full           | Use `test.use({ storageState: { cookies: [], origins: [] } })` |
-| OAuth/SSO provider               | Mock the callback              | Fast     | Per test       | Never hit real OAuth providers in CI                           |
-| MFA is required                  | TOTP generation or bypass      | Moderate | Per test       | Generate real TOTP codes or use a test-mode bypass             |
-| Token expires mid-suite          | Session refresh fixture        | Fast     | Per check      | Fixture validates the session before use                       |
-| Single test needs different user | `loginAs(role)` fixture        | Moderate | Per call       | Rare: prefer per-project roles                                 |
-| API-first app (no login UI)      | API login via `request.post()` | Fastest  | Per test       | No browser needed for auth                                     |
-
-### UI Login vs API Login vs Storage State
-
-```text
-Need to test the login page itself?
-├── Yes → UI login with LoginPage POM, no storageState
-└── No → Do you have a login API endpoint?
-    ├── Yes → API login in global setup, save storageState (fastest)
-    └── No → UI login in global setup, save storageState
-              └── Tokens expire quickly?
-                  ├── Yes → Add session refresh fixture
-                  └── No → Standard storageState reuse is fine
-```
-
-## Anti-Patterns
-
-| Don't Do This                                                             | Problem                                     | Do This Instead                                                           |
-| ------------------------------------------------------------------------- | ------------------------------------------- | ------------------------------------------------------------------------- |
-| Log in via UI before every test                                           | Adds 2-5 seconds per test                   | Use `storageState` to skip login entirely                                 |
-| Share a single auth state file across parallel workers that mutate state  | Race conditions                             | Use per-worker fixtures with `{ scope: 'worker' }`                        |
-| Hardcode credentials in test files                                        | Security risk                               | Use environment variables and `.env` files                                |
-| Ignore token expiration                                                   | Tests fail intermittently with 401 errors   | Add a session validity check in your auth fixture                         |
-| Hit real OAuth providers in CI                                            | Flaky: rate limits, CAPTCHA, network issues | Mock the OAuth callback or use API session injection                      |
-| Use `page.waitForTimeout(2000)` after login                               | Arbitrary delay                             | `await page.waitForURL('/home')` or `await expect(heading).toBeVisible()` |
-| Store `.auth/*.json` files in git                                         | Tokens in version control                   | Add `.auth/` to `.gitignore`                                              |
-| Create one "god" test account with all permissions                        | Cannot test role-based access control       | Create separate accounts per role                                         |
-| Use `browser.newContext()` without `storageState` for authenticated tests | Every context starts unauthenticated        | Pass `storageState` when creating the context                             |
-| Test MFA by disabling it everywhere                                       | You never test the MFA flow                 | Use TOTP generation for at least one test                                 |
-
-## Troubleshooting
-
-### Global setup fails with "Target page, context or browser has been closed"
-
-**Cause**: The login page redirected unexpectedly, or the browser closed before `storageState()` was called.
-
-**Fix**:
-
-- Add `await page.waitForURL()` after the login action
-- Check that `baseURL` in your config matches the actual server URL and protocol
-- Add error handling to global setup:
-
-```typescript
-const response = await page.waitForResponse("**/api/auth/**");
-if (!response.ok()) {
-  throw new Error(
-    `Login failed in global setup: ${response.status()} ${await response.text()}`
-  );
-}
-```
-
-### Tests fail with 401 Unauthorized after running for a while
-
-**Cause**: The session token saved in `storageState` has expired.
-
-**Fix**:
-
-- Use the session refresh fixture pattern
-- Increase token expiry in test environment configuration
-- Switch to API-based login in a worker-scoped fixture
-
-### `storageState` file is empty or contains no cookies
-
-**Cause**: `storageState()` was called before the login response set cookies.
-
-**Fix**:
-
-- Wait for the post-login page to load: `await page.waitForURL('/home')`
-- Verify cookies exist before saving:
-
-```typescript
-const cookies = await context.cookies();
-if (cookies.length === 0) {
-  throw new Error("No cookies found after login");
-}
-await context.storageState({ path: ".auth/session.json" });
-```
-
-### Different browsers get different cookies
-
-**Cause**: Some auth flows set cookies with `SameSite=Strict` or use browser-specific cookie behavior.
-
-**Fix**:
-
-- Generate separate auth state files per browser project
-- Check if your auth uses `SameSite=None; Secure` cookies that require HTTPS:
-
-```typescript
-projects: [
-  {
-    name: 'chromium',
-    use: { ...devices['Desktop Chrome'], storageState: '.auth/chromium-session.json' },
-  },
-  {
-    name: 'firefox',
-    use: { ...devices['Desktop Firefox'], storageState: '.auth/firefox-session.json' },
-  },
-],
-```
-
-### Parallel tests interfere with each other's sessions
-
-**Cause**: Multiple workers share the same test account and one worker's actions affect others.
-
-**Fix**:
-
-- Use per-worker test accounts: `worker-${test.info().parallelIndex}@example.com`
-- Use the per-worker authentication fixture pattern
-- Make tests idempotent
-
-### OAuth mock does not work — still redirects to real provider
-
-**Cause**: `page.route()` was registered after the navigation that triggers the OAuth redirect.
-
-**Fix**:
-
-- Register route handlers before any navigation: call `page.route()` before `page.goto()`
-- Log the actual redirect URL to verify the pattern:
-
-```typescript
-page.on("request", (req) => {
-  if (req.url().includes("oauth") || req.url().includes("accounts.provider")) {
-    console.log("OAuth request:", req.url());
-  }
-});
-```
-
-## Related
-
-- [fixtures-hooks.md](../core/fixtures-hooks.md) — custom fixtures for auth setup and teardown
-- [configuration.md](../core/configuration.md) — `storageState`, projects, and global setup configuration
-- [global-setup.md](../core/global-setup.md) — global setup patterns and project dependencies
-- [network-advanced.md](network-advanced.md) — route interception patterns used in OAuth mocking
-- [api-testing.md](../testing-patterns/api-testing.md) — API request context used in API-based login
-- [flaky-tests.md](../debugging/flaky-tests.md) — diagnosing auth-related flakiness