Si mantienes un archivo OpenAPI pero tu servicio en ejecución se desvía lentamente de él, Specmatic está diseñado exactamente para esa brecha. Trata tu especificación como un contrato ejecutable, luego prueba un servicio real contra ella y ejecuta la misma especificación como un stub inteligente. Esta guía explica qué hace Specmatic, cómo las pruebas de contrato difieren de las pruebas basadas en ejemplos, y dónde encaja la herramienta, con una nota sobre cómo se compara con un enfoque de plataforma más amplio como las pruebas de contrato de API de Apidog. Para el formato de especificación subyacente, la Especificación OpenAPI es la fuente de verdad de la que lee Specmatic.
Qué es Specmatic
Specmatic es una herramienta de código abierto para el desarrollo impulsado por contratos. La idea central es sencilla: tu especificación de API es el contrato, y Specmatic hace que ese contrato sea ejecutable. Apúntalo a un archivo OpenAPI y podrá realizar dos tareas complementarias.
- Ejecutar la especificación como pruebas contra un servicio en vivo, verificando que el servicio cumpla con cada ruta, código de estado y esquema que la especificación promete.
- Ejecutar la especificación como un servidor stub, para que los consumidores puedan desarrollar contra un mock que responda exactamente como lo indica el contrato.
Ambas tareas leen el mismo archivo. No hay una "definición de prueba" y una "especificación" separadas para mantener sincronizadas, que es el objetivo principal. Specmatic también va más allá de OpenAPI. La versión 2.0 añadió GraphQL y gRPC, y soporta AsyncAPI para contratos de eventos estilo Kafka, además de formatos como WSDL y Avro. Sin embargo, para la mayoría de los equipos, el punto de entrada es un archivo YAML o JSON de OpenAPI simple.
Lo ejecutas desde la línea de comandos o una imagen de Docker, por lo que se integra en CI sin mucha ceremonia. La empresa detrás ofrece complementos comerciales, pero el motor de contratos en sí es gratuito y de código abierto.
Pruebas de contrato vs. pruebas basadas en ejemplos
Esta es la distinción que confunde a la mayoría de las personas, por lo que vale la pena ser preciso.
Las pruebas basadas en ejemplos son lo que haces en la mayoría de los clientes de API. Escribes una solicitud, afirmas la respuesta que obtuviste, tal vez verificas un código de estado y uno o dos campos. Cada prueba es un ejemplo escrito a mano. Si tu especificación tiene 40 endpoints, escribes y mantienes muchos ejemplos, y los huecos son fáciles de pasar por alto.
Las pruebas de contrato invierten el modelo. En lugar de afirmar ejemplos específicos, afirmas que el servicio coincide con el contrato. Specmatic lee el esquema y genera pruebas a partir de él. Verifica que las respuestas se ajusten a los tipos declarados, que los campos requeridos estén presentes, que los códigos de estado coincidan y que el servicio rechace solicitudes mal formadas de la manera que la especificación implica. No escribes las afirmaciones una por una. La especificación es la afirmación.
| Aspecto | Pruebas basadas en ejemplos | Pruebas de contrato con Specmatic |
|---|---|---|
| Fuente de verdad | Casos de prueba escritos a mano | La propia especificación OpenAPI |
| Qué mantienes | Cada solicitud y afirmación | La especificación, que de todos modos mantienes |
| Cobertura | Solo lo que recordaste escribir | Cada operación que declara la especificación |
| Detección de desviaciones | Manual | Automática cuando la especificación cambia |
| Fallo típico | Un ejemplo específico falló | El servicio ya no coincide con el contrato |
Hay un segundo eje que vale la pena mencionar. Las pruebas de contrato vienen en diferentes modalidades, y Specmatic se sitúa en una específica. Las pruebas de contrato impulsadas por el consumidor al estilo Pact hacen que los consumidores publiquen sus expectativas a un intermediario, y los proveedores las verifican. Specmatic, en cambio, realiza pruebas impulsadas por contrato: la especificación es el único contrato al que ambas partes se adhieren, y Specmatic valida al proveedor contra ella y simula al proveedor para los consumidores. No es un intermediario de Pact, y no gestiona los pactos publicados por el consumidor. Si deseas una visión más amplia, consulta este resumen de herramientas de mocking y pruebas de contrato de API.
Cómo funciona Specmatic
Puedes instalar la CLI directamente o descargar la imagen de Docker. Docker es la opción común en CI porque evita la configuración local del entorno de ejecución.
Ejecución de pruebas de contrato
El comando de prueba apunta a Specmatic hacia una especificación y un servicio en ejecución. Una ejecución local mínima se ve así.
# Native CLI
specmatic test api.yaml --testBaseURL=http://localhost:8080
# Docker
docker run -v "$(pwd):/usr/src/app" specmatic/specmatic \
test api.yaml --testBaseURL=http://host.docker.internal:8080
Specmatic lee api.yaml, genera solicitudes para las operaciones que describe, las envía a la URL base y valida cada respuesta contra el esquema. Una prueba fallida significa que el servicio y el contrato no concuerdan. Solucionas uno o el otro. Ese es el ciclo.
Ejecutar la especificación como un stub
El servidor stub es la otra mitad. Inícialo y Specmatic sirve respuestas que coinciden con el contrato, para que un front-end o un servicio descendente puedan construirse a partir de él antes de que exista el backend real.
specmatic stub api.yaml --port=9000
Por defecto, genera respuestas válidas según el esquema sobre la marcha. También puedes guardar ejemplos concretos en un directorio _examples junto a la especificación, y el stub los devolverá cuando una solicitud coincida. Esto te proporciona datos realistas y controlables sin tener que levantar un backend real. Si estás comparando opciones de stub y mock entre herramientas, el resumen de servidores mock y pruebas de contrato sitúa a Specmatic en contexto.
Specmatic también puede ayudarte a crear la especificación en primer lugar. Puede actuar como un proxy frente a un servicio existente, capturar tráfico real y generar un documento OpenAPI más archivos de ejemplo a partir de lo que ve. Esto es útil cuando tienes un servicio pero aún no tienes una especificación.
El modelo de especificación como contrato y stub
He aquí por qué es importante ejecutar un solo archivo tanto como prueba como stub. Cuando la especificación es el contrato, el lado de la prueba y el lado del stub nunca pueden estar en desacuerdo, porque leen el mismo documento.
- El equipo del proveedor ejecuta
specmatic testen CI. Si cambian la API sin actualizar la especificación, las pruebas de contrato fallan. - El equipo del consumidor ejecuta
specmatic stublocalmente. Desarrollan contra respuestas que están garantizadas para coincidir con el mismo contrato.
Así, la especificación se convierte en un acuerdo vivo, no en un documento obsoleto en el que nadie confía. Esta es la diferencia entre un stub y un mock más rico, y vale la pena entender las ideas subyacentes en API stubbing vs mocking antes de diseñar un flujo de trabajo en torno a ello.
Specmatic también añade la verificación de compatibilidad con versiones anteriores. El comando backward-compatibility-check inicia un stub de la nueva versión de una especificación, genera pruebas de la versión anterior y las ejecuta contra el nuevo stub. Si algo que solía funcionar ya no lo hace, lo descubres antes de lanzarlo. Eso es una fuerte salvaguarda para los microservicios que se despliegan de forma independiente, y es una variante de la idea más amplia cubierta en las pruebas de contrato bidireccionales.
Dónde encaja Specmatic
Specmatic se gana su lugar cuando estas condiciones son ciertas para tu equipo:
- Tu especificación OpenAPI (o AsyncAPI, GraphQL, gRPC) es real y razonablemente completa.
- Tienes equipos o servicios de proveedor y consumidor separados que necesitan mantenerse sincronizados.
- Quieres que la desviación de la especificación falle una compilación automáticamente, no que se detecte en una revisión.
- Te sientes cómodo con un flujo de trabajo centrado en la CLI y CI.
Es menos adecuado si no mantienes una especificación, si quieres un espacio de trabajo visual para diseñar y explorar APIs, o si quieres una única herramienta que también gestione la depuración ad-hoc, la documentación y la colaboración en equipo. Specmatic se centra en el motor de contratos y realiza ese trabajo de manera excelente.
Ese enfoque es también donde una plataforma como Apidog toma una forma diferente. Apidog está impulsado por esquemas de la misma manera: lee tu especificación OpenAPI, valida las respuestas contra el esquema y levanta un servidor mock desde tu esquema OpenAPI sin código. La diferencia honesta es el alcance. Specmatic es una herramienta de contrato nítida y nativa de CLI. Apidog integra diseño, pruebas, mocking y documentación en un solo espacio de trabajo con un editor visual, de modo que la especificación, las pruebas y el mock conviven y se mantienen sincronizados mientras trabajas. Apidog tampoco es un broker de contratos impulsado por el consumidor al estilo Pact, por lo que si tu equipo necesita específicamente un broker de pactos, ninguna de las dos herramientas lo es.
Si quieres generar pruebas ejecutables directamente desde una especificación dentro de ese tipo de espacio de trabajo, mira cómo Apidog maneja la generación de colecciones de pruebas de API a partir de especificaciones OpenAPI.
Preguntas frecuentes
¿Es Specmatic gratuito?
Sí. El motor de contratos principal es de código abierto y de uso gratuito desde la CLI o Docker. Existen ofertas comerciales a su alrededor, pero puedes ejecutar pruebas de contrato y servidores stub a partir de especificaciones OpenAPI sin pagar. Consulta el sitio oficial y GitHub para obtener detalles actuales sobre los niveles de pago.
¿Specmatic solo funciona con OpenAPI?
No. OpenAPI es el punto de entrada más común, pero Specmatic también soporta AsyncAPI para contratos basados en eventos, además de GraphQL y gRPC desde la versión 2.0, junto con formatos como WSDL y Avro. El modelo es el mismo en todos ellos: la especificación es el contrato ejecutable. Si eres nuevo en el formato, comienza con este tutorial de la Especificación OpenAPI.
¿Es Specmatic lo mismo que Pact?
No exactamente. Pact está impulsado por el consumidor: los consumidores publican expectativas a un broker y los proveedores las verifican. Specmatic está impulsado por el contrato: la especificación es el único contrato compartido, y Specmatic valida al proveedor contra ella mientras simula el proveedor para los consumidores. Ambos reducen las sorpresas de integración, pero organizan el contrato de manera diferente.
¿Puede Specmatic generar una especificación OpenAPI por mí?
Sí. Specmatic puede ejecutarse como un proxy delante de un servicio existente, capturar tráfico real de solicitudes y respuestas, y generar un documento OpenAPI más archivos de ejemplo a partir de él. Esto es útil cuando tienes un servicio en funcionamiento pero aún no tienes una especificación formal para probar.
Conclusión
Specmatic responde a un problema específico y real: mantener un servicio en ejecución honesto frente a la especificación OpenAPI que se supone que debe seguir. Al hacer que la especificación sea ejecutable, te proporciona pruebas de contrato y un stub coincidente desde un solo archivo, con verificaciones de compatibilidad con versiones anteriores. Si trabajas en la terminal y CI, y mantienes una especificación sólida, encaja perfectamente.
Si prefieres tener el contrato, las pruebas, el mock y la documentación en un solo espacio de trabajo visual que lea el mismo archivo OpenAPI, prueba Apidog. Valida las respuestas contra tu esquema, simula endpoints sin código y convierte las especificaciones en colecciones de pruebas ejecutables. Descarga Apidog para apuntarlo a tu especificación y ver el ciclo completo de diseño a prueba en un solo lugar.