workspace/knowledge-base/reference/erp-inmobiliaria-legacy/gamilit/frontend/e2e

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

auth.spec.ts

Authentication and registration flows:

• Login page display
• Form validation
• Invalid credentials handling
• Registration flow
• Password visibility toggle
• Session management

navigation.spec.ts

Basic navigation and routing:

• Homepage loading
• 404 handling
• Protected routes
• Performance checks
• Accessibility basics

student-journey.spec.ts

Complete student user journey:

• Dashboard display
• Module selection
• Exercise flow (start → answer → complete)
• Gamification elements (XP, achievements, leaderboard)
• Progress tracking

🎯 Test Status

Most tests are currently skipped (marked with test.skip()) because they require:

• Test user accounts in database
• Backend API running
• Specific test data setup

Currently Active Tests:

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

Tests Requiring Setup:

⏸️ Successful login flow (needs test user) ⏸️ Student dashboard (needs authentication) ⏸️ Exercise flow (needs test data) ⏸️ Gamification features (needs game state)

🔧 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 Goals

Critical Flows (Priority 1) 🔥

• Authentication (Login/Register)
• Student: Browse → Start Exercise → Complete
• Teacher: Create Assignment → View Progress
• Leaderboard display

Important Flows (Priority 2) 🟡

• Profile management
• Achievement unlock
• Social features (friends, classrooms)
• Progress tracking

Nice to Have (Priority 3) 🟢

• Settings/preferences
• Notifications
• Search functionality
• Mobile responsiveness

🏗️ Test Data Setup (TODO)

To enable all tests, we need:

1. Database Seeds:

   • Test student account
   • Test teacher account
   • Sample modules and exercises
   • Sample achievements

2. Environment:

   • Backend API running on localhost:3006
   • Frontend dev server on localhost:3005
   • Test database with seed data

3. Helper Functions:

   • setupTestData() - Create test data
   • loginAsStudent() - Authenticate test user
   • loginAsTeacher() - Authenticate test user
   • cleanupTestData() - Remove test data

🎨 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

---

Last Updated: November 9, 2025 Test Framework: Playwright v1.40+ Coverage: 3 test files, ~20 test cases (12 active, 8 skipped)