Pruebas de correo con Cypress e InboxTap

Respeta el límite entre el navegador y Node

Crea InboxTapClient en cypress.config.ts, dentro del proceso de Node de Cypress. Registra las tareas en setupNodeEvents y llámalas después desde la prueba para crear un destinatario y esperar un valor capturado.

No importes inboxtap/client directamente en una prueba del navegador. Mantener el acceso de red en el proceso de tareas también evita que la API local necesite CORS o exponerse a la página examinada.

Registra tareas pequeñas y serializables

Devuelve cadenas simples, como la dirección generada, la URL capturada o el OTP. Cypress serializa todos los argumentos y resultados de las tareas, así que pasa los filtros de asunto y los patrones de expresiones regulares como cadenas, no como objetos RegExp, funciones ni instancias de clases.

El controlador de una tarea debe devolver un valor o una promesa que se resuelva con uno. Cypress interpreta undefined como una tarea no controlada; devuelve null de forma explícita en una orden sin resultado.

import { defineConfig } from "cypress";
import { InboxTapClient, TestInbox } from "inboxtap/client";

const inboxTap = new InboxTapClient();

interface LinkArgs {
  to: string;
  subject?: string;
  contains?: string;
  timeoutMs?: number;
}

export default defineConfig({
  e2e: {
    setupNodeEvents(on) {
      on("task", {
        "inboxtap:createInbox": async (alias: string) =>
          (await inboxTap.createInbox({ alias })).address,

        "inboxtap:waitForLink": ({ to, ...options }: LinkArgs) =>
          new TestInbox(inboxTap, to).waitForLink(options),
      });
    },
  },
});

• Documentación de cy.task() de Cypress ↗

Crea una dirección por prueba

Llama a la tarea createInbox dentro de cada prueba e introduce esa dirección exacta en la aplicación. Las tareas de espera posteriores reconstruyen un TestInbox a partir de la dirección y aplican el filtrado por destinatario en el servidor.

Un destinatario nuevo es más fiable que vaciar un buzón compartido en beforeEach. Conserva las pruebas útiles para el diagnóstico e impide que las ejecuciones paralelas eliminen o lean mensajes ajenos.

Coordina los dos tiempos límite

El ayudante de espera de InboxTap tiene su propio timeoutMs, mientras que cy.task() dispone de un tiempo límite de orden de Cypress. Concede al tiempo exterior de Cypress un margen algo mayor que a la espera de InboxTap. Si la entrega falla, la tarea se rechazará con el contexto específico del correo en vez de que Cypress lo sustituya por un tiempo límite genérico.

Mantén ambas esperas acotadas. Una prueba lenta debe fallar con contexto suficiente para saber si la aplicación omitió el envío, usó un puerto SMTP incorrecto o envió a otro destinatario.

Elige entre el SDK y HTTP directo

cy.request() puede acceder a la API HTTP de loopback de InboxTap mediante el proxy de Cypress en Node y basta para comprobar un pequeño endpoint. Las tareas del SDK suelen ser preferibles porque TestInbox examina mensajes existentes y recién llegados, filtra por destinatario y extrae enlaces o códigos.

Elijas el enfoque que elijas, mantén InboxTap enlazado a loopback e inícialo junto con la aplicación antes de que comience Cypress. La integración está pensada para procesos locales y de CI en el mismo ejecutor, no para exponer un servicio de buzón sin autenticación.