# 🧪 Testing Guide - MCP ADR Analysis Server

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

## 📋 Table of Contents

- [Quick Start](#quick-start)
- [Testing Architecture](#testing-architecture)
- [Test Types & Categories](#test-types--categories)
- [Running Tests](#running-tests)
- [Writing Tests](#writing-tests)
- [Testing Best Practices](#testing-best-practices)
- [Troubleshooting](#troubleshooting)
- [CI/CD Integration](#cicd-integration)

---

## 🚀 Quick Start

### Prerequisites

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

### Installation & Setup

```bash
# 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

```bash
# 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

```typescript
// 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

```typescript
// 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

```typescript
// 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

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

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

---

## 🏃‍♂️ Running Tests

### Basic Commands

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```typescript
/**
 * @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:

```typescript
// 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

```typescript
// 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

```typescript
// 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

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

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

### 3. Async Testing

```typescript
// ✅ 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

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

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

### 5. Performance Considerations

```typescript
// ✅ 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**:

```bash
# 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**:

```bash
# 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**:

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

# Check resource status
npm test -- --verbose
```

### Debug Mode

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

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

### Performance Debugging

```bash
# 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

```bash
# Simulate CI environment
CI=true npm test

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

### Pre-commit Testing

```bash
# 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

```bash
# 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

- **[Jest Documentation](https://jestjs.io/./getting-started)**
- **[TypeScript Testing Guide](https://typescript-eslint.io/./linting/troubleshooting/)**
- **[MCP Protocol Testing](https://modelcontextprotocol.io/./testing)**
- **[Server Architecture](../explanation/server-architecture.md)**
- **[Contributing Guide](https://github.com/tosin2013/mcp-adr-analysis-server/blob/main/CONTRIBUTING.md)**

---

**Need Help?**

- 🐛 **Issues**: [GitHub Issues](https://github.com/tosin2013/mcp-adr-analysis-server/issues)
- 💬 **Discussions**: [GitHub Discussions](https://github.com/tosin2013/mcp-adr-analysis-server/issues)
- 📖 **Documentation**: [Full Documentation](./index.md)

---

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