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:

Issue	Solution
Port already in use (3000/8080/5432)	make stop then make dev OR change ports in .env
Database won't connect	Ensure Docker is running: docker ps
Backend panic on startup	Check migrations: make db-reset
Frontend build errors	Clear cache: cd edgequake_webui && rm -rf .next node_modules && make frontend-dev

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://loca

---

*Content truncated.*