5. Errores típicos que aparecen al integrar módulos

5.1 Introducción

Cuando dos o más módulos se integran, pueden aparecer errores que no se detectan al probar cada parte de forma aislada. Esto ocurre porque la integración agrega comunicación, formatos de datos, configuraciones, dependencias, estados compartidos y tiempos de respuesta.

Conocer los errores típicos ayuda a diseñar mejores pruebas. Si sabemos qué suele fallar, podemos preparar escenarios que busquen esos problemas de manera intencional.

En este tema revisaremos fallas comunes al integrar módulos y veremos cómo pueden manifestarse en una aplicación real.

5.2 Errores de contrato

Un error de contrato ocurre cuando dos módulos no coinciden en el acuerdo que permite comunicarse. El contrato puede estar definido por parámetros, campos, tipos de datos, códigos de respuesta, nombres de columnas, mensajes o reglas de validación.

Ejemplos frecuentes:

• Un módulo envía el campo userId, pero el otro espera usuarioId.
• Un servicio devuelve una fecha como texto, pero el consumidor espera un objeto de fecha.
• Una respuesta deja de incluir un campo obligatorio.
• Una función empieza a devolver null en un caso que antes no lo hacía.
• Una API cambia un código de estado y el cliente no lo contempla.

Estos errores son especialmente peligrosos porque cada módulo puede parecer correcto por separado, pero fallar al conectarse.

5.3 Errores de formato de datos

Aunque los módulos intercambien los campos correctos, los datos pueden llegar con un formato inesperado. Esto ocurre mucho con fechas, importes, identificadores, números decimales, listas y estructuras anidadas.

Algunos ejemplos:

• Una fecha llega como 04/05/2026, pero el otro módulo espera 2026-05-04.
• Un importe usa coma decimal y otro módulo espera punto decimal.
• Un identificador numérico llega como texto.
• Una lista vacía llega como null.
• Un campo booleano llega como "true" en lugar de true.

Las pruebas de integración deben incluir datos representativos para revelar estas diferencias antes de que afecten operaciones reales.

5.4 Errores de configuración

Una integración puede fallar aunque el código esté bien, simplemente porque el ambiente está mal configurado. Este tipo de error es muy común al pasar de desarrollo local a pruebas, staging o producción.

Ejemplos habituales:

• La aplicación apunta a una base de datos incorrecta.
• Falta una variable de entorno.
• Una URL de servicio externo pertenece a otro ambiente.
• Un token o una credencial está vencido.
• Una cola de mensajes no existe o tiene otro nombre.
• El archivo de configuración no fue desplegado junto con la aplicación.

Las pruebas de integración ayudan a comprobar que las dependencias necesarias están disponibles y correctamente conectadas.

5.5 Errores de dependencia no disponible

Un módulo puede necesitar una base de datos, una API, una cola, un servidor de archivos o un servicio interno. Si esa dependencia no está disponible, la integración falla.

La dependencia puede no estar disponible por varias razones:

• El servicio está caído.
• La red no permite la conexión.
• El recurso no fue creado en el ambiente.
• La dependencia tarda demasiado en responder.
• La versión desplegada no es compatible con el consumidor.

Una buena prueba no solo detecta que la dependencia falta; también permite verificar si el sistema informa el problema de forma clara y mantiene un estado consistente.

5.6 Errores de orden de ejecución

Algunas integraciones dependen de que las operaciones ocurran en cierto orden. Si el orden cambia o se ejecuta una parte antes de tiempo, el resultado puede ser incorrecto.

Por ejemplo:

• Se intenta enviar una factura antes de guardar la venta.
• Se descuenta stock antes de validar que el pago fue aceptado.
• Un proceso lee registros antes de que otro termine de escribirlos.
• Se publica un evento sin que el estado principal haya quedado confirmado.

Estos errores suelen aparecer en flujos con varios pasos, especialmente si hay procesos asíncronos o eventos.

5.7 Errores de persistencia

Cuando una integración usa una base de datos o almacenamiento, pueden aparecer problemas al guardar, actualizar o consultar información.

Ejemplos comunes:

• La operación guarda datos incompletos.
• Una actualización modifica campos que no debería modificar.
• Una relación entre tablas queda inválida.
• Una transacción no se confirma.
• Una operación falla, pero deja datos intermedios.
• Una consulta no devuelve registros que sí existen.

Por eso muchas pruebas de integración no se limitan a observar la respuesta inmediata. También revisan el estado final que quedó guardado.

5.8 Errores de transacciones y consistencia

En operaciones complejas, varios cambios deben ocurrir como una unidad. Si una parte se completa y otra falla, el sistema puede quedar inconsistente.

Ejemplo: una compra crea una orden, descuenta stock y registra un pago. Si se descuenta stock pero la orden no se crea, el sistema queda en un estado incorrecto.

Las pruebas de integración deben verificar qué ocurre cuando una operación intermedia falla:

• ¿Se revierten los cambios anteriores?
• ¿Queda registrada la falla?
• ¿El usuario recibe una respuesta comprensible?
• ¿El sistema evita duplicados al reintentar?

5.9 Errores de manejo de nulos y datos faltantes

Los datos faltantes son una causa frecuente de fallas de integración. Un módulo puede asumir que un campo siempre existe, pero otro módulo puede omitirlo en ciertos casos.

Ejemplos:

• Un usuario no tiene teléfono y el módulo de notificaciones lo requiere.
• Una dirección no tiene código postal y el módulo de envíos falla.
• Una respuesta externa no incluye descripción del error.
• Un cálculo recibe una lista vacía y no sabe cómo procesarla.

Una prueba de integración debe incluir casos con datos completos, datos opcionales ausentes y datos inválidos para comprobar que el sistema responde correctamente.

5.10 Errores de interpretación de reglas de negocio

Dos módulos pueden usar la misma palabra con significados distintos. Esto genera errores difíciles de detectar porque no siempre se manifiestan como una excepción técnica.

Por ejemplo:

• Un módulo considera “cliente activo” a quien tiene cuenta habilitada; otro lo considera activo solo si hizo una compra reciente.
• Un servicio interpreta “pedido cancelado” como una operación final; otro permite reactivarlo.
• Un módulo calcula descuentos antes de impuestos y otro después de impuestos.

Las pruebas de integración deben validar reglas compartidas con ejemplos concretos, especialmente cuando intervienen conceptos importantes del negocio.

5.11 Errores de tiempo de respuesta

Una integración puede funcionar en condiciones ideales, pero fallar cuando una dependencia responde lento. Esto puede producir timeouts, reintentos innecesarios, operaciones duplicadas o respuestas incompletas.

Conviene probar situaciones como:

• Respuesta lenta de un servicio externo.
• Base de datos con consultas más pesadas de lo esperado.
• Proceso asíncrono que tarda en consumir un mensaje.
• Timeout mal configurado para una operación crítica.

No se trata todavía de hacer pruebas de rendimiento profundas, sino de comprobar que la integración se comporta bien frente a demoras razonables o esperadas.

5.12 Errores en procesos asíncronos

Las integraciones asíncronas agregan desafíos porque el resultado no aparece de inmediato. Un componente publica un mensaje o evento y otro lo procesa más tarde.

Errores típicos en este tipo de integración:

• El mensaje se publica en la cola incorrecta.
• El consumidor no reconoce el formato del mensaje.
• El mensaje se procesa dos veces.
• El mensaje se pierde si ocurre un error intermedio.
• El estado final se verifica antes de que el proceso haya terminado.

Estas pruebas necesitan mecanismos claros para esperar el resultado y evitar dependencias frágiles basadas solo en pausas arbitrarias.

5.13 Errores de concurrencia

La concurrencia aparece cuando varias operaciones ocurren al mismo tiempo o casi al mismo tiempo. En integración, esto puede generar problemas de estado compartido.

Ejemplos:

• Dos compras descuentan el último producto disponible.
• Dos procesos actualizan el mismo registro y uno pisa cambios del otro.
• Una lectura ocurre mientras otra operación todavía no terminó de escribir.
• Un proceso intenta crear dos veces el mismo recurso.

No todas las pruebas de integración deben cubrir concurrencia, pero los flujos críticos con datos compartidos merecen especial atención.

5.14 Errores de limpieza entre pruebas

Las pruebas de integración suelen usar datos, archivos, bases de datos o colas. Si una prueba deja residuos, puede afectar a otra prueba posterior.

Señales de este problema:

• Una prueba pasa cuando se ejecuta sola, pero falla al ejecutarse con toda la suite.
• El resultado depende del orden de ejecución.
• Aparecen datos duplicados de ejecuciones anteriores.
• Una cola contiene mensajes viejos.
• Un archivo temporal no fue eliminado.

El aislamiento y la limpieza son fundamentales para que las pruebas de integración sean confiables.

5.15 Ejemplo integrador de fallas combinadas

Supongamos que un sistema registra una venta y envía una notificación. En una prueba de integración podrían aparecer varias fallas:

5.16 Qué debes recordar de este tema

• Muchos errores de integración no aparecen en pruebas unitarias.
• Los contratos, formatos, configuraciones y dependencias son fuentes frecuentes de fallas.
• La persistencia y las transacciones deben verificarse observando el estado final del sistema.
• Los procesos asíncronos y concurrentes requieren cuidados especiales.
• Una prueba de integración confiable necesita datos controlados y limpieza adecuada.
• Conocer los errores típicos ayuda a diseñar mejores escenarios de prueba.

5.17 Conclusión

Los errores de integración suelen aparecer en los puntos donde los componentes se encuentran: interfaces, datos, contratos, configuración, persistencia y dependencias. Por eso son errores que pueden pasar inadvertidos si solo se prueban piezas aisladas.

El objetivo de las pruebas de integración es exponer esos problemas con escenarios claros y evidencia útil para diagnosticarlos.

En el próximo tema estudiaremos con más detalle las interfaces, los contratos y las responsabilidades entre componentes, porque allí se definen muchas de las reglas que una integración debe respetar.