@upyo/mock

Mock transport for the Upyo email library - perfect for testing email functionality without actually sending emails.

Features

• Memory-based storage: Stores “sent” messages in memory for verification
• Configurable behavior: Simulate delays, failures, and custom responses
• Rich testing API: Query, filter, and wait for messages in tests
• Type-safe: Full TypeScript support with readonly interfaces
• Cross-runtime: Works on Deno, Node.js, Bun, and edge functions

Installation

npm  add       @upyo/core @upyo/mock
pnpm add       @upyo/core @upyo/mock
yarn add       @upyo/core @upyo/mock
deno add --jsr @upyo/core @upyo/mock
bun  add       @upyo/core @upyo/mock

Usage

Basic testing

import { createMessage } from "@upyo/core";
import { MockTransport } from "@upyo/mock";

// Create a mock transport
const transport = new MockTransport();

const message = createMessage({
  from: "[email protected]",
  to: "[email protected]",
  subject: "Test Email",
  content: { text: "This is a test email." },
});

// "Send" the email (it will be stored in memory)
const receipt = await transport.send(message);

// Verify the result
console.log(receipt.successful); // true
console.log(receipt.messageId); // "mock-message-1"

// Check what was sent
const sentMessages = transport.getSentMessages();
console.log(sentMessages.length); // 1
console.log(sentMessages[0].subject); // "Test Email"

Advanced configuration

import { MockTransport } from "@upyo/mock";

const transport = new MockTransport({
  // Simulate network delay
  delay: 100,

  // Or use random delays
  randomDelayRange: { min: 50, max: 200 },

  // Simulate random failures (10% failure rate)
  failureRate: 0.1,

  // Custom default response
  defaultResponse: {
    successful: true,
    messageId: "custom-id-prefix"
  }
});

Testing with failures

const transport = new MockTransport();

// Set up a specific failure for the next send
transport.setNextResponse({
  successful: false,
  errorMessages: ["Invalid recipient address"]
});

const receipt = await transport.send(message);
console.log(receipt.successful); // false
console.log(receipt.errorMessages); // ["Invalid recipient address"]

Message querying and filtering

const transport = new MockTransport();

// Send some test messages
await transport.send(createMessage({
  from: "[email protected]",
  to: "[email protected]",
  subject: "Welcome User 1",
  content: { text: "Welcome!" }
}));

await transport.send(createMessage({
  from: "[email protected]",
  to: "[email protected]",
  subject: "Welcome User 2",
  content: { text: "Welcome!" }
}));

// Query sent messages
const allMessages = transport.getSentMessages();
console.log(allMessages.length); // 2

const user1Messages = transport.getMessagesTo("[email protected]");
console.log(user1Messages.length); // 1

const welcomeMessages = transport.getMessagesBySubject("Welcome User 1");
console.log(welcomeMessages.length); // 1

// Custom filtering
const textMessages = transport.findMessagesBy(msg =>
  "text" in msg.content && msg.content.text.includes("Welcome")
);
console.log(textMessages.length); // 2

Async testing utilities

const transport = new MockTransport();

// Wait for a specific number of messages
const waitPromise = transport.waitForMessageCount(3, 5000); // 5 second timeout

// Send messages from elsewhere in your code...
setTimeout(() => transport.send(message1), 100);
setTimeout(() => transport.send(message2), 200);
setTimeout(() => transport.send(message3), 300);

await waitPromise; // Resolves when 3 messages are sent

// Wait for a specific message
const specificMessage = await transport.waitForMessage(
  msg => msg.subject === "Important Alert",
  3000 // 3 second timeout
);

Cleanup and reset

const transport = new MockTransport();

// Send some messages and configure behavior
await transport.send(message);
transport.setDelay(100);
transport.setFailureRate(0.2);

// Clear just the sent messages
transport.clearSentMessages();
console.log(transport.getSentMessagesCount()); // 0

// Or reset everything to initial state
transport.reset(); // Clears messages and resets all configuration