Contract Testing de APIs y microservicios con Pact

El problema que resuelve

Con dos servicios, probar que se entienden es fácil: los levantás juntos y listo. Con quince servicios que se llaman entre sí, ese enfoque se desarma, y siempre por las mismas tres razones:

• Hay que levantar todo junto. Cada prueba necesita el resto del sistema corriendo, con sus bases de datos y sus dependencias.
• Es lenta y frágil. Cualquier servicio caído, cualquier dato inconsistente, cualquier lentitud de red hace fallar pruebas que no tenían nada que ver.
• Cuando falla, no dice quién rompió qué. Este es el peor de los tres: una prueba roja en un entorno compartido inicia una investigación entre equipos en lugar de señalar al responsable.

Y hay un problema anterior, más silencioso: el proveedor de una API no sabe quién usa qué. Cuando alguien quiere renombrar un campo, la pregunta «¿esto rompe a alguien?» no tiene respuesta, así que se elige entre no cambiar nada nunca o cambiar y esperar.

Qué es, con precisión

La expresión que hace todo el trabajo es «por separado». El contrato existe justamente para que cada lado pueda verificarse solo, en su propio pipeline, sin el otro corriendo. De ahí salen las tres ventajas que son el reverso exacto de los tres problemas anteriores: es rápido, no es frágil, y cuando falla se sabe qué lado incumplió.

Pact es la herramienta de código abierto más difundida para hacerlo. Es code-first: el contrato no se escribe en un documento aparte, se genera ejecutando los tests del consumidor.

Consumidor y proveedor

Dos términos y conviene fijarlos bien, porque todo lo demás depende de ellos:

• Consumidor: la aplicación que pide los datos. Un frontend, un servicio que llama a otro, un trabajo que lee de una cola.
• Proveedor: la aplicación que entrega los datos. Una API, un servicio, quien publica en la cola.

Pact usa estos términos y no «cliente» y «servidor» de forma deliberada: el vocabulario se aplica igual a la comunicación por mensajes, donde las etiquetas cliente-servidor no encajan. Un mismo servicio suele ser consumidor de unos y proveedor de otros al mismo tiempo, y va a tener contratos en los dos roles.

Por qué lo dirige el consumidor

Pact usa el enfoque dirigido por el consumidor: el contrato «se genera durante la ejecución de los tests automatizados del consumidor». No lo escribe quien publica la API, lo produce quien la usa.

La lógica es sólida: quien consume es el único que sabe qué necesita de verdad. Un proveedor que documenta su API describe todo lo que ofrece; un consumidor que genera un pacto documenta exactamente los campos que usa, ni uno más.

La documentación describe el enfoque como «contrato por ejemplo»: cada caso de prueba describe un par concreto de petición y respuesta que después se verifica, en lugar de una especificación abstracta.

Fase 1: en el consumidor

La documentación de Pact describe cuatro pasos, y el detalle importa porque explica por qué el resultado es confiable:

1. Se registran la petición y la respuesta esperadasUsando el lenguaje de Pact, se declara qué se va a pedir y qué se espera recibir. Ese registro se hace contra un servicio simulado.
2. El código del consumidor hace una petición realY acá está la clave: real, contra el proveedor simulado que crea el propio marco. No se simula la llamada: se ejecuta el código de tu cliente HTTP con toda su configuración.
3. El simulado compara y respondeCompara la petición que llegó con la esperada, y si coincide emite la respuesta declarada.
4. El consumidor confirma que la entendióEl test verifica que tu código procesó esa respuesta correctamente.

El marco exige que «los tests de Pact solo son exitosos si cada paso se completa sin error». Esa doble comprobación —tu código pide bien y entiende bien— es lo que evita el problema clásico de los mocks escritos a mano: un simulacro que devuelve lo que tu código espera, aunque el servicio real devuelva otra cosa.

Al terminar, «el marco de Pact genera un archivo de pacto que describe cada interacción». Ese archivo JSON es el contrato.

Fase 2: en el proveedor

La segunda fase invierte el flujo. Cada interacción del pacto se reproduce contra el proveedor real: «en la verificación del proveedor, cada petición se envía al proveedor, y la respuesta que genera se compara con la respuesta mínima esperada descrita en el test del consumidor».

Tres cosas que conviene notar de esta fase:

• El proveedor corre de verdad. Con su código, sus validaciones y su serialización. Lo que se simula, si hace falta, son sus dependencias.
• Corre en el pipeline del proveedor. No hace falta el consumidor: solo el archivo de pacto.
• Necesita estados previos. Si el pacto dice «pedido 42 existe y está pagado», el proveedor tiene que poder llegar a ese estado antes de responder. Pact llama a eso provider states, y es la parte que más trabajo de configuración lleva.

La respuesta mínima esperada

Este es el concepto más elegante del diseño y el que hay que entender para no usarlo mal. La verificación pasa cuando «cada petición genera una respuesta que contiene al menos los datos descritos en la respuesta mínima esperada».

Fijate que ese conjunto es exactamente el de los cambios que en producción romperían a alguien, y ninguno más. Por eso el contract testing no se convierte en un freno: la evolución compatible pasa sin ruido y solo se detiene lo que de verdad rompe.

El broker y «can-i-deploy»

Con los contratos generándose en un pipeline y verificándose en otro, aparece un problema de información: «los números de versión de todas las aplicaciones que se probaron juntas, y si las pruebas pasaron o fallaron» quedan repartidos entre muchas ejecuciones de CI.

El Pact Broker es «una aplicación para compartir contratos dirigidos por el consumidor y resultados de verificación». Reúne esos datos y permite determinar qué versiones de tus aplicaciones se pueden desplegar juntas de forma segura.

Su consecuencia más útil es un comando:

# Antes de desplegar, preguntar si esta versión es compatible
pact-broker can-i-deploy \
  --pacticipant NOMBRE_DEL_PROVEEDOR \
  --version VERSION_DEL_PROVEEDOR

Lo usan los dos lados: el proveedor antes de desplegar, para confirmar compatibilidad con los consumidores que ya están en el ambiente; y el consumidor antes de liberar su cambio. Es la diferencia entre desplegar con información y desplegar con esperanza.

El broker además versiona los contratos automáticamente y maneja etiquetas y ramas, que permiten marcar qué versión está en cada ambiente y comprobar compatibilidad hacia atrás entre varias versiones de consumidores y proveedores.

Contract testing y OpenAPI

Es la pregunta que aparece siempre, y no son alternativas: resuelven cosas distintas.

Lo habitual y sensato es tener las dos: la especificación como documentación y contrato de diseño, y los pactos como red de seguridad de lo que efectivamente se consume.

Qué no cubre

Prometer más de esto es la forma más común de que la iniciativa se abandone a los tres meses:

• No verifica la lógica de negocio. Comprueba que la respuesta tenga un campo total numérico, no que el total esté bien calculado. Eso son pruebas unitarias y funcionales.
• No verifica que los datos sean correctos. Solo su forma y sus tipos.
• No reemplaza todas las pruebas de punta a punta. Reemplaza a las que solo comprobaban que dos servicios se entendieran; conviene conservar unas pocas para los flujos críticos completos.
• No cubre rendimiento ni carga. Para eso, pruebas de rendimiento con k6 y Grafana.
• No sirve para APIs de terceros que no controlás. Nadie va a correr tu verificación en el pipeline de un proveedor externo. Ahí lo que sirve son pruebas de contrato contra su especificación y monitoreo.
• Tiene costo de adopción. Los provider states y la integración con CI llevan trabajo real. En un sistema con dos servicios, probablemente no valga la pena.

Errores frecuentes

• Escribir el pacto desde el proveedor. Pierde todo el sentido: vuelve a describir lo que se ofrece en lugar de lo que se usa.
• Declarar en el pacto campos que no se usan. Cada campo declarado es una restricción que el proveedor no va a poder cambiar. Declarar solo lo que consumís.
• Usar valores exactos donde alcanza el tipo. Si tu código solo necesita que id sea un número, declarar que vale exactamente 42 vuelve el contrato frágil sin ganar nada.
• Verificar contra un proveedor simulado. La fase 2 pierde todo su valor si no corre contra el servicio real.
• No publicar los pactos en un broker. Sin broker no hay can-i-deploy, y se pierde el beneficio principal.
• Prometer que reemplaza las pruebas de integración. Genera una expectativa que no se cumple y desprestigia la práctica.
• Adoptarlo en un sistema con dos servicios. El costo de configuración no se recupera; conviene cuando hay varios equipos desplegando por separado.

Preguntas frecuentes

Fuentes

Documentación oficial y material de la comunidad consultados para esta guía. Fecha de consulta: 27 de julio de 2026.

Aportes de la comunidad Underc0de

1. Underc0de, foro. El mundo de las pruebas de API, sección QA y Testing, 23 de julio de 2024.
2. Underc0de, foro. Testeo de APIs con Postman, por ANTRAX, 3 de octubre de 2021.
3. Underc0de, foro. Corriendo colecciones de APIs con Newman y reporte en HTML, por ANTRAX, 22 de marzo de 2022.

Documentación oficial

4. Pact. Documentación oficial. Definición de contract testing, roles de consumidor y proveedor, enfoque dirigido por el consumidor y «contrato por ejemplo», citados textualmente.
5. Pact. How Pact works. Los cuatro pasos de la fase del consumidor, la generación del archivo de pacto y la verificación contra la respuesta mínima esperada.
6. Pact. Pact Broker. Qué es el broker, el problema de información que resuelve, el comando can-i-deploy y el manejo de versiones, etiquetas y ramas.