Authentication State and Browser Projects

Required tools

• Node.js (20.x or 22.x LTS)
• @playwright/test (1.62.x)
• A terminal (any)

Setup

1. Continue from the pw-learning-lab project created in this course's first guided local lab (or recreate it if starting fresh).
2. Add a tests-setup/ folder for the authentication setup project.
3. Pick any real, publicly-accessible site with a login form you're comfortable using for practice (or use a local test app if you have one) — this lab's file structure assumes a generic login form.

Project structure

pw-learning-lab/
  playwright.config.ts
  tests-setup/
    auth.setup.ts
  tests/
    dashboard.spec.ts
  playwright/.auth/
    user.json (generated, not committed)

Starter files

import { test as setup, expect } from "@playwright/test";

const authFile = "playwright/.auth/user.json";

setup("authenticate once", async ({ page }) => {
  // TODO: navigate to your chosen site's login page
  // TODO: fill in credentials using environment variables (process.env.TEST_USER / process.env.TEST_PASS),
  //       never hard-coded real credentials
  // TODO: submit and assert something confirming a successful sign-in
  // TODO: await page.context().storageState({ path: authFile });
});

import { test, expect } from "@playwright/test";

test("an already-authenticated page shows signed-in content", async ({ page }) => {
  // TODO: navigate directly to a page that requires authentication --
  // this test should start ALREADY signed in, via the project's storageState
  // TODO: assert something that only appears when signed in
});

Requirements

• auth.setup.ts reads credentials from environment variables, never hard-coded literals.
• auth.setup.ts saves storageState to playwright/.auth/user.json after a real, successful sign-in.
• playwright.config.ts defines a 'setup' project and at least one other project with `dependencies: ['setup']` and `use: { storageState: 'playwright/.auth/user.json' }`.
• dashboard.spec.ts uses only role-based locators (getByRole/getByLabel/getByText), no structural CSS/XPath selectors.
• playwright/.auth/ is added to .gitignore so the saved session is never committed.

Commands to run

• Set credentials for this session only (not committed anywhere)

  export TEST_USER=your-test-username TEST_PASS=your-test-password

• Run the full suite (setup runs automatically first, via dependencies)

  npx playwright test

Expected behavior

Running `npx playwright test` runs the setup project first (a real sign-in, producing playwright/.auth/user.json), then runs dashboard.spec.ts already signed in, with no login-form interaction inside that test at all.

Verify it yourself

• npx playwright test

  Expected: The setup project passes, then dashboard.spec.ts passes without ever visiting the login page

• cat playwright/.auth/user.json

  Expected: A real JSON file containing cookies/storage state now exists locally

• git status

  Expected: playwright/.auth/ does NOT appear as untracked — confirms .gitignore is working

Troubleshooting

• dashboard.spec.ts still shows signed-out content — Confirm the project running dashboard.spec.ts actually declares `dependencies: ['setup']` and `use: { storageState: ... }` pointing at the same path auth.setup.ts wrote to.
• `Error: TEST_USER is not defined` — Export the environment variables in the same terminal session before running the tests — they are never hard-coded in the committed files.
• storageState file is empty or missing expected cookies — Confirm auth.setup.ts's assertion after submitting genuinely confirms a signed-in state BEFORE calling storageState() — capturing state before sign-in actually completes saves a signed-out session.

Extension challenge

Add a second, deliberately anonymous project (no storageState) running a dedicated login.spec.ts that tests the sign-in flow itself for real — confirming the pattern from this lesson: storageState is an optimization for tests that aren't about login, not a replacement for testing login at all.