proffesor-for-testing__agentic-qe/docs/phase3/TESTING-GUIDE.md

Phase 3 Visualization Services - Testing Guide

🎯 Services Status

All backend services are RUNNING:

• ✅ WebSocket Server: ws://localhost:8080 (Process ID: 22922)
• ✅ REST API Server: http://localhost:3001 (Process ID: 22922)
• ⚠️ React Frontend: Not implemented yet (designed in frontend/ but files don't exist)

📊 Testing the REST API

1. Test Events Endpoint

# Get all events (empty initially - no telemetry data generated yet)
curl -s http://localhost:3001/api/visualization/events | jq '.'

# Response:
# {
#   "success": true,
#   "data": [],
#   "metadata": {
#     "timestamp": "2025-11-21T14:25:02.738Z",
#     "request_id": "req-1763735102737-gqqvjkb",
#     "pagination": {
#       "limit": 50,
#       "offset": 0,
#       "total": 0,
#       "has_more": false
#     }
#   }
# }

2. Test Metrics Endpoint

# Get aggregated metrics
curl -s http://localhost:3001/api/visualization/metrics | jq '.'

# Response includes:
# - time_range (last 24 hours)
# - events (total, by_type, by_agent)
# - reasoning (chains, steps, confidence)
# - overall stats

3. Test All Endpoints

# Events
curl http://localhost:3001/api/visualization/events

# Metrics
curl http://localhost:3001/api/visualization/metrics

# Reasoning chain (example - replace with real ID when available)
curl http://localhost:3001/api/visualization/reasoning/chain-123

# Agent history (example)
curl http://localhost:3001/api/visualization/agents/test-gen/history

# Session data (example)
curl http://localhost:3001/api/visualization/sessions/session-123

# Graph visualization (example)
curl http://localhost:3001/api/visualization/graph/session-123

🔌 Testing the WebSocket Server

1. Install wscat (if not installed)

npm install -g wscat

2. Connect to WebSocket

# Connect to WebSocket server
wscat -c ws://localhost:8080

# You should see:
# Connected (press CTRL+C to quit)

3. Subscribe to Events

Once connected, send subscription message:

{
  "type": "subscribe",
  "agents": ["test-gen", "coverage-analyzer"],
  "event_types": ["test_generated", "coverage_analyzed"],
  "sessions": ["session-123"]
}

4. Test Heartbeat

The server automatically sends heartbeat messages every 30 seconds:

{
  "type": "heartbeat",
  "timestamp": "2025-11-21T14:25:00.000Z",
  "server_time": 1763735100000
}

5. Unsubscribe

{
  "type": "unsubscribe"
}

🧪 Generate Test Data

The REST API returns empty arrays because no telemetry events have been generated yet. To populate data:

Option 1: Run AQE Fleet Agents

# Initialize AQE Fleet
npx aqe init --topology hierarchical --max-agents 10

# Run a test generation task (generates telemetry events)
npx aqe generate --agent qe-test-generator --task "Generate tests for UserService"

# Now query the API again
curl http://localhost:3001/api/visualization/events
# Should show events generated by the agent

Option 2: Manually Insert Test Events

# Use the EventStore API directly (create a test script)
node -e "
const { EventStore } = require('./dist/persistence/event-store.js');
const store = new EventStore({ dbPath: './data/agentic-qe.db' });

store.recordEvent({
  agent_id: 'test-gen',
  event_type: 'test_generated',
  payload: { testCount: 10, coverage: 85 },
  session_id: 'test-session-1'
});

console.log('Test event inserted');
"

# Query again
curl http://localhost:3001/api/visualization/events

📊 Check Service Logs

Backend Services Log

tail -f /tmp/backend-services.log

Check Running Processes

# Check if services are running
netstat -tuln | grep -E ':(3001|8080)'

# Should show:
# tcp6  0  0 :::3001  :::*  LISTEN  (REST API)
# tcp6  0  0 :::8080  :::*  LISTEN  (WebSocket)

# Check process
ps aux | grep "start-visualization-services"

🛑 Stop Services

# Find and kill the services process
pkill -f "start-visualization-services"

# Or if you have the PID (22922 in this case)
kill 22922

# Verify stopped
netstat -tuln | grep -E ':(3001|8080)'
# Should return nothing

🔄 Restart Services

# Start backend services
node scripts/start-visualization-services.ts > /tmp/backend-services.log 2>&1 &

# Check logs
tail -f /tmp/backend-services.log

# Verify running
curl http://localhost:3001/api/visualization/events
wscat -c ws://localhost:8080

🎨 About the Frontend UI

The React frontend was designed but not implemented:

• Architecture documented in docs/implementation/phase3/VISUALIZATION-ARCHITECTURE.md
• Component designs created (MindMap, QualityMetrics, etc.)
• TypeScript config fixed (frontend/tsconfig.json, frontend/vite.config.ts)
• But actual frontend/ directory with React components doesn't exist

To Implement the Frontend (Future Work):

1. Create frontend/ directory structure
2. Implement React components:
   • MindMap.tsx - Interactive Cytoscape.js graph
   • QualityMetrics.tsx - Recharts quality charts
   • EventTimeline.tsx - Timeline visualization
3. Connect to WebSocket at ws://localhost:8080
4. Query REST API at http://localhost:3001/api/visualization/*
5. Run: cd frontend && npm run dev (starts on port 3000)

📈 Integration Testing Workflow

1. Start Services

# Terminal 1: Start backend
node scripts/start-visualization-services.ts

2. Generate Telemetry Data

# Terminal 2: Run AQE agents
npx aqe generate --agent qe-test-generator --task "Test UserService"

3. Verify Data Flow

# Terminal 3: Check REST API
curl http://localhost:3001/api/visualization/events | jq '.data | length'
# Should show > 0 events

# Check metrics
curl http://localhost:3001/api/visualization/metrics | jq '.data.events.total'

4. Monitor Real-time Events

# Terminal 4: Connect WebSocket
wscat -c ws://localhost:8080

# Subscribe to all events
{"type": "subscribe"}

# Watch events stream in real-time as agents run

🐛 Troubleshooting

Services Won't Start

# Check if ports are already in use
lsof -i :3001
lsof -i :8080

# Kill conflicting processes
kill <PID>

# Check database exists
ls -la data/agentic-qe.db

# Create data directory if missing
mkdir -p data

Empty Data Returned

• Cause: No telemetry events generated yet
• Solution: Run AQE Fleet agents to populate data

WebSocket Connection Refused

• Cause: WebSocket server not running
• Solution: Check logs, restart services

TypeScript Errors

# Rebuild project
npm run build

# Check compilation succeeded
echo $?  # Should be 0

✅ Success Criteria

Phase 3 is working correctly when:

• ✅ Both servers start without errors
• ✅ Ports 3001 and 8080 are listening
• ✅ REST API returns valid JSON responses
• ✅ WebSocket accepts connections
• ✅ When AQE agents run, events appear in API responses
• ✅ WebSocket broadcasts events in real-time
• ⚠️ Frontend UI (optional - not implemented yet)

🎯 Current Status Summary

Component	Status	Notes
WebSocket Server	✅ Running	Port 8080, ready for connections
REST API Server	✅ Running	Port 3001, 6 endpoints working
Database	✅ Ready	SQLite at data/agentic-qe.db
Telemetry Data	⚠️ Empty	Need to run AQE agents
React Frontend	❌ Not Implemented	Designed but not built
Grafana Dashboards	✅ Ready	3 dashboards in dashboards/grafana/

---

Generated: 2025-11-21T14:25:00Z Services PID: 22922 Database: ./data/agentic-qe.db