Add Email Testing Utilities

[jedau]

Description:
Add utilities for sending, receiving, and validating emails in E2E tests. Support SMTP/IMAP protocols and integration with email testing services (MailSlurp, Mailinator, Ethereal).

Acceptance Criteria:

• Create test/utils/email.ts with email testing helpers
• Support for SMTP email sending
• Support for IMAP/POP3 email receiving and reading
• Integration with email testing services (MailSlurp, Mailinator, Ethereal Email)
• Email content parsing (plain text, HTML, attachments)
• Email assertion helpers: expectEmailReceived(), expectEmailSubject(), expectEmailContains()
• Support for temporary disposable email addresses
• Email polling with timeout and retry logic
• Clean up test emails after scenarios
• Create test/features/email-notifications.feature example
• Create test/steps/email.steps.ts with email step definitions
• Document in docs/EMAIL-TESTING.md
• Add examples in TRAINING-EXERCISES.md

Technical Approach:

import { EmailClient } from './utils/email'

// Example: Verify email received after user registration
Given('I have a disposable email address', async function () {
  this.testEmail = await EmailClient.createDisposableEmail()
})

When('I register with email {string}', async function (email: string) {
  await this.getPageObject('RegistrationPage').fillEmail(this.testEmail)
  await this.getPageObject('RegistrationPage').submitForm()
})

Then('I should receive a verification email', async function () {
  const email = await EmailClient.waitForEmail({
    to: this.testEmail,
    subject: 'Verify your email',
    timeout: 30000,
  })
  expect(email).toBeDefined()
  expect(email.subject).toContain('Verify')
})

Then('the email should contain a verification link', async function () {
  const email = await EmailClient.getLatestEmail(this.testEmail)
  const verificationLink = EmailClient.extractLink(email.html, /verify/)
  expect(verificationLink).toMatch(/^https?:\/\/.*\/verify/)
})

// Example: Send test email via SMTP
await EmailClient.sendEmail({
  from: 'test@example.com',
  to: 'recipient@example.com',
  subject: 'Test Email',
  body: 'This is a test email',
  html: '<p>This is a test email</p>',
})

// Example: Read emails from inbox
const emails = await EmailClient.getEmails({
  to: 'test@example.com',
  since: new Date(Date.now() - 3600000), // Last hour
  subject: 'Password Reset',
})

// Example: Parse email content
const latestEmail = await EmailClient.getLatestEmail('test@example.com')
const plainText = EmailClient.getPlainText(latestEmail)
const htmlContent = EmailClient.getHtmlContent(latestEmail)
const attachments = EmailClient.getAttachments(latestEmail)

Integration with Testing Services:

// MailSlurp integration (recommended for CI/CD)
import { MailSlurp } from 'mailslurp-client'

const mailslurp = new MailSlurp({ apiKey: process.env.MAILSLURP_API_KEY })
const inbox = await mailslurp.createInbox()
const email = await mailslurp.waitForLatestEmail(inbox.id, 30000)

// Ethereal Email integration (free test accounts)
import nodemailer from 'nodemailer'

const testAccount = await nodemailer.createTestAccount()
const transporter = nodemailer.createTransporter({
  host: 'smtp.ethereal.email',
  port: 587,
  auth: { user: testAccount.user, pass: testAccount.pass },
})

Environment Configuration:

# .env.example
MAILSLURP_API_KEY=your_api_key_here
SMTP_HOST=smtp.ethereal.email
SMTP_PORT=587
IMAP_HOST=imap.ethereal.email
IMAP_PORT=993
EMAIL_TIMEOUT=30000

Benefits:

• Test email notifications and workflows end-to-end
• Verify email content, formatting, and links
• Test password reset, account verification, and notification features
• Validate email triggers and timing
• Test with real email protocols (SMTP/IMAP)
• Support for both real and disposable email addresses
• Integration with popular email testing services
• Isolated email testing without affecting production inboxes

Use Cases:

• User registration with email verification
• Password reset flows
• Notification email testing
• Email template validation
• Transactional email verification
• Email delivery confirmation
• Multi-step email workflows

Why v0.7.0:
Fits perfectly with Enhanced Testing & Quality milestone alongside API testing (#34), API mocking (#134), and custom assertions (#140). Email testing is a common E2E testing requirement that integrates with external services, similar to API and database testing capabilities.

References:

• MailSlurp: https://www.mailslurp.com/
• Nodemailer: https://nodemailer.com/
• Ethereal Email: https://ethereal.email/
• Mailinator: https://www.mailinator.com/
• IMAP Simple: https://github.com/chadxz/imap-simple
• Playwright Email Testing Guide: https://playwright.dev/docs/test-advanced#testing-emails
• CodeceptJS Email Helper: https://codecept.io/helpers/Email/
• Serenity/JS Email Example: https://serenity-js.org/handbook/integration/emails/