dcrouter/test/readme.md

# DCRouter SMTP Test Suite

This comprehensive test suite validates the production readiness of the dcrouter SMTP implementation. All tests are built using TypeScript with tstest/tapbundle/smartexpect for consistent test patterns across the codebase.

## 📊 Test Status Legend

**Test Result Status**:
| Status | Symbol | Meaning | Description |
|--------|--------|---------|-------------|
| **✅ PASSED** | ✅ | Test executed and passed | Test ran successfully and all assertions passed |
| **❌ FAILED** | ❌ | Test executed but failed | Test ran but assertions failed or errors occurred |
| **⚠️ TIMEOUT** | ⚠️ | Test execution timed out | Test exceeded maximum execution time limit |
| **🔧 VALIDATION** | 🔧 | Expected validation passed | Test confirmed proper error handling/validation works |

## 📈 Production Readiness Levels

| Level | Symbol | Criteria | Description |
|-------|--------|----------|-------------|
| **🟢 PRODUCTION READY** | 🟢 | ≥80% success rate | Component validated for production deployment |
| **🟡 NEAR READY** | 🟡 | 60-79% success rate | Component needs minor fixes before production |
| **🟠 DEVELOPMENT** | 🟠 | 40-59% success rate | Component in active development, not production ready |
| **🔴 NOT READY** | 🔴 | <40% success rate | Component requires significant work before production |

## Test Organization

Tests are organized into logical categories within the `suite/` directory:

```
test/
├── readme.md                   # This file
├── helpers/
│   ├── server.loader.ts       # SMTP server lifecycle management
│   ├── test.utils.ts          # Common test utilities
│   └── smtp.client.ts         # Test SMTP client utilities
└── suite/
    ├── connection/            # Connection management tests (CM)
    ├── commands/              # SMTP command tests (CMD)
    ├── email-processing/      # Email processing tests (EP)
    ├── security/              # Security tests (SEC)
    ├── error-handling/        # Error handling tests (ERR)
    ├── performance/           # Performance tests (PERF)
    ├── reliability/           # Reliability tests (REL)
    ├── edge-cases/            # Edge case tests (EDGE)
    └── rfc-compliance/        # RFC compliance tests (RFC)
```

## Test Categories

### 1. Connection Management (CM)

Tests for validating SMTP connection handling, TLS support, and connection lifecycle management.

| ID    | Test Description                          | Priority | Implementation |
|-------|-------------------------------------------|----------|----------------|
| CM-01 | TLS Connection Test                       | High     | `suite/connection/test.tls-connection.ts` |
| CM-02 | Multiple Simultaneous Connections         | High     | `suite/connection/test.multiple-connections.ts` |
| CM-03 | Connection Timeout                        | High     | `suite/connection/test.connection-timeout.ts` |
| CM-04 | Connection Limits                         | Medium   | `suite/connection/test.connection-limits.ts` |
| CM-05 | Connection Rejection                      | Medium   | `suite/connection/test.connection-rejection.ts` |
| CM-06 | STARTTLS Connection Upgrade               | High     | `suite/connection/test.starttls-upgrade.ts` |
| CM-07 | Abrupt Client Disconnection               | Medium   | `suite/connection/test.abrupt-disconnection.ts` |
| CM-08 | TLS Version Compatibility                 | Medium   | `suite/connection/test.tls-versions.ts` |
| CM-09 | TLS Cipher Configuration                  | Medium   | `suite/connection/test.tls-ciphers.ts` |
| CM-10 | Plain Connection Test                     | Low      | `suite/connection/test.plain-connection.ts` |
| CM-11 | TCP Keep-Alive Test                       | Low      | `suite/connection/test.keepalive.ts` |

### 2. SMTP Commands (CMD)

Tests for validating proper SMTP protocol command implementation.

| ID     | Test Description                          | Priority | Implementation |
|--------|-------------------------------------------|----------|----------------|
| CMD-01 | EHLO Command                              | High     | `suite/commands/test.ehlo-command.ts` |
| CMD-02 | MAIL FROM Command                         | High     | `suite/commands/test.mail-from.ts` |
| CMD-03 | RCPT TO Command                           | High     | `suite/commands/test.rcpt-to.ts` |
| CMD-04 | DATA Command                              | High     | `suite/commands/test.data-command.ts` |
| CMD-05 | NOOP Command                              | Medium   | `suite/commands/test.noop-command.ts` |
| CMD-06 | RSET Command                              | Medium   | `suite/commands/test.rset-command.ts` |
| CMD-07 | VRFY Command                              | Low      | `suite/commands/test.vrfy-command.ts` |
| CMD-08 | EXPN Command                              | Low      | `suite/commands/test.expn-command.ts` |
| CMD-09 | SIZE Extension                            | Medium   | `suite/commands/test.size-extension.ts` |
| CMD-10 | HELP Command                              | Low      | `suite/commands/test.help-command.ts` |
| CMD-11 | Command Pipelining                        | Medium   | `suite/commands/test.command-pipelining.ts` |
| CMD-12 | HELO Command                              | Low      | `suite/commands/test.helo-command.ts` |
| CMD-13 | QUIT Command                              | High     | `suite/commands/test.quit-command.ts` |

### 3. Email Processing (EP)

Tests for validating email content handling, parsing, and delivery.

| ID    | Test Description                          | Priority | Implementation |
|-------|-------------------------------------------|----------|----------------|
| EP-01 | Basic Email Sending                       | High     | `suite/email-processing/test.basic-email.ts` |
| EP-02 | Invalid Email Address Handling            | High     | `suite/email-processing/test.invalid-addresses.ts` |
| EP-03 | Multiple Recipients                       | Medium   | `suite/email-processing/test.multiple-recipients.ts` |
| EP-04 | Large Email Handling                      | High     | `suite/email-processing/test.large-email.ts` |
| EP-05 | MIME Handling                             | High     | `suite/email-processing/test.mime-handling.ts` |
| EP-06 | Attachment Handling                       | Medium   | `suite/email-processing/test.attachments.ts` |
| EP-07 | Special Character Handling                | Medium   | `suite/email-processing/test.special-chars.ts` |
| EP-08 | Email Routing                             | High     | `suite/email-processing/test.email-routing.ts` |
| EP-09 | Delivery Status Notifications             | Medium   | `suite/email-processing/test.dsn.ts` |

### 4. Security (SEC)

Tests for validating security features and protections.

| ID     | Test Description                          | Priority | Implementation |
|--------|-------------------------------------------|----------|----------------|
| SEC-01 | Authentication                            | High     | `suite/security/test.authentication.ts` |
| SEC-02 | Authorization                             | High     | `suite/security/test.authorization.ts` |
| SEC-03 | DKIM Processing                           | High     | `suite/security/test.dkim.ts` |
| SEC-04 | SPF Checking                              | High     | `suite/security/test.spf.ts` |
| SEC-05 | DMARC Policy Enforcement                  | Medium   | `suite/security/test.dmarc.ts` |
| SEC-06 | IP Reputation Checking                    | High     | `suite/security/test.ip-reputation.ts` |
| SEC-07 | Content Scanning                          | Medium   | `suite/security/test.content-scanning.ts` |
| SEC-08 | Rate Limiting                             | High     | `suite/security/test.rate-limiting.ts` |
| SEC-09 | TLS Certificate Validation                | High     | `suite/security/test.tls-validation.ts` |
| SEC-10 | Header Injection Prevention               | High     | `suite/security/test.header-injection.ts` |
| SEC-11 | Bounce Management                         | Medium   | `suite/security/test.bounce-management.ts` |

### 5. Error Handling (ERR)

Tests for validating proper error handling and recovery.

| ID     | Test Description                          | Priority | Implementation |
|--------|-------------------------------------------|----------|----------------|
| ERR-01 | Syntax Error Handling                     | High     | `suite/error-handling/test.syntax-errors.ts` |
| ERR-02 | Invalid Sequence Handling                 | High     | `suite/error-handling/test.invalid-sequence.ts` |
| ERR-03 | Temporary Failure Handling                | Medium   | `suite/error-handling/test.temp-failures.ts` |
| ERR-04 | Permanent Failure Handling                | Medium   | `suite/error-handling/test.perm-failures.ts` |
| ERR-05 | Resource Exhaustion Handling              | High     | `suite/error-handling/test.resource-exhaustion.ts` |
| ERR-06 | Malformed MIME Handling                   | Medium   | `suite/error-handling/test.malformed-mime.ts` |
| ERR-07 | Exception Handling                        | High     | `suite/error-handling/test.exceptions.ts` |
| ERR-08 | Error Logging                             | Medium   | `suite/error-handling/test.error-logging.ts` |

### 6. Performance (PERF)

Tests for validating performance characteristics and benchmarks.

| ID      | Test Description                         | Priority | Implementation |
|---------|------------------------------------------|----------|----------------|
| PERF-01 | Throughput Testing                       | Medium   | `suite/performance/test.throughput.ts` |
| PERF-02 | Concurrency Testing                      | High     | `suite/performance/test.concurrency.ts` |
| PERF-03 | CPU Utilization                          | Medium   | `suite/performance/test.cpu-usage.ts` |
| PERF-04 | Memory Usage                             | Medium   | `suite/performance/test.memory-usage.ts` |
| PERF-05 | Connection Processing Time               | Medium   | `suite/performance/test.connection-time.ts` |
| PERF-06 | Message Processing Time                  | Medium   | `suite/performance/test.message-time.ts` |
| PERF-07 | Resource Cleanup                         | High     | `suite/performance/test.resource-cleanup.ts` |

### 7. Reliability (REL)

Tests for validating system reliability and stability.

| ID     | Test Description                          | Priority | Implementation |
|--------|-------------------------------------------|----------|----------------|
| REL-01 | Long-Running Operation                    | High     | `suite/reliability/test.long-running.ts` |
| REL-02 | Restart Recovery                          | High     | `suite/reliability/test.restart-recovery.ts` |
| REL-03 | Resource Leak Detection                   | High     | `suite/reliability/test.resource-leaks.ts` |
| REL-04 | Error Recovery                            | High     | `suite/reliability/test.error-recovery.ts` |
| REL-05 | DNS Resolution Failure Handling           | Medium   | `suite/reliability/test.dns-failures.ts` |
| REL-06 | Network Interruption Handling             | Medium   | `suite/reliability/test.network-interruptions.ts` |

### 8. Edge Cases (EDGE)

Tests for validating handling of unusual or extreme scenarios.

| ID      | Test Description                          | Priority | Implementation |
|---------|-------------------------------------------|----------|----------------|
| EDGE-01 | Very Large Email                          | Low      | `suite/edge-cases/test.very-large-email.ts` |
| EDGE-02 | Very Small Email                          | Low      | `suite/edge-cases/test.very-small-email.ts` |
| EDGE-03 | Invalid Character Handling                | Medium   | `suite/edge-cases/test.invalid-chars.ts` |
| EDGE-04 | Empty Commands                            | Low      | `suite/edge-cases/test.empty-commands.ts` |
| EDGE-05 | Extremely Long Lines                      | Medium   | `suite/edge-cases/test.long-lines.ts` |
| EDGE-06 | Extremely Long Headers                    | Medium   | `suite/edge-cases/test.long-headers.ts` |
| EDGE-07 | Unusual MIME Types                        | Low      | `suite/edge-cases/test.unusual-mime.ts` |
| EDGE-08 | Nested MIME Structures                    | Low      | `suite/edge-cases/test.nested-mime.ts` |

### 9. RFC Compliance (RFC)

Tests for validating compliance with SMTP-related RFCs.

| ID     | Test Description                          | Priority | Implementation |
|--------|-------------------------------------------|----------|----------------|
| RFC-01 | RFC 5321 Compliance                       | High     | `suite/rfc-compliance/test.rfc5321.ts` |
| RFC-02 | RFC 5322 Compliance                       | High     | `suite/rfc-compliance/test.rfc5322.ts` |
| RFC-03 | RFC 7208 SPF Compliance                   | Medium   | `suite/rfc-compliance/test.rfc7208-spf.ts` |
| RFC-04 | RFC 6376 DKIM Compliance                  | Medium   | `suite/rfc-compliance/test.rfc6376-dkim.ts` |
| RFC-05 | RFC 7489 DMARC Compliance                 | Medium   | `suite/rfc-compliance/test.rfc7489-dmarc.ts` |
| RFC-06 | RFC 8314 TLS Compliance                   | Medium   | `suite/rfc-compliance/test.rfc8314-tls.ts` |
| RFC-07 | RFC 3461 DSN Compliance                   | Low      | `suite/rfc-compliance/test.rfc3461-dsn.ts` |

## Running Tests

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

### Run Specific Test Category
```bash
# Run all connection tests
pnpm test test/suite/connection

# Run all security tests
pnpm test test/suite/security
```

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

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

## Test Infrastructure

### Server Loader Module

All test files import the server loader module which provides:
- Automatic SMTP server lifecycle management
- Server starts before test execution
- Server stops after test completion
- Port allocation and cleanup
- Resource tracking and cleanup

Example test structure:
```typescript
import { tap, expect } from '@git.zone/tstest/tapbundle';
import { startTestServer, stopTestServer } from '../../helpers/server.loader.js';

let testServer: any;

tap.test('setup - start SMTP server', async () => {
  testServer = await startTestServer({
    port: 2525,
    tlsEnabled: true
  });
  expect(testServer).toBeInstanceOf(Object);
});

// Your tests here...

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

tap.start();
```

## Performance Benchmarks

Expected performance metrics for production deployment:
- **Throughput**: >90 operations per second
- **Memory Efficiency**: <2% memory increase under load
- **Concurrent Connections**: >1000 simultaneous connections
- **Connection Time**: <5000ms for TLS connections
- **Resource Cleanup**: <100ms average cleanup time

## Security Requirements

All security tests must pass for production deployment:
- TLS 1.2+ support required
- Strong cipher suites only
- DKIM signature verification
- SPF record checking
- DMARC policy enforcement
- Rate limiting active
- Header injection prevention

## Production Readiness Gates

### Gate 1: Server Production Ready (Target: >95% tests passing)
- All critical connection tests passing
- All SMTP command tests passing
- Security vulnerabilities addressed
- Performance benchmarks met

### Gate 2: Client Production Ready (Target: >90% tests passing)
- Client authentication working
- Connection pooling efficient
- Error handling comprehensive
- Performance targets achieved

### Gate 3: Integration Validated (Target: >80% tests passing)
- End-to-end email flow working
- Client-server communication stable
- Security policies enforced
- Performance maintained under load

## Certification

Upon successful completion of all test categories with required pass rates:
- **🟢 PRODUCTION READY**: Component certified for production deployment
- **🟡 NEAR READY**: Minor fixes required before production
- **🟠 DEVELOPMENT**: Significant work needed
- **🔴 NOT READY**: Major issues requiring resolution

## Contributing

When adding new tests:
1. Follow the existing test structure
2. Use descriptive test names
3. Include proper setup and cleanup
4. Add test to appropriate category
5. Update this README with test details
6. Ensure tests use tstest/tapbundle/smartexpect

## Migration Status

### Current Progress
**Last Updated**: 2025-05-23

**Overall Migration Progress**: 23 tests migrated from production test suite

#### Migration Summary by Category:

| Category | Tests Migrated | Total Tests | Status |
|----------|---------------|-------------|---------|
| Connection Management (CM) | 4 | 11 | 🟠 36% |
| SMTP Commands (CMD) | 10 | 13 | 🟢 77% |
| Email Processing (EP) | 4 | 9 | 🟠 44% |
| Error Handling (ERR) | 2 | 8 | 🟠 25% |
| Security (SEC) | 1 | 11 | 🔴 9% |
| Performance (PERF) | 1 | 7 | 🔴 14% |
| Reliability (REL) | 0 | 6 | 🔴 0% |
| Edge Cases (EDGE) | 1 | 8 | 🔴 13% |
| RFC Compliance (RFC) | 0 | 7 | 🔴 0% |

#### Recently Migrated Tests:
- ✅ `test.tls-connection.ts` - TLS connection handling
- ✅ `test.multiple-connections.ts` - Multiple simultaneous connections
- ✅ `test.connection-timeout.ts` - Connection timeout handling
- ✅ `test.starttls-upgrade.ts` - STARTTLS connection upgrade (NEW)
- ✅ `test.ehlo-command.ts` - EHLO command validation
- ✅ `test.mail-from.ts` - MAIL FROM command validation
- ✅ `test.rcpt-to.ts` - RCPT TO command validation
- ✅ `test.data-command.ts` - DATA command and email content handling
- ✅ `test.noop-command.ts` - NOOP command functionality
- ✅ `test.rset-command.ts` - RSET command functionality
- ✅ `test.quit-command.ts` - QUIT command handling
- ✅ `test.size-extension.ts` - SIZE extension support (NEW)
- ✅ `test.vrfy-command.ts` - VRFY command functionality (NEW)
- ✅ `test.helo-command.ts` - HELO command validation (NEW)
- ✅ `test.basic-email-sending.ts` - Basic email sending flow
- ✅ `test.invalid-email-addresses.ts` - Invalid email address validation
- ✅ `test.multiple-recipients.ts` - Multiple recipients handling
- ✅ `test.syntax-errors.ts` - Syntax error handling
- ✅ `test.invalid-sequence.ts` - Invalid command sequence handling
- ✅ `test.authentication.ts` - SMTP authentication
- ✅ `test.throughput.ts` - Throughput performance testing
- ✅ `test.very-large-email.ts` - Large email handling
- ✅ `test.basic-email.ts` - Basic email processing

#### Next Priority Tests to Migrate:
1. **High Priority** (All completed ✅):
   - ✅ RSET command (CMD-06)
   - ✅ QUIT command (CMD-13)
   - ✅ Invalid sequence handling (ERR-02)
   - ✅ Multiple recipients (EP-03)

2. **Medium Priority**:
   - STARTTLS upgrade (CM-06)
   - SIZE extension (CMD-09)
   - Large email handling (EP-04)
   - Rate limiting (SEC-08)
   - VRFY command (CMD-07)
   - HELO command (CMD-12)
   - Connection limits (CM-04)
   - Temporary failure handling (ERR-03)

3. **Lower Priority**:
   - EXPN command (CMD-08)
   - HELP command (CMD-10)
   - Long running operation (REL-01)
   - RFC compliance tests (RFC-01 to RFC-07)

### Migration Notes:
- All tests have been converted to use `@git.zone/tstest/tapbundle` framework
- Each test file is self-contained with its own server lifecycle management
- Test files follow the naming pattern `test.*.ts` for automatic discovery
- Helper modules provide consistent server management across all tests

### Session Progress (2025-05-23):
**First Session**:
- Migrated 4 additional tests, bringing total from 15 to 19
- Completed all high priority tests
- SMTP Commands category reached 54% completion (7/13 tests)
- Email Processing category reached 44% completion (4/9 tests)
- Error Handling category reached 25% completion (2/8 tests)

**Second Session**:
- Migrated 4 more tests, bringing total from 19 to 23
- Completed 3 more SMTP command tests (SIZE, VRFY, HELO)
- Added STARTTLS upgrade test for connection management
- SMTP Commands category now at 77% completion (10/13 tests)
- Connection Management category now at 36% completion (4/11 tests)
- Overall test migration progress: 27.4% (23/84 total tests)