E2E Testing

Playwright Test against the real application — real server, real browser, real data.

Conventions

• Tests live in e2e/ at the project root, NOT co-located with source

• Authenticated tests: e2e/flow-name.spec.ts — run with saved session automatically

• Unauthenticated tests: e2e/flow-name.unauth.spec.ts — fresh browser, no session

• Run with bun run e2e

• Test data lives in e2e/seeds/ as JSON files

• Import test from ./utils (shared fixture), expect from @playwright/test

import { expect } from "@playwright/test"; import { test } from "./utils";

The shared test fixture waits for [data-hydrated] after every page.goto() — buttons and handlers are ready immediately.

Playwright API

API Use

page.goto("/path")

Navigate to URL

page.getByRole("button", { name })

Query by ARIA role

page.getByText("text")

Query by text content

page.getByLabel("label")

Query by form label

locator.click()

Click interaction

locator.fill("value")

Type into input

expect(page).toHaveURL(pattern)

Assert current URL

expect(locator).toBeVisible()

Assert element visible

page.waitForURL(pattern)

Wait for navigation

page.context().storageState()

Save auth state

E2E vs Component Test

Scenario Test type

Multi-step user flow across pages E2E

Authentication and authorization E2E

CRUD lifecycle E2E

API integration across pages E2E

Isolated UI component behavior Component

Form validation feedback Component

Component state management Component

Rule of thumb: involves chained steps across the real app → E2E. Tests isolated UI behavior → component test.

Examples

See examples/ for complete test examples by pattern:

Example When to use

examples/navigation.md

Page transitions, link clicks, URL assertions

examples/form-submission.md

Form fills, submissions, validation

examples/crud-flow.md

Create, edit, delete lifecycle

examples/auth-persistence.md

Login setup, session reuse, unauthenticated tests

Acceptance Checklist

• Test lives in e2e/ directory

• Uses correct extension: .spec.ts (authenticated) or .unauth.spec.ts (unauthenticated)

• Imports test from ./utils , expect from @playwright/test

• Tests a real user flow, not isolated component behavior

• Uses seed data from e2e/seeds/ when needed

• No manual hydration waits (fixture handles it)

• Tests behavior, not implementation details