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

E2E Tests - GAMILIT

End-to-End tests using Playwright for the GAMILIT educational gamification platform.

📋 Overview

This directory contains End-to-End (E2E) tests that verify critical user flows and ensure the application works correctly from a user's perspective.

🚀 Running Tests

Run all E2E tests (headless)

npm run test:e2e

Run with UI (interactive mode)

npm run test:e2e:ui

Run with browser visible (headed mode)

npm run test:e2e:headed

Debug mode (step through tests)

npm run test:e2e:debug

View test report

npm run test:e2e:report

Run specific test file

npx playwright test auth.spec.ts

Run tests in specific browser

npx playwright test --project=chromium
npx playwright test --project=firefox
npx playwright test --project="Mobile Chrome"

📁 Test Files

Core Tests

• auth.spec.ts - Authentication and registration flows
• navigation.spec.ts - Basic navigation and routing
• student-journey.spec.ts - Original student journey tests (legacy)

Critical Flow Tests (NEW)

student-exercise-m4.spec.ts

Module 4 exercise flows for students:

• Complete Quiz TikTok with time penalty tracking
• Complete Infografia Interactiva with drag-drop
• Submit exercises and view points
• Track exercise progress

teacher-flow.spec.ts

Teacher workflow tests:

• View pending submissions
• Review and grade student work
• Receive notifications for new submissions
• Filter submissions by student/exercise
• View student progress analytics
• Export reports
• Bulk grade submissions

admin-flow.spec.ts

Admin portal tests:

• Access admin dashboard
• Manage feature flags (view, toggle, create)
• Configure feature flag targeting rules
• Manage user roles and permissions
• Search and filter users
• Edit user permissions

gamification-flow.spec.ts

Gamification system tests:

• Display and track XP/levels
• Gain XP after exercise completion
• Level up animations
• View and unlock achievements
• Display leaderboard with rankings
• Filter leaderboard by period/classroom
• Earn and display ML Coins

🎯 Test Status

Implemented Critical Flow Tests (NEW):

✅ Student Exercise Flow - M4 Quiz TikTok with time penalty ✅ Student Exercise Flow - Infografia drag-drop exercise ✅ Teacher Flow - View and grade submissions ✅ Teacher Flow - Notification system ✅ Admin Flow - Feature flag management ✅ Admin Flow - Role and permission management ✅ Gamification - XP and level progression ✅ Gamification - Achievement system ✅ Gamification - Leaderboard functionality

Legacy Tests (Original):

✅ Login page display ✅ Form validation ✅ Navigation basics ✅ 404 handling ✅ Protected routes redirect ✅ Performance checks

Tests Requiring Test Data Setup:

Most new critical flow tests will run but may skip certain scenarios if:

• Test user accounts don't exist in database
• Backend API is not running
• Specific test data (exercises, achievements) is not seeded

Note: Tests are designed to gracefully skip scenarios when prerequisites are not met.

🔧 Configuration

Configuration is in playwright.config.ts:

• Test directory: ./e2e
• Base URL: http://localhost:3005
• Browsers: Chromium, Firefox, Mobile Chrome
• Retries: 2 (on CI), 0 (local)
• Reports: HTML, List, JSON

📊 Test Coverage Status

Critical Flows (Priority 1) 🔥

• Authentication (Login/Register)
• Student: Browse → Start Exercise → Complete
• Student: Module 4 Quiz TikTok with time penalty
• Student: Module 4 Infografia drag-drop
• Teacher: View submissions → Review → Grade
• Teacher: Receive notifications
• Admin: Feature flag management
• Admin: Role and permission management
• Gamification: XP and level progression
• Gamification: Achievement system
• Leaderboard display and filtering

Important Flows (Priority 2) 🟡

• Student progress tracking
• Teacher: Filter submissions by student/exercise
• Teacher: Export reports
• Teacher: Bulk grading
• Admin: Search and filter users
• Profile management
• Social features (friends, classrooms)

Nice to Have (Priority 3) 🟢

• Settings/preferences
• Advanced notifications
• Search functionality
• Mobile responsiveness
• Visual regression testing

🏗️ Test Data Setup

Required Test Users

Create these users in your test database:

// Student user
{
  email: 'student@test.gamilit.com',
  password: 'TestStudent123!',
  role: 'student',
  displayName: 'Test Student'
}

// Teacher user
{
  email: 'teacher@test.gamilit.com',
  password: 'TestTeacher123!',
  role: 'teacher',
  displayName: 'Test Teacher'
}

// Admin user
{
  email: 'admin@test.gamilit.com',
  password: 'TestAdmin123!',
  role: 'admin',
  displayName: 'Test Admin'
}

Environment Setup

1. Backend API: Running on http://localhost:3006
2. Frontend: Running on http://localhost:3005
3. Database: Test database with seeded data

Fixtures and Helpers (IMPLEMENTED)

All test files now use centralized fixtures and helpers:

• fixtures/test-users.ts - Test user credentials and exercise IDs
• fixtures/auth-helpers.ts - Login/logout helper functions
• helpers/page-helpers.ts - Reusable page interaction functions

Helper Functions Available:

• loginAsStudent(page) - Authenticate as student
• loginAsTeacher(page) - Authenticate as teacher
• loginAsAdmin(page) - Authenticate as admin
• waitForPageLoad(page) - Wait for complete page load
• waitForToast(page) - Wait for toast notifications
• waitForModal(page) - Wait for modal dialogs
• waitForLoadingToFinish(page) - Wait for spinners to disappear

🎨 Visual Regression Testing

Future enhancement: Add visual regression tests using Playwright's screenshot comparison:

test('should match homepage screenshot', async ({ page }) => {
  await page.goto('/');
  await expect(page).toHaveScreenshot('homepage.png');
});

📈 CI/CD Integration

Tests are configured to run in CI with:

• Automatic retries (2 attempts)
• Screenshot on failure
• Video on failure
• HTML report generation

GitHub Actions Example:

- 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/

🐛 Debugging Tips

Test Failing? Try:

1. Run in headed mode: npm run test:e2e:headed
2. Run in debug mode: npm run test:e2e:debug
3. Check screenshot in test-results/ directory
4. View video in test-results/ directory
5. Check console errors in test output

Common Issues:

• Timeout errors: Increase timeout or check if backend is running
• Element not found: Check if UI has changed
• Authentication issues: Verify test user credentials
• Flaky tests: Add explicit waits or check for race conditions

📚 Resources

• Playwright Documentation
• Best Practices
• Debugging Guide
• Selectors Guide

🎓 Writing New Tests

Test Structure:

import { test, expect } from '@playwright/test';

test.describe('Feature Name', () => {
  test.beforeEach(async ({ page }) => {
    // Setup before each test
    await page.goto('/feature');
  });

  test('should do something', async ({ page }) => {
    // Test implementation
    await page.click('button');
    await expect(page.locator('result')).toBeVisible();
  });
});

Best Practices:

• Use data-testid attributes for stable selectors
• Write descriptive test names
• Keep tests independent
• Clean up test data
• Use Page Object Model for complex flows
• Avoid hard-coded waits (use Playwright's auto-waiting)

✅ Definition of Done for E2E Tests

A test is "Done" when:

• Test written and passing
• Test is not flaky (runs consistently)
• Test has meaningful assertions
• Test cleans up after itself
• Test is documented (comments if complex)
• Test runs in CI

📦 Test Structure

e2e/
├── fixtures/
│   ├── test-users.ts          # Test user credentials and data
│   └── auth-helpers.ts        # Authentication helper functions
├── helpers/
│   └── page-helpers.ts        # Reusable page interaction helpers
├── auth.spec.ts               # Authentication tests
├── navigation.spec.ts         # Navigation tests
├── student-journey.spec.ts    # Legacy student tests
├── student-exercise-m4.spec.ts   # M4 exercise flow tests (NEW)
├── teacher-flow.spec.ts       # Teacher workflow tests (NEW)
├── admin-flow.spec.ts         # Admin portal tests (NEW)
├── gamification-flow.spec.ts  # Gamification tests (NEW)
└── README.md                  # This file

🎯 Quick Start

1. Start the application:

# Terminal 1: Start backend
cd apps/backend
npm run dev

# Terminal 2: Start frontend
cd apps/frontend
npm run dev

2. Seed test data:

# Run database seeds to create test users and data
npm run db:seed:test

3. Run tests:

# Run all tests
npm run test:e2e

# Run specific flow
npx playwright test student-exercise-m4.spec.ts

# Run with UI (recommended for development)
npm run test:e2e:ui

---

Last Updated: December 5, 2025 Test Framework: Playwright v1.56+ Coverage: 8 test files, 60+ test cases Critical Flows Covered: Student Exercises, Teacher Review, Admin Management, Gamification