workspace/projects/gamilit/apps/frontend/e2e/TEST_SETUP.md

E2E Test Setup Guide

This guide will help you set up the environment to run E2E tests for GAMILIT.

Prerequisites

1. Node.js >= 18.0.0
2. npm >= 9.0.0
3. PostgreSQL database
4. Backend API running
5. Frontend dev server running

Step 1: Install Dependencies

cd apps/frontend
npm install
npx playwright install chromium

Step 2: Database Setup

Create test users in your database. You can use this SQL script:

-- Test Student
INSERT INTO users (email, password_hash, role, display_name, created_at, updated_at)
VALUES (
  'student@test.gamilit.com',
  '$2b$10$...',  -- Hash for 'TestStudent123!'
  'student',
  'Test Student',
  NOW(),
  NOW()
);

-- Test Teacher
INSERT INTO users (email, password_hash, role, display_name, created_at, updated_at)
VALUES (
  'teacher@test.gamilit.com',
  '$2b$10$...',  -- Hash for 'TestTeacher123!'
  'teacher',
  'Test Teacher',
  NOW(),
  NOW()
);

-- Test Admin
INSERT INTO users (email, password_hash, role, display_name, created_at, updated_at)
VALUES (
  'admin@test.gamilit.com',
  '$2b$10$...',  -- Hash for 'TestAdmin123!'
  'admin',
  'Test Admin',
  NOW(),
  NOW()
);

OR use the backend seed command (if available):

cd apps/backend
npm run db:seed:test

Step 3: Environment Variables

Create a .env.test file in the frontend directory:

VITE_API_URL=http://localhost:3006
VITE_APP_URL=http://localhost:3005
VITE_ENABLE_FEATURE_FLAGS=true

Step 4: Start Services

Open 2 terminal windows:

Terminal 1 - Backend:

cd apps/backend
npm run dev

Terminal 2 - Frontend:

cd apps/frontend
npm run dev

Wait for both services to be ready.

Step 5: Run Tests

Option A: Run all tests (headless)

npm run test:e2e

Option B: Run with UI (recommended for development)

npm run test:e2e:ui

Option C: Run specific flow

# Student exercises
npx playwright test student-exercise-m4.spec.ts

# Teacher workflow
npx playwright test teacher-flow.spec.ts

# Admin features
npx playwright test admin-flow.spec.ts

# Gamification
npx playwright test gamification-flow.spec.ts

Option D: Debug mode

npm run test:e2e:debug

Test Data Requirements

For all tests to pass, you need:

Users

• ✅ Student user: student@test.gamilit.com
• ✅ Teacher user: teacher@test.gamilit.com
• ✅ Admin user: admin@test.gamilit.com

Exercises

• Module 4 with Quiz TikTok exercise
• Module 4 with Infografia Interactiva exercise

Optional (for full coverage)

• Sample achievements
• Sample classrooms
• Some existing submissions for teacher tests

Troubleshooting

Tests timeout

• Issue: Tests fail with timeout errors
• Solution: Make sure backend and frontend are running and accessible at the configured URLs

Element not found errors

• Issue: Tests can't find elements on page
• Solution: Check if the UI has changed, update selectors or add data-testid attributes

Authentication fails

• Issue: Login tests fail
• Solution:
  • Verify test users exist in database
  • Check password hashes match the test passwords
  • Ensure backend authentication is working

Flaky tests

• Issue: Tests pass sometimes but fail randomly
• Solution:
  • Add explicit waits using waitForPageLoad() or waitForLoadingToFinish()
  • Check for race conditions
  • Use data-testid attributes for more stable selectors

Tests skip automatically

• Issue: Many tests show as "skipped"
• Solution: This is intentional. Tests skip gracefully when:
  • Required elements don't exist (feature not implemented)
  • Test data is missing
  • Backend endpoints are not available

Running Tests in CI

Example GitHub Actions workflow:

name: E2E Tests

on: [push, pull_request]

jobs:
  e2e:
    runs-on: ubuntu-latest

    services:
      postgres:
        image: postgres:15
        env:
          POSTGRES_PASSWORD: postgres
        options: >-
          --health-cmd pg_isready
          --health-interval 10s
          --health-timeout 5s
          --health-retries 5          

    steps:
      - uses: actions/checkout@v3

      - name: Setup Node
        uses: actions/setup-node@v3
        with:
          node-version: 18

      - name: Install dependencies
        run: |
          npm ci
          npx playwright install chromium          

      - name: Setup database
        run: npm run db:migrate && npm run db:seed:test

      - name: Start backend
        run: npm run dev --workspace=backend &

      - name: Start frontend
        run: npm run dev --workspace=frontend &

      - name: Wait for services
        run: npx wait-on http://localhost:3005 http://localhost:3006

      - name: Run E2E tests
        run: npm run test:e2e

      - name: Upload test results
        if: always()
        uses: actions/upload-artifact@v3
        with:
          name: playwright-report
          path: playwright-report/

Test Coverage Report

After running tests, view the HTML report:

npm run test:e2e:report

This will open a browser with detailed test results, screenshots, and videos of failed tests.

Best Practices

1. Keep tests independent - Each test should set up and tear down its own state
2. Use data-testid - Add data-testid attributes to important UI elements
3. Avoid hard waits - Use Playwright's auto-waiting or helper functions
4. Test user journeys - Focus on complete flows, not individual components
5. Handle async operations - Always wait for loading states to finish
6. Clean test data - Remove or reset test data after tests run

Next Steps

Once tests are running successfully:

1. Add more specific test scenarios
2. Implement visual regression testing
3. Add performance benchmarks
4. Set up continuous testing in CI/CD
5. Create test data factories for easier test setup

Support

If you encounter issues:

1. Check the main README: e2e/README.md
2. Review test output for error messages
3. Run tests in headed mode to see what's happening
4. Check browser console logs in test results
5. Review screenshots/videos in test-results/ directory