Testing Guide

This document provides an overview of the testing infrastructure and how to run tests in the Momentum project.

Test Structure

The project has two types of tests:

1. Unit Tests - Jest + React Testing Library (frontend components and hooks)
2. E2E Tests - Playwright (end-to-end user flows)

Running Tests

All test commands should be run from the project root (/momentum/).

Run All Tests

npm test
# or
npm run test:all

Runs both unit tests and E2E tests sequentially.

---

Unit Tests (Jest + React Testing Library)

# Run unit tests once
npm run test:unit

# Run unit tests in watch mode (for development)
npm run test:unit:watch

# Run unit tests with coverage report
npm run test:unit:coverage

# Run unit tests in CI mode (used by GitHub Actions)
npm run test:unit:ci

What’s Tested:

• React components (Button, Header, CourseCard)
• Custom hooks (useCourseFilters)
• Component rendering, interactions, and edge cases
• 100% code coverage on components and hooks

Location: frontend/components/**/__tests__/, frontend/hooks/__tests__/

---

E2E Tests (Playwright)

# Run E2E tests (headless)
npm run test:e2e

# Run E2E tests with browser UI visible
npm run test:e2e:headed

# Run E2E tests in interactive UI mode
npm run test:e2e:ui

# Run E2E tests in debug mode
npm run test:e2e:debug

# View last test report
npm run test:e2e:report

# Run on specific browsers
npm run test:e2e:chromium
npm run test:e2e:firefox
npm run test:e2e:webkit

What’s Tested:

• Complete user flows and interactions
• Navigation between pages
• Form submissions
• Multi-page workflows
• Cross-browser compatibility

Location: tests/ (project root)

---

Coverage Requirements

Unit Tests

• Threshold: 80% minimum coverage required
• Metrics: Lines, Statements, Functions, Branches
• Current: 100% coverage on all components and hooks

Coverage Report

After running npm run test:unit:coverage, view the detailed report at:

frontend/coverage/lcov-report/index.html

---

CI/CD Integration

Automated Testing on Pull Requests

Both test suites run automatically on PRs:

1. Unit Tests Workflow (.github/workflows/unit-tests.yml)
   • Runs on PR open/synchronize
   • Posts coverage report as PR comment
   • Fails if coverage < 80% or tests fail
   • Required to pass before merging
2. Playwright Tests Workflow (.github/workflows/playwright.yml)
   • Runs on PR open/synchronize
   • Posts test results as PR comment
   • Uploads HTML report as artifact
   • Required to pass before merging

---

Writing Tests

Unit Test Example (Jest + RTL)

// components/ui/__tests__/Button.test.tsx
import { render, screen } from '@testing-library/react';
import userEvent from '@testing-library/user-event';
import { Button } from '../Button';

describe('Button Component', () => {
  it('should call onClick when clicked', async () => {
    const handleClick = jest.fn();
    const user = userEvent.setup();

    render(<Button onClick={handleClick}>Click me</Button>);
    await user.click(screen.getByRole('button'));

    expect(handleClick).toHaveBeenCalledTimes(1);
  });
});

E2E Test Example (Playwright)

// tests/courses.spec.ts
import { test, expect } from '@playwright/test';

test('should display course catalog', async ({ page }) => {
  await page.goto('/courses');

  await expect(page.getByRole('heading', { name: /courses/i })).toBeVisible();
  await expect(page.getByTestId('course-card')).toHaveCount.toBeGreaterThan(0);
});

---

Test Configuration Files

File	Purpose
frontend/jest.config.js	Jest configuration for unit tests
frontend/jest.setup.js	Test environment setup (jest-dom)
playwright.config.ts	Playwright configuration for E2E tests
.github/workflows/unit-tests.yml	CI workflow for unit tests
.github/workflows/playwright.yml	CI workflow for E2E tests

---

Troubleshooting

Unit Tests

Issue: Tests failing with module resolution errors

# Clear Jest cache
cd frontend
npx jest --clearCache

Issue: Coverage not updating

# Delete coverage folder and re-run
rm -rf frontend/coverage
npm run test:unit:coverage

E2E Tests

Issue: Browser not installed

npx playwright install --with-deps

Issue: Tests timing out

• Increase timeout in playwright.config.ts
• Use test.setTimeout(60000) in specific tests

---

Best Practices

Unit Tests

• Test user behavior, not implementation details
• Use semantic queries (getByRole, getByLabelText)
• Mock external dependencies
• Aim for descriptive test names
• Group related tests with describe blocks

E2E Tests

• Test critical user journeys
• Use data-testid sparingly (prefer accessible queries)
• Keep tests independent
• Clean up test data after each test
• Use page object model for complex flows

---

Quick Reference

Command	Description
npm test	Run all tests (unit + E2E)
npm run test:unit	Run unit tests
npm run test:unit:watch	Unit tests in watch mode
npm run test:unit:coverage	Unit tests with coverage
npm run test:e2e	Run E2E tests
npm run test:e2e:ui	E2E tests in UI mode
npm run test:e2e:debug	E2E tests in debug mode

---

Last Updated: 2025-11-14