Tester les emails avec Vitest et InboxTap

Utiliser l’adaptateur officiel de Vitest

Installez InboxTap, Nodemailer 9 et Vitest, puis étendez le test de base depuis inboxtap/fixtures/vitest. L’adaptateur démarre les écouteurs SMTP et HTTP sur des ports attribués par le système d’exploitation, vérifie son transport avant de rendre la main et ferme l’état de démarrage, partiel ou complet, à la fin du fichier.

Le paquet garde Vitest derrière un sous-chemin optionnel. Importer la racine d’InboxTap ou le SDK client ne charge ni Vitest ni Nodemailer dans les projets qui n’emploient pas cette configuration.

• Documentation Vitest sur les ressources et le contexte de test ↗

Associer les ressources et les assertions natives

La valeur inboxTap injectée n’est partagée que par les tests d’un même fichier. Son transport convient aux tests directs d’un modèle d’email, tandis qu’inboxTap.smtp peut configurer une instance de l’application qui doit exercer toute la frontière d’intégration.

Enregistrez l’adaptateur d’assertions auprès de l’objet expect de Vitest. Attendez toHaveDeliveredOnce(), car cette assertion peut observer une courte fenêtre bornée ; les assertions de destinataire et de lien sur un message restent synchrones.

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");
});

Attendre avant de prendre un instantané de livraison

toHaveDeliveredOnce() inspecte les messages déjà présents. L’envoi par le transport fourni ne se termine qu’après l’acceptation et le stockage de la transaction par InboxTap : l’instantané immédiat de l’exemple est donc valide. Lorsque l’application place l’email dans une file d’attente et rend la main plus tôt, attendez d’abord inbox.waitForMessage(), puis vérifiez le nombre de livraisons.

quietMs peut détecter une livraison supplémentaire pendant cette fenêtre d’observation explicite, mais ne prouve pas qu’aucune nouvelle tentative n’aura lieu plus tard. L’idempotence à long terme reste une assertion applicative.

Exécuter des tests simultanés en sécurité

Chaque test reçoit une adresse générée, même lorsque des cas test.concurrent partagent le même serveur propre au fichier. Le filtrage par destinataire sépare les lectures de boîte : nul besoin de sérialiser les tests ni de vider l’état global entre eux.

Ciblez les règles de panne SMTP sur inbox.address lorsque des tests simultanés partagent une configuration. Une règle non ciblée portant sur la prochaine transaction peut légitimement être consommée par la première livraison qui atteint DATA.

Exercer les chemins d’échec à la frontière SMTP

Utilisez inboxTap.server.faults pour renvoyer une erreur transitoire 451, une erreur permanente 550, un délai borné, une barrière de pause ou une déconnexion par bloc. Les transactions échouées ou déconnectées ne créent aucun message partiellement capturé.

InboxTap contrôle le comportement de livraison, pas la couche de persistance. Les tests doivent encore vérifier la limite de tentatives, le délai progressif, la déduplication, l’état présenté à l’utilisateur et les enregistrements métier de l’application.

Définir soigneusement la portée des collecteurs de rapport

L’adaptateur d’assertions Vitest étend un objet expect sur place. Ne rattachez pas différents collecteurs propres aux tests à un même expect partagé pendant une exécution simultanée. Utilisez l’expect lié au test fourni par Vitest, enregistrez explicitement les messages ou créez délibérément un seul rapport pour la suite.