vip-coordinator/TESTING.md

VIP Coordinator - Testing Guide

This guide covers the complete testing infrastructure for the VIP Coordinator application.

Overview

The testing setup includes:

• Backend Tests: Jest with Supertest for API testing
• Frontend Tests: Vitest with React Testing Library
• E2E Tests: Playwright for end-to-end testing
• Test Database: Separate PostgreSQL instance for tests
• CI/CD Pipeline: GitHub Actions for automated testing

Quick Start

Running All Tests

# Using Make
make test

# Using Docker Compose
docker-compose -f docker-compose.test.yml up

Running Specific Test Suites

# Backend tests only
make test-backend

# Frontend tests only
make test-frontend

# E2E tests only
make test-e2e

# Generate coverage reports
make test-coverage

Backend Testing

Setup

The backend uses Jest with TypeScript support and Supertest for API testing.

Configuration: backend/jest.config.js Test Setup: backend/src/tests/setup.ts

Writing Tests

Unit Tests

// backend/src/services/__tests__/authService.test.ts
import { testPool } from '../../tests/setup';
import { testUsers, insertTestUser } from '../../tests/fixtures';

describe('AuthService', () => {
  it('should create a new user', async () => {
    // Your test here
  });
});

Integration Tests

// backend/src/routes/__tests__/vips.test.ts
import request from 'supertest';
import app from '../../app';

describe('VIP API', () => {
  it('GET /api/vips should return all VIPs', async () => {
    const response = await request(app)
      .get('/api/vips')
      .set('Authorization', 'Bearer token');
    
    expect(response.status).toBe(200);
  });
});

Test Utilities

• Fixtures: backend/src/tests/fixtures.ts - Pre-defined test data
• Test Database: Automatically set up and torn down for each test
• Mock Services: JWT, Google OAuth, etc.

Running Backend Tests

cd backend
npm test                 # Run all tests
npm run test:watch      # Watch mode
npm run test:coverage   # With coverage

Frontend Testing

Setup

The frontend uses Vitest with React Testing Library.

Configuration: frontend/vitest.config.ts Test Setup: frontend/src/tests/setup.ts

Writing Tests

Component Tests

// frontend/src/components/__tests__/VipForm.test.tsx
import { render, screen } from '../../tests/test-utils';
import VipForm from '../VipForm';

describe('VipForm', () => {
  it('renders all form fields', () => {
    render(<VipForm onSubmit={jest.fn()} onCancel={jest.fn()} />);
    expect(screen.getByLabelText(/full name/i)).toBeInTheDocument();
  });
});

Page Tests

// frontend/src/pages/__tests__/Dashboard.test.tsx
import { render, waitFor } from '../../tests/test-utils';
import Dashboard from '../Dashboard';

describe('Dashboard', () => {
  it('loads and displays VIPs', async () => {
    render(<Dashboard />);
    await waitFor(() => {
      expect(screen.getByText('John Doe')).toBeInTheDocument();
    });
  });
});

Test Utilities

• Custom Render: Includes providers (Router, Toast, etc.)
• Mock Data: Pre-defined users, VIPs, drivers
• API Mocks: Mock fetch responses

Running Frontend Tests

cd frontend
npm test                # Run all tests
npm run test:ui        # With UI
npm run test:coverage  # With coverage

E2E Testing

Setup

E2E tests use Playwright for cross-browser testing.

Configuration: e2e/playwright.config.ts

Writing E2E Tests

// e2e/tests/vip-management.spec.ts
import { test, expect } from '@playwright/test';

test('create new VIP', async ({ page }) => {
  await page.goto('/');
  // Login flow
  await page.click('text=Add VIP');
  await page.fill('[name="name"]', 'Test VIP');
  await page.click('text=Submit');
  await expect(page.locator('text=Test VIP')).toBeVisible();
});

Running E2E Tests

# Local development
npx playwright test

# In Docker
make test-e2e

Database Testing

Test Database Setup

• Separate database instance for tests
• Automatic schema creation and migrations
• Test data seeding
• Cleanup after each test

Database Commands

# Set up test database with schema and seed data
make db-setup

# Run migrations only
make db-migrate

# Seed test data
make db-seed

Creating Migrations

cd backend
npm run db:migrate:create "add_new_column"

Docker Test Environment

Configuration

File: docker-compose.test.yml

Services:

• test-db: PostgreSQL for tests (port 5433)
• test-redis: Redis for tests (port 6380)
• backend-test: Backend test runner
• frontend-test: Frontend test runner
• e2e-test: E2E test runner

Environment Variables

Create .env.test based on .env.example:

DATABASE_URL=postgresql://test_user:test_password@test-db:5432/vip_coordinator_test
REDIS_URL=redis://test-redis:6379
GOOGLE_CLIENT_ID=test_client_id
# ... other test values

CI/CD Pipeline

GitHub Actions Workflows

Main CI Pipeline

File: .github/workflows/ci.yml

Runs on every push and PR:

1. Backend tests with coverage
2. Frontend tests with coverage
3. Security scanning
4. Docker image building
5. Deployment (staging/production)

E2E Test Schedule

File: .github/workflows/e2e-tests.yml

Runs daily or on-demand:

• Cross-browser testing
• Multiple environments
• Result notifications

Dependency Updates

File: .github/workflows/dependency-update.yml

Weekly automated updates:

• npm package updates
• Security fixes
• Automated PR creation

Best Practices

Test Organization

• Group related tests in describe blocks
• Use descriptive test names
• One assertion per test when possible
• Use beforeEach/afterEach for setup/cleanup

Test Data

• Use fixtures for consistent test data
• Clean up after tests
• Don't rely on test execution order
• Use unique identifiers to avoid conflicts

Mocking

• Mock external services (Google OAuth, APIs)
• Use test doubles for database operations
• Mock time-dependent operations

Performance

• Run tests in parallel when possible
• Use test database in memory (tmpfs)
• Cache Docker layers in CI

Troubleshooting

Common Issues

Port Conflicts

# Check if ports are in use
lsof -i :5433  # Test database
lsof -i :6380  # Test Redis

Database Connection Issues

# Ensure test database is running
docker-compose -f docker-compose.test.yml up test-db -d

# Check logs
docker-compose -f docker-compose.test.yml logs test-db

Test Timeouts

• Increase timeout in test configuration
• Check for proper async/await usage
• Ensure services are ready before tests

Debug Mode

# Run tests with debug output
DEBUG=* npm test

# Run specific test file
npm test -- authService.test.ts

# Run tests matching pattern
npm test -- --grep "should create user"

Coverage Reports

Coverage reports are generated in:

• Backend: backend/coverage/
• Frontend: frontend/coverage/

View HTML reports:

# Backend
open backend/coverage/lcov-report/index.html

# Frontend
open frontend/coverage/index.html

Contributing

When adding new features:

1. Write tests first (TDD approach)
2. Ensure all tests pass
3. Maintain >80% code coverage
4. Update test documentation

Resources

• Jest Documentation
• Vitest Documentation
• React Testing Library
• Playwright Documentation
• Supertest Documentation