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
│   ├── 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

cd dcrouter
pnpm test

Run Specific Test Category

# Run all connection tests
pnpm test test/suite/connection

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

Run Single Test File

# Run TLS connection test
tsx test/suite/connection/test.tls-connection.ts

Run Tests with Verbose Output

# 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:

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)