@debugmcp/mcp-debugger/docs/development/testing-guide.md

Run-time step-through debugging for LLM agents.

# MCP Debug Server - Testing Guide

This guide covers how to write and run tests for the MCP Debug Server project, which maintains 90%+ test coverage.

## Test Framework

The project uses **Vitest** as the test runner, chosen for its:
- Fast execution with native ESM support
- Compatible API with Jest
- Built-in TypeScript support
- Excellent watch mode
- Snapshot testing capabilities

## Running Tests

### Basic Commands

```bash
# Run all tests once
npm test

# Run tests in watch mode (recommended for development)
npm run test:watch

# Run tests with coverage
npm run test:coverage

# Run only unit tests
npm run test:unit

# Run only integration tests
npm run test:integration

# Run a specific test file
npm test -- tests/unit/session/session-manager.test.ts

# Run tests matching a pattern
npm test -- --grep "ProxyManager"
```

### Coverage Reports

```bash
# Generate coverage report
npm run test:coverage

# View HTML coverage report
npm run coverage:report
# Opens in browser: coverage/index.html

# Check coverage thresholds
npm run coverage:check
```

Current coverage thresholds (from `vitest.config.ts`):
- Statements: 90%
- Branches: 85%
- Functions: 90%
- Lines: 90%

## Writing Tests

### Test File Organization

Tests mirror the source code structure:

```
src/session/session-manager.ts
→ tests/unit/session/session-manager.test.ts

src/proxy/proxy-manager.ts
→ tests/unit/proxy/proxy-manager.test.ts
→ tests/unit/proxy/proxy-manager-lifecycle.test.ts
→ tests/unit/proxy/proxy-manager-error.test.ts
```

### Basic Test Structure

```typescript
import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
import { ComponentToTest } from '../../../src/component-to-test.js';

describe('ComponentToTest', () => {
  let component: ComponentToTest;
  let mockDependency: MockType;

  beforeEach(() => {
    // Setup before each test
    mockDependency = createMockDependency();
    component = new ComponentToTest(mockDependency);
  });

  afterEach(() => {
    // Cleanup after each test
    vi.clearAllMocks();
    vi.useRealTimers(); // If using fake timers
  });

  describe('methodName', () => {
    it('should handle normal case', async () => {
      // Arrange
      const input = 'test-input';
      const expectedOutput = 'expected-output';
      
      // Act
      const result = await component.methodName(input);
      
      // Assert
      expect(result).toBe(expectedOutput);
      expect(mockDependency.someMethod).toHaveBeenCalledWith(input);
    });

    it('should handle error case', async () => {
      // Arrange
      mockDependency.someMethod.mockRejectedValue(new Error('Test error'));
      
      // Act & Assert
      await expect(component.methodName('input'))
        .rejects.toThrow('Test error');
    });
  });
});
```

### Testing Patterns

#### 1. Mocking Dependencies

```typescript
// Using test utilities
import { createMockLogger, createMockFileSystem } from '../../utils/test-utils.js';

const mockLogger = createMockLogger();
const mockFileSystem = createMockFileSystem();

// Verify mock calls
expect(mockLogger.info).toHaveBeenCalledWith(
  '[Component] Operation completed',
  { sessionId: 'test-123' }
);
```

#### 2. Testing Async Operations

```typescript
it('should handle async operation', async () => {
  // Setup promise that will resolve
  const resultPromise = Promise.resolve('success');
  vi.mocked(mockService.fetchData).mockReturnValue(resultPromise);
  
  // Test async method
  const result = await component.processData();
  
  // Verify
  expect(result).toBe('success');
});
```

#### 3. Testing with Fake Timers

```typescript
it('should timeout after specified duration', async () => {
  vi.useFakeTimers();
  
  try {
    // Start operation that has timeout
    const operationPromise = component.operationWithTimeout();
    
    // Create expectation before advancing time
    const expectPromise = expect(operationPromise)
      .rejects.toThrow('Operation timed out');
    
    // Advance time
    await vi.advanceTimersByTimeAsync(5001);
    
    // Verify timeout
    await expectPromise;
  } finally {
    vi.useRealTimers();
  }
});
```

#### 4. Testing Event Emissions

```typescript
it('should emit events correctly', async () => {
  // Create promise to capture event
  const eventPromise = new Promise<{ data: string }>((resolve) => {
    component.once('data-ready', (data) => resolve({ data }));
  });
  
  // Trigger action that emits event
  component.processData();
  
  // Verify event
  const result = await eventPromise;
  expect(result.data).toBe('processed');
});
```

#### 5. Testing with Fake Process Implementation

```typescript
import { FakeProxyProcessLauncher } from '../../implementations/test/fake-process-launcher.js';

it('should handle process messages', async () => {
  const fakeLauncher = new FakeProxyProcessLauncher();
  
  // Prepare fake behavior
  fakeLauncher.prepareProxy((proxy) => {
    setTimeout(() => {
      proxy.simulateMessage({
        type: 'status',
        status: 'initialized'
      });
    }, 100);
  });
  
  const manager = new ProxyManager(fakeLauncher, mockFs, mockLogger);
  await manager.start(config);
  
  // Verify process was launched
  expect(fakeLauncher.launchedProxies).toHaveLength(1);
});
```

### Testing Error Scenarios

```typescript
describe('error handling', () => {
  it('should handle file not found', async () => {
    // Mock file system to simulate error
    vi.mocked(mockFileSystem.pathExists).mockResolvedValue(false);
    
    await expect(component.loadFile('missing.txt'))
      .rejects.toThrow('File not found: missing.txt');
  });

  it('should clean up on error', async () => {
    // Simulate error during operation
    vi.mocked(mockService.connect).mockRejectedValue(
      new Error('Connection failed')
    );
    
    await expect(component.initialize()).rejects.toThrow();
    
    // Verify cleanup
    expect(component.isInitialized()).toBe(false);
    expect(mockService.disconnect).toHaveBeenCalled();
  });

  it('should use centralized error messages', async () => {
    await expect(component.operationWithTimeout())
      .rejects.toThrow(ErrorMessages.operationTimeout(30));
  });
});
```

### Integration Testing

Integration tests use real implementations where possible:

```typescript
// tests/integration/python_debug_workflow.test.ts
import { createRealDependencies } from '../utils/integration-helpers.js';

describe('Python Debug Workflow', () => {
  let sessionManager: SessionManager;
  let testPort: number;

  beforeEach(async () => {
    // Use real implementations
    const deps = await createRealDependencies();
    testPort = await TestPortManager.getNextPort();
    
    sessionManager = new SessionManager(
      { logDirBase: './test-logs' },
      deps
    );
  });

  it('should debug Python script end-to-end', async () => {
    // Create session
    const session = await sessionManager.createSession({
      language: DebugLanguage.PYTHON,
      name: 'Integration Test'
    });

    // Set breakpoint
    await sessionManager.setBreakpoint(
      session.id,
      'test-script.py',
      10
    );

    // Start debugging
    const result = await sessionManager.startDebugging(
      session.id,
      'test-script.py'
    );

    expect(result.success).toBe(true);
    
    // ... continue with full workflow
  });
});
```

## Test Utilities

### Mock Creation Helpers

Located in `tests/utils/test-utils.ts`:

```typescript
export function createMockLogger(): ILogger {
  return {
    info: vi.fn(),
    error: vi.fn(),
    debug: vi.fn(),
    warn: vi.fn()
  };
}

export function createMockFileSystem(): IFileSystem {
  return {
    readFile: vi.fn().mockResolvedValue(''),
    writeFile: vi.fn().mockResolvedValue(undefined),
    pathExists: vi.fn().mockResolvedValue(true),
    ensureDir: vi.fn().mockResolvedValue(undefined),
    // ... all required methods
  };
}
```

### Test Fixtures

Located in `tests/fixtures/`:

```typescript
// python-scripts.ts
export const SIMPLE_SCRIPT = `
def main():
    x = 10
    y = 20
    result = x + y
    print(f"Result: {result}")
    
if __name__ == "__main__":
    main()
`;

export const SCRIPT_WITH_LOOP = `
def calculate():
    total = 0
    for i in range(10):
        total += i
    return total
`;
```

### Port Management

For tests that need network ports:

```typescript
import { TestPortManager } from '../utils/port-manager.js';

const port = TestPortManager.getNextPort(); // Returns unique port
// Use port for test...
TestPortManager.release(port); // Optional cleanup
```

## Debugging Tests

### VS Code Debugging

1. Set breakpoint in test file
2. Open test file
3. Press F5 or use "Debug Tests" launch configuration
4. Step through test execution

### Console Logging

```typescript
it('should process data', async () => {
  console.log('Input:', testData);
  
  const result = await component.process(testData);
  
  console.log('Output:', result);
  console.log('Mock calls:', mockService.mock.calls);
  
  expect(result).toBeDefined();
});
```

### Vitest UI Mode

```bash
# Run tests with UI
npm run test:ui
```

This opens a browser with:
- Test execution visualization
- Code coverage overlay
- Test filtering and search
- Snapshot management

## Best Practices

### 1. Test Naming

Use descriptive test names that explain what and why:

```typescript
// ❌ Bad
it('should work', () => {});
it('test error', () => {});

// ✅ Good
it('should return empty array when no sessions exist', () => {});
it('should throw timeout error when adapter does not respond within 30s', () => {});
```

### 2. Test Organization

Group related tests:

```typescript
describe('SessionManager', () => {
  describe('initialization', () => {
    it('should create log directory', () => {});
    it('should validate dependencies', () => {});
  });
  
  describe('session lifecycle', () => {
    describe('createSession', () => {
      it('should generate unique session ID', () => {});
      it('should set initial state to CREATED', () => {});
    });
    
    describe('closeSession', () => {
      it('should cleanup resources', () => {});
      it('should handle already closed session', () => {});
    });
  });
});
```

### 3. Avoid Test Interdependence

Each test should be independent:

```typescript
// ❌ Bad - tests depend on order
let sharedSession: Session;

it('should create session', () => {
  sharedSession = createSession();
});

it('should use session', () => {
  // Fails if previous test didn't run
  expect(sharedSession.id).toBeDefined();
});

// ✅ Good - independent tests
it('should create session', () => {
  const session = createSession();
  expect(session.id).toBeDefined();
});

it('should process session', () => {
  const session = createSession();
  const result = processSession(session);
  expect(result).toBeDefined();
});
```

### 4. Use Factories for Complex Objects

```typescript
function createTestSession(overrides?: Partial<Session>): Session {
  return {
    id: 'test-session-123',
    state: SessionState.CREATED,
    language: DebugLanguage.PYTHON,
    breakpoints: new Map(),
    ...overrides
  };
}

// Usage
it('should handle paused session', () => {
  const session = createTestSession({ state: SessionState.PAUSED });
  // ... test logic
});
```

### 5. Test Both Success and Failure Paths

```typescript
describe('file operations', () => {
  it('should read file successfully', async () => {
    mockFs.readFile.mockResolvedValue('content');
    const result = await component.readConfig();
    expect(result).toBe('content');
  });

  it('should handle file read error', async () => {
    mockFs.readFile.mockRejectedValue(new Error('ENOENT'));
    await expect(component.readConfig())
      .rejects.toThrow('Configuration file not found');
  });
});
```

## Common Issues and Solutions

### Issue: Flaky Timing Tests

**Problem**: Tests fail intermittently due to timing
**Solution**: Use fake timers or increase timeouts

```typescript
// Use fake timers for deterministic tests
vi.useFakeTimers();
await vi.advanceTimersByTimeAsync(1000);

// Or increase timeout for integration tests
it('should complete within timeout', async () => {
  await expect(longOperation()).resolves.toBeDefined();
}, 10000); // 10 second timeout
```

### Issue: Memory Leaks in Tests

**Problem**: Tests consume increasing memory
**Solution**: Proper cleanup in afterEach

```typescript
afterEach(async () => {
  // Close all sessions
  await sessionManager.closeAllSessions();
  
  // Clear all mocks
  vi.clearAllMocks();
  
  // Reset singletons
  SingletonService.reset();
  
  // Clear timers
  vi.useRealTimers();
});
```

### Issue: Cannot Mock ES Modules

**Problem**: Mocking ES module imports
**Solution**: Use vi.mock with factory

```typescript
vi.mock('../../../src/utils/logger.js', () => ({
  createLogger: vi.fn(() => ({
    info: vi.fn(),
    error: vi.fn()
  }))
}));
```

## Summary

Writing good tests for the MCP Debug Server:
1. Use descriptive test names
2. Keep tests independent and focused
3. Mock external dependencies
4. Test both success and error paths
5. Clean up resources properly
6. Use test utilities and helpers
7. Maintain high coverage standards

Remember: Tests are documentation that never goes out of date!