e2e/
├── playwright.config.ts          # Playwright configuration
├── package.json                  # Dependencies and scripts
├── tsconfig.json                 # TypeScript configuration
├── .env.test                     # Test environment variables
├── .env.example                  # Example environment file
├── global-setup.ts               # Global test setup
├── README.md                     # Quick start guide
│
├── fixtures/                     # Role-based test fixtures
│   ├── auth.ts                   # Authentication helpers
│   ├── employee.ts               # Employee role fixture
│   ├── employer.ts               # Employer role fixture
│   └── contractor.ts             # Contractor role fixture
│
├── utils/                        # Shared utilities
│   ├── test-data.ts              # Test data generators
│   └── selectors.ts              # Common CSS selectors
│
├── tests/
│   ├── auth/                     # Authentication tests
│   │   ├── login.spec.ts
│   │   ├── otp.spec.ts
│   │   └── password-reset.spec.ts
│   │
│   ├── employee/                 # Employee flow tests
│   │   ├── dashboard.spec.ts
│   │   ├── onboarding/
│   │   │   ├── personal-details.spec.ts
│   │   │   ├── employment-eligibility.spec.ts
│   │   │   ├── contact-details.spec.ts
│   │   │   ├── emergency-contact.spec.ts
│   │   │   ├── bank-details.spec.ts
│   │   │   ├── statutory-tax.spec.ts
│   │   │   └── full-flow.spec.ts
│   │   ├── verification/
│   │   │   └── verification.spec.ts
│   │   ├── requests/
│   │   │   ├── leave-request.spec.ts
│   │   │   ├── expense-claim.spec.ts
│   │   │   └── requests-list.spec.ts
│   │   ├── profile/
│   │   │   └── profile.spec.ts
│   │   └── tax/
│   │       └── tax.spec.ts
│   │
│   ├── employer/                 # Employer flow tests
│   │   ├── dashboard.spec.ts
│   │   ├── setup/
│   │   │   └── first-login.spec.ts
│   │   ├── contracts/
│   │   │   └── contracts.spec.ts
│   │   ├── requests/
│   │   │   └── requests.spec.ts
│   │   └── settings/
│   │       └── settings.spec.ts
│   │
│   └── rbac/                     # Access control tests
│       └── access-control.spec.ts
│
└── docs/                         # Documentation
    ├── employee-flows.md
    ├── employer-flows.md
    ├── backend-analysis.md
    └── test-plan.md

# Install dependencies
cd e2e
npm install
npx playwright install

# Run all tests
npm test

# Run with browser visible
npm run test:headed

# Run with Playwright UI
npm run test:ui

# By role
npm run test:employee      # All employee tests
npm run test:employer      # All employer tests
npm run test:auth          # Authentication tests
npm run test:rbac          # RBAC tests

# By file
npx playwright test tests/employee/onboarding/

# By test name
npx playwright test -g "login"

# Debug single test
npm run test:debug

# With trace
npx playwright test --trace on

# Record new test
npm run codegen

# View HTML report
npm run report

# Generate JSON report
npx playwright test --reporter=json

# Enable E2E testing mode
E2E_TESTING_MODE=True
E2E_OTP_BYPASS_CODE=000000

cd nemesis
source venv/bin/activate
python manage.py runserver

cd aether
npm run dev

cd nemesis
python manage.py loaddata fixtures/users.json
python manage.py loaddata fixtures/company.json
python manage.py loaddata fixtures/employee.json
python manage.py loaddata fixtures/contractor.json

# URLs
FRONTEND_URL=http://localhost:5173
API_URL=http://localhost:8000

# OTP Bypass (must match backend)
E2E_OTP_BYPASS_CODE=000000

# Test Users
TEST_EMPLOYEE_EMAIL=test-employee@rapid.one
TEST_EMPLOYEE_PASSWORD=Test@123

TEST_EMPLOYER_EMAIL=test-employer@rapid.one
TEST_EMPLOYER_PASSWORD=Test@123

TEST_CONTRACTOR_EMAIL=test-contractor@rapid.one
TEST_CONTRACTOR_PASSWORD=Test@123

name: E2E Tests

on:
  push:
    branches: [main, develop]
  pull_request:
    branches: [main]

jobs:
  e2e:
    runs-on: ubuntu-latest

    services:
      postgres:
        image: postgres:14
        env:
          POSTGRES_DB: rapid_test
          POSTGRES_USER: postgres
          POSTGRES_PASSWORD: postgres
        ports:
          - 5432:5432

      redis:
        image: redis:7
        ports:
          - 6379:6379

    steps:
      - uses: actions/checkout@v4

      - name: Setup Python
        uses: actions/setup-python@v4
        with:
          python-version: '3.11'

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'

      - name: Install Backend Dependencies
        run: |
          cd nemesis
          pip install -r requirements.txt

      - name: Setup Backend
        run: |
          cd nemesis
          python manage.py migrate
          python manage.py loaddata fixtures/users.json
        env:
          E2E_TESTING_MODE: 'True'
          E2E_OTP_BYPASS_CODE: '000000'
          DATABASE_NAME: rapid_test
          DATABASE_USERNAME: postgres
          DATABASE_PASSWORD: postgres
          DATABASE_HOST: localhost

      - name: Start Backend
        run: |
          cd nemesis
          python manage.py runserver &
        env:
          E2E_TESTING_MODE: 'True'
          E2E_OTP_BYPASS_CODE: '000000'

      - name: Install Frontend Dependencies
        run: |
          cd aether
          npm ci

      - name: Start Frontend
        run: |
          cd aether
          npm run dev &

      - name: Install E2E Dependencies
        run: |
          cd e2e
          npm ci
          npx playwright install --with-deps

      - name: Run E2E Tests
        run: |
          cd e2e
          npm test
        env:
          FRONTEND_URL: http://localhost:5173
          API_URL: http://localhost:8000
          E2E_OTP_BYPASS_CODE: '000000'

      - name: Upload Test Report
        uses: actions/upload-artifact@v3
        if: always()
        with:
          name: playwright-report
          path: e2e/playwright-report/

version: '3.8'

services:
  backend:
    build: ./nemesis
    environment:
      - E2E_TESTING_MODE=True
      - E2E_OTP_BYPASS_CODE=000000
    ports:
      - "8000:8000"

  frontend:
    build: ./aether
    ports:
      - "5173:5173"

  e2e:
    build: ./e2e
    depends_on:
      - backend
      - frontend
    environment:
      - FRONTEND_URL=http://frontend:5173
      - API_URL=http://backend:8000
    command: npm test

// Group related tests
test.describe('Feature Name', () => {
  // Setup before each test
  test.beforeEach(async ({ page }) => {
    // Navigate to page
  });

  test('should do something', async ({ page }) => {
    // Test implementation
  });
});

// Instead of manual auth
import { test, expect } from '../../fixtures/employee';

test('employee test', async ({ page }) => {
  // page is already authenticated
});

// Priority order:
// 1. data-testid (most stable)
await page.locator('[data-testid="submit-button"]');

// 2. Role + name
await page.getByRole('button', { name: 'Submit' });

// 3. Name attribute
await page.locator('input[name="email"]');

// 4. Text content (fallback)
await page.locator('text=/submit/i');

// Wait for navigation
await expect(page).toHaveURL(/\/dashboard/);

// Wait for element
await expect(page.locator('[data-testid="table"]')).toBeVisible();

// Wait for API response
await page.waitForResponse(resp => resp.url().includes('/api/'));

// Wait for network idle
await page.waitForLoadState('networkidle');

// Retry assertions
await expect(element).toBeVisible({ timeout: 10000 });

// Multiple valid outcomes
await Promise.race([
  expect(page).toHaveURL(/\/success/),
  expect(page.locator('text=Success')).toBeVisible(),
]);

// Catch optional elements
await element.click().catch(() => {});

# Run with debug logs
DEBUG=pw:api npm test

# Run single test in debug mode
npx playwright test tests/auth/login.spec.ts --debug

# Generate trace for failed tests
npx playwright test --trace on

# View trace
npx playwright show-trace trace.zip