claim/E2E_SETUP.md

E2E Testing Setup Complete ✅

Playwright end-to-end tests have been added to the project.

What Was Added

Configuration

• playwright.config.ts - Main config with auto-start dev server
• package.json - Added test scripts (test:e2e, test:e2e:ui, test:e2e:debug)
• .gitignore - Excluded test results and reports

Test Files (5 test suites)

• e2e/smoke.spec.ts - Homepage and navigation smoke tests
• e2e/claim-form-mileage.spec.ts - Mileage claim end-to-end tests
  • Full form submission
  • Date validation (period bounds)
  • Total calculation verification
• e2e/claim-form-expenses.spec.ts - Expenses claim tests
  • Multiple line items
  • Numeric month input (5 → MAY)
• e2e/claim-form-ot.spec.ts - Overtime claim tests
  • DD/MM/YYYY date format
  • Validation for month-only rejection
• e2e/claim-form-meal.spec.ts - Meal & Accommodation tests
  • Time input formatting
  • Date range support

Component Updates

• AdminClaimForm.jsx - Updated data-testid from item-row-N to line-item-N for consistency

Quick Start

1. Install Playwright Browsers

cd frontend
npx playwright install

2. Run Tests

# Headless (CI mode)
yarn test:e2e

# Interactive UI mode (recommended for development)
yarn test:e2e:ui

# Debug mode (step through tests)
yarn test:e2e:debug

3. Run Specific Test Suite

npx playwright test claim-form-mileage.spec.ts

Test Coverage

✅ Implemented

• Claim form creation (all 4 types: Expenses, Mileage, OT, Meal)
• Date input validation
  • Period bounds checking (e.g., can't enter Dec date in May claim)
  • Format validation (DD/MM/YYYY for mileage/OT, month-only for expenses)
• Total calculations (mileage KM × rate + toll + parking)
• Preview iframe updates
• Save functionality

⏳ TODO (Future Enhancements)

• Authentication flows (login/logout)
• Excel export download
• PDF preview verification
• Import existing claims
• Edit claim workflow
• Attachment upload/download
• Claims list filtering/sorting

CI Integration

Add this to .github/workflows/e2e.yml:

name: E2E Tests

on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
        with:
          node-version: '18'
      
      - name: Install dependencies
        run: cd frontend && yarn install
      
      - name: Install Playwright browsers
        run: cd frontend && npx playwright install --with-deps
      
      - name: Start backend
        run: |
          cd backend
          python -m venv venv
          source venv/bin/activate
          pip install -r requirements.txt
          python server.py &
      
      - name: Run E2E tests
        run: cd frontend && yarn test:e2e
      
      - name: Upload test report
        if: failure()
        uses: actions/upload-artifact@v3
        with:
          name: playwright-report
          path: frontend/playwright-report/

Best Practices

1. Use data-testid for stable selectors (already added to form)
2. Use await expect() with built-in retry instead of waitForTimeout()
3. Test user flows, not implementation details
4. Keep tests independent - each test should work standalone
5. Use page objects for complex, reused interactions

Example: Running Your First Test

cd frontend

# Install browsers (one-time setup)
npx playwright install

# Run mileage claim tests in UI mode
yarn test:e2e:ui e2e/claim-form-mileage.spec.ts

The UI mode lets you:

• See tests run in real browser
• Time-travel through test steps
• Inspect DOM at each step
• Debug failing tests visually

Debugging Failed Tests

When a test fails:

1. Check screenshots: frontend/test-results/<test-name>/test-failed-1.png
2. View trace: npx playwright show-trace test-results/<folder>/trace.zip
3. Run in headed mode: npx playwright test --headed --debug
4. Check terminal output for assertion errors

Next Steps

1. Run yarn test:e2e:ui to see tests in action
2. Add authentication tests when auth is implemented
3. Extend tests to cover Excel export and PDF verification
4. Add to CI pipeline for automated regression testing

See frontend/e2e/README.md for detailed documentation.