playwright-test

Playwright Test

Instructions

Create Playwright end-to-end tests for Next.js pages based on the use case $ARGUMENTS. Playwright tests run in a real browser against the running application with a real database via Testcontainers.

End-to-end means end-to-end. Each test walks the complete user journey from entry point to final outcome — exactly as a real user would. Tests navigate by clicking links and buttons, not by jumping to internal URLs. If a real user must click three screens to reach a form, the test clicks through those same three screens.

Inputs

Input	Location	Required
Use case specification	docs/use_cases/UC-XXX.md	Yes
Frontend design	docs/designs/UC-XXX-design.html	Yes

The use case specification defines what the system does (scenarios, alternative flows, business rules). The frontend design defines how it looks and behaves (screens, components, states, user actions, navigation flow). Together they determine the test scenarios and assertions:

• Test scenarios derive from the use case Main Success Scenario and Alternative Flows
• Page structure and selectors derive from the frontend design's Components and Layout sections
• Assertions derive from the frontend design's States (default, loading, empty, error, success) and Data Displayed sections
• User interactions derive from the frontend design's User Actions (triggers, results)
• Navigation expectations derive from the frontend design's Navigation Flow and Screen Map

If docs/designs/$ARGUMENTS-design.html does not exist, stop and tell the user to run /design-screens $ARGUMENTS first.

Test Philosophy: Journeys, Not Fragments

The purpose of E2E tests is to verify that the complete user journey works end-to-end. Each test represents one path through the use case — either the Main Success Scenario or an Alternative Flow.

How many tests per use case:

• 1 test for the Main Success Scenario (the happy path, all steps start to finish)
• 1 test per Alternative Flow that diverges meaningfully from the MSS
• Business rules are verified inline within the journey they belong to, not as separate tests

A typical use case produces 3–8 tests total, not dozens.

What makes it E2E:

• The test starts at the application's entry point (e.g., landing page, login screen)
• Every navigation happens through UI interactions (clicks, form submissions) — never page.goto() to internal pages
• The test verifies intermediate states along the way, not just the final outcome
• The test verifies Postconditions:
  • For success flows: data is visible and correctly stored in the system.
  • For failure flows: the system state remains unchanged (e.g., no partial records created, original values preserved). Use API calls in afterEach or inline to verify deep system state if UI-only verification is insufficient.
• The test ends with a verifiable outcome (data visible, confirmation shown, redirect happened)

page.goto() is only used ONCE per test — to open the application entry point (e.g., page.goto('/') or page.goto('/login')). All subsequent navigation must happen through the UI.

Traceability Convention

E2E tests use the helper at e2e/helpers/traced.ts to link each test to its use case, change requests, and bug fixes. Use Cases are grouped with raw test.describe(...) (not a custom wrapper) so IDE plugins (WebStorm/IntelliJ, VSCode Playwright) can walk into the block and show gutter run icons for each test inside.

The helper exports three functions:

• uc(id) — returns the { tag } options object for test.describe(). Validates the UC doc exists.
• meta(uc, { scenario, verifies?, fixes? }) — returns Playwright's { tag, annotation } second-arg object for a test inside the describe. Validates referenced CR/BUG docs exist.
• bug(id) — same shape, for a pure bug regression test that has no clean UC home. Validates the BUG doc exists.

Anchor each UC group with test.describe(...) and uc(...):

import { test, expect } from '@playwright/test';
import { uc, meta } from './helpers/traced';

test.describe('UC-XXX: [Use Case Name]', uc('UC-XXX'), () => {
  test('[end-to-end journey description]',
    meta('UC-XXX', {
      scenario: 'MSS',
      verifies: ['CR-NNN'], // optional: change requests this test asserts the delta of
      fixes: ['BUG-NNN'],   // optional: bugs this test guards against regressing
    }),
    async ({ page }) => {
      // ... test body
    });

  test('[alternative flow description]',
    meta('UC-XXX', { scenario: 'AF-1' }),
    async ({ page }) => {
      // ... test body
    });
});

Multiple UCs per file (when journeys share a page or flow): one top-level test.describe(...) block per UC.

Pure bug regression tests (no clean UC home) — file bug-NNN-*.spec.ts:

import { test, expect } from '@playwright/test';
import { bug } from './helpers/traced';

test('[regression description]', bug('BUG-NNN'), async ({ page }) => {
  // ... test body
});

Scenario types (the required scenario field on meta('UC-NNN', {...})):

• 'MSS' — Main Success Scenario (one per UC)
• 'AF-N' — Alternative Flow N (e.g., 'AF-1', 'AF-2')
• 'EX-N' — Exception path N

The helper validates that referenced UCs, CRs, and BUGs exist as files under docs/use_cases/, docs/change_requests/, and docs/bugs/ at registration time. A typo'd CR-002 fails before any browser starts.

Why raw test.describe() instead of a custom wrapper: JetBrains' Playwright plugin (and the VSCode equivalent) only walks test() and test.describe() calls — it does not enter callbacks of arbitrary helper functions. A useCase() wrapper that calls test.describe() internally works at runtime but hides the inner tests from the IDE's AST walker. Keeping test.describe(...) literally in source is what makes gutter run/debug icons appear for each test.

The UC id is repeated three times per describe (title, uc(), each meta()). This is intentional: a single source of truth would require either fragile module-level state or a wrapper the IDE can't see into.

Inline comments — when a single line/assertion exists because of a CR or BUG, leave a one-line marker comment so a code reader sees it without reading tags:

// CR-003: month/year picker
await page.locator('input[type="month"]').first().fill('2025-06');

// Verifies BR-001: [Rule Name]
await expect(page.getByText('Error')).toBeVisible();

// Verifies Success Postcondition: [Postcondition Name]
await expect(page.locator('table')).toContainText(['New Item']);

DO NOT

• Navigate with page.goto() to internal pages — only use page.goto() once per test to open the entry point. All other navigation must happen through clicking links, buttons, and submitting forms. This is the most important rule: if you bypass navigation, you are not testing E2E
• Write one test per step or per screen — each test must cover the full journey. A test that only checks "form displays correctly" is not an E2E test
• Create separate tests for business rules — verify business rules inline within the journey where they apply
• Run tests on multiple browsers — use Chromium only. The playwright.config.ts must have exactly one project
• Access the database directly in tests — use the test API endpoints (/api/e2e/users) instead
• Use waitForLoadState('networkidle') — it waits for zero network activity for 500ms, but Next.js dev-server HMR websockets, analytics pings, and prefetch requests can delay or prevent it from settling, causing flaky timeouts in CI. Instead, wait for the specific UI element that signals the page is ready (a heading, a table row, a form field)
• Skip waiting for page loads or network requests to complete
• Use hard-coded delays (page.waitForTimeout) instead of proper waits
• Delete all data in cleanup (only remove data created during the test)
• Hard-code database connection strings — DATABASE_URL is injected by global setup
• Write tests that contradict the frontend design (e.g., asserting a table when the design specifies cards)
• Skip, exclude, or filter out tests — never use --grep-invert, --grep, test.skip(), test.fixme(), or any other mechanism to avoid running tests. All tests must run and pass
• Claim tests pass without verifying output — you must check the actual Playwright output for "X passed" and "0 failed" before declaring success
• Sleep or wait between test retries — when tests fail, diagnose and fix the root cause immediately, then re-run. Never use sleep, setTimeout, or any delay between retry attempts. The fix-then-rerun cycle must be immediate
• Ignore or work around database-dependent tests — Testcontainers provides the database; if Docker is not running, stop and tell the user instead of skipping DB tests
• Write no-op or trivially-true tests — every test must contain meaningful assertions that would fail if the feature were broken (e.g., never assert expect(true).toBe(true) or assert only that a page loads without checking content)
• Register a test or describe without the helper — every test(...) call in an E2E spec must be tagged via meta('UC-NNN', { scenario, ... }) (inside a test.describe) or bug('BUG-NNN') (pure regression, module scope). Every UC test.describe(...) must pass uc('UC-NNN') as its second arg. Raw test('title', async (...) => ...) or test.describe('title', () => {...}) with no helper metadata is a violation — it loses the traceability link, the HTML report annotation, and the registration-time doc validation

Nexa Rules Gate

Read and follow ${CLAUDE_PLUGIN_ROOT}/shared/readiness/NEXA_RULES_GATE.md.

Sprint Branch Gate

Read and follow ${CLAUDE_PLUGIN_ROOT}/shared/readiness/SPRINT_BRANCH_GATE.md.

Test User Provisioning

Every E2E test requires an authenticated user. User provisioning operates at two levels:

Suite-Level User (default)

Each test file provisions one shared user for all tests in the file. This user is a standard, fully-valid user suitable for happy-path scenarios.

Lifecycle (managed via test.beforeAll / test.afterAll):

1. Before all tests: Create a user directly in the database via the test API endpoint:
   • Email: e2e-{random8chars}@example.com
   • Password: bcrypt-hashed (plaintext stored in a variable for login)
   • account_type: as needed by the use case (default to the most common type)
   • status: "ACTIVE"
   • email_confirmed: true
   • All consent flags: true
   • auth_provider: "EMAIL"
   • created_at / updated_at: current timestamp
2. After each test: Clear cookies and storage to prevent session leakage between tests.
3. After all tests: Delete the user and all related records via the test API endpoint.

Per-Test User Override

Individual tests that need a user with different characteristics (e.g., inactive status, unconfirmed email, a different account type) provision their own user, overriding the suite-level user.

Lifecycle (managed via test.beforeEach / test.afterEach or inline):

1. Before the test: Create a custom user directly in the database via the test API endpoint:
   • Email: e2e-{random8chars}@example.com
   • Password: bcrypt-hashed (plaintext stored in a variable for login)
   • account_type: as needed by the specific test scenario
   • status: as needed by the test scenario (e.g., "SUSPENDED", "PENDING")
   • email_confirmed: as needed (e.g., false for unconfirmed-email flows)
   • All consent flags: true
   • auth_provider: "EMAIL"
   • created_at / updated_at: current timestamp
2. Start of test: Log in as this custom user via the login page UI.
3. After the test: Delete this custom user and all related records via the test API endpoint (use finally blocks to ensure cleanup runs even on failure). Cookies are cleared by the suite-level afterEach.

Test API Endpoint

The application must expose a test-only API endpoint for user provisioning and cleanup. This endpoint is only available when NODE_ENV=test:

• POST /api/e2e/users — Creates a user in the database. Accepts the user fields above. Returns the created user with id.
• DELETE /api/e2e/users/:id — Deletes the user and all related records (cascade).

If this endpoint does not exist in the project, create it before writing tests. Use the template at templates/e2e-users-api.ts.

Test User Helper

Use the helper at templates/test-user.ts to provision and clean up users. If e2e/helpers/test-user.ts does not exist, create it from the template.

Other Test Data

Approach	Location	Purpose
Prisma seed	prisma/seed.ts	Baseline reference data (non-user)
API calls	Within test setup	Test-specific entity data
Manual cleanup	afterEach hooks	Remove data created during test

Test Data Conventions

• Use only example.com for test emails and accounts (e.g., [email protected], [email protected]). This is an IANA-reserved domain that will never route real mail.

Testcontainers Global Setup

Before writing tests, ensure the project has a global setup file that starts a PostgreSQL Testcontainer, runs Prisma migrations, and seeds the database. The dev server is handled separately by Playwright's webServer option.

If e2e/global-setup.ts does not exist, create it using templates/global-setup.ts.

.env.e2e — Single Source of Truth

All E2E test environment variables live in a .env.e2e file at the project root. The global setup loads it via dotenv, and the webServer command sources it before starting the dev server. This eliminates dynamic env file generation and scattered env: blocks.

NODE_ENV=test
DATABASE_URL=postgresql://test:test@localhost:5432/testdb
DIRECT_URL=postgresql://test:test@localhost:5432/testdb
NEXT_PUBLIC_APP_URL=http://localhost:3000
AUTH_SECRET=test-secret-for-vitest-at-least-32-characters-long
AUTH_URL=http://localhost:3000
E2E_TEST=true

Add project-specific env vars as needed. Commit this file (add !.env.e2e to .gitignore if .env* is ignored).

Playwright Configuration

Single browser only — use Chromium. Do NOT add Firefox or WebKit projects. Cross-browser testing is not the purpose of E2E tests; verifying user journeys is.

import { defineConfig, devices } from '@playwright/test';

export default defineConfig({
  testDir: './e2e',
  globalSetup: './e2e/global-setup.ts',
  globalTeardown: './e2e/global-teardown.ts',
  fullyParallel: false,
  forbidOnly: !!process.env.CI,
  retries: process.env.CI ? 2 : 0,
  workers: process.env.CI ? 3 : 6,
  reporter: 'html',
  use: {
    baseURL: 'http://localhost:3000',
    trace: 'on-first-retry',
  },
  webServer: {
    // .env.e2e is the single source of truth for E2E test env vars.
    // `set -a` exports all sourced vars into the process environment.
    command: 'bash -c \'set -a; source .env.e2e; set +a; exec npx next dev\'',
    url: 'http://localhost:3000',
    reuseExistingServer: false,
    timeout: 60_000,
  },
  projects: [
    {
      name: 'chromium',
      use: { ...devices['Desktop Chrome'] },
    },
    // Do NOT add firefox or webkit — single browser only for E2E
  ],
});

Templates

• Global setup: templates/global-setup.ts
• Global teardown: templates/global-teardown.ts
• Test user helper: templates/test-user.ts
• E2E users API endpoint: templates/e2e-users-api.ts
• Test example: templates/example.spec.ts
• Traceability helper: templates/traced.ts — copy verbatim into the project at e2e/helpers/traced.ts. Do not modify; a future plugin update may bring fixes.

Common Patterns

Suite-Level User Provisioning

import { test, expect } from '@playwright/test';
import { createTestUser, deleteTestUser, type TestUser } from './helpers/test-user';

let suiteUser: TestUser;

test.beforeAll(async ({ request }) => {
  // Create the suite-level user via test API
  suiteUser = await createTestUser(request, { accountType: 'BUYER' });
});

test.afterEach(async ({ context }) => {
  // Clear cookies and storage between tests to prevent session leakage
  await context.clearCookies();
});

test.afterAll(async ({ request }) => {
  await deleteTestUser(request, suiteUser.id);
});

Login via UI (start of each test)

test.describe('UC-XXX: [Use Case Name]', uc('UC-XXX'), () => {
  test('user signs in and lands on dashboard',
    meta('UC-XXX', { scenario: 'MSS' }),
    async ({ page }) => {
      // Start at login — the ONLY page.goto() allowed
      await page.goto('/login');
      await expect(page.getByLabel('Email')).toBeVisible();

      // Log in as the suite user
      await page.getByLabel('Email').fill(suiteUser.email);
      await page.getByLabel('Password').fill(suiteUser.plainPassword);
      await page.getByRole('button', { name: 'Sign in' }).click();
      await expect(page.getByRole('heading', { name: 'Dashboard' })).toBeVisible();

      // ... continue the journey
    });
});

Per-Test User Override

test.describe('UC-XXX: [Use Case Name]', uc('UC-XXX'), () => {
  test('suspended user sees account-locked screen',
    meta('UC-XXX', { scenario: 'AF-2' }),
    async ({ page, request }) => {
      // Create a custom user for this test
      const suspendedUser = await createTestUser(request, {
        accountType: 'BUYER',
        status: 'SUSPENDED',
      });

      try {
        await page.goto('/login');
        await expect(page.getByLabel('Email')).toBeVisible();
        await page.getByLabel('Email').fill(suspendedUser.email);
        await page.getByLabel('Password').fill(suspendedUser.plainPassword);
        await page.getByRole('button', { name: 'Sign in' }).click();

        // Verify suspended user sees the locked screen
        await expect(page.getByText('Account suspended')).toBeVisible();
      } finally {
        // Always clean up the per-test user
        await deleteTestUser(request, suspendedUser.id);
      }
    });
});

Entry Point — the only page.goto() in the test

// Start at the application entry point — the ONLY page.goto() allowed
await page.goto('/');
await expect(page.getByRole('heading')).toBeVisible();

Navigate Through the UI (never via URL)

// Click a navigation link to reach the next screen
await page.getByRole('link', { name: 'Items' }).click();
await expect(page.getByRole('heading', { name: 'Items' })).toBeVisible();

// Click a button to open a form/modal
await page.getByRole('button', { name: 'Add New' }).click();

// Click a table row to navigate to detail
await page.locator('table tbody tr').first().click();
await expect(page.getByRole('heading')).toContainText('Item Details');

Verify Intermediate State Along the Journey

// After navigating to the list screen, verify it loaded correctly
const rows = page.locator('table tbody tr');
await expect(rows.first()).toBeVisible();
await expect(rows).toHaveCount(10);

// Then continue the journey...
await page.getByRole('button', { name: 'Create' }).click();

Form Interactions

await page.getByLabel('Name').fill('Test Value');
await page.getByLabel('Category').selectOption('option-1');
await page.getByLabel('Active').check();
await page.getByRole('button', { name: 'Save' }).click();

Verify Final Outcome

// After form submission, verify the result is visible
await expect(page.getByText('Item created successfully')).toBeVisible();
await expect(page.locator('table tbody tr')).toContainText(['Test Value']);

Cleanup Entity Data Created During Test

// Clean up non-user test data via API at end of test
await page.request.delete(`/api/examples/${createdId}`);

Dialog Interactions

page.on('dialog', dialog => dialog.accept());
await page.getByRole('dialog').getByRole('button', { name: 'Confirm' }).click();

Assertions Reference

Assertion Type	Example
Text content	await expect(locator).toHaveText('Expected')
Input value	await expect(locator).toHaveValue('value')
Element count	await expect(locator).toHaveCount(5)
Visibility	await expect(locator).toBeVisible()
URL	await expect(page).toHaveURL('/path')
Enabled	await expect(locator).toBeEnabled()
Contains text	await expect(locator).toContainText('partial')

Tracking

Read and follow the Before Implementation steps in ${CLAUDE_PLUGIN_ROOT}/shared/tracking/TRACKING.md.

Workflow

1. Read the use case specification from docs/use_cases/
2. Read the frontend design from docs/designs/ — extract screens, components, states, and navigation flow
3. Plan the journeys — map each test to a complete path through the application:
   • One test for the MSS: entry point → each screen in sequence → final outcome
   • One test per AF that diverges from the MSS
   • Note the entry point URL (the only page.goto() allowed) and every UI interaction needed to complete each journey
   • Identify which business rules are verified inline within each journey
4. Use TodoWrite to create a task for each journey test (expect 3–8 tests total, not dozens)
5. Ensure Testcontainers global setup exists (e2e/global-setup.ts); create from template if missing
6. Ensure global teardown exists (e2e/global-teardown.ts); create from template if missing
7. Ensure playwright.config.ts references the global setup/teardown and has only Chromium (one project)
8. Ensure the test user helper exists (e2e/helpers/test-user.ts); create from template if missing
9. Ensure the traceability helper exists (e2e/helpers/traced.ts); create from templates/traced.ts if missing. Do not modify the template.
10. Ensure the E2E users API endpoint exists (app/api/e2e/users/route.ts and app/api/e2e/users/[id]/route.ts); create from template if missing
11. Create test file using the template. Group every UC's tests in a top-level test.describe('UC-NNN: ...', uc('UC-NNN'), () => {...}), and pass meta('UC-NNN', { scenario, ... }) (or bug('BUG-NNN') for pure regressions) as each test's second arg (see Traceability Convention)
12. For each journey test:
    • Set up suite-level user in test.beforeAll (create via test API, log in via UI)
    • For tests needing a custom user, create a per-test user override (see Common Patterns)
    • Read the spec for the use case and identify which CR-NNN and BUG-NNN IDs (if any) the test verifies — populate the verifies and fixes arrays in the meta(...) call accordingly
    • page.goto() to the login page (the only goto in the test), log in via UI
    • After every navigation or action that loads a new page, wait for a specific UI element (heading, table row, form field) — never waitForLoadState('networkidle')
    • Navigate through each screen by clicking links, buttons, and submitting forms
    • Verify intermediate states along the way (page loaded, data displayed, form visible)
    • Perform the key interactions (fill forms, click actions, confirm dialogs)
    • Assert the final outcome (success message, data in list, redirect to expected page)
    • Clean up test-specific entity data if created during test
    • Clean up per-test override users in finally blocks or test.afterEach
    • Clear cookies and storage in test.afterEach to prevent session leakage between tests
    • Delete suite user in test.afterAll
13. Run the /code-quality skill
14. Run all tests with npx playwright test (no filters, no --grep, no --grep-invert, no --project subset)
15. Verify the test results — this is mandatory before declaring success:
    • The Playwright output must show 0 failed and the exit code must be 0
    • If the output shows failures, timeouts, or errors, the tests did not pass — do not claim otherwise
    • Count the number of passed tests and confirm it matches the number of tests you wrote
    • If any test is skipped, that counts as a failure — investigate and fix it
    • If a test failure reveals a route mismatch (e.g., test expects /register but app uses /sign-up), this means the test is not navigating through the UI — fix the test to click through the real navigation instead of hardcoding URLs
    • If a test fails at registration time with [traced] CR-NNN not found under docs/... — the referenced doc does not exist. Either the ID is typo'd, the doc was renamed, or the CR/BUG was never created. Fix the reference, do not silence the helper.
16. If a test fails:
    • Check that Docker is running (Testcontainers requires it)
    • Read the error message carefully and fix the root cause in the test or implementation
    • Re-run npx playwright test and go back to step 15
    • Use await page.screenshot() for debugging visual state if needed
    • Do NOT skip, exclude, or filter out failing tests as a "fix"
17. Mark todos complete

Post-Implementation Tracking

Read and follow the After Implementation steps in ${CLAUDE_PLUGIN_ROOT}/shared/tracking/TRACKING.md.