dcrouter/test/test.config.md

# DCRouter Test Configuration

## Running Tests

### Run All Tests
```bash
cd dcrouter
pnpm test
```

### Run Specific Category
```bash
# Run all connection tests
tsx test/run-category.ts connection

# Run all security tests  
tsx test/run-category.ts security

# Run all performance tests
tsx test/run-category.ts performance
```

### Run Individual Test File
```bash
# Run TLS connection test
tsx test/suite/connection/test.tls-connection.ts

# Run authentication test
tsx test/suite/security/test.authentication.ts
```

### Run Tests with Verbose Output
```bash
# All tests with verbose logging
pnpm test -- --verbose

# Individual test with verbose
tsx test/suite/connection/test.tls-connection.ts --verbose
```

## Test Server Configuration

Each test file starts its own SMTP server with specific configuration. Common configurations:

### Basic Server
```typescript
const testServer = await startTestServer({
  port: 2525,
  hostname: 'localhost'
});
```

### TLS-Enabled Server
```typescript
const testServer = await startTestServer({
  port: 2525,
  hostname: 'localhost',
  tlsEnabled: true
});
```

### Authenticated Server
```typescript
const testServer = await startTestServer({
  port: 2525,
  hostname: 'localhost',
  authRequired: true
});
```

### High-Performance Server
```typescript
const testServer = await startTestServer({
  port: 2525,
  hostname: 'localhost',
  maxConnections: 1000,
  size: 50 * 1024 * 1024 // 50MB
});
```

## Port Allocation

Tests use different ports to avoid conflicts:
- Connection tests: 2525-2530
- Command tests: 2531-2540
- Email processing: 2541-2550
- Security tests: 2551-2560
- Performance tests: 2561-2570
- Edge cases: 2571-2580
- RFC compliance: 2581-2590

## Test Utilities

### Server Lifecycle
All tests follow this pattern:
```typescript
import { tap, expect } from '@git.zone/tstest/tapbundle';
import { startTestServer, stopTestServer } from '../../helpers/server.loader.js';

let testServer;

tap.test('setup', async () => {
  testServer = await startTestServer({ port: 2525 });
});

// Your tests here...

tap.test('cleanup', async () => {
  await stopTestServer(testServer);
});

tap.start();
```

### SMTP Client Testing
```typescript
import { createTestSmtpClient } from '../../helpers/smtp.client.js';

const client = createTestSmtpClient({
  host: 'localhost',
  port: 2525
});
```

### Low-Level SMTP Testing
```typescript
import { connectToSmtp, sendSmtpCommand } from '../../helpers/test.utils.js';

const socket = await connectToSmtp('localhost', 2525);
const response = await sendSmtpCommand(socket, 'EHLO test.example.com', '250');
```

## Performance Benchmarks

Expected minimums for production:
- Throughput: >10 emails/second
- Concurrent connections: >100
- Memory increase: <2% under load
- Connection time: <5000ms
- Error rate: <5%

## Debugging Failed Tests

### Enable Verbose Logging
```bash
DEBUG=* tsx test/suite/connection/test.tls-connection.ts
```

### Check Server Logs
Tests output server logs to console. Look for:
- 🚀 Server start messages
- 📧 Email processing logs
- ❌ Error messages
- ✅ Success confirmations

### Common Issues

1. **Port Already in Use**
   - Tests use unique ports
   - Check for orphaned processes: `lsof -i :2525`
   - Kill process: `kill -9 <PID>`

2. **TLS Certificate Errors**
   - Tests use self-signed certificates
   - Production should use real certificates

3. **Timeout Errors**
   - Increase timeout in test configuration
   - Check network connectivity
   - Verify server started successfully

4. **Authentication Failures**
   - Test servers may not validate credentials
   - Check authRequired configuration
   - Verify AUTH mechanisms supported