1# Authentication Testing
2 
3## Table of Contents
4 
51. [Quick Reference](#quick-reference)
62. [Patterns](#patterns)
73. [Decision Guide](#decision-guide)
84. [Anti-Patterns](#anti-patterns)
95. [Troubleshooting](#troubleshooting)
106. [Related](#related)
11 
12> **When to use**: Apps with login, session management, or protected routes. Authentication is the most common source of slow test suites.
13 
14## Quick Reference
15 
16```typescript
17// Storage state reuse — the #1 pattern for fast auth
18await page.goto("/login");
19await page.getByLabel("Username").fill("[email protected]");
20await page.getByLabel("Password").fill("secretPass123");
21await page.getByRole("button", { name: "Log in" }).click();
22await page.context().storageState({ path: ".auth/session.json" });
23 
24// Reuse in config — every test starts authenticated
25{
26  use: {
27    storageState: ".auth/session.json"
28  }
29}
30 
31// API login — skip the UI entirely
32const context = await browser.newContext();
33const response = await context.request.post("/api/auth/login", {
34  data: { email: "[email protected]", password: "secretPass123" },
35});
36await context.storageState({ path: ".auth/session.json" });
37```
38 
39## Patterns
40 
41### Storage State Reuse
42 
43**Use when**: You need authenticated tests and want to avoid logging in before every test.
44**Avoid when**: Tests require completely fresh sessions, or you are testing the login flow itself.
45 
46`storageState` serializes cookies and localStorage to a JSON file. Load it in any browser context to start authenticated instantly.
47 
48```typescript
49// scripts/generate-auth.ts — run once to generate the state file
50import { chromium } from "@playwright/test";
51 
52async function generateAuthState() {
53  const browser = await chromium.launch();
54  const context = await browser.newContext();
55  const page = await context.newPage();
56 
57  await page.goto("http://localhost:4000/login");
58  await page.getByLabel("Username").fill("[email protected]");
59  await page.getByLabel("Password").fill("secretPass123");
60  await page.getByRole("button", { name: "Log in" }).click();
61  await page.waitForURL("/home");
62 
63  await context.storageState({ path: ".auth/session.json" });
64  await browser.close();
65}
66 
67generateAuthState();
68```
69 
70```typescript
71// playwright.config.ts — load saved state for all tests
72import { defineConfig } from "@playwright/test";
73 
74export default defineConfig({
75  use: {
76    baseURL: "http://localhost:4000",
77    storageState: ".auth/session.json",
78  },
79});
80```
81 
82```typescript
83// tests/home.spec.ts — test starts already logged in
84import { test, expect } from "@playwright/test";
85 
86test("authenticated user sees home page", async ({ page }) => {
87  await page.goto("/home");
88  await expect(page.getByRole("heading", { name: "Home" })).toBeVisible();
89});
90```
91 
92### Global Setup Authentication
93 
94**Use when**: You want to authenticate once before the entire test suite runs.
95**Avoid when**: Different tests need different users, or your tokens expire faster than your suite runs.
96 
97```typescript
98// global-setup.ts
99import { chromium, type FullConfig } from "@playwright/test";
100 
101async function globalSetup(config: FullConfig) {
102  const { baseURL } = config.projects[0].use;
103  const browser = await chromium.launch();
104  const context = await browser.newContext();
105  const page = await context.newPage();
106 
107  await page.goto(`${baseURL}/login`);
108  await page.getByLabel("Username").fill(process.env.TEST_USER_EMAIL!);
109  await page.getByLabel("Password").fill(process.env.TEST_USER_PASSWORD!);
110  await page.getByRole("button", { name: "Log in" }).click();
111  await page.waitForURL("**/home");
112 
113  await context.storageState({ path: ".auth/session.json" });
114  await browser.close();
115}
116 
117export default globalSetup;
118```
119 
120```typescript
121// playwright.config.ts
122import { defineConfig } from "@playwright/test";
123 
124export default defineConfig({
125  globalSetup: require.resolve("./global-setup"),
126  use: {
127    baseURL: "http://localhost:4000",
128    storageState: ".auth/session.json",
129  },
130});
131```
132 
133Add `.auth/` to `.gitignore`. Auth state files contain session tokens and should never be committed.
134 
135### Per-Worker Authentication
136 
137**Use when**: Each parallel worker needs its own authenticated session to avoid race conditions for tests that modify server-side state.
138**Avoid when**: Tests are read-only and a modifying shared session is safe, you can use a single shared account.
139 
140> **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.
141 
142```typescript
143// fixtures/auth.ts
144import { test as base, type BrowserContext } from "@playwright/test";
145 
146type AuthFixtures = {
147  authenticatedContext: BrowserContext;
148};
149 
150export const test = base.extend<{}, AuthFixtures>({
151  authenticatedContext: [
152    async ({ browser }, use) => {
153      const context = await browser.newContext();
154      const page = await context.newPage();
155 
156      await page.goto("/login");
157      await page
158        .getByLabel("Username")
159        .fill(`worker-${test.info().parallelIndex}@example.com`);
160      await page.getByLabel("Password").fill("secretPass123");
161      await page.getByRole("button", { name: "Log in" }).click();
162      await page.waitForURL("/home");
163      await page.close();
164 
165      await use(context);
166      await context.close();
167    },
168    { scope: "worker" },
169  ],
170});
171 
172export { expect } from "@playwright/test";
173```
174 
175```typescript
176// tests/settings.spec.ts
177import { test, expect } from "../fixtures/auth";
178 
179test("update display name", async ({ authenticatedContext }) => {
180  const page = await authenticatedContext.newPage();
181  await page.goto("/settings/profile");
182  await page.getByLabel("Display name").fill("Updated Name");
183  await page.getByRole("button", { name: "Save" }).click();
184  await expect(page.getByText("Profile saved")).toBeVisible();
185});
186```
187 
188### Multiple Roles
189 
190**Use when**: Your app has role-based access control and you need to test different permission levels.
191**Avoid when**: Your app has a single user role.
192 
193```typescript
194// global-setup.ts — authenticate all roles
195import { chromium, type FullConfig } from "@playwright/test";
196 
197const accounts = [
198  {
199    role: "admin",
200    email: "[email protected]",
201    password: process.env.ADMIN_PASSWORD!,
202  },
203  {
204    role: "member",
205    email: "[email protected]",
206    password: process.env.MEMBER_PASSWORD!,
207  },
208  {
209    role: "guest",
210    email: "[email protected]",
211    password: process.env.GUEST_PASSWORD!,
212  },
213];
214 
215async function globalSetup(config: FullConfig) {
216  const { baseURL } = config.projects[0].use;
217 
218  for (const { role, email, password } of accounts) {
219    const browser = await chromium.launch();
220    const context = await browser.newContext();
221    const page = await context.newPage();
222 
223    await page.goto(`${baseURL}/login`);
224    await page.getByLabel("Username").fill(email);
225    await page.getByLabel("Password").fill(password);
226    await page.getByRole("button", { name: "Log in" }).click();
227    await page.waitForURL("**/home");
228 
229    await context.storageState({ path: `.auth/${role}.json` });
230    await browser.close();
231  }
232}
233 
234export default globalSetup;
235```
236 
237```typescript
238// playwright.config.ts — one project per role
239import { defineConfig } from "@playwright/test";
240 
241export default defineConfig({
242  globalSetup: require.resolve("./global-setup"),
243  projects: [
244    {
245      name: "admin",
246      use: { storageState: ".auth/admin.json" },
247      testMatch: "**/*.admin.spec.ts",
248    },
249    {
250      name: "member",
251      use: { storageState: ".auth/member.json" },
252      testMatch: "**/*.member.spec.ts",
253    },
254    {
255      name: "guest",
256      use: { storageState: ".auth/guest.json" },
257      testMatch: "**/*.guest.spec.ts",
258    },
259    {
260      name: "anonymous",
261      use: { storageState: { cookies: [], origins: [] } },
262      testMatch: "**/*.anon.spec.ts",
263    },
264  ],
265});
266```
267 
268```typescript
269// tests/admin-panel.admin.spec.ts
270import { test, expect } from "@playwright/test";
271 
272test("admin can access user management", async ({ page }) => {
273  await page.goto("/admin/users");
274  await expect(
275    page.getByRole("heading", { name: "User Management" })
276  ).toBeVisible();
277  await expect(page.getByRole("button", { name: "Remove user" })).toBeEnabled();
278});
279```
280 
281```typescript
282// tests/admin-panel.guest.spec.ts
283import { test, expect } from "@playwright/test";
284 
285test("guest cannot access admin panel", async ({ page }) => {
286  await page.goto("/admin/users");
287  await expect(page.getByText("Access denied")).toBeVisible();
288});
289```
290 
291**Alternative**: Use a fixture that accepts a role parameter when you need role switching within a single spec file.
292 
293```typescript
294// fixtures/auth.ts — role-based fixture
295import { test as base, type Page } from "@playwright/test";
296import fs from "fs";
297 
298type RoleFixtures = {
299  loginAs: (role: "admin" | "member" | "guest") => Promise<Page>;
300};
301 
302export const test = base.extend<RoleFixtures>({
303  loginAs: async ({ browser }, use) => {
304    const pages: Page[] = [];
305 
306    await use(async (role) => {
307      const statePath = `.auth/${role}.json`;
308      if (!fs.existsSync(statePath)) {
309        throw new Error(
310          `Auth state for role "${role}" not found at ${statePath}`
311        );
312      }
313      const context = await browser.newContext({ storageState: statePath });
314      const page = await context.newPage();
315      pages.push(page);
316      return page;
317    });
318 
319    for (const page of pages) {
320      await page.context().close();
321    }
322  },
323});
324 
325export { expect } from "@playwright/test";
326```
327 
328```typescript
329// tests/role-comparison.spec.ts
330import { test, expect } from "../fixtures/auth";
331 
332test("admin sees remove button, guest does not", async ({ loginAs }) => {
333  const adminPage = await loginAs("admin");
334  await adminPage.goto("/admin/users");
335  await expect(
336    adminPage.getByRole("button", { name: "Remove user" })
337  ).toBeVisible();
338 
339  const guestPage = await loginAs("guest");
340  await guestPage.goto("/admin/users");
341  await expect(guestPage.getByText("Access denied")).toBeVisible();
342});
343```
344 
345### OAuth/SSO Mocking
346 
347**Use when**: Your app authenticates via a third-party OAuth provider and you cannot hit the real provider in tests.
348**Avoid when**: You have a dedicated test tenant on the OAuth provider.
349 
350A typical OAuth flow works like this:
351 
3521. User clicks "Sign in with Provider" → browser navigates to `https://accounts.provider.com/authorize?...`
3532. 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`)
3543. Your backend exchanges the `code` for an access token, creates a session, and redirects the user to a logged-in page
355 
356In 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.
357 
358For 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.
359 
360```typescript
361// tests/oauth-login.spec.ts — mock the callback route
362import { test, expect } from "@playwright/test";
363 
364test("login via mocked OAuth flow", async ({ page }) => {
365  await page.route("https://accounts.provider.com/**", async (route) => {
366    const callbackUrl = new URL("http://localhost:4000/auth/callback");
367    callbackUrl.searchParams.set("code", "mock-auth-code-xyz");
368    callbackUrl.searchParams.set("state", "expected-state-value");
369    await route.fulfill({
370      status: 302,
371      headers: { location: callbackUrl.toString() },
372    });
373  });
374 
375  await page.goto("/login");
376  await page.getByRole("button", { name: "Sign in with Provider" }).click();
377 
378  await page.waitForURL("/home");
379  await expect(page.getByRole("heading", { name: "Home" })).toBeVisible();
380});
381```
382 
383```typescript
384// tests/oauth-login.spec.ts — API-based session injection
385import { test, expect } from "@playwright/test";
386 
387test("bypass OAuth entirely via API session injection", async ({
388  page,
389}) => {
390  // Call a test-only endpoint that creates a session without OAuth
391  const response = await page.request.post("/api/test/create-session", {
392    data: {
393      email: "[email protected]",
394      provider: "provider",
395      role: "member",
396    },
397  });
398  expect(response.ok()).toBeTruthy();
399 
400  await page.context().storageState({ path: ".auth/oauth-user.json" });
401  await page.goto("/home");
402  await expect(page.getByRole("heading", { name: "Home" })).toBeVisible();
403});
404```
405 
406**Backend requirement**: Your backend must expose a test-only session creation endpoint (guarded by `NODE_ENV=test`) or accept a known test OAuth code.
407 
408### MFA Handling
409 
410**Use when**: Your app requires two-factor authentication (TOTP, SMS, email codes).
411**Avoid when**: MFA is optional and you can disable it for test accounts.
412 
413**Strategy 1**: Generate real TOTP codes from a shared secret.
414 
415```typescript
416// helpers/totp.ts
417import * as OTPAuth from "otpauth";
418 
419export function generateTOTP(secret: string): string {
420  const totp = new OTPAuth.TOTP({
421    secret: OTPAuth.Secret.fromBase32(secret),
422    digits: 6,
423    period: 30,
424    algorithm: "SHA1",
425  });
426  return totp.generate();
427}
428```
429 
430```typescript
431// tests/mfa-login.spec.ts
432import { test, expect } from "@playwright/test";
433import { generateTOTP } from "../helpers/totp";
434 
435test("login with TOTP two-factor auth", async ({ page }) => {
436  await page.goto("/login");
437  await page.getByLabel("Username").fill("[email protected]");
438  await page.getByLabel("Password").fill("secretPass123");
439  await page.getByRole("button", { name: "Log in" }).click();
440 
441  await expect(page.getByText("Enter your authentication code")).toBeVisible();
442 
443  const code = generateTOTP(process.env.MFA_TOTP_SECRET!);
444  await page.getByLabel("Authentication code").fill(code);
445  await page.getByRole("button", { name: "Verify" }).click();
446 
447  await page.waitForURL("/home");
448  await expect(page.getByRole("heading", { name: "Home" })).toBeVisible();
449});
450```
451 
452**Strategy 2**: Mock MFA at the backend level. Have your backend accept a known bypass code (e.g., `000000`) when `NODE_ENV=test`.
453 
454**Strategy 3**: Disable MFA for test accounts at the infrastructure level.
455 
456### Session Refresh
457 
458**Use when**: Your tokens expire during long test runs.
459**Avoid when**: Your test suite runs quickly and tokens outlast the entire run.
460 
461```typescript
462// fixtures/auth-with-refresh.ts
463import { test as base, type BrowserContext } from "@playwright/test";
464import fs from "fs";
465 
466type AuthFixtures = {
467  authenticatedPage: import("@playwright/test").Page;
468};
469 
470export const test = base.extend<AuthFixtures>({
471  authenticatedPage: async ({ browser }, use) => {
472    const statePath = ".auth/session.json";
473 
474    let context: BrowserContext;
475    if (fs.existsSync(statePath)) {
476      context = await browser.newContext({ storageState: statePath });
477      const page = await context.newPage();
478 
479      const response = await page.request.get("/api/auth/me");
480      if (response.ok()) {
481        await use(page);
482        await context.close();
483        return;
484      }
485      await context.close();
486    }
487 
488    context = await browser.newContext();
489    const page = await context.newPage();
490    await page.goto("/login");
491    await page.getByLabel("Username").fill(process.env.TEST_USER_EMAIL!);
492    await page.getByLabel("Password").fill(process.env.TEST_USER_PASSWORD!);
493    await page.getByRole("button", { name: "Log in" }).click();
494    await page.waitForURL("/home");
495 
496    await context.storageState({ path: statePath });
497 
498    await use(page);
499    await context.close();
500  },
501});
502 
503export { expect } from "@playwright/test";
504```
505 
506### Login Page Object
507 
508**Use when**: Multiple test files need to log in and you want consistent, maintainable login logic.
509**Avoid when**: You use `storageState` everywhere and never navigate through the login UI in tests.
510 
511```typescript
512// page-objects/LoginPage.ts
513import { type Page, type Locator, expect } from "@playwright/test";
514 
515export class LoginPage {
516  readonly page: Page;
517  readonly usernameInput: Locator;
518  readonly passwordInput: Locator;
519  readonly loginButton: Locator;
520  readonly errorMessage: Locator;
521  readonly forgotPasswordLink: Locator;
522 
523  constructor(page: Page) {
524    this.page = page;
525    this.usernameInput = page.getByLabel("Username");
526    this.passwordInput = page.getByLabel("Password");
527    this.loginButton = page.getByRole("button", { name: "Log in" });
528    this.errorMessage = page.getByRole("alert");
529    this.forgotPasswordLink = page.getByRole("link", {
530      name: "Forgot password",
531    });
532  }
533 
534  async goto() {
535    await this.page.goto("/login");
536    await expect(this.loginButton).toBeVisible();
537  }
538 
539  async login(username: string, password: string) {
540    await this.usernameInput.fill(username);
541    await this.passwordInput.fill(password);
542    await this.loginButton.click();
543  }
544 
545  async loginAndWaitForHome(username: string, password: string) {
546    await this.login(username, password);
547    await this.page.waitForURL("/home");
548  }
549 
550  async expectError(message: string | RegExp) {
551    await expect(this.errorMessage).toContainText(message);
552  }
553 
554  async expectFieldError(field: "username" | "password", message: string) {
555    const input =
556      field === "username" ? this.usernameInput : this.passwordInput;
557    await expect(input).toHaveAttribute("aria-invalid", "true");
558    const errorId = await input.getAttribute("aria-describedby");
559    if (errorId) {
560      await expect(this.page.locator(`#${errorId}`)).toContainText(message);
561    }
562  }
563}
564```
565 
566```typescript
567// tests/login.spec.ts
568import { test, expect } from "@playwright/test";
569import { LoginPage } from "../page-objects/LoginPage";
570 
571test.use({ storageState: { cookies: [], origins: [] } });
572 
573test.describe("login page", () => {
574  let loginPage: LoginPage;
575 
576  test.beforeEach(async ({ page }) => {
577    loginPage = new LoginPage(page);
578    await loginPage.goto();
579  });
580 
581  test("successful login redirects to home", async ({ page }) => {
582    await loginPage.loginAndWaitForHome(
583      "[email protected]",
584      "secretPass123"
585    );
586    await expect(page.getByRole("heading", { name: "Home" })).toBeVisible();
587  });
588 
589  test("wrong password shows error", async () => {
590    await loginPage.login("[email protected]", "wrong-password");
591    await loginPage.expectError("Invalid username or password");
592  });
593 
594  test("empty fields show validation errors", async () => {
595    await loginPage.loginButton.click();
596    await loginPage.expectFieldError("username", "Username is required");
597  });
598 
599  test("forgot password link navigates correctly", async ({ page }) => {
600    await loginPage.forgotPasswordLink.click();
601    await page.waitForURL("/forgot-password");
602    await expect(
603      page.getByRole("heading", { name: "Reset password" })
604    ).toBeVisible();
605  });
606});
607```
608 
609### API-Based Login
610 
611**Use when**: You want the fastest possible authentication without any browser interaction.
612**Avoid when**: You are specifically testing the login UI.
613 
614API login is typically 5-10x faster than UI login.
615 
616```typescript
617// global-setup.ts — API-based login (fastest)
618import { request, type FullConfig } from "@playwright/test";
619 
620async function globalSetup(config: FullConfig) {
621  const { baseURL } = config.projects[0].use;
622 
623  const requestContext = await request.newContext({ baseURL });
624 
625  const response = await requestContext.post("/api/auth/login", {
626    data: {
627      email: process.env.TEST_USER_EMAIL!,
628      password: process.env.TEST_USER_PASSWORD!,
629    },
630  });
631 
632  if (!response.ok()) {
633    throw new Error(
634      `API login failed: ${response.status()} ${await response.text()}`
635    );
636  }
637 
638  await requestContext.storageState({ path: ".auth/session.json" });
639  await requestContext.dispose();
640}
641 
642export default globalSetup;
643```
644 
645```typescript
646// fixtures/api-auth.ts — fixture version for per-test authentication
647import { test as base } from "@playwright/test";
648 
649export const test = base.extend({
650  authenticatedPage: async ({ browser, playwright }, use) => {
651    const apiContext = await playwright.request.newContext({
652      baseURL: "http://localhost:4000",
653    });
654 
655    await apiContext.post("/api/auth/login", {
656      data: {
657        email: "[email protected]",
658        password: "secretPass123",
659      },
660    });
661 
662    const state = await apiContext.storageState();
663    const context = await browser.newContext({ storageState: state });
664    const page = await context.newPage();
665 
666    await use(page);
667 
668    await context.close();
669    await apiContext.dispose();
670  },
671});
672 
673export { expect } from "@playwright/test";
674```
675 
676### Unauthenticated Tests
677 
678**Use when**: Testing the login page, signup flow, password reset, public pages, or redirect behavior for unauthenticated users.
679**Avoid when**: The test requires a logged-in user.
680 
681When your config sets a default `storageState`, you must explicitly clear it for unauthenticated tests.
682 
683```typescript
684// tests/public-pages.spec.ts
685import { test, expect } from "@playwright/test";
686 
687test.use({ storageState: { cookies: [], origins: [] } });
688 
689test.describe("unauthenticated access", () => {
690  test("homepage is accessible without login", async ({ page }) => {
691    await page.goto("/");
692    await expect(page.getByRole("heading", { name: "Welcome" })).toBeVisible();
693    await expect(page.getByRole("link", { name: "Log in" })).toBeVisible();
694  });
695 
696  test("protected route redirects to login", async ({ page }) => {
697    await page.goto("/home");
698    await page.waitForURL("**/login**");
699    expect(page.url()).toContain("redirect=%2Fhome");
700  });
701 
702  test("expired session shows re-login prompt", async ({ page, context }) => {
703    await page.goto("/home");
704    await context.clearCookies();
705 
706    await page.goto("/settings");
707    await page.waitForURL("**/login**");
708    await expect(page.getByText("Your session has expired")).toBeVisible();
709  });
710 
711  test("signup flow creates account", async ({ page }) => {
712    await page.goto("/signup");
713    await page.getByLabel("Name").fill("New User");
714    await page.getByLabel("Email").fill(`test-${Date.now()}@example.com`);
715    await page.getByLabel("Password", { exact: true }).fill("secretPass123");
716    await page.getByLabel("Confirm password").fill("secretPass123");
717    await page.getByRole("button", { name: "Create account" }).click();
718 
719    await page.waitForURL("/onboarding");
720    await expect(page.getByText("Welcome, New User")).toBeVisible();
721  });
722});
723```
724 
725## Decision Guide
726 
727| Scenario                         | Approach                       | Speed    | Isolation      | When to Choose                                                 |
728| -------------------------------- | ------------------------------ | -------- | -------------- | -------------------------------------------------------------- |
729| Most tests need auth             | Global setup + `storageState`  | Fastest  | Shared session | Default for nearly every project                               |
730| Tests modify user state          | Per-worker fixture             | Fast     | Per worker     | Tests update profile, change settings, or mutate data          |
731| Multiple user roles              | Per-project `storageState`     | Fastest  | Per role       | App has admin/member/guest roles                               |
732| Testing the login page           | No `storageState`              | N/A      | Full           | Use `test.use({ storageState: { cookies: [], origins: [] } })` |
733| OAuth/SSO provider               | Mock the callback              | Fast     | Per test       | Never hit real OAuth providers in CI                           |
734| MFA is required                  | TOTP generation or bypass      | Moderate | Per test       | Generate real TOTP codes or use a test-mode bypass             |
735| Token expires mid-suite          | Session refresh fixture        | Fast     | Per check      | Fixture validates the session before use                       |
736| Single test needs different user | `loginAs(role)` fixture        | Moderate | Per call       | Rare: prefer per-project roles                                 |
737| API-first app (no login UI)      | API login via `request.post()` | Fastest  | Per test       | No browser needed for auth                                     |
738 
739### UI Login vs API Login vs Storage State
740 
741```text
742Need to test the login page itself?
743├── Yes → UI login with LoginPage POM, no storageState
744└── No → Do you have a login API endpoint?
745    ├── Yes → API login in global setup, save storageState (fastest)
746    └── No → UI login in global setup, save storageState
747              └── Tokens expire quickly?
748                  ├── Yes → Add session refresh fixture
749                  └── No → Standard storageState reuse is fine
750```
751 
752## Anti-Patterns
753 
754| Don't Do This                                                             | Problem                                     | Do This Instead                                                           |
755| ------------------------------------------------------------------------- | ------------------------------------------- | ------------------------------------------------------------------------- |
756| Log in via UI before every test                                           | Adds 2-5 seconds per test                   | Use `storageState` to skip login entirely                                 |
757| Share a single auth state file across parallel workers that mutate state  | Race conditions                             | Use per-worker fixtures with `{ scope: 'worker' }`                        |
758| Hardcode credentials in test files                                        | Security risk                               | Use environment variables and `.env` files                                |
759| Ignore token expiration                                                   | Tests fail intermittently with 401 errors   | Add a session validity check in your auth fixture                         |
760| Hit real OAuth providers in CI                                            | Flaky: rate limits, CAPTCHA, network issues | Mock the OAuth callback or use API session injection                      |
761| Use `page.waitForTimeout(2000)` after login                               | Arbitrary delay                             | `await page.waitForURL('/home')` or `await expect(heading).toBeVisible()` |
762| Store `.auth/*.json` files in git                                         | Tokens in version control                   | Add `.auth/` to `.gitignore`                                              |
763| Create one "god" test account with all permissions                        | Cannot test role-based access control       | Create separate accounts per role                                         |
764| Use `browser.newContext()` without `storageState` for authenticated tests | Every context starts unauthenticated        | Pass `storageState` when creating the context                             |
765| Test MFA by disabling it everywhere                                       | You never test the MFA flow                 | Use TOTP generation for at least one test                                 |
766 
767## Troubleshooting
768 
769### Global setup fails with "Target page, context or browser has been closed"
770 
771**Cause**: The login page redirected unexpectedly, or the browser closed before `storageState()` was called.
772 
773**Fix**:
774 
775- Add `await page.waitForURL()` after the login action
776- Check that `baseURL` in your config matches the actual server URL and protocol
777- Add error handling to global setup:
778 
779```typescript
780const response = await page.waitForResponse("**/api/auth/**");
781if (!response.ok()) {
782  throw new Error(
783    `Login failed in global setup: ${response.status()} ${await response.text()}`
784  );
785}
786```
787 
788### Tests fail with 401 Unauthorized after running for a while
789 
790**Cause**: The session token saved in `storageState` has expired.
791 
792**Fix**:
793 
794- Use the session refresh fixture pattern
795- Increase token expiry in test environment configuration
796- Switch to API-based login in a worker-scoped fixture
797 
798### `storageState` file is empty or contains no cookies
799 
800**Cause**: `storageState()` was called before the login response set cookies.
801 
802**Fix**:
803 
804- Wait for the post-login page to load: `await page.waitForURL('/home')`
805- Verify cookies exist before saving:
806 
807```typescript
808const cookies = await context.cookies();
809if (cookies.length === 0) {
810  throw new Error("No cookies found after login");
811}
812await context.storageState({ path: ".auth/session.json" });
813```
814 
815### Different browsers get different cookies
816 
817**Cause**: Some auth flows set cookies with `SameSite=Strict` or use browser-specific cookie behavior.
818 
819**Fix**:
820 
821- Generate separate auth state files per browser project
822- Check if your auth uses `SameSite=None; Secure` cookies that require HTTPS:
823 
824```typescript
825projects: [
826  {
827    name: 'chromium',
828    use: { ...devices['Desktop Chrome'], storageState: '.auth/chromium-session.json' },
829  },
830  {
831    name: 'firefox',
832    use: { ...devices['Desktop Firefox'], storageState: '.auth/firefox-session.json' },
833  },
834],
835```
836 
837### Parallel tests interfere with each other's sessions
838 
839**Cause**: Multiple workers share the same test account and one worker's actions affect others.
840 
841**Fix**:
842 
843- Use per-worker test accounts: `worker-${test.info().parallelIndex}@example.com`
844- Use the per-worker authentication fixture pattern
845- Make tests idempotent
846 
847### OAuth mock does not work — still redirects to real provider
848 
849**Cause**: `page.route()` was registered after the navigation that triggers the OAuth redirect.
850 
851**Fix**:
852 
853- Register route handlers before any navigation: call `page.route()` before `page.goto()`
854- Log the actual redirect URL to verify the pattern:
855 
856```typescript
857page.on("request", (req) => {
858  if (req.url().includes("oauth") || req.url().includes("accounts.provider")) {
859    console.log("OAuth request:", req.url());
860  }
861});
862```
863 
864## Related
865 
866- [fixtures-hooks.md](../core/fixtures-hooks.md) — custom fixtures for auth setup and teardown
867- [configuration.md](../core/configuration.md) — `storageState`, projects, and global setup configuration
868- [global-setup.md](../core/global-setup.md) — global setup patterns and project dependencies
869- [network-advanced.md](network-advanced.md) — route interception patterns used in OAuth mocking
870- [api-testing.md](../testing-patterns/api-testing.md) — API request context used in API-based login
871- [flaky-tests.md](../debugging/flaky-tests.md) — diagnosing auth-related flakiness
872