From e8987d5970785aecf62c8341ed0f2863d6008103 Mon Sep 17 00:00:00 2001 From: kyle Date: Sat, 31 Jan 2026 17:08:59 +0100 Subject: [PATCH] docs: Remove outdated documentation files Removed 5 obsolete documentation files from June-July 2025: - DEPLOYMENT.md - Referenced Google OAuth (we now use Auth0) - SETUP_GUIDE.md - Referenced Google OAuth and Express (we use NestJS) - TESTING.md - Referenced Jest/Vitest (we now use Playwright) - TESTING_QUICKSTART.md - Same as above - TESTING_SETUP_SUMMARY.md - Old testing infrastructure summary Current documentation is maintained in: - README.md (comprehensive guide) - CLAUDE.md (project overview) - frontend/PLAYWRIGHT_GUIDE.md (current testing guide) - QUICKSTART.md (current setup guide) - And 4 recent production docs from Jan 24, 2026 Co-Authored-By: Claude Sonnet 4.5 --- DEPLOYMENT.md | 266 ------------------------------ SETUP_GUIDE.md | 314 ----------------------------------- TESTING.md | 344 --------------------------------------- TESTING_QUICKSTART.md | 137 ---------------- TESTING_SETUP_SUMMARY.md | 223 ------------------------- 5 files changed, 1284 deletions(-) delete mode 100644 DEPLOYMENT.md delete mode 100644 SETUP_GUIDE.md delete mode 100644 TESTING.md delete mode 100644 TESTING_QUICKSTART.md delete mode 100644 TESTING_SETUP_SUMMARY.md diff --git a/DEPLOYMENT.md b/DEPLOYMENT.md deleted file mode 100644 index 0f079a9..0000000 --- a/DEPLOYMENT.md +++ /dev/null @@ -1,266 +0,0 @@ -# 🚀 VIP Coordinator - Docker Hub Deployment Guide - -Deploy the VIP Coordinator application on any system with Docker in just a few steps! - -## 📋 Prerequisites - -- **Docker** and **Docker Compose** installed on your system -- **Domain name** (optional, can run on localhost for testing) -- **Google Cloud Console** account for OAuth setup - -## 🚀 Quick Start (5 Minutes) - -### 1. Download Deployment Files - -Create a new directory and download these files: - -```bash -mkdir vip-coordinator -cd vip-coordinator - -# Download the deployment files -curl -O https://raw.githubusercontent.com/your-repo/vip-coordinator/main/docker-compose.yml -curl -O https://raw.githubusercontent.com/your-repo/vip-coordinator/main/.env.example -``` - -### 2. Configure Environment - -```bash -# Copy the environment template -cp .env.example .env - -# Edit the configuration (use your preferred editor) -nano .env -``` - -**Required Changes in `.env`:** -- `DB_PASSWORD`: Change to a secure password -- `ADMIN_PASSWORD`: Change to a secure password -- `GOOGLE_CLIENT_ID`: Your Google OAuth Client ID -- `GOOGLE_CLIENT_SECRET`: Your Google OAuth Client Secret - -**For Production Deployment:** -- `DOMAIN`: Your domain name (e.g., `mycompany.com`) -- `VITE_API_URL`: Your API URL (e.g., `https://api.mycompany.com`) -- `GOOGLE_REDIRECT_URI`: Your callback URL (e.g., `https://api.mycompany.com/auth/google/callback`) -- `FRONTEND_URL`: Your frontend URL (e.g., `https://mycompany.com`) - -### 3. Set Up Google OAuth - -1. Go to [Google Cloud Console](https://console.cloud.google.com/) -2. Create a new project or select existing one -3. Enable the Google+ API -4. Go to "Credentials" → "Create Credentials" → "OAuth 2.0 Client IDs" -5. Set application type to "Web application" -6. Add authorized redirect URIs: - - For localhost: `http://localhost:3000/auth/google/callback` - - For production: `https://api.your-domain.com/auth/google/callback` -7. Copy the Client ID and Client Secret to your `.env` file - -### 4. Deploy the Application - -```bash -# Pull the latest images from Docker Hub -docker-compose pull - -# Start the application -docker-compose up -d - -# Check status -docker-compose ps -``` - -### 5. Access the Application - -- **Local Development**: http://localhost -- **Production**: https://your-domain.com - -## 🔧 Configuration Options - -### Environment Variables - -| Variable | Description | Required | Default | -|----------|-------------|----------|---------| -| `DB_PASSWORD` | PostgreSQL database password | ✅ | - | -| `ADMIN_PASSWORD` | Admin interface password | ✅ | - | -| `GOOGLE_CLIENT_ID` | Google OAuth Client ID | ✅ | - | -| `GOOGLE_CLIENT_SECRET` | Google OAuth Client Secret | ✅ | - | -| `GOOGLE_REDIRECT_URI` | OAuth callback URL | ✅ | - | -| `FRONTEND_URL` | Frontend application URL | ✅ | - | -| `VITE_API_URL` | Backend API URL | ✅ | - | -| `DOMAIN` | Your domain name | ❌ | localhost | -| `AVIATIONSTACK_API_KEY` | Flight data API key | ❌ | - | -| `PORT` | Backend port | ❌ | 3000 | - -### Ports - -- **Frontend**: Port 80 (HTTP) -- **Backend**: Port 3000 (API) -- **Database**: Internal only (PostgreSQL) -- **Redis**: Internal only (Cache) - -## 🌐 Production Deployment - -### With Reverse Proxy (Recommended) - -For production, use a reverse proxy like Nginx or Traefik: - -```nginx -# Nginx configuration example -server { - listen 80; - server_name your-domain.com; - return 301 https://$server_name$request_uri; -} - -server { - listen 443 ssl; - server_name your-domain.com; - - # SSL configuration - ssl_certificate /path/to/cert.pem; - ssl_certificate_key /path/to/key.pem; - - location / { - proxy_pass http://localhost:80; - proxy_set_header Host $host; - proxy_set_header X-Real-IP $remote_addr; - } -} - -server { - listen 443 ssl; - server_name api.your-domain.com; - - # SSL configuration - ssl_certificate /path/to/cert.pem; - ssl_certificate_key /path/to/key.pem; - - location / { - proxy_pass http://localhost:3000; - proxy_set_header Host $host; - proxy_set_header X-Real-IP $remote_addr; - } -} -``` - -### SSL/HTTPS Setup - -1. Obtain SSL certificates (Let's Encrypt recommended) -2. Configure your reverse proxy for HTTPS -3. Update your `.env` file with HTTPS URLs -4. Update Google OAuth redirect URIs to use HTTPS - -## 🔍 Troubleshooting - -### Common Issues - -**1. OAuth Login Fails** -- Check Google OAuth configuration -- Verify redirect URIs match exactly -- Ensure HTTPS is used in production - -**2. Database Connection Issues** -- Check if PostgreSQL container is healthy: `docker-compose ps` -- Verify database password in `.env` - -**3. Frontend Can't Reach Backend** -- Verify `VITE_API_URL` in `.env` matches your backend URL -- Check if backend is accessible: `curl http://localhost:3000/health` - -**4. Permission Denied Errors** -- Ensure Docker has proper permissions -- Check file ownership and permissions - -### Viewing Logs - -```bash -# View all logs -docker-compose logs - -# View specific service logs -docker-compose logs backend -docker-compose logs frontend -docker-compose logs db - -# Follow logs in real-time -docker-compose logs -f backend -``` - -### Health Checks - -```bash -# Check container status -docker-compose ps - -# Check backend health -curl http://localhost:3000/health - -# Check frontend -curl http://localhost/ -``` - -## 🔄 Updates - -To update to the latest version: - -```bash -# Pull latest images -docker-compose pull - -# Restart with new images -docker-compose up -d -``` - -## 🛑 Stopping the Application - -```bash -# Stop all services -docker-compose down - -# Stop and remove volumes (⚠️ This will delete all data) -docker-compose down -v -``` - -## 📊 Monitoring - -### Container Health - -All containers include health checks: -- **Backend**: API endpoint health check -- **Database**: PostgreSQL connection check -- **Redis**: Redis ping check -- **Frontend**: Nginx status check - -### Logs - -Logs are automatically rotated and can be viewed using Docker commands. - -## 🔐 Security Considerations - -1. **Change default passwords** in `.env` -2. **Use HTTPS** in production -3. **Secure your server** with firewall rules -4. **Regular backups** of database volumes -5. **Keep Docker images updated** - -## 📞 Support - -If you encounter issues: - -1. Check the troubleshooting section above -2. Review container logs -3. Verify your configuration -4. Check GitHub issues for known problems - -## 🎉 Success! - -Once deployed, you'll have a fully functional VIP Coordinator system with: -- ✅ Google OAuth authentication -- ✅ Mobile-friendly interface -- ✅ Real-time scheduling -- ✅ User management -- ✅ Automatic backups -- ✅ Health monitoring - -The first user to log in will automatically become the system administrator. \ No newline at end of file diff --git a/SETUP_GUIDE.md b/SETUP_GUIDE.md deleted file mode 100644 index 5df7258..0000000 --- a/SETUP_GUIDE.md +++ /dev/null @@ -1,314 +0,0 @@ -# VIP Coordinator Setup Guide - -A comprehensive guide to set up and run the VIP Coordinator system. - -## 🚀 Quick Start - -### Prerequisites -- Docker and Docker Compose -- Google Cloud Console account (for OAuth) - -### 1. Clone and Start -```bash -git clone -cd vip-coordinator -make dev -``` - -The application will be available at: -- **Frontend**: http://localhost:5173 -- **Backend API**: http://localhost:3000 -- **API Documentation**: http://localhost:3000/api-docs.html - -### 2. Google OAuth Setup (Required) - -1. **Create Google Cloud Project**: - - Go to [Google Cloud Console](https://console.cloud.google.com/) - - Create a new project or select existing one - -2. **Enable Google+ API**: - - Navigate to "APIs & Services" > "Library" - - Search for "Google+ API" and enable it - -3. **Create OAuth Credentials**: - - Go to "APIs & Services" > "Credentials" - - Click "Create Credentials" > "OAuth 2.0 Client IDs" - - Application type: "Web application" - - Authorized redirect URIs: `http://localhost:3000/auth/google/callback` - -4. **Configure Environment**: - ```bash - # Copy the example environment file - cp backend/.env.example backend/.env - - # Edit backend/.env and add your Google OAuth credentials: - GOOGLE_CLIENT_ID=your-client-id-here - GOOGLE_CLIENT_SECRET=your-client-secret-here - ``` - -5. **Restart the Application**: - ```bash - make dev - ``` - -### 3. First Login -- Visit http://localhost:5173 -- Click "Continue with Google" -- The first user to log in becomes the system administrator -- Subsequent users need administrator approval - -## 🏗️ Architecture Overview - -### Authentication System -- **JWT-based authentication** with Google OAuth -- **Role-based access control**: Administrator, Coordinator, Driver -- **User approval system** for new registrations -- **Simple setup** - no complex OAuth configurations needed - -### Database -- **PostgreSQL** for persistent data storage -- **Automatic schema initialization** on first run -- **User management** with approval workflows -- **VIP and driver data** with scheduling - -### API Structure -- **RESTful API** with comprehensive endpoints -- **OpenAPI/Swagger documentation** at `/api-docs.html` -- **Role-based endpoint protection** -- **Real-time flight tracking** integration - -## 📋 Features - -### Current Features -- ✅ **User Management**: Google OAuth with role-based access -- ✅ **VIP Management**: Create, edit, track VIPs with flight information -- ✅ **Driver Coordination**: Manage drivers and assignments -- ✅ **Flight Tracking**: Real-time flight status updates -- ✅ **Schedule Management**: Event scheduling with conflict detection -- ✅ **Department Support**: Office of Development and Admin departments -- ✅ **API Documentation**: Interactive Swagger UI - -### User Roles -- **Administrator**: Full system access, user management -- **Coordinator**: VIP and driver management, scheduling -- **Driver**: View assigned schedules (planned) - -## 🔧 Configuration - -### Environment Variables -```bash -# Database -DATABASE_URL=postgresql://vip_user:vip_password@db:5432/vip_coordinator - -# Authentication -GOOGLE_CLIENT_ID=your-google-client-id -GOOGLE_CLIENT_SECRET=your-google-client-secret -JWT_SECRET=your-jwt-secret-key - -# External APIs (Optional) -AVIATIONSTACK_API_KEY=your-aviationstack-key - -# Application -FRONTEND_URL=http://localhost:5173 -PORT=3000 -``` - -### Docker Services -- **Frontend**: React + Vite development server -- **Backend**: Node.js + Express API server -- **Database**: PostgreSQL with automatic initialization -- **Redis**: Caching and real-time updates - -## 🛠️ Development - -### Available Commands -```bash -# Start development environment -make dev - -# View logs -make logs - -# Stop all services -make down - -# Rebuild containers -make build - -# Backend only -cd backend && npm run dev - -# Frontend only -cd frontend && npm run dev -``` - -### API Testing -- **Interactive Documentation**: http://localhost:3000/api-docs.html -- **Health Check**: http://localhost:3000/api/health -- **Authentication Test**: Use the "Try it out" feature in Swagger UI - -## 🔐 Security - -### Authentication Flow -1. User clicks "Continue with Google" -2. Redirected to Google OAuth -3. Google redirects back with authorization code -4. Backend exchanges code for user info -5. JWT token generated and returned -6. Frontend stores token for API requests - -### API Protection -- All API endpoints require valid JWT token -- Role-based access control on sensitive operations -- User approval system for new registrations - -## 📚 API Documentation - -### Key Endpoints -- **Authentication**: `/auth/*` - OAuth and user management -- **VIPs**: `/api/vips/*` - VIP management and scheduling -- **Drivers**: `/api/drivers/*` - Driver management and availability -- **Flights**: `/api/flights/*` - Flight tracking and information -- **Admin**: `/api/admin/*` - System administration - -### Interactive Documentation -Visit http://localhost:3000/api-docs.html for: -- Complete API reference -- Request/response examples -- "Try it out" functionality -- Schema definitions - -## 🚨 Troubleshooting - -### Common Issues - -**OAuth Not Working**: -- Verify Google Client ID and Secret in `.env` -- Check redirect URI in Google Console matches exactly -- Ensure Google+ API is enabled - -**Database Connection Error**: -- Verify Docker containers are running: `docker ps` -- Check database logs: `docker-compose logs db` -- Restart services: `make down && make dev` - -**Frontend Can't Connect to Backend**: -- Verify backend is running on port 3000 -- Check CORS configuration in backend -- Ensure FRONTEND_URL is set correctly - -### Getting Help -1. Check the interactive API documentation -2. Review Docker container logs -3. Verify environment configuration -4. Test with the health check endpoint - -## 🔄 Production Deployment - -### Prerequisites for Production - -1. **Domain Setup**: Ensure your domains are configured: - - Frontend: `https://bsa.madeamess.online` - - API: `https://api.bsa.madeamess.online` - -2. **SSL Certificates**: Configure SSL/TLS certificates for your domains - -3. **Environment Configuration**: Copy and configure production environment: - ```bash - cp .env.example .env.prod - # Edit .env.prod with your secure values - ``` - -### Production Deployment Steps - -1. **Configure Environment Variables**: - ```bash - # Edit .env.prod with secure values: - # - Change DB_PASSWORD to a strong password - # - Generate new JWT_SECRET and SESSION_SECRET - # - Update ADMIN_PASSWORD - # - Set your AVIATIONSTACK_API_KEY - ``` - -2. **Deploy with Production Configuration**: - ```bash - # Load production environment - export $(cat .env.prod | xargs) - - # Build and start production containers - docker-compose -f docker-compose.prod.yml up -d --build - ``` - -3. **Verify Deployment**: - ```bash - # Check container status - docker-compose -f docker-compose.prod.yml ps - - # View logs - docker-compose -f docker-compose.prod.yml logs - ``` - -### Production vs Development Differences - -| Feature | Development | Production | -|---------|-------------|------------| -| Build Target | `development` | `production` | -| Source Code | Volume mounted (hot reload) | Built into image | -| Database Password | Hardcoded `changeme` | Environment variable | -| Frontend Server | Vite dev server (port 5173) | Nginx (port 80) | -| API URL | `http://localhost:3000/api` | `https://api.bsa.madeamess.online/api` | -| SSL/HTTPS | Not configured | Required | -| Restart Policy | Manual | `unless-stopped` | - -### Production Environment Variables - -```bash -# Database Configuration -DB_PASSWORD=your-secure-database-password-here - -# Domain Configuration -DOMAIN=bsa.madeamess.online -VITE_API_URL=https://api.bsa.madeamess.online/api - -# Authentication Configuration (Generate new secure keys) -JWT_SECRET=your-super-secure-jwt-secret-key-change-in-production-12345 -SESSION_SECRET=your-super-secure-session-secret-change-in-production-67890 - -# Google OAuth Configuration -GOOGLE_CLIENT_ID=308004695553-6k34bbq22frc4e76kejnkgq8mncepbbg.apps.googleusercontent.com -GOOGLE_CLIENT_SECRET=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 -GOOGLE_REDIRECT_URI=https://api.bsa.madeamess.online/auth/google/callback - -# Frontend URL -FRONTEND_URL=https://bsa.madeamess.online - -# Flight API Configuration -AVIATIONSTACK_API_KEY=your-aviationstack-api-key - -# Admin Configuration -ADMIN_PASSWORD=your-secure-admin-password - -# Port Configuration -PORT=3000 -``` - -### Production-Specific Troubleshooting - -**SSL Certificate errors**: Ensure certificates are properly configured -**Domain resolution**: Verify DNS settings for your domains -**Environment variables**: Check that all required variables are set in `.env.prod` -**Firewall**: Ensure ports 80, 443, 3000 are accessible - -### Production Logs - -```bash -# View production container logs -docker-compose -f docker-compose.prod.yml logs backend -docker-compose -f docker-compose.prod.yml logs frontend -docker-compose -f docker-compose.prod.yml logs db - -# Follow logs in real-time -docker-compose -f docker-compose.prod.yml logs -f -``` - -This setup guide reflects the current simple, effective architecture of the VIP Coordinator system with production-ready deployment capabilities. \ No newline at end of file diff --git a/TESTING.md b/TESTING.md deleted file mode 100644 index ca47639..0000000 --- a/TESTING.md +++ /dev/null @@ -1,344 +0,0 @@ -# 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 -```bash -# Using Make -make test - -# Using Docker Compose -docker-compose -f docker-compose.test.yml up -``` - -### Running Specific Test Suites -```bash -# 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 -```typescript -// 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 -```typescript -// 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 -```bash -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 -```typescript -// 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(); - expect(screen.getByLabelText(/full name/i)).toBeInTheDocument(); - }); -}); -``` - -#### Page Tests -```typescript -// 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(); - 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 -```bash -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 -```typescript -// 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 -```bash -# 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 -```bash -# 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 -```bash -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`: -```env -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 -```bash -# Check if ports are in use -lsof -i :5433 # Test database -lsof -i :6380 # Test Redis -``` - -#### Database Connection Issues -```bash -# 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 -```bash -# 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: -```bash -# 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](https://jestjs.io/docs/getting-started) -- [Vitest Documentation](https://vitest.dev/guide/) -- [React Testing Library](https://testing-library.com/docs/react-testing-library/intro/) -- [Playwright Documentation](https://playwright.dev/docs/intro) -- [Supertest Documentation](https://github.com/visionmedia/supertest) \ No newline at end of file diff --git a/TESTING_QUICKSTART.md b/TESTING_QUICKSTART.md deleted file mode 100644 index 1dfea92..0000000 --- a/TESTING_QUICKSTART.md +++ /dev/null @@ -1,137 +0,0 @@ -# Testing Quick Start Guide - -## 🚀 Get Testing in 5 Minutes - -### 1. Prerequisites -- Docker installed and running -- Node.js 20+ (for local development) -- Make command available - -### 2. Initial Setup -```bash -# Clone and navigate to project -cd vip-coordinator - -# Copy environment variables -cp .env.example .env - -# Edit .env and add your values (or use defaults for testing) -``` - -### 3. Run Your First Tests - -#### Option A: Using Docker (Recommended) -```bash -# Run all tests -make test - -# Run specific test suites -make test-backend # Backend only -make test-frontend # Frontend only -``` - -#### Option B: Local Development -```bash -# Backend tests -cd backend -npm install -npm test - -# Frontend tests -cd ../frontend -npm install -npm test -``` - -### 4. Writing Your First Test - -#### Backend Test Example -Create `backend/src/routes/__tests__/health.test.ts`: -```typescript -import request from 'supertest'; -import express from 'express'; - -const app = express(); -app.get('/health', (req, res) => res.json({ status: 'ok' })); - -describe('Health Check', () => { - it('should return status ok', async () => { - const response = await request(app).get('/health'); - expect(response.status).toBe(200); - expect(response.body.status).toBe('ok'); - }); -}); -``` - -#### Frontend Test Example -Create `frontend/src/components/__tests__/Button.test.tsx`: -```typescript -import { render, screen } from '@testing-library/react'; -import { Button } from '../Button'; - -describe('Button', () => { - it('renders with text', () => { - render(); - expect(screen.getByText('Click me')).toBeInTheDocument(); - }); -}); -``` - -### 5. Common Commands - -```bash -# Database setup -make db-setup # Initialize test database - -# Run tests with coverage -make test-coverage # Generate coverage reports - -# Clean up -make clean # Remove all test containers - -# Get help -make help # Show all available commands -``` - -### 6. VS Code Integration - -Add to `.vscode/settings.json`: -```json -{ - "jest.autoRun": { - "watch": true, - "onStartup": ["all-tests"] - }, - "vitest.enable": true, - "vitest.commandLine": "npm test" -} -``` - -### 7. Debugging Tests - -```bash -# Run specific test file -npm test -- authService.test.ts - -# Run in watch mode -npm run test:watch - -# Debug mode -node --inspect-brk node_modules/.bin/jest --runInBand -``` - -### 8. Tips - -- ✅ Run tests before committing -- ✅ Write tests for new features -- ✅ Keep tests simple and focused -- ✅ Use the provided fixtures and utilities -- ✅ Check coverage reports regularly - -### Need Help? - -- See `TESTING.md` for detailed documentation -- Check example tests in `__tests__` directories -- Review `TESTING_SETUP_SUMMARY.md` for architecture overview - -Happy Testing! 🎉 \ No newline at end of file diff --git a/TESTING_SETUP_SUMMARY.md b/TESTING_SETUP_SUMMARY.md deleted file mode 100644 index fd71072..0000000 --- a/TESTING_SETUP_SUMMARY.md +++ /dev/null @@ -1,223 +0,0 @@ -# VIP Coordinator - Testing Infrastructure Setup Summary - -## Overview -This document summarizes the comprehensive testing infrastructure that has been set up for the VIP Transportation Coordination System. The system previously had NO automated tests, and now has a complete testing framework ready for implementation. - -## What Was Accomplished - -### 1. ✅ Backend Testing Infrastructure (Jest + Supertest) -- **Configuration**: Created `backend/jest.config.js` with TypeScript support -- **Test Setup**: Created `backend/src/tests/setup.ts` with: - - Test database initialization - - Redis test instance - - Automatic cleanup between tests - - Global setup/teardown -- **Test Fixtures**: Created `backend/src/tests/fixtures.ts` with: - - Mock users (admin, coordinator, driver, pending) - - Mock VIPs (flight and self-driving) - - Mock drivers and schedule events - - Helper functions for database operations -- **Sample Tests**: Created example tests for: - - Authentication service (`authService.test.ts`) - - VIP API endpoints (`vips.test.ts`) -- **NPM Scripts**: Added test commands to package.json - -### 2. ✅ Frontend Testing Infrastructure (Vitest + React Testing Library) -- **Configuration**: Created `frontend/vitest.config.ts` with: - - JSdom environment - - React plugin - - Coverage configuration -- **Test Setup**: Created `frontend/src/tests/setup.ts` with: - - React Testing Library configuration - - Global mocks (fetch, Google Identity Services) - - Window API mocks -- **Test Utilities**: Created `frontend/src/tests/test-utils.tsx` with: - - Custom render function with providers - - Mock data for all entities - - API response mocks -- **Sample Tests**: Created example tests for: - - GoogleLogin component - - VipForm component -- **NPM Scripts**: Added test commands to package.json - -### 3. ✅ Security Improvements -- **Environment Variables**: - - Created `.env.example` template - - Updated `docker-compose.dev.yml` to use env vars - - Removed hardcoded Google OAuth credentials -- **Secure Config**: Created `backend/src/config/env.ts` with: - - Zod schema validation - - Type-safe environment variables - - Clear error messages for missing vars -- **Git Security**: Verified `.gitignore` includes all sensitive files - -### 4. ✅ Database Migration System -- **Migration Service**: Created `backend/src/services/migrationService.ts` with: - - Automatic migration runner - - Checksum verification - - Migration history tracking - - Migration file generator -- **Seed Service**: Created `backend/src/services/seedService.ts` with: - - Test data for all entities - - Reset functionality - - Idempotent operations -- **CLI Tool**: Created `backend/src/scripts/db-cli.ts` with commands: - - `db:migrate` - Run pending migrations - - `db:migrate:create` - Create new migration - - `db:seed` - Seed test data - - `db:setup` - Complete database setup -- **NPM Scripts**: Added all database commands - -### 5. ✅ Docker Test Environment -- **Test Compose File**: Created `docker-compose.test.yml` with: - - Separate test database (port 5433) - - Separate test Redis (port 6380) - - Test runners for backend/frontend - - Health checks for all services - - Memory-based database for speed -- **E2E Dockerfile**: Created `Dockerfile.e2e` for Playwright -- **Test Runner Script**: Created `scripts/test-runner.sh` with: - - Color-coded output - - Service orchestration - - Cleanup handling - - Multiple test modes - -### 6. ✅ CI/CD Pipeline (GitHub Actions) -- **Main CI Pipeline**: Created `.github/workflows/ci.yml` with: - - Backend test job with PostgreSQL/Redis services - - Frontend test job with build verification - - Docker image building and pushing - - Security scanning with Trivy - - Deployment jobs for staging/production -- **E2E Test Schedule**: Created `.github/workflows/e2e-tests.yml` with: - - Daily scheduled runs - - Manual trigger option - - Multi-browser testing - - Result artifacts -- **Dependency Updates**: Created `.github/workflows/dependency-update.yml` with: - - Weekly automated updates - - Security fixes - - Automated PR creation - -### 7. ✅ Enhanced Makefile -Updated `Makefile` with new commands: -- `make test` - Run all tests -- `make test-backend` - Backend tests only -- `make test-frontend` - Frontend tests only -- `make test-e2e` - E2E tests only -- `make test-coverage` - Generate coverage reports -- `make db-setup` - Initialize database -- `make db-migrate` - Run migrations -- `make db-seed` - Seed data -- `make clean` - Clean all Docker resources -- `make help` - Show all commands - -### 8. ✅ Documentation -- **TESTING.md**: Comprehensive testing guide covering: - - How to write tests - - How to run tests - - Best practices - - Troubleshooting - - Coverage reports -- **This Summary**: Complete overview of changes - -## Current State vs. Previous State - -### Before: -- ❌ No automated tests -- ❌ No test infrastructure -- ❌ Hardcoded credentials in Docker files -- ❌ No database migration system -- ❌ No CI/CD pipeline -- ❌ No test documentation - -### After: -- ✅ Complete test infrastructure for backend and frontend -- ✅ Sample tests demonstrating patterns -- ✅ Secure environment variable handling -- ✅ Database migration and seeding system -- ✅ Docker test environment -- ✅ GitHub Actions CI/CD pipeline -- ✅ Comprehensive documentation -- ✅ Easy-to-use Make commands - -## Next Steps - -The remaining tasks from the todo list that need implementation: - -1. **Create Backend Unit Tests** (High Priority) - - Auth service tests - - Scheduling service tests - - Flight tracking service tests - - Database service tests - -2. **Create Backend Integration Tests** (High Priority) - - Complete VIP API tests - - Driver API tests - - Schedule API tests - - Admin API tests - -3. **Create Frontend Component Tests** (Medium Priority) - - Navigation components - - Form components - - Dashboard components - - Error boundary tests - -4. **Create Frontend Integration Tests** (Medium Priority) - - Page-level tests - - User workflow tests - - API integration tests - -5. **Set up E2E Testing Framework** (Medium Priority) - - Install Playwright properly - - Create page objects - - Set up test data management - -6. **Create E2E Tests** (Medium Priority) - - Login flow - - VIP management flow - - Driver assignment flow - - Schedule management flow - -## How to Get Started - -1. **Install Dependencies**: - ```bash - cd backend && npm install - cd ../frontend && npm install - ``` - -2. **Set Up Environment**: - ```bash - cp .env.example .env - # Edit .env with your values - ``` - -3. **Run Tests**: - ```bash - make test # Run all tests - ``` - -4. **Start Writing Tests**: - - Use the example tests as templates - - Follow the patterns established - - Refer to TESTING.md for guidelines - -## Benefits of This Setup - -1. **Quality Assurance**: Catch bugs before production -2. **Refactoring Safety**: Change code with confidence -3. **Documentation**: Tests serve as living documentation -4. **CI/CD**: Automated deployment pipeline -5. **Security**: No more hardcoded credentials -6. **Developer Experience**: Easy commands and clear structure - -## Technical Debt Addressed - -1. **No Tests**: Now have complete test infrastructure -2. **Security Issues**: Credentials now properly managed -3. **No Migrations**: Database changes now versioned -4. **Manual Deployment**: Now automated via CI/CD -5. **No Standards**: Clear testing patterns established - -This testing infrastructure provides a solid foundation for maintaining and scaling the VIP Coordinator application with confidence. \ No newline at end of file