smartmta/test/readme.md

# Mailer SMTP Test Suite (Deno)

Comprehensive SMTP server and client test suite ported from dcrouter to Deno-native testing.

## Test Framework

- **Framework**: Deno native testing (`Deno.test`)
- **Assertions**: `@std/assert` from Deno standard library
- **Run Command**: `deno test --allow-all --no-check test/`
- **Run Single Test**: `deno test --allow-all --no-check test/suite/smtpserver_commands/test.cmd-01.ehlo-command.test.ts`

## Test Infrastructure

### Helpers (`test/helpers/`)

- **`server.loader.ts`** - Test SMTP server lifecycle management
  - Start/stop test servers with configurable options
  - TLS certificate handling
  - Mock email processing
  - Port management utilities

- **`utils.ts`** - SMTP protocol test utilities
  - TCP connection management (Deno-native)
  - SMTP command sending/receiving
  - Protocol handshake helpers
  - MIME message creation
  - Retry and timing utilities

- **`smtp.client.ts`** - SMTP client test utilities
  - Test client creation with various configurations
  - Email sending helpers
  - Connection pooling testing
  - Throughput measurement

### Fixtures (`test/fixtures/`)

- **`test-cert.pem`** - Self-signed certificate for TLS testing
- **`test-key.pem`** - Private key for TLS testing

## Test Suite Organization

All tests follow the naming convention: `test.<category-id>.<description>.test.ts`

### Test Categories

#### 1. Connection Management (CM) - `smtpserver_connection/`

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

| ID | Test | Priority | Status |
|----|------|----------|--------|
| CM-01 | TLS Connection | High | Planned |
| CM-02 | Multiple Simultaneous Connections | High | Planned |
| CM-03 | Connection Timeout | High | Planned |
| CM-06 | STARTTLS Upgrade | High | Planned |
| CM-10 | Plain Connection | Low | Planned |

#### 2. SMTP Commands (CMD) - `smtpserver_commands/`

Tests for SMTP protocol command implementation.

| ID | Test | Priority | Status |
|----|------|----------|--------|
| **CMD-01** | **EHLO Command** | **High** | **✅ PORTED** |
| **CMD-02** | **MAIL FROM Command** | **High** | **✅ PORTED** |
| CMD-03 | RCPT TO Command | High | Planned |
| CMD-04 | DATA Command | High | Planned |
| CMD-06 | RSET Command | Medium | Planned |
| CMD-13 | QUIT Command | High | Planned |

#### 3. Email Processing (EP) - `smtpserver_email-processing/`

Tests for email content handling, parsing, and delivery.

| ID | Test | Priority | Status |
|----|------|----------|--------|
| EP-01 | Basic Email Sending | High | Planned |
| EP-02 | Invalid Email Address Handling | High | Planned |
| EP-04 | Large Email Handling | High | Planned |
| EP-05 | MIME Handling | High | Planned |

#### 4. Security (SEC) - `smtpserver_security/`

Tests for security features and protections.

| ID | Test | Priority | Status |
|----|------|----------|--------|
| SEC-01 | Authentication | High | Planned |
| SEC-03 | DKIM Processing | High | Planned |
| SEC-04 | SPF Checking | High | Planned |
| SEC-06 | IP Reputation Checking | High | Planned |
| SEC-08 | Rate Limiting | High | Planned |
| SEC-10 | Header Injection Prevention | High | Planned |

#### 5. Error Handling (ERR) - `smtpserver_error-handling/`

Tests for proper error handling and recovery.

| ID | Test | Priority | Status |
|----|------|----------|--------|
| ERR-01 | Syntax Error Handling | High | Planned |
| ERR-02 | Invalid Sequence Handling | High | Planned |
| ERR-05 | Resource Exhaustion | High | Planned |
| ERR-07 | Exception Handling | High | Planned |

## Currently Ported Tests

### ✅ CMD-01: EHLO Command (`test.cmd-01.ehlo-command.test.ts`)

**Tests**: 5 total (5 passing)
- Server startup/shutdown
- EHLO response with proper capabilities
- Invalid hostname handling
- Command pipelining (multiple EHLO)

**Key validations**:
- ✓ Server advertises SIZE capability
- ✓ Server advertises 8BITMIME capability
- ✓ Last capability line uses "250 " (space, not hyphen)
- ✓ Server handles invalid hostnames gracefully
- ✓ Second EHLO resets session state

### ✅ CMD-02: MAIL FROM Command (`test.cmd-02.mail-from.test.ts`)

**Tests**: 6 total
- Valid sender address acceptance
- Invalid sender address rejection
- SIZE parameter support
- Command sequence enforcement

**Key validations**:
- ✓ Accepts valid email formats
- ✓ Accepts IP literals (user@[192.168.1.1])
- ✓ Rejects malformed addresses
- ✓ Supports SIZE parameter
- ✓ Enforces EHLO before MAIL FROM

## Running Tests

### Run All Tests
```bash
deno test --allow-all --no-check test/
```

### Run Specific Category
```bash
# SMTP commands tests
deno test --allow-all --no-check test/suite/smtpserver_commands/

# Connection tests
deno test --allow-all --no-check test/suite/smtpserver_connection/
```

### Run Single Test File
```bash
deno test --allow-all --no-check test/suite/smtpserver_commands/test.cmd-01.ehlo-command.test.ts
```

### Run with Verbose Output
```bash
deno test --allow-all --no-check --trace-leaks test/
```

## Test Development Guidelines

### Writing New Tests

1. **Use Deno.test() format**:
```typescript
Deno.test({
  name: 'CMD-XX: Description of test',
  async fn() {
    // Test implementation
  },
  sanitizeResources: false,  // Required for network tests
  sanitizeOps: false,        // Required for network tests
});
```

2. **Import assertions from @std/assert**:
```typescript
import { assert, assertEquals, assertMatch } from '@std/assert';
```

3. **Use test helpers**:
```typescript
import { startTestServer, stopTestServer } from '../../helpers/server.loader.ts';
import { connectToSmtp, sendSmtpCommand } from '../../helpers/utils.ts';
```

4. **Always cleanup**:
- Close connections with `closeSmtpConnection()` or `conn.close()`
- Stop test servers with `stopTestServer()`
- Use try/finally blocks for guaranteed cleanup

5. **Test isolation**:
- Each test file uses its own port (e.g., CMD-01 uses 25251, CMD-02 uses 25252)
- Setup and cleanup tests ensure clean state

## Key Differences from dcrouter Tests

### Framework
- **Before**: `@git.zone/tstest/tapbundle` (Node.js)
- **After**: Deno.test (native)

### Assertions
- **Before**: `expect(x).toBeTruthy()`, `expect(x).toEqual(y)`
- **After**: `assert(x)`, `assertEquals(x, y)`, `assertMatch(x, regex)`

### Network I/O
- **Before**: Node.js `net` module
- **After**: Deno `Deno.connect()` / `Deno.listen()`

### Imports
- **Before**: `.js` extensions, Node-style imports
- **After**: `.ts` extensions, Deno-style imports

## Test Priorities

### Phase 1: Core SMTP Functionality (High Priority)
- ✅ CMD-01: EHLO Command
- ✅ CMD-02: MAIL FROM Command
- 🔄 CMD-03: RCPT TO Command
- 🔄 CMD-04: DATA Command
- 🔄 CMD-13: QUIT Command
- 🔄 CM-01: TLS Connection
- 🔄 EP-01: Basic Email Sending

### Phase 2: Security & Validation (High Priority)
- 🔄 SEC-01: Authentication
- 🔄 SEC-06: IP Reputation
- 🔄 SEC-08: Rate Limiting
- 🔄 SEC-10: Header Injection Prevention
- 🔄 ERR-01: Syntax Error Handling
- 🔄 ERR-02: Invalid Sequence Handling

### Phase 3: Advanced Features (Medium Priority)
- 🔄 SEC-03: DKIM Processing
- 🔄 SEC-04: SPF Checking
- 🔄 EP-04: Large Email Handling
- 🔄 EP-05: MIME Handling
- 🔄 CM-02: Multiple Connections
- 🔄 CM-06: STARTTLS Upgrade

### Phase 4: Complete Coverage (All Remaining)
- All performance tests
- All reliability tests
- All edge case tests
- All RFC compliance tests
- SMTP client tests

## Current Status

**Infrastructure**: ✅ Complete
- Deno-native test helpers
- Server lifecycle management
- SMTP protocol utilities
- Test certificates

**Tests Ported**: 2/100+ test files
- CMD-01: EHLO Command (5 tests passing)
- CMD-02: MAIL FROM Command (6 tests)

**Next Steps**:
1. Port CMD-03 (RCPT TO), CMD-04 (DATA), CMD-13 (QUIT)
2. Port CM-01 (TLS connection test)
3. Port EP-01 (Basic email sending)
4. Port security tests (SEC-01, SEC-06, SEC-08)
5. Continue with remaining high-priority tests

## Production Readiness Criteria

### Gate 1: Core Functionality (>90% tests passing)
- Basic SMTP command handling
- Connection management
- Email delivery
- Error handling

### Gate 2: Security (>95% tests passing)
- Authentication mechanisms
- TLS/STARTTLS support
- Rate limiting
- Injection prevention

### Gate 3: Enterprise Ready (>85% tests passing)
- Full RFC compliance
- Performance under load
- Advanced security features
- Complete edge case handling

## Contributing

When porting tests from dcrouter:

1. Maintain test IDs and organization
2. Convert to Deno.test() format
3. Use @std/assert for assertions
4. Update imports to .ts extensions
5. Use Deno-native TCP connections
6. Preserve test logic and validations
7. Add `sanitizeResources: false, sanitizeOps: false` for network tests
8. Update this README with ported tests

## Resources

- [Deno Testing](https://deno.land/manual/basics/testing)
- [Deno Standard Library - Assert](https://deno.land/std/assert)
- [RFC 5321 - SMTP](https://tools.ietf.org/html/rfc5321)
- [RFC 5322 - Internet Message Format](https://tools.ietf.org/html/rfc5322)