28. Diagnóstico de fallas de integración

28.1 Introducción

Cuando falla una prueba unitaria, muchas veces la causa está cerca del código probado. En una prueba de integración, la causa puede estar en cualquiera de los componentes conectados o en la forma en que se comunican.

Diagnosticar una falla de integración requiere ordenar la investigación: revisar datos, contratos, configuración, dependencias, estado inicial, estado final y evidencias de ejecución.

En este tema veremos un método práctico para analizar fallas de integración sin convertir la investigación en una búsqueda desordenada.

28.2 Qué es diagnosticar una falla

Diagnosticar una falla significa encontrar qué ocurrió, dónde ocurrió y por qué ocurrió. No es suficiente decir “la prueba falló”. Necesitamos entender la causa para corregirla o ajustar la prueba si el problema está en el ambiente o en los datos.

Un buen diagnóstico responde:

• ¿Qué resultado se esperaba?
• ¿Qué resultado se obtuvo?
• ¿Qué componentes participaron?
• ¿Qué dato o comunicación fue incorrecta?
• ¿El problema está en código, contrato, configuración, datos o ambiente?
• ¿La falla es reproducible?

28.3 Primer paso: leer el objetivo de la prueba

Antes de investigar, conviene volver al objetivo del caso. Si no sabemos qué colaboración se estaba verificando, será difícil interpretar la falla.

Preguntas iniciales:

• ¿Qué integración estaba probando el caso?
• ¿Qué componentes estaban dentro del alcance?
• ¿Qué dependencias eran reales y cuáles simuladas?
• ¿Qué resultado esperado estaba definido?
• ¿Qué estado final debía quedar?

Muchas investigaciones se complican porque la prueba no expresa claramente su intención.

28.4 Comparar esperado contra obtenido

El diagnóstico comienza comparando resultado esperado y resultado obtenido. Esta diferencia guía la investigación.

Ejemplos:

• Se esperaba una orden pagada, pero quedó pendiente.
• Se esperaba un evento publicado, pero la cola está vacía.
• Se esperaba un error de validación, pero ocurrió un error técnico.
• Se esperaba que no cambiara el stock, pero se descontó.
• Se esperaba un archivo con registros, pero se generó vacío.

Cuanto más concreto sea el resultado esperado, más directa será esta comparación.

28.5 Verificar reproducibilidad

Una falla reproducible es más fácil de diagnosticar. Si la falla aparece solo algunas veces, puede indicar problemas de estado compartido, concurrencia, tiempo, ambiente o dependencias inestables.

Conviene probar:

• Ejecutar solo esa prueba.
• Ejecutarla varias veces.
• Ejecutarla dentro de toda la suite.
• Cambiar el orden de ejecución si la herramienta lo permite.
• Revisar si depende de datos residuales.

Si la prueba pasa sola y falla en conjunto, probablemente haya un problema de aislamiento.

28.6 Revisar estado inicial

Un estado inicial incorrecto puede explicar muchas fallas. Antes de culpar a la lógica, debemos confirmar que la prueba comenzó desde las condiciones esperadas.

Revisar:

• Datos necesarios existentes.
• Datos que no deberían existir.
• Colas vacías o preparadas.
• Archivos de entrada correctos.
• Servicios simulados configurados con la respuesta esperada.
• Cachés limpias si afectan el caso.

Una prueba puede fallar porque el escenario estaba mal preparado, no porque la integración real esté rota.

28.7 Revisar configuración

La configuración es una causa frecuente de fallas de integración. Una URL, credencial, puerto, cola o base de datos incorrecta puede romper todo el flujo.

Conviene verificar:

• Variables de entorno usadas.
• Cadena de conexión a base de datos.
• URL de servicios internos o externos.
• Credenciales de prueba.
• Nombre de colas, tópicos o buckets.
• Modo de ejecución del ambiente.

Si el código funcionaba y empezó a fallar sin cambios, la configuración debe revisarse temprano.

28.8 Revisar contratos

Una falla puede deberse a que productor y consumidor ya no coinciden en el contrato.

Señales de problema de contrato:

• Campo faltante.
• Nombre de campo cambiado.
• Tipo de dato diferente.
• Nuevo valor de estado no contemplado.
• Error con formato inesperado.
• Evento publicado con versión distinta.

Cuando la falla ocurre al interpretar una respuesta o mensaje, revisar el contrato suele ser más útil que revisar reglas internas.

28.9 Revisar transformación de datos

Los datos pueden ser correctos al entrar, pero transformarse mal entre capas o servicios. Esto ocurre con mapeos, conversiones, formatos y redondeos.

Revisar:

• Campos perdidos durante el mapeo.
• Fechas convertidas a otra zona horaria.
• Importes redondeados incorrectamente.
• Estados internos traducidos a valores externos.
• Valores nulos transformados en cadenas vacías o al revés.

Una buena forma de diagnosticar es seguir el dato paso a paso por los componentes involucrados.

28.10 Revisar dependencias simuladas

Si la prueba usa stubs, fakes o servicios simulados, también pueden ser la causa de la falla.

Preguntas útiles:

• ¿El doble está configurado para el escenario correcto?
• ¿Devuelve la respuesta esperada?
• ¿Valida la solicitud de forma compatible con el contrato?
• ¿Quedó estado residual de otra prueba?
• ¿Está desactualizado respecto del servicio real?

Una simulación mal configurada puede hacer fallar una prueba válida o esconder un defecto real.

28.11 Revisar estado final

El estado final muestra qué dejó la integración después de ejecutarse. Es una fuente clave para diagnosticar.

Puede incluir:

• Registros creados o modificados.
• Mensajes publicados o pendientes.
• Archivos generados.
• Estados internos de servicios simulados.
• Eventos de auditoría.
• Datos que no deberían haber cambiado.

Comparar el estado final con el esperado ayuda a ubicar qué paso del flujo se ejecutó y cuál no.

28.12 Clasificar la causa probable

Después de reunir evidencia, conviene clasificar la causa probable. Esto ordena la corrección.

28.13 Reducir el alcance para aislar

Si una prueba amplia falla y no es clara la causa, puede ser útil reducir el alcance temporalmente.

Por ejemplo:

• Probar solo servicio y repositorio.
• Probar solo repositorio y base de datos.
• Probar productor de evento sin consumidor.
• Probar consumidor con un mensaje preparado.
• Reemplazar una dependencia externa por simulación para aislar el problema.

Reducir el alcance no significa cambiar la cobertura final, sino usar pruebas más pequeñas para encontrar la causa.

28.14 No corregir a ciegas

Un error común es cambiar código o prueba sin entender la causa. Esto puede ocultar el problema real o crear una prueba menos valiosa.

Antes de corregir, conviene confirmar:

• Qué condición produjo la falla.
• Qué evidencia la demuestra.
• Qué componente debería comportarse distinto.
• Si el resultado esperado era correcto.
• Si la prueba estaba mal preparada.

Un buen diagnóstico evita cambios innecesarios y reduce regresiones futuras.

28.15 Ejemplo: evento no publicado

Supongamos que una prueba esperaba un evento de orden creada, pero la cola está vacía.

Diagnóstico posible:

• Confirmar que la orden se creó correctamente.
• Verificar si la regla indica publicar evento para ese estado.
• Revisar configuración de cola.
• Revisar si el evento fue publicado en otro canal.
• Revisar si la prueba limpió la cola después de publicar.
• Confirmar si el productor está habilitado en modo prueba.

La falla puede estar en código, configuración, datos del escenario o incluso en la propia prueba.

28.16 Ejemplo: stock incorrecto

Supongamos que una compra de 2 unidades con stock inicial 10 deja stock 7 en lugar de 8.

Posibles líneas de investigación:

• Verificar el stock inicial real antes de ejecutar.
• Buscar si otra prueba modificó el mismo producto.
• Revisar si el evento fue procesado dos veces.
• Confirmar que la cantidad solicitada era 2.
• Revisar si hubo reintento que duplicó descuento.
• Verificar transacciones y concurrencia.

Este tipo de falla muestra por qué estado inicial, aislamiento e idempotencia son importantes.

28.17 Errores comunes al diagnosticar

Durante el diagnóstico suelen aparecer errores como:

• Asumir que el código está mal sin revisar datos y ambiente.
• Cambiar la prueba para que pase sin entender el defecto.
• Ignorar fallas intermitentes.
• No comparar estado esperado contra estado obtenido.
• No revisar dependencias simuladas.
• No confirmar reproducibilidad.
• No registrar la causa encontrada para evitar repetir el análisis.

28.18 Lista de verificación

Para diagnosticar una falla de integración, podemos seguir esta lista:

• ¿Cuál era el objetivo de la prueba?
• ¿Qué resultado se esperaba y qué se obtuvo?
• ¿La falla es reproducible?
• ¿El estado inicial era correcto?
• ¿La configuración apunta al ambiente correcto?
• ¿Los contratos siguen siendo compatibles?
• ¿El estado final revela en qué paso falló el flujo?
• ¿La causa parece estar en código, datos, configuración, ambiente o prueba?

28.19 Qué debes recordar de este tema

• Diagnosticar es identificar qué ocurrió, dónde y por qué.
• La investigación debe partir del objetivo y resultado esperado de la prueba.
• Estado inicial, configuración, contratos y dependencias simuladas son causas frecuentes.
• Una falla intermitente suele indicar problemas de aislamiento, tiempo o ambiente.
• Reducir el alcance puede ayudar a aislar la causa.
• No conviene corregir a ciegas sin evidencia suficiente.

28.20 Conclusión

Las fallas de integración pueden tener muchas causas posibles. Un diagnóstico ordenado evita perder tiempo y permite corregir el problema correcto.

La clave es reunir evidencia, comparar esperado contra obtenido, revisar estado y contratos, y reducir la incertidumbre paso a paso.

En el próximo tema profundizaremos en logs, mensajes de error y evidencias para investigar problemas.