tests/PLAYWRIGHT-TEST-STRATEGY.md

Playwright Test Strategy with First-User Testing

Overview

This project uses Playwright's project dependencies to orchestrate complex test scenarios including first-user admin role testing.

Test Execution Flow

graph TD
    A[Start Tests] --> B{First User Tests?}
    B -->|Yes| C[first-user-setup]
    C --> D[Clear Database]
    D --> E[first-user tests]
    E --> F[Test Admin Role Assignment]
    F --> G[setup]
    B -->|No/Skip| G[setup]
    G --> H[Seed Test Users]
    H --> I[Create Auth States]
    I --> J[chromium tests]
    I --> K[admin tests]
    I --> L[mobile tests]

Available Test Commands

Run Everything (First-User + Standard Tests)

pnpm test:e2e:all
# or just
pnpm test:e2e

This runs:

1. First-user tests with clean database
2. Seeds test users
3. Runs all standard tests

Run Only First-User Tests

pnpm test:e2e:first-user

This runs:

1. Clears database
2. Tests first user gets admin role
3. Tests second user gets regular role

Run Only Standard Tests (Skip First-User)

pnpm test:e2e:standard

This runs:

1. Seeds test users (if needed)
2. Creates auth states
3. Runs chromium + admin tests

Run with UI

pnpm test:e2e:ui

Opens Playwright UI to run/debug any test configuration

Project Configuration

first-user-setup Project

• Purpose: Clear database for first-user testing
• File: tests/lifecycle/first-user.setup.ts
• Runs: Before first-user tests only

first-user Project

• Purpose: Test first user admin role assignment
• File: tests/auth/first-user-admin.spec.ts
• Dependencies: first-user-setup
• Database State: Empty (0 users)

setup Project

• Purpose: Seed users and create auth states
• File: tests/lifecycle/auth-states.setup.ts
• Dependencies: first-user (unless SKIP_FIRST_USER_TEST=1)
• Database State: Populated with test users

chromium Project

• Purpose: Standard browser tests
• Dependencies: setup
• Database State: Seeded with test users

admin Project

• Purpose: Admin functionality tests
• Dependencies: setup
• Database State: Seeded with admin user

Environment Variables

SKIP_FIRST_USER_TEST=1

Skip first-user tests and go straight to standard tests. Useful for faster testing when not changing auth logic.

SKIP_FIRST_USER_TEST=1 pnpm test:e2e

How It Works

1. Database State Management

The projects handle database state transitions:

• Clean → First-User Tests → Seeded → Standard Tests

2. Dependency Chain

Playwright ensures tests run in the correct order:

first-user-setup → first-user → setup → [chromium, admin, mobile]

3. Smart Seeding

The setup project checks if users exist before seeding:

• If < 3 users: Runs seed script
• If ≥ 3 users: Skips seeding

4. Auth State Creation

After seeding, setup creates browser auth states for:

• Admin user
• Editor user
• Regular user

These are saved as JSON files and reused by other tests.

Troubleshooting

Tests fail with "User already exists"

The database has leftover data. Run:

pnpm test:e2e:clean  # Clean all test data
pnpm test:e2e        # Run tests fresh

First-user not getting admin role

1. Check Better Auth hook is enabled in auth-instance.ts
2. Verify database is truly empty before test
3. Check logs for "User creation hook" message

Tests hanging on sign-in

1. Check for translation errors in console
2. Verify no duplicate keys in messages/en.json
3. Check for circular dependencies in role definitions

Want to skip first-user tests

pnpm test:e2e:standard
# or
SKIP_FIRST_USER_TEST=1 pnpm test:e2e

Best Practices

1. Don't mix test types: First-user tests need empty DB, standard tests need seeded DB

2. Use projects for dependencies: Let Playwright handle the orchestration

3. Check logs: Each setup phase logs its actions for debugging

4. Clean state for CI: CI should always run full suite to ensure clean state

CI Configuration

# Example GitHub Actions
- name: Run E2E Tests
  run: |
    # Always run full suite in CI for consistency
    pnpm test:e2e:all

This ensures CI always tests:

1. First-user admin assignment
2. All standard functionality
3. Admin features
4. Mobile responsiveness