PSA/server/docs/PERSISTENT_TEST_HARNESS.md

Persistent E2E Test Harness

This guide explains how to use the persistent E2E test harness for faster and more efficient testing.

Overview

The persistent test harness starts all required services once and keeps them running while you run multiple test suites. This eliminates the overhead of starting/stopping Docker containers for each test run, making E2E tests much faster.

Architecture

Services Included

• PostgreSQL (port 5433) - Test database
• Redis (port 6380) - Test cache and workflow events
• MailHog (ports 1025/8025) - Email capture for testing
• Workflow Worker (port 4001) - Processes workflow events
• Webhook Mock (port 8080) - Mock external webhooks

Test Optimization

• Services start once and stay running
• Only test data is cleaned between tests
• Database connections are reused
• Faster service health checks
• Reduced timeouts for warm services

Quick Start

1. Start the Test Harness

npm run test:harness:start

This will:

• Start all Docker services
• Wait for health checks to pass
• Display service status
• Keep services running in the background

2. Run E2E Tests

# Run optimized email processing tests
npm test src/test/e2e/email-processing-persistent.test.ts

# Or run any E2E test against the persistent harness
npm test src/test/e2e/

3. Check Service Status

npm run test:harness:status

4. Stop the Test Harness (when done)

npm run test:harness:stop

Available Commands

Command	Description
npm run test:harness:start	Start all test services
npm run test:harness:stop	Stop all test services
npm run test:harness:restart	Restart all test services
npm run test:harness:status	Check service health status
npm run test:harness:logs	View logs from all services
npm run test:harness:logs mailhog	View logs from specific service
npm run test:harness:reset	Reset test data without restarting services

Performance Comparison

Traditional E2E Tests

• Setup time: 30-60 seconds per test suite
• Teardown time: 10-20 seconds per test suite
• Total overhead: 40-80 seconds per test suite

Persistent Harness E2E Tests

• Setup time: 2-5 seconds per test suite
• Teardown time: 1-2 seconds per test suite
• Total overhead: 3-7 seconds per test suite

Result: 80-90% reduction in test overhead time!

Usage Patterns

Development Workflow

# Start harness once in the morning
npm run test:harness:start

# Run tests throughout the day
npm test src/test/e2e/email-processing-persistent.test.ts
npm test src/test/e2e/workflow-integration.test.ts

# Stop harness at end of day
npm run test:harness:stop

CI/CD Pipeline

# In your CI script
npm run test:harness:start
npm test src/test/e2e/
npm run test:harness:stop

Debugging

# Start harness
npm run test:harness:start

# View logs while running tests
npm run test:harness:logs

# Check specific service
npm run test:harness:logs workflow-worker-test

Test Files

Optimized Tests

• email-processing-persistent.test.ts - Email processing with persistent harness
• Use PersistentE2ETestContext for faster setup/teardown

Traditional Tests (still available)

• email-processing.test.ts - Email processing with service startup/shutdown
• Use E2ETestContext for isolated service management

Troubleshooting

Services Not Starting

# Check Docker is running
docker info

# Check port conflicts
lsof -i :5433  # PostgreSQL
lsof -i :6380  # Redis
lsof -i :8025  # MailHog
lsof -i :4001  # Workflow Worker

# View detailed logs
npm run test:harness:logs

Test Failures

# Check service health
npm run test:harness:status

# Reset test data
npm run test:harness:reset

# Restart if needed
npm run test:harness:restart

Port Conflicts

If you have conflicts with existing services:

1. Stop conflicting services
2. Or modify ports in docker-compose.e2e-with-worker.yaml
3. Update corresponding URLs in test configuration

Best Practices

1. Start Harness Before Development

Always start the harness at the beginning of your development session:

npm run test:harness:start

2. Monitor Service Health

Periodically check that services are healthy:

npm run test:harness:status

3. Reset Data When Needed

If tests start behaving unexpectedly, reset the data:

npm run test:harness:reset

4. Use Persistent Tests

For regular development, use the optimized persistent test files:

npm test src/test/e2e/email-processing-persistent.test.ts

5. Clean Shutdown

Always stop the harness when done to free resources:

npm run test:harness:stop

Configuration

Service Ports

• PostgreSQL: 5433 (different from production 5432)
• Redis: 6380 (different from production 6379)
• MailHog SMTP: 1025
• MailHog Web: 8025
• Workflow Worker: 4001
• Webhook Mock: 8080

Environment Variables

The persistent harness automatically sets:

• DB_HOST=localhost
• DB_PORT=5433
• DB_NAME_SERVER=server
• REDIS_HOST=localhost
• REDIS_PORT=6380
• EMAIL_HOST=localhost
• EMAIL_PORT=1025

Extending the Harness

Adding New Services

1. Add service to docker-compose.e2e-with-worker.yaml
2. Add health check to scripts/test-harness.js
3. Update PersistentE2ETestContext.verifyServicesRunning()

Custom Test Context

Create your own persistent test context by extending PersistentE2ETestContext:

import { PersistentE2ETestContext } from './utils/persistent-test-context';

export class MyCustomTestContext extends PersistentE2ETestContext {
  // Add custom setup/teardown logic
}