Cómo probar enlaces mágicos de principio a fin

Define el contrato antes de la prueba

Anota el remitente esperado, la familia de asuntos, el origen y la ruta de retorno, la caducidad, el comportamiento de registro y el destino posterior al acceso. Un proveedor puede llamar enlace mágico a varios mecanismos sin contraseña, pero la aplicación sigue siendo responsable de la URL exacta y de la política de cuentas.

Decide si una dirección desconocida puede crear una cuenta. Por ejemplo, el complemento de enlace mágico de Better Auth permite el registro de forma predeterminada salvo que se active disableSignUp. La prueba debe codificar la decisión del producto y no heredar por accidente el valor predeterminado de un proveedor.

• Comportamiento de los enlaces mágicos en Better Auth ↗
• Comportamiento del correo sin contraseña en Supabase ↗

Usa un destinatario nuevo en cada caso

Crea el buzón de InboxTap dentro de la prueba e introduce inbox.address en el formulario real de acceso o en la solicitud de API. El destinatario generado permite que pruebas simultáneas compartan un servidor de captura mientras cada lectura permanece filtrada por su propio sobre SMTP.

Evita un buzón para toda la batería y no borres todos los mensajes en beforeEach. La limpieza global crea condiciones de carrera, mientras que una dirección única conserva las pruebas necesarias para diagnosticar una redirección fallida o una entrega duplicada.

Extrae y valida antes de navegar

waitForLink() busca enlaces HTTP o HTTPS en el texto y el HTML capturados y puede exigir un fragmento estable de la ruta. Las plantillas suelen contener URL de asistencia, privacidad, logotipos y cancelación de suscripción, por lo que un filtro contains impide que la prueba siga el primer enlace no relacionado.

Trata el valor devuelto como una credencial. Analízalo con URL, compara el origen esperado completo y la ruta de retorno antes de navegar. No uses una comprobación imprecisa del sufijo del host, no imprimas la cadena de consulta ni incluyas el token en el título de la prueba.

const rawUrl = await inbox.waitForLink({
  contains: "/auth/callback",
  timeoutMs: 20_000,
});

const url = new URL(rawUrl);
expect(url.origin).toBe(appOrigin);
expect(url.pathname).toBe("/auth/callback");

await page.goto(url.href);

Comprueba la sesión, no solo la página

Después de abrir el enlace, verifica la URL final y un indicador respaldado por el servidor de la identidad autenticada. Un mensaje visible de éxito puede pasar aunque sean incorrectos la cookie de sesión, la identidad del usuario o el estado de autorización.

Comprueba también la redirección prevista y si la dirección de correo quedó verificada cuando el proveedor de autenticación combina la prueba de propiedad con la verificación. Esos resultados pertenecen a la comprobación de la aplicación; InboxTap solo demuestra qué cruzó SMTP.

Cubre la reutilización, la caducidad y el destinatario incorrecto

Canjea la misma URL por segunda vez y comprueba el comportamiento configurado de uso único. Ejercita la caducidad con el reloj admitido por el proveedor o con una configuración de prueba breve, no con una espera sin límite. Un token mal formado o modificado debe fallar sin crear una sesión.

Si el producto vincula un enlace a un correo o a una transacción pendiente, demuestra que no puede autenticar otra cuenta. No intentes probarlo cambiando únicamente las direcciones de InboxTap; realiza la comprobación sobre la sesión y la identidad almacenada por la aplicación.

• Un enlace válido solo establece la cuenta y la redirección esperadas.
• Un token reutilizado, caducado o modificado se rechaza.
• Las páginas de error y los registros no muestran el valor secreto.

Mantén las pruebas libres de tokens

Los diagnósticos de los comparadores de InboxTap no incluyen cuerpos ni valores de URL con tokens. Los informes eliminan superficies de secretos habituales y seudonimizan direcciones, pero esa protección no ofrece garantías absolutas. Revisa cada artefacto antes de compartirlo fuera del entorno de pruebas.

Prefiere comprobaciones sobre el origen, la ruta, la presencia de parámetros y el estado final de la aplicación. Evita instantáneas del correo sin procesar, de la barra de direcciones del navegador o del enlace capturado completo cuando una comprobación estructural menor demuestre lo mismo.