Pruebas de correo con Vitest e InboxTap

Usa el adaptador oficial

Instala InboxTap, Nodemailer 9 y Vitest, y amplía la prueba base desde inboxtap/fixtures/vitest. El adaptador inicia escuchas SMTP y HTTP en puertos asignados por el sistema operativo, verifica su transporte antes de ceder el control y cierra el estado parcial o completo del inicio cuando termina el ámbito del archivo.

El paquete mantiene Vitest detrás de una subruta opcional. Importar la raíz de InboxTap o el SDK de cliente no carga Vitest ni Nodemailer en proyectos que no usan este recurso.

• Documentación de recursos y contexto de prueba de Vitest ↗

Combina recursos y comparadores nativos

El recurso inboxTap inyectado solo se comparte entre las pruebas de un archivo. Su transporte sirve para comprobar directamente una plantilla de correo, mientras que inboxTap.smtp puede configurar una instancia de la aplicación que deba recorrer todo el límite de integración.

Registra el adaptador de comparadores con el objeto expect de Vitest. Espera toHaveDeliveredOnce() porque puede observar un intervalo de calma acotado; los comparadores de destinatarios y enlaces de cada mensaje siguen siendo síncronos.

import { expect, test as base } from "vitest";
import { extendInboxTap } from "inboxtap/fixtures/vitest";
import { extendInboxTapExpect } from "inboxtap/matchers/vitest";

extendInboxTapExpect(expect);
const test = extendInboxTap(base);

test.concurrent("captures one delivery", async ({ inboxTap, inbox }) => {
  await inboxTap.transport.sendMail({
    from: "app@local.test",
    to: inbox.address,
    subject: "Account",
    text: "https://app.local.test/verify",
  });

  const email = await inbox.waitForMessage();
  await expect(inbox).toHaveDeliveredOnce({ quietMs: 100 });
  expect(email).toHaveRecipient(inbox.address);
  expect(email).toContainLink("/verify");
});

Espera antes de tomar una instantánea

toHaveDeliveredOnce() comprueba los mensajes que ya existen. El envío mediante el transporte proporcionado se resuelve después de que InboxTap acepte y almacene la transacción, por lo que la instantánea inmediata del ejemplo es válida. Cuando la aplicación encola el correo y responde antes, espera primero inbox.waitForMessage() y comprueba después el recuento de entregas.

quietMs puede detectar una entrega adicional durante ese intervalo explícito de observación, pero no demuestra que nunca vaya a producirse un reintento posterior. La idempotencia a largo plazo continúa siendo una garantía de la aplicación.

Ejecuta pruebas simultáneas con seguridad

Cada prueba recibe una dirección generada, incluso cuando los casos test.concurrent comparten el mismo servidor del archivo. El filtrado por destinatario mantiene independientes las lecturas de los buzones, así que no hace falta serializar las pruebas ni borrar el estado global entre ellas.

Dirige las reglas de fallos SMTP a inbox.address cuando las pruebas simultáneas compartan un recurso. Una regla sin destinatario para la siguiente transacción puede ser consumida legítimamente por la entrega que alcance DATA en primer lugar.

Ejercita las rutas de fallo en el límite SMTP

Usa inboxTap.server.faults para devolver un 451 transitorio, un 550 permanente, un retraso acotado, una compuerta de pausa o una desconexión por bloques. Las transacciones fallidas o desconectadas no generan mensajes parciales capturados.

InboxTap controla el comportamiento de entrega, no la capa de persistencia. Las pruebas todavía deben verificar el límite de reintentos, la espera incremental, la deduplicación, el estado visible para el usuario y los registros de negocio de la aplicación.

Delimita con cuidado los recopiladores de informes

El adaptador de comparadores de Vitest amplía un objeto expect en el sitio. No adjuntes recopiladores de informes distintos para cada prueba a un mismo expect compartido mientras haya pruebas simultáneas. Usa el expect ligado a la prueba que ofrece Vitest, registra mensajes de forma explícita o crea deliberadamente un único informe para la batería.