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

# Phase 1 Testing Guide - How to Verify Implementation

**Date**: 2025-10-16
**Version**: v1.0.5 "Cost Optimizer"
**Purpose**: Comprehensive testing guide to verify Phase 1 implementation

---

## Overview

This guide explains how to test and verify that Phase 1 (Multi-Model Router + Streaming MCP Tools) is implemented correctly according to requirements.

---

## 1. Quick Verification Checklist

Before detailed testing, verify these basics:

```bash
# 1. Build verification (MUST PASS)
npm run build
# Expected: No errors, clean compilation

# 2. Type checking (MUST PASS)
npm run typecheck
# Expected: No type errors

# 3. Check files exist
ls -la src/core/routing/
ls -la src/mcp/streaming/
# Expected: See all implementation files

# 4. Check imports work
node -e "require('./dist/core/routing/index.js')"
# Expected: No errors
```

✅ If all pass, implementation files are correctly structured.

---

## 2. Manual Testing - Multi-Model Router

### Test 1: Router Initialization

Create test file: `tests/manual/test-router-init.ts`

```typescript
import {
  AdaptiveModelRouter,
  ModelRouter,
  AIModel,
  DEFAULT_ROUTER_CONFIG
} from '../../src/core/routing';
import { SwarmMemoryManager } from '../../src/core/memory/SwarmMemoryManager';
import { EventBus } from '../../src/core/EventBus';

async function testRouterInit() {
  console.log('🧪 Testing Router Initialization...\n');

  // 1. Create dependencies
  const memoryStore = new SwarmMemoryManager(':memory:');
  await memoryStore.initialize();

  const eventBus = new EventBus();

  // 2. Create router
  const router = new AdaptiveModelRouter(
    memoryStore,
    eventBus,
    DEFAULT_ROUTER_CONFIG
  );

  console.log('✅ Router initialized successfully');
  console.log('Config:', DEFAULT_ROUTER_CONFIG);

  await memoryStore.close();
}

testRouterInit().catch(console.error);
```

Run:
```bash
npx ts-node tests/manual/test-router-init.ts
```

**Expected Result**: "✅ Router initialized successfully"

---

### Test 2: Model Selection

Create test file: `tests/manual/test-model-selection.ts`

```typescript
import {
  AdaptiveModelRouter,
  AIModel,
  TaskComplexity,
  QETask
} from '../../src/core/routing';
import { SwarmMemoryManager } from '../../src/core/memory/SwarmMemoryManager';
import { EventBus } from '../../src/core/EventBus';

async function testModelSelection() {
  console.log('🧪 Testing Model Selection...\n');

  const memoryStore = new SwarmMemoryManager(':memory:');
  await memoryStore.initialize();
  const eventBus = new EventBus();

  const router = new AdaptiveModelRouter(memoryStore, eventBus, {
    enabled: true,
    defaultModel: AIModel.CLAUDE_SONNET_4_5,
    enableCostTracking: true,
    enableFallback: true,
    maxRetries: 3,
    costThreshold: 1.0
  });

  // Test 1: Simple task → should select GPT-3.5
  const simpleTask: QETask = {
    id: 'test-1',
    type: 'qe-test-generator',
    description: 'Generate simple unit tests',
    data: { complexity: 'simple' },
    priority: 1,
    metadata: {}
  };

  const selection1 = await router.selectModel(simpleTask);
  console.log('Simple Task Selection:');
  console.log('  Model:', selection1.model);
  console.log('  Complexity:', selection1.complexity);
  console.log('  Reasoning:', selection1.reasoning);
  console.log('  Estimated Cost:', `$${selection1.estimatedCost.toFixed(4)}`);

  // Verify: Should be GPT-3.5 (cheapest)
  if (selection1.model === AIModel.GPT_3_5_TURBO) {
    console.log('✅ Simple task correctly routed to GPT-3.5\n');
  } else {
    console.log('❌ Expected GPT-3.5, got:', selection1.model, '\n');
  }

  // Test 2: Complex task → should select GPT-4 or Claude Sonnet
  const complexTask: QETask = {
    id: 'test-2',
    type: 'qe-test-generator',
    description: 'Generate property-based tests with complex edge cases',
    data: { complexity: 'complex', requiresReasoning: true },
    priority: 1,
    metadata: {}
  };

  const selection2 = await router.selectModel(complexTask);
  console.log('Complex Task Selection:');
  console.log('  Model:', selection2.model);
  console.log('  Complexity:', selection2.complexity);
  console.log('  Reasoning:', selection2.reasoning);
  console.log('  Estimated Cost:', `$${selection2.estimatedCost.toFixed(4)}`);

  // Verify: Should be GPT-4 or Claude Sonnet (powerful models)
  if (selection2.model === AIModel.GPT_4 || selection2.model === AIModel.CLAUDE_SONNET_4_5) {
    console.log('✅ Complex task correctly routed to powerful model\n');
  } else {
    console.log('❌ Expected GPT-4 or Claude Sonnet, got:', selection2.model, '\n');
  }

  // Test 3: Security critical task → should select Claude Sonnet 4.5
  const criticalTask: QETask = {
    id: 'test-3',
    type: 'qe-security-scanner',
    description: 'Security vulnerability analysis',
    data: { requiresSecurity: true },
    priority: 1,
    metadata: {}
  };

  const selection3 = await router.selectModel(criticalTask);
  console.log('Critical Task Selection:');
  console.log('  Model:', selection3.model);
  console.log('  Complexity:', selection3.complexity);
  console.log('  Reasoning:', selection3.reasoning);
  console.log('  Estimated Cost:', `$${selection3.estimatedCost.toFixed(4)}`);

  // Verify: Should be Claude Sonnet 4.5 (most capable)
  if (selection3.model === AIModel.CLAUDE_SONNET_4_5) {
    console.log('✅ Critical task correctly routed to Claude Sonnet 4.5\n');
  } else {
    console.log('❌ Expected Claude Sonnet 4.5, got:', selection3.model, '\n');
  }

  await memoryStore.close();
}

testModelSelection().catch(console.error);
```

Run:
```bash
npx ts-node tests/manual/test-model-selection.ts
```

**Expected Results**:
- Simple task → GPT-3.5 (cheapest)
- Complex task → GPT-4 or Claude Sonnet (powerful)
- Critical task → Claude Sonnet 4.5 (most capable)

---

### Test 3: Cost Tracking

Create test file: `tests/manual/test-cost-tracking.ts`

```typescript
import {
  AdaptiveModelRouter,
  AIModel
} from '../../src/core/routing';
import { SwarmMemoryManager } from '../../src/core/memory/SwarmMemoryManager';
import { EventBus } from '../../src/core/EventBus';

async function testCostTracking() {
  console.log('🧪 Testing Cost Tracking...\n');

  const memoryStore = new SwarmMemoryManager(':memory:');
  await memoryStore.initialize();
  const eventBus = new EventBus();

  const router = new AdaptiveModelRouter(memoryStore, eventBus, {
    enabled: true,
    defaultModel: AIModel.CLAUDE_SONNET_4_5,
    enableCostTracking: true,
    enableFallback: true,
    maxRetries: 3,
    costThreshold: 1.0
  });

  // Simulate token usage for different models
  console.log('Tracking costs for multiple model calls...\n');

  await router.trackCost(AIModel.GPT_3_5_TURBO, 1000);
  await router.trackCost(AIModel.GPT_4, 500);
  await router.trackCost(AIModel.CLAUDE_HAIKU, 2000);
  await router.trackCost(AIModel.CLAUDE_SONNET_4_5, 1500);

  // Get statistics
  const stats = await router.getStats();

  console.log('Cost Statistics:');
  console.log('  Total Requests:', stats.totalRequests);
  console.log('  Total Cost:', `$${stats.totalCost.toFixed(4)}`);
  console.log('  Average Cost per Task:', `$${stats.avgCostPerTask.toFixed(4)}`);
  console.log('  Cost Savings:', `$${stats.costSavings.toFixed(4)}`);
  console.log('\nModel Distribution:');
  for (const [model, count] of Object.entries(stats.modelDistribution)) {
    console.log(`  ${model}: ${count} requests`);
  }

  // Verify: Total cost should be calculated
  if (stats.totalCost > 0) {
    console.log('\n✅ Cost tracking working correctly');
  } else {
    console.log('\n❌ Cost tracking not working - total cost is 0');
  }

  // Export cost dashboard
  const dashboard = await router.exportCostDashboard();
  console.log('\n✅ Cost dashboard exported:', JSON.stringify(dashboard, null, 2));

  await memoryStore.close();
}

testCostTracking().catch(console.error);
```

Run:
```bash
npx ts-node tests/manual/test-cost-tracking.ts
```

**Expected Results**:
- Total cost calculated correctly
- Model distribution shows all 4 models
- Dashboard exports successfully

---

### Test 4: Fallback Mechanism

Create test file: `tests/manual/test-fallback.ts`

```typescript
import {
  AdaptiveModelRouter,
  AIModel,
  QETask
} from '../../src/core/routing';
import { SwarmMemoryManager } from '../../src/core/memory/SwarmMemoryManager';
import { EventBus } from '../../src/core/EventBus';

async function testFallback() {
  console.log('🧪 Testing Fallback Mechanism...\n');

  const memoryStore = new SwarmMemoryManager(':memory:');
  await memoryStore.initialize();
  const eventBus = new EventBus();

  const router = new AdaptiveModelRouter(memoryStore, eventBus, {
    enabled: true,
    defaultModel: AIModel.CLAUDE_SONNET_4_5,
    enableCostTracking: true,
    enableFallback: true,
    maxRetries: 3,
    costThreshold: 1.0
  });

  const task: QETask = {
    id: 'test-fallback',
    type: 'qe-test-generator',
    description: 'Test fallback',
    data: {},
    priority: 1,
    metadata: {}
  };

  // Test fallback chain for each model
  console.log('Testing fallback chains:\n');

  const models = [
    AIModel.GPT_4,
    AIModel.GPT_3_5_TURBO,
    AIModel.CLAUDE_SONNET_4_5,
    AIModel.CLAUDE_HAIKU
  ];

  for (const model of models) {
    const fallback = router.getFallbackModel(model, task);
    console.log(`${model} → ${fallback}`);
  }

  console.log('\n✅ Fallback mechanism implemented');

  await memoryStore.close();
}

testFallback().catch(console.error);
```

Run:
```bash
npx ts-node tests/manual/test-fallback.ts
```

**Expected Results**:
- Each model has a defined fallback
- Fallback chains make sense (expensive → cheaper)

---

## 3. Manual Testing - Streaming MCP Tools

### Test 5: Streaming Progress Updates

Create test file: `tests/manual/test-streaming.ts`

```typescript
import { TestExecuteStreamHandler } from '../../src/mcp/streaming/TestExecuteStreamHandler';
import { StreamingMCPTool } from '../../src/mcp/streaming/StreamingMCPTool';
import { EventEmitter } from 'events';

async function testStreaming() {
  console.log('🧪 Testing Streaming Progress...\n');

  const memoryStore = new Map<string, any>();
  const eventBus = new EventEmitter();

  const handler = new TestExecuteStreamHandler(memoryStore, eventBus);

  // Create test execution spec
  const spec = {
    testSuites: ['tests/unit/example.test.ts'],
    environments: ['node'],
    parallelExecution: false,
    retryCount: 0,
    timeoutSeconds: 30,
    reportFormat: 'json' as const
  };

  const params = {
    spec,
    fleetId: 'test-fleet',
    enableRealtimeUpdates: true
  };

  console.log('Starting streaming execution...\n');

  // Execute with progress tracking
  try {
    const generator = handler.execute(params);

    let progressCount = 0;
    let hasResult = false;

    for await (const event of generator) {
      if (event.type === 'progress') {
        progressCount++;
        console.log(`Progress ${progressCount}: ${event.message} (${event.percent}%)`);
      } else if (event.type === 'result') {
        hasResult = true;
        console.log('\nFinal Result:', JSON.stringify(event.data, null, 2));
      }
    }

    if (progressCount > 0) {
      console.log(`\n✅ Streaming working: ${progressCount} progress updates received`);
    } else {
      console.log('\n⚠️ No progress updates received');
    }

    if (hasResult) {
      console.log('✅ Final result received');
    } else {
      console.log('⚠️ No final result received');
    }

  } catch (error) {
    console.error('❌ Streaming error:', error);
  }
}

testStreaming().catch(console.error);
```

Run:
```bash
npx ts-node tests/manual/test-streaming.ts
```

**Expected Results**:
- Multiple progress updates emitted
- Final result received at end
- Progress percentage increases

---

## 4. Integration Testing - Router + Streaming Together

### Test 6: Full Integration

Create test file: `tests/manual/test-integration.ts`

```typescript
import {
  createRoutingEnabledFleetManager,
  AIModel
} from '../../src/core/routing';
import { FleetManager } from '../../src/core/FleetManager';
import { Task } from '../../src/core/Task';
import { SwarmMemoryManager } from '../../src/core/memory/SwarmMemoryManager';
import { EventBus } from '../../src/core/EventBus';

async function testIntegration() {
  console.log('🧪 Testing Full Integration (Router + Fleet)...\n');

  // 1. Set up infrastructure
  const memoryStore = new SwarmMemoryManager(':memory:');
  await memoryStore.initialize();

  const eventBus = new EventBus();
  const fleetManager = new FleetManager(memoryStore, eventBus);

  // 2. Enable routing
  const routingFleet = createRoutingEnabledFleetManager(
    fleetManager,
    memoryStore,
    eventBus,
    { enabled: true }
  );

  console.log('✅ Routing-enabled FleetManager created\n');

  // 3. Create a test task
  const task = new Task(
    'test-generation',
    'Generate unit tests for UserService',
    {
      filePath: './src/services/UserService.ts',
      framework: 'jest',
      coverageTarget: 95
    },
    {
      capabilities: ['ai-test-generation'],
      agentTypes: ['test-generator']
    }
  );

  // 4. Listen for routing events
  let modelSelected = false;
  eventBus.on('routing:model-selected', (data) => {
    console.log('🎯 Model Selected Event:');
    console.log('  Task ID:', data.taskId);
    console.log('  Model:', data.model);
    console.log('  Complexity:', data.complexity);
    console.log('  Reasoning:', data.reasoning);
    modelSelected = true;
  });

  // 5. Submit task (routing should happen automatically)
  console.log('Submitting task...\n');
  await routingFleet.submitTask(task);

  // 6. Verify routing happened
  if (modelSelected) {
    console.log('\n✅ Integration test passed: Router intercepted task');
  } else {
    console.log('\n⚠️ No routing event received');
  }

  // 7. Get router statistics
  const stats = await routingFleet.getRouterStats();
  console.log('\nRouter Statistics:');
  console.log('  Total Requests:', stats.totalRequests);
  console.log('  Total Cost:', `$${stats.totalCost.toFixed(4)}`);

  await memoryStore.close();
}

testIntegration().catch(console.error);
```

Run:
```bash
npx ts-node tests/manual/test-integration.ts
```

**Expected Results**:
- Routing event emitted when task submitted
- Model selection logged
- Statistics updated

---

## 5. Feature Flag Testing

### Test 7: Feature Flags On/Off

Create test file: `tests/manual/test-feature-flags.ts`

```typescript
import {
  createRoutingEnabledFleetManager,
  AIModel
} from '../../src/core/routing';
import { FleetManager } from '../../src/core/FleetManager';
import { SwarmMemoryManager } from '../../src/core/memory/SwarmMemoryManager';
import { EventBus } from '../../src/core/EventBus';

async function testFeatureFlags() {
  console.log('🧪 Testing Feature Flags...\n');

  const memoryStore = new SwarmMemoryManager(':memory:');
  await memoryStore.initialize();
  const eventBus = new EventBus();
  const fleetManager = new FleetManager(memoryStore, eventBus);

  // Test 1: Routing DISABLED (default)
  console.log('Test 1: Routing disabled (default behavior)');
  const disabledFleet = createRoutingEnabledFleetManager(
    fleetManager,
    memoryStore,
    eventBus,
    { enabled: false }
  );

  console.log('✅ Fleet created with routing disabled\n');

  // Test 2: Routing ENABLED
  console.log('Test 2: Routing enabled');
  const enabledFleet = createRoutingEnabledFleetManager(
    fleetManager,
    memoryStore,
    eventBus,
    { enabled: true }
  );

  console.log('✅ Fleet created with routing enabled\n');

  // Test 3: Per-request override
  console.log('Test 3: Feature flags are configurable');
  console.log('✅ Configuration can be changed at runtime\n');

  await memoryStore.close();
}

testFeatureFlags().catch(console.error);
```

Run:
```bash
npx ts-node tests/manual/test-feature-flags.ts
```

**Expected Results**:
- Both enabled and disabled modes work
- No errors when toggling flags

---

## 6. Automated Test Suite (When Jest Fixed)

Once Jest infrastructure is fixed, run:

```bash
# Run Phase 1 unit tests
npm test -- tests/unit/routing/ModelRouter.test.ts
npm test -- tests/unit/mcp/StreamingMCPTool.test.ts

# Run integration tests
npm test -- tests/integration/phase1/

# Run performance tests
npm test -- tests/performance/phase1-perf.test.ts

# Run with coverage
npm test -- --coverage --testPathPattern="phase1|routing|streaming"
```

**Expected Results**:
- 90%+ tests passing
- Code coverage > 90%
- Performance targets met

---

## 7. Performance Benchmarking

Create test file: `tests/manual/benchmark-phase1.ts`

```typescript
import {
  AdaptiveModelRouter,
  AIModel,
  QETask
} from '../../src/core/routing';
import { SwarmMemoryManager } from '../../src/core/memory/SwarmMemoryManager';
import { EventBus } from '../../src/core/EventBus';

async function benchmark() {
  console.log('⚡ Phase 1 Performance Benchmarks\n');

  const memoryStore = new SwarmMemoryManager(':memory:');
  await memoryStore.initialize();
  const eventBus = new EventBus();

  const router = new AdaptiveModelRouter(memoryStore, eventBus, {
    enabled: true,
    defaultModel: AIModel.CLAUDE_SONNET_4_5,
    enableCostTracking: true,
    enableFallback: true,
    maxRetries: 3,
    costThreshold: 1.0
  });

  const task: QETask = {
    id: 'benchmark',
    type: 'qe-test-generator',
    description: 'Benchmark task',
    data: {},
    priority: 1,
    metadata: {}
  };

  // Benchmark 1: Model Selection Latency
  console.log('1. Model Selection Latency (target: <50ms)');
  const iterations = 100;
  let totalTime = 0;

  for (let i = 0; i < iterations; i++) {
    const start = Date.now();
    await router.selectModel(task);
    const end = Date.now();
    totalTime += (end - start);
  }

  const avgLatency = totalTime / iterations;
  console.log(`   Average: ${avgLatency.toFixed(2)}ms`);

  if (avgLatency < 50) {
    console.log('   ✅ PASS (< 50ms)\n');
  } else {
    console.log(`   ⚠️ FAIL (> 50ms)\n`);
  }

  // Benchmark 2: Cost Tracking Overhead
  console.log('2. Cost Tracking Overhead (target: <1ms)');
  totalTime = 0;

  for (let i = 0; i < iterations; i++) {
    const start = Date.now();
    await router.trackCost(AIModel.GPT_3_5_TURBO, 1000);
    const end = Date.now();
    totalTime += (end - start);
  }

  const avgCostTracking = totalTime / iterations;
  console.log(`   Average: ${avgCostTracking.toFixed(2)}ms`);

  if (avgCostTracking < 1) {
    console.log('   ✅ PASS (< 1ms)\n');
  } else {
    console.log(`   ⚠️ FAIL (> 1ms)\n`);
  }

  // Benchmark 3: Statistics Retrieval
  console.log('3. Statistics Retrieval');
  const start = Date.now();
  await router.getStats();
  const end = Date.now();
  console.log(`   Time: ${end - start}ms`);
  console.log('   ✅ Complete\n');

  await memoryStore.close();
}

benchmark().catch(console.error);
```

Run:
```bash
npx ts-node tests/manual/benchmark-phase1.ts
```

**Expected Results**:
- Model selection: <50ms ✅
- Cost tracking: <1ms ✅
- All benchmarks pass

---

## 8. Verification Checklist

Use this checklist to confirm Phase 1 is fully implemented:

### Multi-Model Router

- [ ] ✅ Build compiles (0 TypeScript errors)
- [ ] ✅ AdaptiveModelRouter class exists
- [ ] ✅ ComplexityAnalyzer works (simple/moderate/complex/critical)
- [ ] ✅ CostTracker persists to SwarmMemoryManager
- [ ] ✅ Model selection returns correct models for task types
- [ ] ✅ Fallback chains defined for all models
- [ ] ✅ Feature flags work (enabled/disabled)
- [ ] ✅ Events emitted for monitoring
- [ ] ✅ FleetManager integration wrapper works
- [ ] ✅ Cost dashboard exports successfully

### Streaming MCP Tools

- [ ] ✅ StreamingMCPTool base class exists
- [ ] ✅ TestExecuteStreamHandler streams progress
- [ ] ✅ CoverageAnalyzeStreamHandler streams coverage
- [ ] ✅ Progress protocol defined (ToolProgress, ToolResult)
- [ ] ✅ AsyncGenerator pattern works
- [ ] ✅ Resource cleanup happens
- [ ] ✅ Error handling robust
- [ ] ✅ Backward compatible (non-streaming still works)

### Documentation

- [ ] ✅ User guides complete (4 docs)
- [ ] ✅ API references complete (2 docs)
- [ ] ✅ Architecture documented (2 docs)
- [ ] ✅ Migration guide provided
- [ ] ✅ Code examples work

### Performance

- [ ] ⚠️ Model selection <50ms (needs benchmark)
- [ ] ⚠️ Cost tracking <1ms (needs benchmark)
- [ ] ⚠️ Streaming overhead <5% (needs measurement)

---

## 9. Known Issues

### Jest Test Infrastructure

**Issue**: `ENOENT: no such file or directory, uv_cwd`

**Impact**: Cannot run automated test suite

**Workaround**: Use manual testing scripts above

**Fix**: Debug Jest configuration
```bash
# Try different test environments
npm test -- --testEnvironment=node

# Check for conflicting packages
npm ls graceful-fs

# Update Jest config in jest.config.js
```

---

## 10. Next Steps After Verification

Once all manual tests pass:

1. **Fix Jest infrastructure** (2-4 hours)
2. **Run automated test suite** (2 hours)
3. **Performance benchmarks** (4 hours)
4. **Create test report** (1 hour)
5. **Ready for release decision**

---

## Summary

**To verify Phase 1 implementation:**

1. ✅ Run build and typecheck (1 min)
2. ✅ Run 7 manual test scripts (15-30 min)
3. ✅ Check verification checklist (5 min)
4. ⚠️ Run performance benchmarks (optional, 10 min)
5. ⚠️ Fix Jest and run automated tests (when ready)

**Confidence**: If manual tests pass, Phase 1 is correctly implemented per requirements.

---

**Created**: 2025-10-16
**Status**: Ready for testing
**Estimated Time**: 30-45 minutes for full manual verification