MCP ACS Debugger Server - E2E Testing Guide

December 12, 2025 · View on GitHub

This document provides comprehensive instructions for running and troubleshooting E2E tests for the MCP ACS Debugger Server.

Table of Contents

Prerequisites

Before running E2E tests, ensure you have:

  1. Node.js 16+ installed
  2. Built packages: Run npx nx build @ai-capabilities-suite/mcp-server to build both the core and server packages
  3. Test fixtures: The test fixtures are located in packages/debugger-core/test-fixtures/

Running E2E Tests

Automated E2E Tests

The E2E test suite validates the MCP protocol implementation and all debugging tools.

# Run all E2E tests
npx nx test @ai-capabilities-suite/mcp-server --testPathPattern=e2e

# Run with increased timeout (recommended)
npx nx test @ai-capabilities-suite/mcp-server --testPathPattern=e2e --testTimeout=60000

# Run a specific test
npx nx test @ai-capabilities-suite/mcp-server --testPathPattern="should detect a hanging process"

Test Coverage

The E2E test suite covers:

  1. MCP Protocol Initialization (1 test)

    • Server initialization with protocol version and capabilities

  2. Tool Discovery (2 tests)

    • Listing all available tools
    • Validating tool schemas

  3. Hang Detection (2 tests)

    • Detecting infinite loops
    • Detecting normal completion without false positives

  4. Debug Session Management (1 test)

    • Starting debug sessions with paused state

  5. Session Operations (5 tests)

    • Setting breakpoints
    • Continuing execution
    • Stepping over code
    • Inspecting variables
    • Getting call stacks

  6. Error Handling (4 tests)

    • Invalid session IDs
    • Missing required parameters
    • Invalid tool names
    • Proper error response structure

Total: 15 tests

Expected Results

All tests should pass:

Test Suites: 1 passed, 1 total
Tests:       15 passed, 15 total

Manual Testing

For interactive testing with colored output and clear pass/fail indicators, use the manual testing script:

# Make the script executable (first time only)
chmod +x packages/mcp-server/test-mcp-manual.js

# Run manual tests
node packages/mcp-server/test-mcp-manual.js

The manual testing script provides:

  • ✓ Green checkmarks for passing tests
  • ✗ Red X marks for failing tests
  • ℹ Blue info messages
  • ⚠ Yellow warnings
  • Detailed test output with response data
  • Summary with success rate percentage

Manual Test Coverage

The manual script tests:

  1. Protocol initialization
  2. Tool discovery
  3. Hang detection (infinite loop)
  4. Debug session start
  5. Breakpoint setting
  6. Error handling

Using MCP Inspector

The MCP Inspector is a tool for interactively testing MCP servers. It's particularly useful for debugging protocol issues.

Installation

npm install -g @modelcontextprotocol/inspector

Usage

  1. Start the MCP server:

    node packages/mcp-server/dist/src/index.js

  2. In another terminal, use the inspector:

    mcp-inspector

  3. Connect to the server using stdio transport

  4. Test tools interactively:

    • View available tools
    • Call tools with custom parameters
    • Inspect responses in real-time

Example Inspector Session

// Initialize
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2024-11-05",
    "capabilities": {},
    "clientInfo": {"name": "inspector", "version": "1.0.0"}
  }
}

// List tools
{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/list"
}

// Call debugger_detect_hang
{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "debugger_detect_hang",
    "arguments": {
      "command": "node",
      "args": ["test-fixtures/infinite-loop.js"],
      "timeout": 2000,
      "sampleInterval": 100
    }
  }
}

Troubleshooting

Common Issues

1. Build Errors

Problem: Tests fail with "Cannot find module" errors

Solution:

# Clean and rebuild
rm -rf packages/*/dist
npx nx build @ai-capabilities-suite/mcp-core
npx nx build @ai-capabilities-suite/mcp-server

2. Test Timeouts

Problem: Tests timeout with "Request timeout for X" errors

Solution:

  • Increase test timeout: --testTimeout=60000
  • Check if the server is starting correctly
  • Look for stderr output in test logs

3. WebSocket Connection Issues

Problem: "ws_1.default is not a constructor" or similar WebSocket errors

Solution:

  • Ensure you're using CommonJS module format
  • Check that ws package is properly installed
  • Verify tsconfig.json has "module": "CommonJS"

4. False Positive Hang Detection

Problem: Normal completion scripts are detected as hung

Solution:

  • Increase the timeout parameter in hang detection calls
  • The default 2000ms may be too short for some scripts
  • Use 5000ms or higher for scripts with I/O operations

5. Session State Issues

Problem: "Cannot step over in state: running" or "Process must be paused"

Solution:

  • Ensure the process is paused before calling step/inspect operations
  • Set breakpoints and continue to them before stepping
  • Wait for breakpoint events after calling continue

Debug Logging

Enable debug logging to see detailed server output:

# Run tests with server stderr visible
npx nx test @ai-capabilities-suite/mcp-server --testPathPattern=e2e 2>&1 | grep -A 5 "Server stderr"

Checking Server Health

Test if the server responds to basic requests:

echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0.0"}}}' | node packages/mcp-server/dist/src/index.js

Expected output:

{"result":{"protocolVersion":"2024-11-05","capabilities":{"tools":{"listChanged":true}},"serverInfo":{"name":"debugger-server","version":"1.0.0"}},"jsonrpc":"2.0","id":1}

Test Fixtures

If tests fail due to missing fixtures, verify they exist:

ls -la packages/debugger-core/test-fixtures/

Required fixtures:

  • infinite-loop.js - For hang detection tests
  • normal-completion.js - For normal completion tests
  • simple-script.js - For basic debugging tests
  • step-test-simple.js - For step operation tests

Getting Help

If you encounter issues not covered here:

  1. Check the test output for specific error messages
  2. Review the server stderr output
  3. Verify all dependencies are installed: npm install
  4. Ensure Node.js version is 16 or higher: node --version
  5. Check that the build completed successfully

Continuous Integration

For CI/CD pipelines, use:

# Build and test in one command
npx nx build @ai-capabilities-suite/mcp-server && \
npx nx test @ai-capabilities-suite/mcp-server --testPathPattern=e2e --testTimeout=60000

CI Best Practices

  1. Always build before testing: E2E tests require built artifacts
  2. Use adequate timeouts: CI environments may be slower
  3. Cache node_modules: Speed up builds with dependency caching
  4. Run tests in isolation: Each test should be independent
  5. Collect test artifacts: Save test logs and coverage reports

Performance Benchmarks

Expected test execution times (approximate):

  • Protocol initialization: < 20ms
  • Tool discovery: < 10ms
  • Hang detection (infinite loop): ~2.5s
  • Hang detection (normal): ~500ms
  • Debug session start: ~200ms
  • Session operations: ~100-500ms each
  • Error handling: < 10ms

Total suite execution: ~6-8 seconds

Next Steps

After E2E tests pass:

  1. Run unit tests: npx nx test @ai-capabilities-suite/mcp-core
  2. Run property-based tests (if implemented)
  3. Test with real-world debugging scenarios
  4. Integrate with MCP clients (Kiro, VS Code, etc.)
  5. Deploy to production environment

Additional Resources