Una integración puede superar los tests unitarios y aun así fallar cuando el proveedor cambia un campo, revoca una credencial o responde de otra manera en su sandbox. Una buena estrategia combina comprobaciones locales deterministas, contratos explícitos y una pequeña cantidad de evidencia real bajo control. Ninguna capa demuestra por sí sola todo lo que hace falta saber.
Separa el código que controlas del comportamiento que pertenece a otra organización. Conviene que predominen los tests unitarios: tú decides el mapeo, la validación, los reintentos y la idempotencia. Las pruebas de contrato hacen explícitos los supuestos entre consumidor y proveedor. Después vienen las comprobaciones más amplias en un entorno sandbox y, al final, una sonda pequeña de producción para descubrir problemas de credenciales, rutas o configuración que los entornos de prueba no reproducen.
Un contrato no es una copia de todo el esquema del proveedor. Describe las interacciones que utiliza el consumidor: método, ruta, campos relevantes de la petición, estado y estructura mínima de respuesta. Las herramientas de contratos impulsados por el consumidor pueden generar esas expectativas desde sus pruebas y permitir que el proveedor las verifique contra su implementación. Elige reglas de coincidencia con intención: ejemplos exactos sirven para identificadores y enums; reglas flexibles pueden encajar con fechas o IDs generados.
El contrato no demuestra semántica de negocio, disponibilidad ni las necesidades de todos los consumidores. Comprueba compatibilidad con supuestos declarados. Trata sus cambios como cambios de API, publica versión y entorno, y exige que el proveedor verifique la versión antes del despliegue.
| Capa | Buena evidencia de | No demuestra |
|---|---|---|
| Unitaria | Transformaciones locales, reintentos y casos límite | Compatibilidad en la red o comportamiento remoto |
| Contrato | Compatibilidad de supuestos del cliente con un proveedor verificado | Disponibilidad, latencia o configuración real de la cuenta |
| Sandbox | Credenciales y peticiones representativas de extremo a extremo | Datos, límites, integraciones o comportamiento idénticos a producción |
| Sonda de producción | Alcance actual y una transacción segura y acotada | Todos los flujos, corrección a escala o ausencia de fallos ocultos |
Los sandboxes pueden omitir funciones, usar datos sintéticos o responder de otro modo a los límites de tráfico. Documenta esas diferencias y cubre localmente lo que puedas. Un resultado positivo en sandbox no justifica afirmar sin matices que “la integración está probada”. Registra el entorno, el alcance de las credenciales, los escenarios y las exclusiones conocidas.
En APIs externas, prueba timeouts, conexiones interrumpidas, límites de solicitudes, credenciales vencidas, payloads malformados, duplicados, bucles de paginación y éxitos parciales. Asegúrate de que las personas puedan observar el resultado adecuado: reintentos acotados, escrituras idempotentes, errores útiles y preservación de los datos originales. Los relojes y adaptadores de transporte inyectables vuelven estos escenarios deterministas.
Usa fixtures realistas sin información personal. Elimina tokens, identificadores y datos sensibles de los ejemplos versionados. Mantén los contratos lo bastante pequeños para que quien revisa entienda el compromiso.
Ejecuta pruebas unitarias y de contrato en cada cambio. Programa las suites de sandbox o ejecútalas antes del release cuando el entorno sea estable, en vez de bloquear cada pull request por una caída externa. Las comprobaciones controladas en producción deberían ser de solo lectura cuando sea posible, usar una cuenta dedicada de bajo privilegio y alertar por fallos sostenidos, no por un único timeout.
Distingue entre un test fallido y una dependencia externa no disponible. Informa claramente de las comprobaciones bloqueadas u omitidas, guarda secretos en el almacén de CI, limita su alcance y evita imprimir cabeceras o cuerpos en los logs.
Un equipo pequeño puede comenzar con pruebas de mapeo e idempotencia, añadir contratos para consumidores críticos, documentar el checklist de sandbox y monitorizar una lectura sintética importante en producción. Sigue la antigüedad de la verificación de contratos, el éxito del sandbox, la disponibilidad de la sonda y los incidentes causados por cambios de esquema. Son señales de confianza y operación, no una calificación universal.
Para profundizar, consulta la fiabilidad de webhooks, las claves de idempotencia y los límites de API.
La pirámide de pruebas de integración representa responsabilidades e incertidumbre. Mantén la mayoría de pruebas rápidas y deterministas, usa contratos para verificar compatibilidad, considera el sandbox como evidencia parcial y reserva producción para señales seguras y acotadas. No hace falta simular todo Internet en CI: hay que saber qué fallo puede detectar cada capa antes que el cliente.