Test Infrastructure Analysis

Overview

The test infrastructure provides comprehensive integration testing for MCP (Model Context Protocol) connections using a combination of Vitest for test execution and Playwright for browser automation. The system tests real MCP server connections and validates the use-mcp library functionality in realistic scenarios.

Test Architecture

Project Structure (test/package.json)

Dependencies (Lines 13-21)

Testing Framework:

  • vitest: Modern test runner with TypeScript support
  • @vitest/ui: Visual test interface for debugging
  • playwright: Browser automation for integration tests
  • typescript: Type safety for test code

Test Execution:

  • @types/node: Node.js type definitions for server utilities

Test Scripts (Lines 5-11)

Execution Modes:

  • test: Default headless test execution
  • test:headed: Browser visible during test execution
  • test:headless: Explicit headless mode with environment variable
  • test:watch: File watching mode for development
  • test:ui: Visual test interface for debugging
  • test:debug: Hanging process reporter for debugging stuck tests

Vitest Configuration (vitest.config.ts)

Test Setup (Lines 4-9)

Global Lifecycle:

  • globalSetup: Starts test servers before all tests
  • globalTeardown: Cleans up test servers after all tests
  • testTimeout: 60000: 60-second timeout for integration tests

Debug Configuration:

  • reporters: Conditional reporter based on environment variable
  • hanging-process: Special reporter for debugging hanging tests

Integration Test Implementation

Browser Setup (mcp-connection.test.ts Lines 10-37)

Browser Lifecycle:

  • beforeAll: Launches Chromium with headless/headed mode control
  • afterAll: Comprehensive cleanup of browser and test servers
  • Cleanup Strategy: Forced cleanup before Vitest exits

Page Management (Lines 39-49):

  • Fresh Context: New browser context for each test
  • Console Logging: Captures browser errors for debugging
  • Error Monitoring: Logs browser-side errors to test output

Test State Management (test-utils.ts)

State Interface (Lines 11-30):

export interface TestState {
  honoPort?: number
  cfAgentsPort?: number  
  staticPort?: number
}

export interface ServerConfig {
  name: string
  directory: string
  portKey: keyof TestState
  endpoints: ServerEndpoint[]
  expectedTools: number
  expectedResources?: number
  expectedPrompts?: number
}

Server Configuration:

  • Port Management: Dynamic port allocation for test servers
  • Endpoint Mapping: Multiple transport types per server
  • Expectation Validation: Expected tool/resource/prompt counts

Global Test Setup (global-setup.ts)

Environment Preparation (Lines 17-23):

interface GlobalState extends TestState {
  honoServer?: ChildProcess
  cfAgentsServer?: ChildProcess
  staticServer?: Server
  processGroupId?: number
  allChildProcesses?: Set<number>
}

Setup Process:

  1. Build Preparation: Ensures all dependencies are built
  2. Port Allocation: Finds available ports for test servers
  3. Server Startup: Spawns MCP servers for testing
  4. State Persistence: Saves server information for tests
  5. Process Tracking: Maintains cleanup registry

Server Management Functions

Command Execution (Lines 29-48):

  • Shell Commands: Executes build and setup commands
  • Environment Variables: Passes custom environment to processes
  • Error Handling: Captures and reports command failures
  • Stdio Inheritance: Shows build output for debugging

Port Management (Line 50+):

  • Dynamic Allocation: Finds available ports starting from base
  • Conflict Prevention: Avoids port conflicts in CI environments
  • Port Persistence: Saves port assignments for test access

Test Server Integration

MCP Server Testing

Server Types:

  1. Hono MCP Server: Party-themed server with tools and resources
  2. CF Agents Server: Calculator server with OAuth authentication
  3. Static Server: Serves test client applications

Server Lifecycle:

  • Startup: Servers launched before test execution
  • Health Checks: Validation that servers are responding
  • Cleanup: Graceful shutdown after tests complete

Transport Testing

Transport Types:

  • HTTP: Request/response MCP communication
  • SSE: Server-Sent Events for streaming
  • Auto: Automatic transport selection with fallback

Test Coverage:

  • Connection Establishment: Validates successful MCP connections
  • Tool Execution: Tests tool calling with parameters
  • Resource Access: Validates resource reading functionality
  • Prompt Usage: Tests prompt template functionality

Browser Automation

Playwright Integration

Browser Configuration:

  • Chromium: Primary browser for testing
  • Headless Control: Environment-based visibility control
  • Context Isolation: Fresh context per test for isolation

Page Interaction:

  • MCP UI Testing: Tests the inspector and chat-ui interfaces
  • Connection Testing: Validates real browser MCP connections
  • Error Capture: Monitors browser console for runtime errors

Test Scenarios

Connection Testing:

  1. Server Discovery: Tests server endpoint discovery
  2. Authentication Flow: Validates OAuth popup handling
  3. Tool Execution: Tests tool calling through browser interface
  4. Resource Reading: Validates resource access in browser
  5. Error Handling: Tests error scenarios and recovery

CI/CD Integration

Environment Configuration

Test Modes:

  • Local Development: Headed mode for visual debugging
  • CI/CD: Headless mode for automated testing
  • Debug Mode: Special reporters for investigating issues

Environment Variables:

  • HEADLESS: Controls browser visibility
  • VITEST_REPORTER: Selects test reporter
  • Port variables: Override default ports if needed

Build Integration

Prerequisites:

  • Library Build: Ensures use-mcp is compiled
  • Example Builds: Builds chat-ui and inspector
  • Server Preparation: Ensures MCP servers are ready

Validation:

  • Type Checking: TypeScript compilation validation
  • Linting: Code quality checks
  • Integration: End-to-end functionality validation

Test Utilities

Process Management

Server Spawning:

  • Child Process Management: Tracks all spawned processes
  • Output Monitoring: Waits for server ready signals
  • Cleanup Registration: Ensures proper shutdown

Error Handling:

  • Timeout Management: Prevents hanging tests
  • Resource Cleanup: Ensures no orphaned processes
  • Error Logging: Detailed error reporting for debugging

State Persistence

Test State File:

  • Port Information: Server port assignments
  • Process IDs: For cleanup operations
  • Configuration: Test-specific settings

Cache Management:

  • State Directory: .cache/use-mcp-tests/
  • Persistence: Survives between test runs
  • Cleanup: Automatic cleanup on completion

Testing Best Practices

Isolation

Test Independence:

  • Fresh Browser Context: Each test gets clean browser state
  • Port Isolation: Each server gets unique port
  • State Reset: Clean state between test runs

Reliability

Timeout Management:

  • Generous Timeouts: 60 seconds for integration tests
  • Progressive Timeouts: Different timeouts for different operations
  • Early Termination: Fail fast on critical errors

Debugging

Development Support:

  • Headed Mode: Visual browser debugging
  • Console Logging: Browser error capture
  • State Inspection: Test state file examination
  • Process Monitoring: Detailed process lifecycle logging

Performance

Efficient Testing:

  • Server Reuse: Single server instance for all tests
  • Parallel Execution: Tests run concurrently where safe
  • Resource Management: Proper cleanup prevents resource leaks

This test infrastructure provides comprehensive validation of the use-mcp library in realistic browser environments, ensuring that the library works correctly with real MCP servers and handles edge cases gracefully. The combination of unit testing, integration testing, and browser automation provides confidence in the library's reliability and performance.