Skip to main content

🧪 Testing Guide - MCP ADR Analysis Server

Confidence: 95% - Comprehensive guide based on analysis of existing testing infrastructure

📋 Table of Contents​

🚀 Quick Start​

Prerequisites​

  • Node.js: ≥20.0.0
  • npm: ≥9.0.0
  • Memory: ≥1GB available RAM
  • Disk: ≥1GB free space

Installation & Setup​

# Install dependencies
npm install

# Run all tests
npm test

# Run tests with coverage
npm run test:coverage

# Run tests in watch mode
npm run test:watch

Verify Installation​

# Quick smoke test
npm run test tests/smoke.test.ts

# Test infrastructure health
./scripts/test-infrastructure.sh validate

🏗️ Testing Architecture​

Core Components​

tests/
├── __mocks__/           # Mock implementations for external dependencies
├── integration/         # Cross-component integration tests
├── performance/         # Performance and load tests
├── tools/              # Individual tool unit tests
├── utils/              # Utility function tests
├── setup.ts            # Global test configuration
└── README.md           # Testing documentation

Key Technologies​

  • Jest: Primary testing framework with TypeScript support
  • ts-jest: TypeScript transformation and ESM support
  • Tree-sitter Mocks: Native module mocking for cross-platform compatibility
  • Custom Matchers: Domain-specific assertions for ADR validation

Test Infrastructure Features​

  • ✅ Resource Monitoring: Memory and file handle tracking
  • ✅ Automatic Cleanup: Temp directory and mock cleanup
  • ✅ Coverage Thresholds: 85% minimum coverage requirement
  • ✅ Performance Tracking: Memory usage and execution time monitoring
  • ✅ CI/CD Integration: JUnit XML reporting for CI systems

🎯 Test Types & Categories​

1. Unit Tests (tests/tools/, tests/utils/)​

Purpose: Test individual functions and classes in isolation

// Example: Tool unit test
describe('ADRValidationTool', () => {
  it('should validate ADR structure', async () => {
    const result = await adrValidationTool.validate(mockAdr);
    expect(result).toBeValidAdr();
  });
});

Coverage: Functions, classes, utilities, and individual tools

2. Integration Tests (tests/integration/)​

Purpose: Test component interactions and workflows

// Example: Memory system integration
describe('Memory System Integration', () => {
  it('should handle complex workflow chains', async () => {
    const workflow = await orchestrator.executeChain(steps);
    expect(workflow.success).toBe(true);
  });
});

Coverage: Tool chains, memory systems, MCP protocol interactions

3. Performance Tests (tests/performance/)​

Purpose: Validate performance characteristics and resource usage

// Example: Memory performance test
describe('Memory Performance', () => {
  it('should handle large datasets efficiently', async () => {
    const result = await processLargeDataset(testData);
    expect(result).toShowSignificantImprovement(0.1);
  });
});

Coverage: Memory usage, execution time, resource efficiency

4. End-to-End Tests (scripts/test-mcp-*.sh)​

Purpose: Test complete MCP server functionality

# MCP server integration test
./scripts/test-mcp-server.sh

# MCP functionality validation
./scripts/test-mcp-functionality.sh

🏃‍♂️ Running Tests​

Basic Commands​

# All tests (recommended)
npm test

# Specific test categories
npm run test:unit           # Unit tests only
npm run test:integration    # Integration tests only
npm run test:performance    # Performance tests only

# Advanced testing
npm run test:advanced       # Advanced prompting tests
npm run test:quality        # Code quality validation
npm run test:infrastructure # Infrastructure tests

Test Infrastructure Script​

# Comprehensive test runner with resource monitoring
./scripts/test-infrastructure.sh [TYPE] [OPTIONS]

# Examples:
./scripts/test-infrastructure.sh unit
./scripts/test-infrastructure.sh integration --verbose
./scripts/test-infrastructure.sh performance --timeout=600
./scripts/test-infrastructure.sh cleanup  # Clean up test artifacts

Coverage & Reporting​

# Generate coverage report
npm run test:coverage

# View coverage in browser
open coverage/lcov-report/index.html

# CI-friendly JUnit output
npm test -- --ci --reporters=jest-junit

Watch Mode Development​

# Watch for changes and re-run tests
npm run test:watch

# Watch specific test pattern
npm run test:watch -- --testPathPattern=tools

✍️ Writing Tests​

Test File Structure​

/**
 * @fileoverview Tests for [Component Name]
 * @category [Unit|Integration|Performance]
 */

import { describe, it, expect, beforeEach, afterEach } from '@jest/globals';
import { testInfrastructure } from '../utils/test-infrastructure.js';
import { ComponentUnderTest } from '../../src/path/to/component.js';

describe('ComponentUnderTest', () => {
  let component: ComponentUnderTest;
  let testContext: any;

  beforeEach(async () => {
    testContext = await testInfrastructure.createTestContext();
    component = new ComponentUnderTest(testContext.config);
  });

  afterEach(async () => {
    await testInfrastructure.cleanupTestContext(testContext);
  });

  describe('core functionality', () => {
    it('should perform expected behavior', async () => {
      // Arrange
      const input = testContext.createMockInput();
      
      // Act
      const result = await component.process(input);
      
      // Assert
      expect(result).toBeDefined();
      expect(result.success).toBe(true);
    });
  });
});

Custom Matchers​

The testing framework includes custom Jest matchers for domain-specific assertions:

// ADR validation
expect(adrObject).toBeValidAdr();

// Schema validation
expect(dataObject).toHaveValidSchema();

// Prompt validation
expect(promptObject).toBeValidPromptObject();

// Performance improvement validation
expect(performanceResult).toShowSignificantImprovement(0.15);

Mock Usage​

// Tree-sitter mocks (automatically available)
import TreeSitter from 'tree-sitter';  // Uses mock implementation

// Custom mocks
import { mockFileSystem } from '../__mocks__/file-system.js';

beforeEach(() => {
  mockFileSystem.reset();
  mockFileSystem.addFile('/test/path', 'content');
});

Test Data Management​

// Use test infrastructure for consistent test data
const testData = testInfrastructure.generateTestData({
  type: 'adr',
  count: 5,
  complexity: 'medium'
});

// Create temporary directories
const tempDir = await testInfrastructure.createTempDirectory();

🎯 Testing Best Practices​

1. Test Organization​

  • Group related tests using describe blocks
  • Use descriptive test names that explain the expected behavior
  • Follow AAA pattern: Arrange, Act, Assert

2. Resource Management​

// ✅ Good: Proper cleanup
afterEach(async () => {
  await testInfrastructure.cleanupTestContext(testContext);
});

// ❌ Bad: No cleanup
afterEach(() => {
  // Missing cleanup
});

3. Async Testing​

// ✅ Good: Proper async handling
it('should handle async operations', async () => {
  const result = await asyncOperation();
  expect(result).toBeDefined();
});

// ❌ Bad: Missing await
it('should handle async operations', () => {
  const result = asyncOperation(); // Missing await
  expect(result).toBeDefined();
});

4. Test Isolation​

// ✅ Good: Independent tests
beforeEach(() => {
  component = new Component(freshConfig);
});

// ❌ Bad: Shared state
const component = new Component(config); // Shared across tests

5. Performance Considerations​

// ✅ Good: Performance-aware testing
it('should complete within reasonable time', async () => {
  const startTime = Date.now();
  await heavyOperation();
  const duration = Date.now() - startTime;
  expect(duration).toBeLessThan(5000); // 5 seconds
});

🔧 Troubleshooting​

Common Issues​

1. Memory Issues​

Problem: Tests fail with out-of-memory errors

Solution:

# Increase Node.js memory limit
export NODE_OPTIONS="--max-old-space-size=4096"
npm test

2. Tree-sitter Native Module Issues​

Problem: Tree-sitter modules fail to load in test environment

Solution: The project includes comprehensive mocks in tests/__mocks__/ that automatically handle this.

3. Timeout Issues​

Problem: Tests timeout in CI environment

Solution:

# Use infrastructure script with custom timeout
./scripts/test-infrastructure.sh integration --timeout=600

4. Resource Leaks​

Problem: Tests leave temporary files or handles open

Solution:

# Run cleanup
./scripts/test-infrastructure.sh cleanup

# Check resource status
npm test -- --verbose

Debug Mode​

# Enable debug logging
DEBUG=mcp-adr:* npm test

# Run single test with full output
npm test -- --testNamePattern="specific test" --verbose

Performance Debugging​

# Run with memory profiling
node --inspect-brk node_modules/.bin/jest --runInBand

# Performance test analysis
npm run test:performance -- --verbose

🚀 CI/CD Integration​

GitHub Actions Configuration​

The project includes automated testing in CI with:

  • Multiple Node.js versions (20.x, 22.x)
  • Cross-platform testing (Ubuntu, macOS, Windows)
  • Coverage reporting with threshold enforcement
  • Performance regression detection

Local CI Simulation​

# Simulate CI environment
CI=true npm test

# Generate CI-compatible reports
npm test -- --ci --coverage --reporters=jest-junit

Pre-commit Testing​

# Run pre-commit checks
npm run lint
npm run typecheck
npm test

# Or use the pre-commit script
./scripts/pre-commit-check.sh

📊 Coverage Requirements​

The project maintains 85% minimum coverage across:

  • Branches: 85%
  • Functions: 85%
  • Lines: 85%
  • Statements: 85%

Coverage Exclusions​

  • Type definition files (*.d.ts)
  • Test files (*.test.ts)
  • Mock implementations
  • Performance test utilities

Viewing Coverage​

# Generate and view coverage
npm run test:coverage
open coverage/lcov-report/index.html

🤝 Contributing Tests​

Before Submitting​

  1. Run full test suite: npm test
  2. Check coverage: npm run test:coverage
  3. Validate performance: npm run test:performance
  4. Run linting: npm run lint

Test Contribution Guidelines​

  1. Write tests for new features - All new functionality must include tests
  2. Maintain coverage thresholds - Don't reduce overall coverage
  3. Use existing patterns - Follow established testing patterns
  4. Document complex tests - Add comments for non-obvious test logic
  5. Test edge cases - Include boundary conditions and error scenarios

Review Checklist​

  • Tests follow naming conventions
  • Proper async/await usage
  • Resource cleanup implemented
  • Custom matchers used appropriately
  • Performance considerations addressed
  • Documentation updated if needed

📚 Additional Resources​

Need Help?

This guide is maintained as part of the MCP ADR Analysis Server project. Last updated: October 2025