Un courrier de confirmation est la partie d’un parcours d’inscription qu’un test de navigateur ne peut pas mener seul. Quelque chose doit posséder une adresse, recevoir le message et rendre le code au test. Une API de boîte temporaire fait exactement cela : la suite demande à un service de créer une boîte en HTTP, lit ce qui arrive et jette la boîte quand le cas est terminé. Il n’y a pas de navigateur, pas de boîte humaine partagée et pas de copier-coller manuel.
Cet article porte sur le versant API de ce montage. Il ne s’agit pas de pointer votre application vers un point de réception local : c’est comment capturer les e-mails dans la CI, et les deux résolvent des problèmes différents. La capture locale prouve ce que votre application envoie. Une API de boîte prouve ce qui arrive réellement, par un vrai chemin de livraison, à une adresse que le test possède.
Pourquoi utiliser une API de boîte dans les tests ?
Parce que l’alternative est une vraie boîte humaine, ou rien.
Une boîte partagée est un mauvais montage. Plusieurs exécutions lisent la même boîte, les messages d’une exécution précédente y traînent encore, et l’adresse accumule un trafic que nul test n’a demandé. Chaque assertion doit alors deviner quel message appartient au cas courant, et c’est dans la devinette que naît l’instabilité.
Récolter l’interface web d’un fournisseur avec un navigateur est la deuxième mauvaise option. Elle fait dépendre le test d’un balisage qui change sans prévenir, d’un état de session et d’une connexion que la suite doit surveiller. Dès que le fournisseur restyle un bouton, une suite verte devient rouge pour une raison sans rapport avec le produit.
Une API de boîte supprime les deux problèmes. L’adresse est créée pour le cas, elle est vide par construction, et elle se lit via une interface stable que le test peut appeler directement. La suite ne se soucie plus de l’apparence du fournisseur, seulement de la tenue du contrat : créer, recevoir, lire, supprimer.
Il y a aussi un argument de vie privée. Une adresse créée par API ne représente personne. Ce n’est pas la boîte d’une personne, ce n’est pas un endroit où un vrai message pourrait atterrir, et elle est jetée avec l’exécution.
De quels points de terminaison un test a-t-il vraiment besoin ?
Une API de boîte peut exposer des dizaines de routes, mais un client de test a besoin de quatre opérations, et il aide de les nommer comme la suite les utilisera.
Créer renvoie une adresse et un identifiant. L’adresse est ce que l’application sous test est invitée à utiliser comme destinataire. L’identifiant, souvent un jeton, est ce dont le test se sert pour interroger cette boîte à chaque appel ultérieur. La suite doit traiter le couple comme un seul objet et ne jamais reconstruire l’identifiant à partir de l’adresse, car les fournisseurs sont libres de rendre les deux indépendants.
Lister renvoie des résumés plutôt que des corps : une entrée par message, avec un identifiant, l’expéditeur, l’objet et l’heure d’arrivée. C’est l’appel qu’une boucle d’interrogation doit utiliser, car il est bon marché et suffit à répondre à la seule question qui compte au début : quelque chose est-il déjà arrivé.
Lire renvoie un message en entier, parties texte et HTML comprises. C’est là que vit le code, et c’est l’appel à faire seulement après que lister a signalé une correspondance.
Vider retire les messages d’une boîte ou supprime la boîte entièrement. Un test en a besoin pour deux raisons : réinitialiser entre les tentatives sans créer une nouvelle adresse, et nettoyer quand le cas se termine.
Certains services ajoutent un point d’attente ou d’interrogation longue, qui garde la connexion jusqu’à l’arrivée d’un message ou l’échéance d’un délai. C’est pratique, mais un client doit pouvoir retomber sur lister, car l’appel d’attente est la partie la plus susceptible d’être limitée en débit.
Interroger le code sans instabilité
L’erreur la plus courante dans ce genre de test est la pause fixe. Un nombre constant de secondes est une supposition : trop court quand la livraison est lente, inutilement long quand elle est rapide, et faux dans les deux sens sur une machine de CI chargée. Remplacez-la par une boucle qui appelle lister, vérifie une correspondance et revient dès qu’elle en trouve une, avec un plafond qui fait échouer le test plutôt que suspendre le travail.
La correspondance est la seconde moitié du problème. Le message voulu est celui adressé à l’adresse créée par le cas et, si la boîte peut contenir plus d’un type de courrier, celui dont l’objet porte un fragment stable. Préférez la correspondance la plus récente, pour qu’une livraison dupliquée par une nouvelle tentative ne trompe pas la lecture. Ne prenez jamais le premier message sans condition ; sur une adresse réutilisée, c’est exactement ainsi qu’un ancien code finit validé.
L’extraction doit être ancrée. Un corps peut contenir un numéro de référence, un horodatage et un prix, et un analyseur qui prend la première suite de chiffres prendra parfois l’un d’eux au lieu du code. Cherchez la formulation qui introduit le code, lisez le code dans son voisinage, et échouez avec le corps attaché quand rien ne correspond.
Enfin, respectez la limite de renvoi. Un parcours de code n’autorise en général que quelques envois dans une courte fenêtre, et cette limite fait partie du comportement testé. Un test qui rappuie sur le bouton pour obtenir un code frais finira refusé et échouera pour la mauvaise raison. Réessayez en relisant la boîte, pas en déclenchant un autre message.
L’intégrer à une suite de bout en bout ou de CI
La forme propre est un montage. Avant le début du parcours, le montage crée une boîte et renvoie son adresse. Le test pilote l’application avec cette adresse. Une fois que l’application confirme avoir envoyé quelque chose, l’assertion lit la boîte et extrait le code. Quand le cas se termine, le montage supprime la boîte.
Gardez le client petit et injectable. Un module enveloppe les quatre appels ; le test dépend de ce module, jamais de HTTP brut dispersé dans la suite. Cela permet de substituer un double dans les tests unitaires et de pointer la même suite vers un autre fournisseur sans réécrire les assertions.
En CI, les identifiants appartiennent au coffre de secrets du travail, jamais au dépôt et jamais à une ligne de journal. Donnez à chaque travail ou à chaque worker parallèle sa propre boîte, et préfixez les adresses générées par quelque chose qui identifie l’exécution, afin qu’un message égaré soit attribuable à l’inspection. Réglez le délai d’expiration du client sous celui du travail lui-même, pour qu’une interrogation bloquée échoue avec un message clair plutôt qu’une annulation brutale.
Réessayez la lecture, pas tout le parcours. Si le code n’est pas encore arrivé, attendez et relisez ; relancer l’inscription produirait un second message et, avec lui, un second candidat pour l’assertion. Et tenez l’API de boîte hors des parcours de production : c’est de l’infrastructure de test, et une suite ne devrait jamais pouvoir envoyer à un vrai client depuis elle.
Le parcours autour du code, plutôt que la mécanique de sa lecture, est traité dans les tests de parcours de vérification d’e-mail, et l’étape d’analyse en particulier est le sujet de les tests OTP dans les suites de bout en bout.
Isolation et nettoyage
Une adresse par cas est la règle qui prévient la plupart des échecs entre tests. Elle supprime le besoin de raisonner sur le message qui appartient à qui, et elle fait disparaître la question de la fraîcheur, car la boîte n’a jamais reçu que le trafic d’un cas.
Le nettoyage doit être explicite et inconditionnel. Supprimez la boîte dans un démontage qui s’exécute que le cas passe ou échoue, pas seulement sur le chemin heureux. Se fier au seul délai de vie du fournisseur est une erreur : le message peut subsister assez longtemps pour être lu par une exécution ultérieure sur la même machine, et cette durée est une commodité, pas une garantie.
Si le nettoyage échoue, consignez-le et laissez la suite se terminer. Une erreur de nettoyage mérite d’être connue, mais elle n’est pas identique à un défaut de produit, et faire échouer l’exécution pour elle apprend à l’équipe à ignorer les échecs de démontage. Traitez tout ce que l’adresse a reçu comme des données de test : cela existe pour une assertion, cela ne doit être ni exporté ni partagé, et cela ne doit jamais être considéré comme le point de contact de quiconque.
Limites et réserves
Une API de boîte reste une dépendance tierce, et ses limites deviennent les vôtres. Les limites par minute peuvent refuser une rafale de créations issues d’une grande exécution parallèle. Les quotas plafonnent le nombre d’adresses existant en même temps. Les messages peuvent être retardés, et un message retardé ressemble exactement à un message manquant jusqu’à ce qu’il arrive.
Les domaines jetables sont aussi largement bloqués. Le domaine d’un fournisseur peut être refusé par le formulaire d’inscription même que vous testez, ce qui transforme un test légitime en échec déroutant. Quand cela arrive, la réponse n’est pas de faire une exception pour le fournisseur, mais de comprendre si le produit sous test rejette volontairement les adresses jetables, et de tester ce comportement délibérément.
Le résumé honnête est que l’API de boîte est le bon outil pour affirmer ce qui arrive. Pour affirmer ce que votre application émet, un point de réception local est plus rapide et sans quota. La plupart des suites matures utilisent les deux : la capture locale pour le gros des assertions, et une API de boîte uniquement là où le vrai chemin de livraison est la chose testée.
Étapes suivantes
Trouvez un test qui lit un code en interrogeant une boîte partagée, et remplacez-le par un montage qui crée une adresse fraîche depuis une API de boîte. Consignez l’adresse avec l’exécution, supprimez-la au démontage, et regardez combien de l’instabilité que vous aviez acceptée cesse simplement. Quand il vous faut une vraie boîte à la main, la page de courrier temporaire en crée une en un instant, et les adresses qu’elle remet sont un échafaudage pour une exécution, jamais une identité réelle.