@bernierllc/email-test-orchestrator

Service package that orchestrates comprehensive email testing workflows. This package coordinates email sending and receiving for tests, manages test email addresses and routing, executes validation workflows across multiple aspects, and generates comprehensive test reports.

Installation

npm install @bernierllc/email-test-orchestrator

Features

• Complete Test Orchestration - End-to-end email testing workflows
• Multi-Validator Coordination - Use multiple validation packages
• Comprehensive Reporting - Detailed test results and analytics
• Test Lifecycle Management - Setup, execution, cleanup
• Async Test Coordination - Handle asynchronous email delivery testing
• Flexible Configuration - Customize SMTP, capture, validation, and reporting

Usage

Basic Example

import { EmailTestOrchestrator } from '@bernierllc/email-test-orchestrator';

const orchestrator = new EmailTestOrchestrator({
  smtp: {
    host: 'localhost',
    port: 2525,
  },
  validation: {
    enabledValidators: ['content', 'delivery', 'compliance'],
  },
});

// Run a single test
const result = await orchestrator.runEmailTest({
  name: 'Welcome Email Test',
  description: 'Test welcome email delivery and content',
  sender: { email: '[email protected]' },
  recipients: [{ email: '[email protected]' }],
  expectations: [
    {
      type: 'delivery',
      criteria: { delivered: true },
      weight: 2,
    },
    {
      type: 'content',
      criteria: { hasSubject: true, hasBody: true },
      weight: 1,
    },
  ],
});

console.log(`Test ${result.success ? 'passed' : 'failed'} with score: ${result.score}`);

Send and Capture Email

const email = await orchestrator.sendAndCapture({
  from: { email: '[email protected]', name: 'Sender' },
  to: [{ email: '[email protected]', name: 'Recipient' }],
  subject: 'Test Email',
  text: 'This is a test email',
});

console.log('Captured email:', email.subject);

Execute Test Suite

const tests = [
  {
    name: 'Welcome Email',
    description: 'Test welcome email',
    sender: { email: '[email protected]' },
    recipients: [{ email: '[email protected]' }],
    expectations: [
      { type: 'delivery', criteria: { delivered: true } },
    ],
  },
  {
    name: 'Password Reset',
    description: 'Test password reset email',
    sender: { email: '[email protected]' },
    recipients: [{ email: '[email protected]' }],
    expectations: [
      { type: 'content', criteria: { hasResetLink: true } },
    ],
  },
];

const suiteResult = await orchestrator.executeTestSuite(tests);

console.log(`Suite: ${suiteResult.report.summary.passed}/${suiteResult.report.summary.totalTests} passed`);

Validate Captured Email

const validationResults = await orchestrator.validateEmail(capturedEmail, [
  {
    type: 'content',
    criteria: { hasSubject: true, hasBody: true },
  },
  {
    type: 'compliance',
    criteria: { hasUnsubscribeLink: true },
  },
  {
    type: 'template',
    criteria: { templateName: 'welcome' },
  },
]);

for (const result of validationResults) {
  console.log(`${result.type}: ${result.success ? 'PASS' : 'FAIL'} (score: ${result.score})`);
}

Test Environment Setup

const context = await orchestrator.setupTestEnvironment({
  mockServer: { port: 2525 },
  session: { name: 'integration-test' },
  cleanup: { retention: '1h' },
});

try {
  // Run tests...
  await orchestrator.runEmailTest(testSpec);
} finally {
  // Clean up
  await context.cleanup();
}

Generate Report

const results = [testResult1, testResult2, testResult3];
const report = await orchestrator.generateReport(results);

console.log('Report Summary:');
console.log(`Total: ${report.summary.totalTests}`);
console.log(`Passed: ${report.summary.passed}`);
console.log(`Failed: ${report.summary.failed}`);
console.log(`Score: ${report.summary.score}%`);
console.log(`Duration: ${report.summary.duration}ms`);

Wait for Email Delivery

const email = await orchestrator.waitForDelivery('email-123', 30000);

if (email) {
  console.log('Email delivered:', email.subject);
} else {
  console.log('Email not delivered within timeout');
}

Configuration

OrchestratorConfig

interface OrchestratorConfig {
  smtp?: {
    host?: string;           // Default: 'localhost'
    port?: number;           // Default: 2525
    secure?: boolean;        // Default: false
    auth?: {
      user: string;
      pass: string;
    };
  };
  capture?: {
    sessionTimeout?: number;    // Default: 300000 (5 minutes)
    retentionPolicy?: string;   // Default: '1h'
  };
  validation?: {
    enabledValidators?: ValidatorType[];  // Default: all validators
    parallelValidation?: boolean;         // Default: true
    validationTimeout?: number;           // Default: 30000
  };
  reporting?: {
    formats?: ReportFormat[];           // Default: ['json']
    includeRawEmails?: boolean;         // Default: false
    includeScreenshots?: boolean;       // Default: false
  };
  logger?: any;  // Custom logger (default: console)
}

Validator Types

• content - Validate email content (subject, body, etc.)
• template - Validate template processing
• compliance - Validate compliance (CAN-SPAM, GDPR, etc.)
• smtp - Validate SMTP delivery information
• delivery - Validate email delivery status

Report Formats

• json - JSON format for programmatic access
• html - HTML format for web viewing
• pdf - PDF format for sharing and archiving
• csv - CSV format for data analysis

API Reference

EmailTestOrchestrator

Methods

• sendAndCapture(options: SendEmailOptions): Promise<CapturedEmail>

  • Send an email and capture it for testing

• executeTestSuite(tests: EmailTestSpec[]): Promise<EmailTestSuiteResult>

  • Execute multiple tests and return suite result

• runEmailTest(testSpec: EmailTestSpec): Promise<EmailTestResult>

  • Run a single email test

• validateEmail(email: CapturedEmail, expectations: EmailExpectation[]): Promise<ValidationResult[]>

  • Validate email against expectations

• generateReport(results: EmailTestResult[]): Promise<TestReport>

  • Generate comprehensive test report

• setupTestEnvironment(config: TestSetupConfig): Promise<TestContext>

  • Set up test environment

• cleanupTestEnvironment(sessionId: string): Promise<void>

  • Clean up test environment

• waitForDelivery(emailId: string, timeout?: number): Promise<CapturedEmail | null>

  • Wait for email delivery with timeout

Dependencies

This package integrates with the following BernierLLC packages:

• @bernierllc/mock-smtp-server - SMTP server coordination
• @bernierllc/email-test-assertions - Test assertions
• @bernierllc/email-sender - Email sending
• @bernierllc/email-parser - Email parsing
• @bernierllc/email-validator - Email validation
• @bernierllc/email-capture - Email capture
• @bernierllc/template-engine - Template processing
• @bernierllc/retry-policy - Retry logic
• @bernierllc/logger - Logging

Production Use Cases

Beyond testing, this package can be used for:

• Email Quality Assurance - Pre-send validation workflows
• Compliance Auditing - Automated compliance checking
• Template Testing - Continuous template validation
• Deliverability Monitoring - Email delivery analysis
• A/B Testing - Email variant testing and comparison

License

Copyright (c) 2025 Bernier LLC. This file is licensed to the client under a limited-use license.