E2e Test Service Management

E2E Test Service Management

When to Use This Skill

Use this skill when you need to:

• Start all services for interactive E2E testing
• Verify service health before running tests
• Monitor logs during test execution
• Stop services cleanly after testing
• Debug test failures with real backend/database
• Test with different configurations (mock LLM vs real LLM)
• Manage service lifecycle in CI/CD pipelines

Perfect For

✅ E2E Testing Workflows - Running Playwright tests with real services
✅ Interactive Debugging - Testing features manually with live backend
✅ Service Isolation - Starting only specific services
✅ Health Monitoring - Detecting service crashes/failures
✅ Log Inspection - Troubleshooting backend/database issues
✅ Test Isolation - Cleaning services between test runs

Service Architecture

Services Overview

┌─────────────────────────────────────────────┐
│           E2E Testing Environment            │
├─────────────────────────────────────────────┤
│                                              │
│  Frontend (Next.js)         Port 3000        │
│  ├─ Playwright Tests                        │
│  ├─ Hot Reload Development                  │
│  └─ TypeScript/React Components              │
│                                              │
│  Backend (Rust)             Port 8080        │
│  ├─ RAG Query Engine                        │
│  ├─ Document Processing                     │
│  ├─ Knowledge Graph API                     │
│  └─ LLM Integration                         │
│                                              │
│  Database (PostgreSQL)       Port 5432       │
│  ├─ pgvector Extension (embeddings)         │
│  ├─ Apache AGE (graph storage)              │
│  ├─ Conversation History                    │
│  └─ Document Metadata                       │
│                                              │
└─────────────────────────────────────────────┘

Service Dependencies

Frontend (3000)
    ↓
Backend (8080)
    ↓
Database (5432)

Services should be started in reverse dependency order: Database → Backend → Frontend
Services should be stopped in dependency order: Frontend → Backend → Database

Quick Start

Start Full Stack (Recommended for Testing)

make dev

What this does:

1. Starts PostgreSQL container (port 5432)
2. Runs backend in development mode (port 8080)
3. Starts frontend dev server (port 3000)
4. Displays URLs and health status

Output example:

✓ PostgreSQL started on localhost:5432
✓ Backend running on http://localhost:8080
✓ Frontend ready on http://localhost:3000

Wait time: 15-30 seconds (depends on system)

Stop All Services

make stop

Stops all services gracefully in the correct order.

Check Service Status

make status

Returns health status of all three services:

🟢 Frontend: http://localhost:3000 (200 OK)
🟢 Backend:  http://localhost:8080 (200 OK)
🟢 Database: localhost:5432 (responding)

Service-Specific Management

Database (PostgreSQL)

Start PostgreSQL Only

make db-start

Starts PostgreSQL container with pgvector and Apache AGE extensions.

Configuration:

• Container name: edgequake-postgres
• Image: postgres:15-alpine with custom extensions
• Volume: edgequake_postgres_data (persistent)
• Port mapping: 5432:5432

Stop PostgreSQL

make db-stop

Stops container gracefully (saves state).

View Database Logs

make db-logs

Streams PostgreSQL logs in real-time for debugging connection issues.

Open Database Shell

make db-shell

Opens interactive psql terminal to:

• Run SQL queries directly
• Inspect conversation history
• Check embeddings storage
• View entity relationships

Reset Database (⚠️ DANGER)

make db-reset

WARNING: Deletes ALL data and reinitializes database. Use only for:

• Cleaning up between test cycles
• Starting with fresh state
• Removing test artifacts

Backend (Rust API)

Start Backend in Development Mode

make backend-dev

Starts backend with:

• Hot reload on code changes
• Debug logging enabled
• Port 8080 (configurable via BACKEND_PORT)
• Automatic database migration

Important Environment Variables:

# Test with real OpenAI
export OPENAI_API_KEY="sk-your-key-here"
make backend-dev

# Test with mock provider (default)
make backend-dev  # Uses mock by default

Build Backend

make backend-build

Creates optimized release binary (slower build, faster runtime).

Run Backend Binary

make backend-run

Runs pre-compiled backend binary (requires backend-build first).

Run Backend Tests

make backend-test

Runs all Rust tests:

• Uses mock LLM provider by default (fast, free)
• To use real OpenAI: OPENAI_API_KEY=sk-... make backend-test

Format & Lint Backend

make backend-fmt      # Format code with rustfmt
make backend-clippy   # Run clippy linter

Frontend (Next.js)

Start Frontend Dev Server

make frontend-dev

Starts development server with:

• Turbopack for fast hot reload
• Port 3000
• TypeScript compilation
• Live error overlay

Build Frontend

make frontend-build

Creates optimized production build in .next/.

Start Production Frontend

make frontend-start

Runs production-optimized server (requires frontend-build first).

Run Frontend Tests

make frontend-test

Runs Jest unit tests for React components.

Lint Frontend Code

make frontend-lint

Runs ESLint to check for code quality issues.

E2E Testing Workflow

Typical Test Execution

# 1. Start all services
make dev
make status              # Verify all are running

# 2. Run Playwright tests
cd edgequake_webui
pnpm exec playwright test

# 3. View test results
# Reports generated in: playwright-report/

# 4. Stop services (when done)
make stop

Running Specific E2E Tests

# Test a specific file
cd edgequake_webui
pnpm exec playwright test e2e/query-page.spec.ts

# Test with specific browser
pnpm exec playwright test --project=chromium

# Run in headed mode (see browser)
pnpm exec playwright test --headed

# Debug mode (pause on failures)
pnpm exec playwright test --debug

Interactive E2E Testing (with MCP Tools)

# 1. Start services
make dev

# 2. Use Playwright MCP tools for interactive testing
# - mcp_microsoft_pla_browser_navigate
# - mcp_microsoft_pla_browser_click
# - mcp_microsoft_pla_browser_type
# - mcp_microsoft_pla_browser_take_screenshot

# 3. Inspect results and failures
# 4. Stop when complete
make stop

Monitor Services During Testing

In separate terminal:

# Watch logs continuously
make db-logs &      # Terminal 1
make backend-logs & # Terminal 2
make frontend-logs &# Terminal 3

# Or view combined logs
tail -f edgequake/target/debug/backend.log

Health Checks & Verification

Manual Health Checks

# Frontend
curl -s http://localhost:3000 | head -20

# Backend API
curl -s http://localhost:8080/api/v1/health | jq

# Database connection
psql -h localhost -U edgequake -d edgequake -c "SELECT 1"

Service Readiness Script

#!/bin/bash
# Wait for all services to be ready

echo "Waiting for services..."

# Frontend
until curl -s http://localhost:3000 > /dev/null 2>&1; do
  echo "  ⏳ Frontend not ready..."
  sleep 1
done
echo "✓ Frontend ready"

# Backend
until curl -s http://localhost:8080/api/v1/health > /dev/null 2>&1; do
  echo "  ⏳ Backend not ready..."
  sleep 1
done
echo "✓ Backend ready"

# Database
until psql -h localhost -U edgequake -d edgequake -c "SELECT 1" > /dev/null 2>&1; do
  echo "  ⏳ Database not ready..."
  sleep 1
done
echo "✓ Database ready"

echo "✅ All services ready for testing"

Troubleshooting

Services Won't Start

Check logs:

make db-logs      # Database issues
make backend-logs # Backend/API issues
make frontend-logs # Frontend issues

Common issues:

Database Connection Issues

# Check PostgreSQL is running
docker ps | grep postgres

# Check logs
docker logs edgequake-postgres

# Test connection directly
psql -h localhost -U edgequake -d edgequake -c "SELECT version()"

Backend Test Failures

# Run backend tests with real LLM
export OPENAI_API_KEY="sk-..."
make backend-test

# Run specific test
cargo test --package edgequake-core --test e2e_pipeline

# See detailed output
cargo test -- --nocapture

Playwright Test Failures

# Run in headed mode to see what's happening
cd edgequake_webui && pnpm exec playwright test --headed

# Run with debug tracing
pnpm exec playwright test --debug

# View test reports
open playwright-report/index.html

Environment Variables

Key Configuration

# Backend
BACKEND_PORT=8080                    # Default
RUST_LOG=debug                       # Log level
OPENAI_API_KEY=sk-...               # Optional (mock by default)

# Frontend
NEXT_PUBLIC_API_URL=http://localhost:8080

# Database
POSTGRES_USER=edgequake
POSTGRES_PASSWORD=edgequake
POSTGRES_DB=edgequake
DATABASE_URL=postgresql://edgequake:edgequake@localhost:5432/edgequake

Create .env.local for overrides

cat > .env.local << EOF
BACKEND_PORT=8080
OPENAI_API_KEY=sk-your-real-key
RUST_LOG=debug
EOF

Best Practices for E2E Testing

1. Always Start with Fresh Services

make stop
make dev
sleep 5  # Wait for startup

2. Monitor Logs During Tests

# Terminal 1: Run tests
cd edgequake_webui && pnpm exec playwright test

# Terminal 2: Monitor backend
make backend-logs

# Terminal 3: Monitor database
make db-logs

3. Use Database Snapshots

# Before risky tests
docker exec edgequake-postgres \
  pg_dump -U edgequake edgequake > /tmp/backup.sql

# After failures, restore
docker exec -i edgequake-postgres \
  psql -U edgequake edgequake < /tmp/backup.sql

4. Test with Different LLM Providers

# Test with mock (fast, deterministic)
make backend-dev

# Test with real OpenAI (costs money, real behavior)
OPENAI_API_KEY=sk-... make backend-dev

5. Check Service Health Before Tests

make status
# All should show 🟢 (green)
# If not, wait and retry

Common E2E Test Patterns

Pattern 1: Test Initial Page Load

# Start services
make dev

# Run focused test
cd edgequake_webui
pnpm exec playwright test --grep "initial load"

Pattern 2: Test with Real Data

# 1. Start services
make dev

# 2. Upload documents via UI or API
curl -X POST http://localhost:8080/api/v1/documents \
  -F "file=@document.pdf"

# 3. Run tests
cd edgequake_webui && pnpm exec playwright test

Pattern 3: Test Error Handling

# 1. Start services
make dev

# 2. Stop backend to simulate failure
make backend-stop

# 3. Run tests to verify error handling
cd edgequake_webui && pnpm exec playwright test

# 4. Restart backend
make backend-dev

Pattern 4: Performance Testing

# 1. Start services with resource monitoring
make dev

# 2. Monitor during test
watch -n 1 'docker stats edgequake-postgres edgequake-backend'

# 3. Run load tests
cd edgequake_webui
pnpm exec playwright test --workers=5  # Parallel execution

Integration with CI/CD

GitHub Actions Example

name: E2E Tests

on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3

      - name: Start services
        run: make dev &

      - name: Wait for services
        run: |
          until curl -s http://localhost:3000; do sleep 1; done
          until curl -s http://localhost:8080/api/v1/health; do sleep 1; done

      - name: Run E2E tests
        run: |
          cd edgequake_webui
          pnpm exec playwright test

      - name: Upload results
        if: always()
        uses: actions/upload-artifact@v3
        with:
          name: playwright-report
          path: edgequake_webui/playwright-report/

      - name: Stop services
        if: always()
        run: make stop

Related Skills

• makefile-dev-workflow - Complete development command reference
• playwright-ux-ui-capture - Capture and document UI workflows
• ux-ui-analyze-single-page - Analyze individual pages

Command Reference Quick Lookup

Session Reflection: Testing Insights

What Worked Well

✅ Service Start/Stop Simplification - Using Make commands instead of manual docker/cargo calls saves time and prevents mistakes
✅ Browser Automation - Interactive E2E testing with MCP tools provides fast feedback and debugging visibility
✅ Console Log Analysis - Monitoring browser and backend logs during tests reveals issues quickly
✅ Isolated Service Management - Starting only needed services reduces resource usage and startup time

Challenges & Solutions

Recommendations

1. Always check make status before running tests
2. Monitor logs in separate terminals during test execution
3. Use db-reset between test cycles for clean state
4. Start small - test one feature, then expand
5. Keep services running for interactive debugging
6. Use MCP tools for browser automation and interactive testing

Last Updated: December 27, 2025
Tested in Session: E2E Testing New Query Button Fix
Verified with: Playwright MCP Tools + Service Management Commands