# Test Suite Documentation
This directory contains a comprehensive testing suite for the MCP Sequence Simulation Server.
## Structure
```
tests/
├── unit/ # Unit tests for individual components
│ ├── sequenceUtils.test.ts # Tests for core sequence utilities
│ ├── generateDNA.test.ts # Tests for DNA generation tool
│ ├── generateProtein.test.ts # Tests for protein generation tool
│ ├── mutateSequence.test.ts # Tests for mutation tool
│ ├── evolveSequence.test.ts # Tests for evolution tool
│ └── simulatePhylogeny.test.ts # Tests for phylogeny simulation
├── integration/ # Integration tests
│ └── mcpServer.test.ts # End-to-end MCP server tests
├── fixtures/ # Test data and fixtures
│ └── sequences.ts # Sample sequences and expected results
├── utils/ # Testing utilities
│ └── testHelpers.ts # Helper functions for tests
├── setup.ts # Test environment setup
└── README.md # This file
```
## Test Categories
### Unit Tests
- **Coverage**: Individual functions and tools
- **Focus**: Logic validation, parameter handling, edge cases
- **Speed**: Fast execution (< 1s per test)
### Integration Tests
- **Coverage**: MCP server communication and workflow
- **Focus**: End-to-end functionality, error handling, performance
- **Speed**: Moderate execution (< 30s per test)
## Running Tests
### All Tests
```bash
npm test
```
### Unit Tests Only
```bash
npm run test:unit
```
### Integration Tests Only
```bash
npm run test:integration
```
### Coverage Report
```bash
npm run test:coverage
```
### Watch Mode
```bash
npm run test:watch
```
## Test Configuration
### Vitest Configuration
- **Environment**: Node.js with native ES module support
- **Coverage Provider**: V8 for accurate coverage reporting
- **Coverage Threshold**: 80% for branches, functions, lines, statements
- **Timeout**: 10 seconds default, 60 seconds for integration tests
### Seeds and Reproducibility
Most tests use fixed seeds for reproducible results:
- Unit tests typically use seed `12345`
- Integration tests use various seeds for different scenarios
- Performance tests may use random seeds to test variance
## Test Data
### Fixtures (`fixtures/sequences.ts`)
- **DNA sequences**: Various lengths, GC content, special cases
- **Protein sequences**: Different compositions, properties
- **Phylogenetic trees**: Newick format examples
- **Expected results**: Pre-calculated values for validation
### Test Helpers (`utils/testHelpers.ts`)
- **Sequence validation**: DNA/protein format checking
- **Statistical validation**: Distribution and tolerance checks
- **Format validation**: FASTA, Newick, NEXUS parsers
- **Performance measurement**: Execution time tracking
## Test Patterns
### 1. Deterministic Testing
```typescript
it('should produce consistent results with seed', async () => {
const result1 = await tool.handler({ seed: 12345, ...params });
const result2 = await tool.handler({ seed: 12345, ...params });
expect(result1).toEqual(result2);
});
```
### 2. Statistical Testing
```typescript
it('should respect GC content parameter', async () => {
const result = await generateDNA.handler({
length: 1000,
gcContent: 0.7,
seed: 12345
});
const actualGC = TestUtils.calculateGCContent(sequence);
expect(TestUtils.isWithinTolerance(actualGC, 0.7, 0.1)).toBe(true);
});
```
### 3. Property-Based Testing
```typescript
it('should maintain valid sequences through mutations', async () => {
const testCases = [
{ rate: 0.1, iterations: 5 },
{ rate: 0.5, iterations: 10 },
{ rate: 0.9, iterations: 1 }
];
testCases.forEach(async ({ rate, iterations }) => {
const result = await mutateSequence.handler({
sequence: testSequence,
substitutionRate: rate,
iterations
});
result.mutations.forEach(mutation => {
expect(TestUtils.validateDNASequence(mutation.sequence)).toBe(true);
});
});
});
```
### 4. Error Handling Testing
```typescript
it('should handle invalid parameters gracefully', async () => {
await expect(tool.handler({
length: -1 // Invalid parameter
})).rejects.toThrow();
});
```
## Coverage Goals
### Functional Coverage
- ✅ All public methods and functions
- ✅ All tool handlers
- ✅ All error paths
- ✅ Edge cases and boundary conditions
### Scenario Coverage
- ✅ Typical use cases
- ✅ Extreme parameters
- ✅ Large datasets
- ✅ Error conditions
- ✅ Performance scenarios
### Data Coverage
- ✅ Short sequences (1-10 bases/residues)
- ✅ Medium sequences (50-500 bases/residues)
- ✅ Long sequences (1000+ bases/residues)
- ✅ Various compositions (GC content, amino acid bias)
- ✅ Edge cases (empty, single character)
## Performance Benchmarks
### Target Performance
- **DNA Generation**: < 100ms for 10kb sequences
- **Protein Generation**: < 50ms for 1kb sequences
- **Mutation**: < 200ms for 5kb sequences, 10 iterations
- **Evolution**: < 5s for 100 generations, 50 population
- **Phylogeny**: < 3s for 10 taxa, 1kb sequences
### Memory Usage
- **Peak memory**: < 100MB for largest test cases
- **Memory leaks**: None detected in 1000+ iterations
## Continuous Integration
### Pre-commit Checks
```bash
npm run build # TypeScript compilation
npm test # All tests pass
npm run test:coverage # Coverage thresholds met
```
### Test Matrix
- **Node.js versions**: 18.x, 20.x
- **Operating systems**: Linux, macOS, Windows
- **Test environments**: Local, CI/CD
## Debugging Tests
### Common Issues
1. **Timing issues**: Increase timeout for slow tests
2. **Random failures**: Check seed usage for deterministic behavior
3. **Memory issues**: Monitor large sequence generation
4. **Integration failures**: Verify server startup and communication
### Debug Tools
```bash
# Run single test with debug info
npm test -- --testNamePattern="specific test" --verbose
# Run with coverage details
npm run test:coverage -- --collectCoverageFrom="src/specific/file.ts"
# Debug integration tests
DEBUG=mcp:* npm run test:integration
```
## Contributing to Tests
### Adding New Tests
1. Create test file in appropriate directory
2. Follow existing naming conventions
3. Include both positive and negative test cases
4. Add fixtures for complex test data
5. Update this documentation
### Test Quality Guidelines
- **Descriptive names**: Test names should clearly state what is being tested
- **Single responsibility**: Each test should verify one specific behavior
- **Deterministic**: Tests should produce consistent results
- **Fast execution**: Unit tests should complete quickly
- **Comprehensive**: Cover edge cases and error conditions
### Best Practices
- Use `describe` blocks to group related tests
- Use `beforeEach`/`afterEach` for test setup/cleanup
- Mock external dependencies in unit tests
- Use real implementations in integration tests
- Validate both success and failure scenarios
