@bernierllc/vitest-email-testing

Vitest plugin and matchers for modern email testing with TypeScript support, concurrent testing, and async assertions.

Features

- 🎯 Custom Vitest Matchers - Email-specific assertion matchers
- ⚡ Fast Test Execution - Optimized for Vitest's speed
- 🔄 Concurrent Testing - Safe parallel test execution
- 📝 TypeScript Support - Full type safety
- 🌐 ES Module Support - Native ESM compatibility
- 🧪 Async Assertions - Promise-based email testing

Installation

``bash
npm install --save-dev @bernierllc/vitest-email-testing
`

Quick Start

$3

`typescript
// vitest.config.ts
import { defineConfig } from 'vitest/config';
import { emailTesting } from '@bernierllc/vitest-email-testing';

export default defineConfig({
plugins: [
emailTesting({
smtp: {
port: 2525,
host: 'localhost'
}
})
],
test: {
globals: true
}
});
`

$3

`typescript
import { describe, test, expect } from 'vitest';

describe('Email Tests', () => {
test('welcome email', async () => {
const email = emailTesting.createTestData({
subject: 'Welcome!',
html: '

Welcome to our service

'
});

expect(email).toHaveEmailSubject(/Welcome/);
expect(email).toHaveHtmlContent('our service');
});
});
`

Custom Matchers

$3

`typescript
expect(email).toHaveEmailRecipient('user@example.com');
expect(email).toHaveEmailSender('noreply@example.com');
expect(email).toHaveEmailSubject('Welcome');
expect(email).toHaveEmailSubject(/Welcome/); // Regex support
`

$3

`typescript
expect(email).toHaveEmailContent('Hello World');
expect(email).toHaveHtmlContent('

Hello

');
expect(email).toHaveTextContent('Plain text');
`

$3

`typescript
expect(email).toHaveCompletedTemplate();
expect(email).toHaveTemplateVariable('userName', 'John Doe');
expect(email).toNotHaveUnreplacedVariables();
`

$3

`typescript
expect(email).toBeCompliantEmail('US');
expect(email).toHaveUnsubscribeLink();
expect(email).toHavePhysicalAddress();
`

$3

`typescript
await expect(email).toHaveBeenDelivered();
await expect(email).toHaveBeenDeliveredWithin(5000);
`

$3

`typescript
const schema = {
type: 'object',
properties: {},
required: ['from', 'to', 'subject']
};

expect(email).toSatisfyEmailSchema(schema);
`

Test Utilities

$3

`typescript
import { generateTestEmail, generateCompliantEmail } from '@bernierllc/vitest-email-testing';

// Basic test email
const email = generateTestEmail({
from: 'sender@example.com',
subject: 'Custom Subject'
});

// Compliant email
const compliantEmail = generateCompliantEmail('US');
`

$3

`typescript
import { createEmailSenderMock } from '@bernierllc/vitest-email-testing';

const mock = createEmailSenderMock();
mock.mockSendSuccess({ delay: 100 });

// Test your code
await sendEmail('user@example.com');

// Verify
expect(mock.send.calls).toHaveLength(1);
`

$3

`typescript
import { batchSendEmails } from '@bernierllc/vitest-email-testing';

const emails = await batchSendEmails(100, (index) =>
generateTestEmail({ to: user${index}@example.com })
);
`

Concurrent Testing

`typescript
describe.concurrent('Email Performance', () => {
test('send 100 emails', async () => {
const emails = await batchSendEmails(100, (i) =>
generateTestEmail({ to: user${i}@example.com })
);

expect(emails).toHaveLength(100);
});
});
`

Configuration Options

`typescript
emailTesting({
smtp: {
port: 2525,
host: 'localhost'
},
environment: {
isolation: 'per-test',
cleanup: 'auto',
timeout: 30000
},
vitest: {
concurrent: true,
globalSetup: true,
snapshotFormat: 'email-optimized'
},
watchTemplates: {
enabled: true,
patterns: ['templates/*/.html'],
rerunTests: true
}
})
`

API Reference

$3

- EmailData - Email data structure
- EmailMatcher - Email matching criteria
- EmailSchema - Email validation schema
- ComplianceRegion - Compliance region type
- EmailTestingConfig - Plugin configuration

$3

- emailTesting(config?) - Vitest plugin
- installEmailMatchers() - Install custom matchers
- createEmailSenderMock(sender?) - Create email sender mock
- generateTestEmail(overrides?) - Generate test email
- generateCompliantEmail(region?) - Generate compliant email
- waitForCondition(condition, options?) - Wait for condition

Integration Documentation

$3

Logger: Not applicable (testing utility)
NeverHub: Not applicable (testing utility)

This package is a testing utility and does not require runtime integrations with @bernierllc/logger or @bernierllc/neverhub-adapter. It is designed to be a standalone testing tool that works independently of application infrastructure.

$3

This package can be used to test email functionality in any @bernierllc service package:

`typescript
// Testing @bernierllc/email-service
import { describe, test, expect } from 'vitest';
import { EmailService } from '@bernierllc/email-service';
import { createEmailSenderMock } from '@bernierllc/vitest-email-testing';

describe('EmailService', () => {
test('sends welcome email', async () => {
const mock = createEmailSenderMock();
const service = new EmailService({ sender: mock });

await service.sendWelcome('user@example.com');

expect(mock.send.calls[0]).toHaveEmailSubject('Welcome');
});
});
``

$3

As a testing utility, this package operates independently and does not depend on external services. All functionality is self-contained within the test environment.

License

Copyright (c) 2025 Bernier LLC. See LICENSE.md for details.