06-testing-quality

06-Testing-Quality

Testing Framework Configuration

The project uses Jest for testing as configured in package.json with TypeScript support via tsx.

Testing Structure

src/
├── __tests__/           # Test files (to be created)
│   ├── server/
│   ├── tools/
│   ├── resources/
│   └── utils/
└── __mocks__/           # Mock implementations

CRITICAL TESTING RULES - MUST FOLLOW

✅ ALWAYS DO:

1. Test all public methods: Every public method must have corresponding tests
2. Mock external dependencies: Mock file system, network calls, and external APIs
3. Test error conditions: Test both success and failure scenarios
4. Validate MCP compliance: Test that tools and resources conform to MCP protocol
5. Use descriptive test names: Test names should clearly describe the scenario

❌ NEVER DO:

1. Skip error testing: Never test only happy path scenarios
2. Test implementation details: Test behavior, not internal implementation
3. Use real file system: Always mock chokidar and fs operations
4. Ignore async behavior: Always properly handle Promise assertions
5. Share test state: Each test must be independent and isolated

Unit Testing Patterns

✅ PROPER Test Structure:

// src/__tests__/server/session-manager.test.ts
import { SessionManager } from '../../server/session-manager.js';
import { Logger } from '../../utils/logger.js';
import { AgentClient, AgentClientType, AgentStatus } from '../../types/index.js';

describe('SessionManager', () => {
  let sessionManager: SessionManager;
  let mockLogger: jest.Mocked<Logger>;

  beforeEach(() => {
    mockLogger = {
      info: jest.fn(),
      warn: jest.fn(),
      error: jest.fn(),
      debug: jest.fn(),
    } as jest.Mocked<Logger>;
    
    sessionManager = new SessionManager(mockLogger);
  });

  describe('registerClient', () => {
    it('should register a valid client and emit clientConnected event', () => {
      // Arrange
      const mockClient: AgentClient = createMockClient({
        id: 'test-client',
        type: AgentClientType.CLAUDE_CODE,
        name: 'Test Client',
      });
      
      const eventSpy = jest.spyOn(sessionManager, 'emit');

      // Act
      sessionManager.registerClient(mockClient);

      // Assert
      expect(sessionManager.getClient('test-client')).toBeDefined();
      expect(eventSpy).toHaveBeenCalledWith('clientConnected', mockClient);
      expect(mockLogger.info).toHaveBeenCalledWith('Client registered: test-client (claude-code)');
    });

    it('should throw error when registering client with missing required fields', () => {
      // Arrange
      const invalidClient = { id: '', type: AgentClientType.CLAUDE_CODE } as AgentClient;

      // Act & Assert
      expect(() => sessionManager.registerClient(invalidClient))
        .toThrow('Invalid client: missing required fields');
    });
  });

  describe('updateClientStatus', () => {
    it('should update client status and emit statusChanged event', () => {
      // Arrange
      const mockClient = createMockClient({ id: 'test-client' });
      sessionManager.registerClient(mockClient);
      const eventSpy = jest.spyOn(sessionManager, 'emit');

      // Act
      sessionManager.updateClientStatus('test-client', AgentStatus.RUNNING);

      // Assert
      const updatedClient = sessionManager.getClient('test-client');
      expect(updatedClient?.status).toBe(AgentStatus.RUNNING);
      expect(eventSpy).toHaveBeenCalledWith('clientStatusChanged', expect.objectContaining({
        client: updatedClient,
        oldStatus: AgentStatus.CONNECTED,
        newStatus: AgentStatus.RUNNING,
      }));
    });
  });
});

// Test helper functions
function createMockClient(overrides: Partial<AgentClient> = {}): AgentClient {
  return {
    id: 'default-client',
    type: AgentClientType.CUSTOM,
    name: 'Default Client',
    version: '1.0.0',
    capabilities: [],
    connectionInfo: {
      connectedAt: new Date(),
      lastActivity: new Date(),
      transport: 'stdio',
    },
    status: AgentStatus.CONNECTED,
    context: {
      workingDirectory: '/test',
    },
    metrics: {
      requestCount: 0,
      errorCount: 0,
      uptime: 0,
    },
    ...overrides,
  };
}