Recevez les e-mails de vos tests, lisez‑les dans vos tests
Votre application envoie un e-mail à l'adresse d'une inbox Facteur, la boîte où arrivent les messages d'un de vos tests. Votre test le récupère par l'API, avec son code, ses liens, ses en-têtes et ses pièces jointes.
// Plusieurs critères, tous ou l'un d'eux (match).
const search = new URLSearchParams({
inbox: 'j3k9x2mq',
match: 'all',
sentTo: adresse,
subject: 'Votre facture',
since: debutDuTest,
wait: '20000', // répond dès que le message arrive
});
const auth = { authorization: 'Bearer ' + process.env.FACTEUR_API_KEY };
const { messages } = await (
await fetch('https://api.facteur.eu/v1/messages?' + search, { headers: auth })
).json();
// Le message lu en entier : rien n'est masqué.
const message = await (
await fetch('https://api.facteur.eu/v1/messages/' + messages[0].id, { headers: auth })
).json();
message.subject; // 'Votre facture de juillet'
message.htmlBody; // le corps HTML
message.textBody; // sa version texte
message.headers['message-id'];
// Extrait à la réception, pas par vos expressions régulières.
const [message] = messages;
message.otp; // '265279', le code le plus probable
message.codes; // tous les nombres de 4 à 8 chiffres
message.links; // les liens décodés, dans l'ordre du message
message.extract; // les valeurs définies sur l'inbox
// Le parcours continue avec le code.
await page.getByLabel('Code').fill(message.otp);
await page.getByRole('button', { name: 'Valider' }).click();
Du message reçu au test qui passe
Une adresse par test
*@<inbox>Tout ce qui précède l'arobase est libre. Un test qui écrit à inscription+run-42 et un autre à inscription+run-43 reçoivent chacun leur message, dans la même inbox. Chaque message garde l'adresse où il a été envoyé, et votre test filtre dessus.
Attendre le message en une requête
GET /messages?wait=La recherche accepte un délai d'attente : elle ne répond qu'à l'arrivée du message, cinq minutes au plus. Si rien n'arrive, elle répond une liste vide, pas une erreur. Votre test décide si c'est un échec.
Le code déjà extrait
message.otpLe champ otp porte le code à usage unique le plus probable. Le champ codes liste tous les nombres de 4 à 8 chiffres du message. Quand plusieurs nombres se disputent et qu'aucun mot n'annonce un code, Facteur laisse otp vide plutôt que de deviner.
Des liens sans échappement
message.linksUn lien écrit en HTML contient & là où l'adresse a un &. Facteur rend les liens décodés, dans l'ordre du message. Votre test passe le premier à son navigateur sans le retoucher.
Les pièces jointes
message.attachmentsChaque pièce jointe a son nom, sa taille et son empreinte SHA-256. Votre test compare l'empreinte à celle de son propre fichier, ou télécharge les octets par l'API. Selon l'offre et l'inbox, les octets peuvent ne pas être gardés : la pièce reste alors décrite.
Les en-têtes, pour retrouver votre test
message.headersAjoutez un en-tête comme X-Test-Id à l'e-mail que votre application envoie, et lisez-le dans le message, en minuscules. Un test retrouve ainsi l'e-mail déclenché par sa propre exécution.
Vos propres valeurs, sans expression régulière
message.extractPour un identifiant maison, vous sélectionnez la valeur dans un vrai message. Facteur en déduit comment retrouver cette valeur et l'applique aux nouveaux messages de l'inbox.
Lire ne coûte rien
Seul un message reçu et gardé compte dans le nombre de messages que comprend votre offre. Un test qui reçoit 3 e-mails et les relit 40 fois en consomme 3, pas 43. La seule limite des lectures est technique : 600 requêtes par minute et par clé d'API.
Suppression automatique
Chaque message est supprimé quand la durée de son offre est passée, avec son fichier brut et ses pièces jointes. La suppression passe toutes les heures et ne se désactive pas.
Cloisonnement par équipe
workspaceUn espace de travail regroupe des inboxes et les personnes qui y ont accès. Une clé d'API peut être limitée à certains espaces, et chaque inbox peut avoir son propre plafond de messages. La CI de l'équipe A ne lit pas les messages de l'équipe B, et ne vide pas son volume.
Deux façons d'y accéder
L'API REST couvre tout, et rien n'est à installer pour l'appeler. Reste le cas où c'est le message qui doit vous prévenir, plutôt que l'inverse.
API REST
Une API décrite en OpenAPI, avec sa référence publique et ses guides sur le portail des développeurs. L'attente se fait côté serveur et l'extraction à la réception : un test appelle la recherche de messages sans aucune dépendance. Les plugins Playwright et Cypress ne sont pas publiés, et les guides n'en ont pas besoin.
Webhooks
Un webhook préviendra votre serveur à chaque message gardé dans une inbox : un appel HTTP signé, qui porte de quoi lire le message par l'API, avec des réessais et le suivi de chaque envoi. La plateforme qui envoie les webhooks n'est pas encore ouverte : aucun webhook ne part aujourd'hui.
Ce que fait un test qui lit un e-mail
-
Étape 01
Lancez la recherche
Elle part avant l'envoi et attend. Elle porte l'inbox, l'adresse visée et la durée d'attente.
GET /messages inbox, sentTo, wait -
Étape 02
Déclenchez l'envoi
Votre test clique sur « S'inscrire ». L'application envoie son e-mail à l'adresse de ce test.
-
Étape 03
Lisez le code
La réponse arrive avec le message. Le test saisit le code ou ouvre le premier lien.
otp: 418302
Écrire le test
Deux guides donnent le fichier complet, pour Playwright et pour Cypress. Les plugins de Facteur pour ces deux outils ne sont pas publiés : les guides appellent l'API directement, avec une clé en lecture seule.