@goonnguyen/human-mcp 1.2.0 → 1.3.0

package/tests/unit/sse-routes.test.ts

@@ -0,0 +1,92 @@
+import { describe, it, expect, beforeEach, afterEach } from "bun:test";
+import { SSEManager } from "../../src/transports/http/sse-routes.js";
+import type { HttpTransportConfig } from "../../src/transports/types.js";
+import type { Response } from "express";
+
+describe("SSEManager", () => {
+  let sseManager: SSEManager;
+  let config: HttpTransportConfig;
+
+  beforeEach(() => {
+    config = {
+      port: 3000,
+      sessionMode: "stateful",
+      enableSseFallback: true,
+      ssePaths: {
+        stream: "/sse",
+        message: "/messages"
+      },
+      security: {
+        enableDnsRebindingProtection: true,
+        allowedHosts: ["127.0.0.1", "localhost"]
+      }
+    };
+    sseManager = new SSEManager(config);
+  });
+
+  afterEach(async () => {
+    await sseManager.cleanup();
+  });
+
+  describe("session management", () => {
+    it("should start with zero sessions", () => {
+      expect(sseManager.getSessionCount()).toBe(0);
+      expect(sseManager.hasSession("non-existent")).toBe(false);
+    });
+
+    it("should track session existence correctly", () => {
+      // Mock response object for testing
+      const mockRes = {
+        setHeader: () => {},
+        write: () => {},
+        end: () => {},
+        on: () => {},
+        removeAllListeners: () => {}
+      } as unknown as Response;
+
+      const transport = sseManager.createSession("/messages", mockRes);
+      
+      expect(sseManager.getSessionCount()).toBe(1);
+      expect(sseManager.hasSession(transport.sessionId)).toBe(true);
+      expect(sseManager.getSession(transport.sessionId)).toBe(transport);
+    });
+
+    it("should return null for non-existent session", () => {
+      expect(sseManager.getSession("non-existent-id")).toBe(null);
+    });
+
+    it("should cleanup sessions correctly", async () => {
+      const mockRes = {
+        setHeader: () => {},
+        write: () => {},
+        end: () => {},
+        on: () => {},
+        removeAllListeners: () => {}
+      } as unknown as Response;
+
+      sseManager.createSession("/messages", mockRes);
+      expect(sseManager.getSessionCount()).toBe(1);
+
+      await sseManager.cleanup();
+      expect(sseManager.getSessionCount()).toBe(0);
+    });
+  });
+
+  describe("configuration handling", () => {
+    it("should use security configuration from config", () => {
+      const mockRes = {
+        setHeader: () => {},
+        write: () => {},
+        end: () => {},
+        on: () => {},
+        removeAllListeners: () => {}
+      } as unknown as Response;
+
+      const transport = sseManager.createSession("/messages", mockRes);
+      
+      // Transport should be created successfully with security config
+      expect(transport).toBeDefined();
+      expect(transport.sessionId).toBeDefined();
+    });
+  });
+});

package/tests/utils/error-scenarios.ts

@@ -0,0 +1,198 @@
+import { mock } from 'bun:test';
+import type { MockError } from '../types/test-types.js';
+
+export class ErrorScenarios {
+  /**
+   * Common network errors for testing
+   */
+  static networkErrors = {
+    CONNECTION_REFUSED: new Error('ECONNREFUSED: Connection refused'),
+    TIMEOUT: new Error('ETIMEDOUT: Request timeout'),
+    DNS_ERROR: new Error('ENOTFOUND: DNS lookup failed'),
+    SSL_ERROR: new Error('SSL certificate verification failed'),
+    NETWORK_UNREACHABLE: new Error('ENETUNREACH: Network is unreachable')
+  };
+
+  /**
+   * HTTP error responses
+   */
+  static httpErrors = {
+    NOT_FOUND: { status: 404, error: 'Resource not found' },
+    UNAUTHORIZED: { status: 401, error: 'Unauthorized access' },
+    FORBIDDEN: { status: 403, error: 'Forbidden' },
+    SERVER_ERROR: { status: 500, error: 'Internal server error' },
+    BAD_GATEWAY: { status: 502, error: 'Bad gateway' },
+    SERVICE_UNAVAILABLE: { status: 503, error: 'Service unavailable' },
+    RATE_LIMITED: { status: 429, error: 'Too many requests' }
+  };
+
+  /**
+   * API specific errors
+   */
+  static apiErrors = {
+    GEMINI_API_ERROR: new Error('Gemini API quota exceeded'),
+    GEMINI_INVALID_KEY: new Error('Invalid Gemini API key'),
+    GEMINI_MODEL_UNAVAILABLE: new Error('Gemini model temporarily unavailable'),
+    CLOUDFLARE_R2_ERROR: new Error('Cloudflare R2 upload failed'),
+    FILE_NOT_FOUND: new Error('ENOENT: File not found'),
+    PERMISSION_DENIED: new Error('EACCES: Permission denied'),
+    DISK_FULL: new Error('ENOSPC: No space left on device')
+  };
+
+  /**
+   * Create a mock that fails with a specific error
+   */
+  static createFailingMock<T>(error: Error | MockError): ReturnType<typeof mock> {
+    return mock(async (..._args: any[]): Promise<T> => {
+      throw error;
+    });
+  }
+
+  /**
+   * Create a mock that fails intermittently
+   */
+  static createIntermittentMock<T>(
+    successValue: T, 
+    error: Error | MockError, 
+    failureRate = 0.5
+  ): ReturnType<typeof mock> {
+    return mock(async (..._args: any[]): Promise<T> => {
+      if (Math.random() < failureRate) {
+        throw error;
+      }
+      return successValue;
+    });
+  }
+
+  /**
+   * Create a mock that times out
+   */
+  static createTimeoutMock<T>(delay = 5000): ReturnType<typeof mock> {
+    return mock(async (..._args: any[]): Promise<T> => {
+      await new Promise(resolve => setTimeout(resolve, delay));
+      throw new Error('Request timeout');
+    });
+  }
+
+  /**
+   * Create a mock fetch that returns HTTP errors
+   */
+  static createErrorResponse(errorType: keyof typeof ErrorScenarios.httpErrors): Response {
+    const error = ErrorScenarios.httpErrors[errorType];
+    return new Response(JSON.stringify({ error: error.error }), {
+      status: error.status,
+      statusText: error.error,
+      headers: { 'Content-Type': 'application/json' }
+    });
+  }
+
+  /**
+   * Create test scenarios for network resilience
+   */
+  static createNetworkResilienceTests() {
+    return {
+      'should handle connection refused': {
+        error: ErrorScenarios.networkErrors.CONNECTION_REFUSED,
+        expectedMessage: 'Connection refused'
+      },
+      'should handle timeout': {
+        error: ErrorScenarios.networkErrors.TIMEOUT,
+        expectedMessage: 'Request timeout'
+      },
+      'should handle DNS errors': {
+        error: ErrorScenarios.networkErrors.DNS_ERROR,
+        expectedMessage: 'DNS lookup failed'
+      },
+      'should handle SSL errors': {
+        error: ErrorScenarios.networkErrors.SSL_ERROR,
+        expectedMessage: 'SSL certificate verification failed'
+      }
+    };
+  }
+
+  /**
+   * Create test scenarios for API errors
+   */
+  static createAPIErrorTests() {
+    return {
+      'should handle Gemini API quota exceeded': {
+        error: ErrorScenarios.apiErrors.GEMINI_API_ERROR,
+        expectedMessage: 'Gemini API quota exceeded'
+      },
+      'should handle invalid API key': {
+        error: ErrorScenarios.apiErrors.GEMINI_INVALID_KEY,
+        expectedMessage: 'Invalid Gemini API key'
+      },
+      'should handle model unavailable': {
+        error: ErrorScenarios.apiErrors.GEMINI_MODEL_UNAVAILABLE,
+        expectedMessage: 'model temporarily unavailable'
+      },
+      'should handle file upload errors': {
+        error: ErrorScenarios.apiErrors.CLOUDFLARE_R2_ERROR,
+        expectedMessage: 'upload failed'
+      }
+    };
+  }
+
+  /**
+   * Create test scenarios for file system errors
+   */
+  static createFileSystemErrorTests() {
+    return {
+      'should handle file not found': {
+        error: ErrorScenarios.apiErrors.FILE_NOT_FOUND,
+        expectedMessage: 'File not found'
+      },
+      'should handle permission denied': {
+        error: ErrorScenarios.apiErrors.PERMISSION_DENIED,
+        expectedMessage: 'Permission denied'
+      },
+      'should handle disk full': {
+        error: ErrorScenarios.apiErrors.DISK_FULL,
+        expectedMessage: 'No space left on device'
+      }
+    };
+  }
+
+  /**
+   * Simulate retry logic testing
+   */
+  static createRetryMock<T>(
+    finalResult: T,
+    failures: (Error | MockError)[],
+    maxRetries = 3
+  ): ReturnType<typeof mock> {
+    let attemptCount = 0;
+    
+    return mock(async (..._args: any[]): Promise<T> => {
+      if (attemptCount < failures.length && attemptCount < maxRetries) {
+        attemptCount++;
+        throw failures[attemptCount - 1];
+      }
+      attemptCount++;
+      return finalResult;
+    });
+  }
+
+  /**
+   * Test concurrent failure scenarios
+   */
+  static createConcurrentFailureMock<T>(
+    results: (T | Error)[]
+  ): ReturnType<typeof mock> {
+    let callIndex = 0;
+    
+    return mock(async (..._args: any[]): Promise<T> => {
+      const result = results[callIndex % results.length];
+      callIndex++;
+      
+      if (result instanceof Error) {
+        throw result;
+      }
+      
+      return result as T;
+    });
+  }
+}
+
+export default ErrorScenarios;

package/tests/utils/index.ts

@@ -0,0 +1,3 @@
+export { TestServerManager, testServerManager } from './test-server-manager.js';
+export { MockHelpers } from './mock-helpers.js';
+export { TestDataGenerators } from './test-data-generators.js';

package/tests/utils/mock-helpers.ts

@@ -0,0 +1,99 @@
+import { mock, type Mock } from 'bun:test';
+import type { MockError, MockHttpResponseData } from '../types/test-types.js';
+
+export interface MockedLogger {
+  info: Mock<() => void>;
+  error: Mock<() => void>;
+  warn: Mock<() => void>;
+  debug: Mock<() => void>;
+}
+
+export interface MockedFS {
+  readFileSync: Mock<() => Buffer>;
+  writeFileSync: Mock<() => void>;
+  existsSync: Mock<() => boolean>;
+  mkdirSync: Mock<() => void>;
+  unlinkSync: Mock<() => void>;
+}
+
+export interface MockedGeminiClient {
+  generateContent: Mock<() => Promise<any>>;
+  getGenerativeModel: Mock<() => any>;
+}
+
+export class MockHelpers {
+  static createLoggerMock(): MockedLogger {
+    return {
+      info: mock(() => {}),
+      error: mock(() => {}),
+      warn: mock(() => {}),
+      debug: mock(() => {})
+    };
+  }
+
+  static createFileSystemMock(): MockedFS {
+    return {
+      readFileSync: mock(() => Buffer.from('mock file content')),
+      writeFileSync: mock(() => {}),
+      existsSync: mock(() => true),
+      mkdirSync: mock(() => {}),
+      unlinkSync: mock(() => {})
+    };
+  }
+
+  static createGeminiClientMock(): MockedGeminiClient {
+    return {
+      generateContent: mock(() => Promise.resolve({
+        response: {
+          text: () => JSON.stringify({
+            summary: "Mock analysis result",
+            details: "Mock detailed analysis",
+            confidence: 0.95
+          })
+        }
+      })),
+      getGenerativeModel: mock(() => ({
+        generateContent: mock(() => Promise.resolve({
+          response: {
+            text: () => JSON.stringify({
+              summary: "Mock analysis result",
+              details: "Mock detailed analysis", 
+              confidence: 0.95
+            })
+          }
+        }))
+      }))
+    };
+  }
+
+  static resetAllMocks(mocks: Record<string, unknown>): void {
+    Object.values(mocks).forEach(mockObj => {
+      if (typeof mockObj === 'object' && mockObj !== null) {
+        Object.values(mockObj).forEach(mockFn => {
+          if (typeof mockFn === 'function' && 'mockRestore' in mockFn) {
+            (mockFn as Mock<any>).mockRestore();
+          }
+        });
+      }
+    });
+  }
+
+  static createMockResponse(data: MockHttpResponseData, status = 200): Response {
+    return new Response(JSON.stringify(data), {
+      status,
+      headers: {
+        'Content-Type': 'application/json'
+      }
+    });
+  }
+
+  static createMockError(message: string, code?: string | number): MockError {
+    const error: MockError = { message };
+    if (code) {
+      error.code = code;
+    }
+    return error as MockError & Error;
+  }
+}
+
+export default MockHelpers;

package/tests/utils/test-data-generators.ts

@@ -0,0 +1,217 @@
+import type { MockAnalysisRequest, MockCompareRequest, MockGeminiResponse, MockComparisonResponse, MockHttpResponseData } from '../types/test-types.js';
+
+export class TestDataGenerators {
+  static createBase64Image(variant: 'small' | 'medium' | 'large' = 'small'): string {
+    // Different sized images for more realistic testing
+    const images = {
+      small: 'iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg==',
+      medium: 'iVBORw0KGgoAAAANSUhEUgAAAAoAAAAKCAYAAACNMs+9AAAAFklEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg==',
+      large: 'iVBORw0KGgoAAAANSUhEUgAAABQAAAAUCAYAAACNiR0NAAAAOklEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJgggAAAABJRU5ErkJgggAAAABJRU5ErkJggg=='
+    };
+    return `data:image/png;base64,${images[variant]}`;
+  }
+
+  static createMockImageBuffer(size: number = 1024): Buffer {
+    // Create buffer with specified size for more realistic testing
+    const base64 = 'iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg==';
+    const buffer = Buffer.from(base64, 'base64');
+    // Pad buffer to reach desired size
+    return size > buffer.length ? Buffer.concat([buffer, Buffer.alloc(size - buffer.length)]) : buffer;
+  }
+
+  static createMockVideoFile(duration: number = 10): string {
+    // Mock MP4 file path with metadata
+    return `/tmp/test-video-${duration}s.mp4`;
+  }
+
+  static createMockGifFile(frames: number = 5): string {
+    // Mock GIF file path with metadata
+    return `/tmp/test-animation-${frames}frames.gif`;
+  }
+
+  static createMockAnalysisRequest(overrides: Partial<MockAnalysisRequest> = {}): MockAnalysisRequest {
+    const prompts = [
+      'Analyze the user interface elements and their layout',
+      'Focus on accessibility and usability issues',
+      'Identify any visual bugs or rendering problems',
+      'Review the overall design consistency',
+      'Check for mobile responsiveness indicators'
+    ];
+    
+    const selectedPrompt = prompts[Math.floor(Math.random() * prompts.length)];
+    
+    return {
+      input: TestDataGenerators.createBase64Image(),
+      detail_level: Math.random() > 0.5 ? 'detailed' : 'quick',
+      custom_prompt: selectedPrompt,
+      ...overrides
+    };
+  }
+
+  static createMockCompareRequest(overrides: Partial<MockCompareRequest> = {}): MockCompareRequest {
+    const prompts = [
+      'Compare the visual differences between these two UI states',
+      'Focus on layout and structural changes',
+      'Identify pixel-level differences and their impact',
+      'Compare accessibility features between versions',
+      'Analyze the user experience implications of changes'
+    ];
+    
+    const comparisonTypes: Array<'pixel' | 'structural' | 'semantic'> = ['pixel', 'structural', 'semantic'];
+    const selectedPrompt = prompts[Math.floor(Math.random() * prompts.length)];
+    const selectedType = comparisonTypes[Math.floor(Math.random() * comparisonTypes.length)];
+    
+    const baseRequest = {
+      input1: TestDataGenerators.createBase64Image('medium'),
+      input2: TestDataGenerators.createBase64Image('medium'),
+      comparison_type: selectedType as 'pixel' | 'structural' | 'semantic',
+      custom_prompt: selectedPrompt
+    };
+    
+    return Object.assign({}, baseRequest, overrides) as MockCompareRequest;
+  }
+
+  static createMockGeminiResponse(overrides: Partial<MockGeminiResponse> = {}): MockGeminiResponse {
+    const responses = [
+      {
+        summary: 'Screenshot shows a web application interface',
+        details: 'This image contains a modern web application with a navigation bar, sidebar, and main content area. The interface uses a clean design with blue accents.',
+        technical_details: {
+          dimensions: '1920x1080',
+          format: 'PNG',
+          colors: 'full color',
+          ui_elements: 'navigation, sidebar, content area'
+        },
+        confidence: 0.92,
+        recommendations: ['Consider improving color contrast', 'Add loading states for better UX']
+      },
+      {
+        summary: 'Mobile app screenshot with user interface elements',
+        details: 'This is a mobile application screenshot showing a login form with input fields and buttons. The design follows modern mobile UI patterns.',
+        technical_details: {
+          dimensions: '375x812',
+          format: 'JPEG',
+          colors: 'full color',
+          platform: 'mobile'
+        },
+        confidence: 0.88,
+        recommendations: ['Optimize for smaller screen sizes', 'Ensure touch targets are adequate']
+      },
+      {
+        summary: 'Code editor interface with syntax highlighting',
+        details: 'The image shows a code editor with syntax highlighting, line numbers, and a file tree. Multiple tabs are open showing different files.',
+        technical_details: {
+          dimensions: '1440x900',
+          format: 'PNG',
+          colors: 'dark theme',
+          editor: 'VS Code-like interface'
+        },
+        confidence: 0.96,
+        recommendations: ['Good use of syntax highlighting', 'Consider font size for readability']
+      }
+    ];
+    
+    const selectedResponse = responses[Math.floor(Math.random() * responses.length)];
+    return Object.assign({}, selectedResponse, overrides) as MockGeminiResponse;
+  }
+
+  static createMockComparisonResponse(overrides: Partial<MockComparisonResponse> = {}): MockComparisonResponse {
+    const responses = [
+      {
+        summary: 'Significant UI differences detected',
+        differences: [
+          'Button color changed from blue to green',
+          'Navigation bar height increased by 10px',
+          'New search icon added in header'
+        ],
+        similarity_score: 0.73,
+        analysis_method: 'semantic',
+        recommendations: [
+          'Review color accessibility standards',
+          'Test navigation changes with users',
+          'Ensure search functionality is intuitive'
+        ],
+        technical_details: {
+          image1_format: 'PNG',
+          image2_format: 'PNG',
+          comparison_method: 'semantic'
+        }
+      },
+      {
+        summary: 'Minor layout adjustments found',
+        differences: [
+          'Slight margin increase in content area',
+          'Font size reduced by 1px'
+        ],
+        similarity_score: 0.91,
+        analysis_method: 'structural',
+        recommendations: [
+          'Changes are minimal and unlikely to impact users',
+          'Consider A/B testing for optimal spacing'
+        ],
+        technical_details: {
+          image1_format: 'JPEG',
+          image2_format: 'PNG',
+          comparison_method: 'structural'
+        }
+      },
+      {
+        summary: 'Images are nearly identical',
+        differences: [],
+        similarity_score: 0.98,
+        analysis_method: 'pixel',
+        recommendations: ['No significant changes detected'],
+        technical_details: {
+          image1_format: 'PNG',
+          image2_format: 'PNG',
+          comparison_method: 'pixel'
+        }
+      }
+    ];
+    
+    const selectedResponse = responses[Math.floor(Math.random() * responses.length)];
+    return Object.assign({}, selectedResponse, overrides) as MockComparisonResponse;
+  }
+
+  static createMockFileStats() {
+    return {
+      isFile: () => true,
+      isDirectory: () => false,
+      size: 1024,
+      mtime: new Date(),
+      ctime: new Date()
+    };
+  }
+
+  static createMockHttpResponse(data: MockHttpResponseData, status = 200, headers: Record<string, string> = {}) {
+    return new Response(typeof data === 'string' ? data : JSON.stringify(data), {
+      status,
+      headers: {
+        'Content-Type': 'application/json',
+        ...headers
+      }
+    });
+  }
+
+  static createMockErrorResponse(message: string, status = 500) {
+    return new Response(JSON.stringify({ error: message }), {
+      status,
+      headers: { 'Content-Type': 'application/json' }
+    });
+  }
+
+  static generateRandomPort(): number {
+    return 3000 + Math.floor(Math.random() * 1000);
+  }
+
+  static createMockSessionData() {
+    return {
+      id: 'test-session-123',
+      created: Date.now(),
+      lastActivity: Date.now(),
+      data: {}
+    };
+  }
+}
+
+export default TestDataGenerators;