Dredd resuelve un problema real, y lo resuelve limpiamente. Lo apuntas a una descripción de API, un documento OpenAPI o un archivo API Blueprint, y a un servidor en ejecución. Lee cada ejemplo en la descripción, envía la solicitud coincidente al backend en vivo y verifica que la respuesta real coincida con lo que prometió la especificación. Si tu especificación dice que GET /orders/{id} devuelve un 200 con un campo id y status, Dredd confirma que el servicio en ejecución realmente hace eso. La especificación deja de ser una documentación que se pudre silenciosamente y se convierte en una prueba que falla ruidosamente.
Esa idea, validar la implementación contra la descripción de la API, es la idea correcta. La divergencia entre lo que dice una especificación y lo que hace un servicio es uno de los errores silenciosos más costosos en el trabajo con APIs. Un equipo de frontend codifica contra el contrato documentado, el backend envía un cambio de nombre de campo, nadie actualiza la documentación y el fallo aparece en producción. Dredd detecta exactamente esa clase de fallos, y durante años ha sido la herramienta de código abierto de referencia para hacerlo desde la línea de comandos.
La fricción está en la configuración y el mantenimiento, no en el concepto. Dredd es una CLI de Node.js que necesita su propio archivo de configuración, un archivo de hooks en tu lenguaje preferido para cualquier caso más allá de los triviales, y un artefacto de especificación separado que mantienes manualmente junto con todo lo demás. Si quieres el mismo resultado que te da Dredd, una puerta de CI que falla cuando tu implementación ya no coincide con su contrato OpenAPI, sin montar una cadena de herramientas de hooks y sin mantener la especificación como un tercer archivo desconectado, Apidog está diseñado para ese flujo de trabajo. Mantiene la especificación, las pruebas y la validación en un solo proyecto, y ejecuta todo de forma headless desde una CLI de npm. Esta guía es justa sobre lo que Dredd hace bien y clara sobre dónde el camino integrado gana.
Qué hace bien Dredd
Primero, démosle a Dredd el mérito que se merece, porque se ha ganado su reputación.
Prueba la implementación, no un mock. Este es el núcleo. Muchas herramientas validan que tu archivo OpenAPI esté bien formado, o que un servidor mock se comporte. Dredd hace algo más difícil: golpea el backend real en ejecución y verifica que los bytes reales que regresan coincidan con los ejemplos documentados. Una ejecución exitosa de Dredd significa que tu servicio desplegado y tu especificación están de acuerdo ahora mismo, no en teoría.
Habla tanto API Blueprint como OpenAPI. Dredd creció junto a API Blueprint, el formato de descripción basado en markdown, y más tarde añadió soporte para OpenAPI 2 y 3. Si tienes un archivo Blueprint heredado o un documento Swagger, Dredd puede leerlo sin un paso de conversión.
Hooks agnósticos al lenguaje. Cuando el bucle predeterminado de solicitud y comparación no es suficiente, necesitas tokens de autenticación, necesitas sembrar una base de datos antes de una prueba, necesitas omitir una transacción, Dredd te permite escribir hooks. El manejador de hooks se ejecuta en Node por defecto, pero Dredd ofrece soporte de protocolo para hooks en Python, Ruby, Go, PHP, Rust y más. Tu equipo escribe la lógica de configuración en un lenguaje que ya conoce.
Es de código abierto y compatible con CI. Dredd se instala con npm install -g dredd, se ejecuta como un solo comando y sale con un código distinto de cero cuando una validación falla, por lo que cualquier sistema de CI puede bloquear una compilación basándose en ello. No hay cuenta SaaS, no hay precios por asiento, nada que firmar. Para un equipo que desea una verificación de contrato autoalojada y programable, esto es importante.
Nada de esto es de relleno. Dredd es una herramienta sólida con una función clara. La pregunta es si su modelo, tres artefactos separados y un archivo de hooks, coincide con cómo realmente quieres trabajar.
Dónde reside la fricción
Tres costes vienen incluidos con el modelo Dredd, y cuánto impactan depende de tu configuración.
La especificación es un tercer artefacto que mantienes manualmente. Dredd valida la implementación contra un archivo de descripción, lo cual es correcto, pero esa descripción generalmente vive separada de donde diseñas y pruebas la API. Editas manualmente un openapi.yaml, mantienes tus escenarios de prueba en otro lugar, y mantienes el servicio en ejecución en otro lugar. Dredd compara dos de esos tres entre sí. Mantener la especificación precisa sigue siendo una tarea manual, y una especificación que se ha desviado silenciosamente de la realidad produce una ejecución de Dredd que es verde y errónea.
Los hooks son código que escribes y mantienes. En el momento en que tu API necesita autenticación, ordenamiento o datos de prueba, el bucle basado en ejemplos deja de ser suficiente. Escribes un hooks.js (o un equivalente en Python o Ruby), lo conectas a través de dredd.yml, y ahora posees una segunda base de código cuyo único trabajo es hacer que la primera sea comprobable. Para una API simple de solo lectura, Dredd es casi libre de configuración. Para una API real con inicios de sesión y endpoints con estado, el archivo de hooks crece, y es código "pegamento" con otro nombre.
La cobertura basada en ejemplos tiene lagunas. Dredd prueba los ejemplos presentes en tu descripción. Si un endpoint tiene una respuesta de ejemplo documentada, eso es lo que se verifica. Los casos límite, las rutas de error y las reglas de validación que no están especificadas como ejemplos en la especificación no se ejercitan a menos que las añadas, expandiendo la especificación o escribiendo más hooks. La cobertura es tan buena como los ejemplos que mantengas, no mejor.
El camino integrado: especificación y pruebas en un solo proyecto
Aquí está la apuesta diferente que hace Apidog. La definición de la API no es un tercer archivo que sincronizas manualmente; es la fuente de verdad que vive en el mismo proyecto que las pruebas que la ejercitan y la validación que protege tu compilación. Cambia el esquema, y las pruebas ven la nueva forma. No hay un openapi.yaml separado a la deriva en un rincón del repositorio, y no hay un archivo de hooks entre la especificación y una prueba funcional.
Diseñas o importas la API una vez. Apidog lee OpenAPI 2 y 3, importa un documento Swagger y carga colecciones de Postman con un clic. Los endpoints, los esquemas de solicitud, los esquemas de respuesta y las respuestas de ejemplo se encuentran todos en un mismo proyecto. Si ya piensas primero en la especificación, esta es la misma disciplina que Dredd fomenta, solo que sin que la especificación sea un archivo suelto. La versión más profunda de ese flujo de trabajo reside en el desarrollo de API spec-first, y si quieres validar el propio documento de la especificación antes de ejecutar cualquier prueba, la validación de especificaciones OpenAPI cubre ese paso.
Construyes la validación contra esos esquemas reales. Cuando un escenario de prueba llama a GET /orders/{id}, afirmas la respuesta contra el esquema que Apidog ya tiene para ese endpoint, no contra un ejemplo copiado a mano. Ese es el chequeo de especificación contra implementación que realiza Dredd, con una diferencia: la especificación que se verifica es el mismo objeto a partir del cual diseñaste la API, por lo que no puede desincronizarse silenciosamente con tu suite de pruebas. Esto es prueba de contratos sin un tercer artefacto, y si quieres una visión más amplia de esa disciplina, el testing de contratos de API y el testing de contratos bidireccionales profundizan en ello.
La configuración que Dredd maneja con un archivo de hooks, tokens de autenticación, ordenamiento, sembrado, tú la manejas con scripts pre- y post-solicitud en JavaScript, que la mayoría de los desarrolladores web ya escriben. No hay una base de código de hooks separada conectada a través de un archivo de configuración. La lógica reside junto a la prueba a la que da soporte.
Instalación y ejecución de la CLI de Apidog
El corredor se publica en npm como apidog-cli. Si tienes Node.js, tienes todo lo que necesitas:
npm install -g apidog-cli
El binario es apidog, por lo que cada ejecución comienza con apidog run. Para ejecutar un escenario de prueba, pasas un token de acceso, el ID del escenario y el ID del entorno:
apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e 1629989 -r cli
No escribes esos IDs a mano. Abre el escenario de prueba en Apidog, ve a su pestaña CI/CD, elige la opción de línea de comandos y genera un token de acceso. Apidog construye el comando completo apidog run para ti con los IDs de escenario y entorno ya completados. Cópialo una vez y parametriza el token desde allí. Trata el token de acceso como una contraseña: almacénalo como un secreto en tu sistema de CI y referéncialo como $APIDOG_ACCESS_TOKEN, como lo hace cada ejemplo aquí.
Para ejecutar más de un escenario, apunta el corredor a una carpeta o a una suite de pruebas en lugar de un solo ID, y elige tus reportadores:
apidog run --access-token $APIDOG_ACCESS_TOKEN -f <folderId> -e 1629989 -r html,junit --out-dir ./test-reports
Esa bandera -r selecciona los reportadores. Apidog soporta cli para una salida legible en la terminal, html para un informe autocontenido que puedes archivar como un artefacto de construcción, junit para el XML que casi todos los paneles de CI analizan en un árbol de aprobado/fallido, y json para resultados estructurados en bruto. Si quieres una visita más profunda al corredor, ejecuta apidog run --help para ver la lista completa de banderas.
Comparación
| Dredd | Apidog | |
|---|---|---|
| Idea principal | Validar la implementación contra una descripción de API | Validar la implementación contra la especificación a partir de la cual fue diseñada |
| Entorno de ejecución | Node.js (npm install -g dredd) |
Node.js (npm install -g apidog-cli) |
| Formato de especificación | API Blueprint, OpenAPI 2/3 | OpenAPI 2/3, importación de Swagger, importación de Postman |
| Ubicación de la especificación | Archivo separado, mantenido manualmente | El mismo proyecto contra el que se ejecutan las pruebas |
| Lógica de configuración | Archivo de hooks (hooks.js, además de Python/Ruby/Go/etc.) |
JavaScript pre/post-solicitud, en la prueba |
| Autoría de pruebas | Ejemplos en la descripción | Editor visual contra esquemas reales |
| Cobertura | Tan buena como los ejemplos en la especificación | Asertos de esquema más escenarios personalizados |
| Reportadores | Integrados más complementos | cli, html, json, junit |
| Alojamiento | Autoalojado, código abierto | Proyecto alojado, la CLI se ejecuta en cualquier lugar |
Lee esa tabla honestamente. Si quieres una herramienta completamente autoalojada, de código abierto, sin cuenta, y tu equipo se siente cómodo manteniendo un archivo de hooks, el modelo de Dredd encaja perfectamente y cambiarlo por el mero hecho de hacerlo no te aporta nada. El argumento a favor del camino integrado es específico: estás cansado de que la especificación sea un tercer archivo que se desvía, no quieres ser dueño de una base de código de hooks, o quieres que el mismo proyecto maneje el diseño, las pruebas y la verificación del contrato juntos.
Integrándolo en CI
La CLI de Apidog sale con cero en caso de éxito y con un valor distinto de cero en caso de fallo, por lo que cualquier sistema de CI puede bloquear una compilación basándose en ello, exactamente como Dredd. Un trabajo mínimo de GitHub Actions necesita Node y un paso de ejecución:
name: api-contract-check
on: [push]
jobs:
test:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: '20'
- run: npm install -g apidog-cli
- run: apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e 1629989 -r cli,junit
env:
APIDOG_ACCESS_TOKEN: ${{ secrets.APIDOG_ACCESS_TOKEN }}
Esa es toda la pipeline. Un trabajo de Dredd se ve similar: instala la CLI, ejecuta un comando, pero también lo apuntas a tu archivo de especificación y a tu archivo de hooks, y mantienes ambos actualizados. La validación se ejecuta de la misma manera; la diferencia es cuántos artefactos mantienes para llegar a ese punto.
Si tu razón para recurrir a Dredd era realmente mantener una especificación y un servicio honestos entre sí, la misma lógica aparece en otras herramientas. Los equipos se enfrentan a esto con Swagger y Postman que se desvían, lo cual cubre el testing impulsado por OpenAPI contra la desviación de Swagger y Postman, y las tiendas Java lo enfrentan con Rest Assured, donde la historia de las alternativas rima: una herramienta fuerte cuyo modelo añade una capa que quizás no desees. También puedes manejar Apidog desde tu editor con la extensión de VS Code si prefieres no salir de tu IDE.
Preguntas frecuentes
¿Es Apidog un reemplazo directo para una configuración de Dredd? No, y no pretende serlo. No existe un conversor que lea tus archivos dredd.yml y hooks.js y emita escenarios de Apidog. Importas tu especificación OpenAPI y reconstruyes la validación en el editor visual. La ventaja es que dejas de mantener un archivo de hooks y una especificación suelta; el coste es una reconstrucción única. Si tienes una suite Dredd grande y madura que funciona, esa reconstrucción es una decisión real, no un regalo.
¿Apidog valida la implementación en vivo, como Dredd? Sí. La CLI envía solicitudes reales a tu servicio en ejecución y afirma las respuestas reales contra los esquemas de tu proyecto. Esa es la misma verificación de especificación contra implementación que realiza Dredd. La diferencia es que el esquema que se verifica es el que usaste para diseñar la API, por lo que no se desvía de tus pruebas.
¿Puedo seguir manejando la autenticación y la configuración de pruebas de la misma manera que me permiten los hooks de Dredd? Sí. Apidog soporta scripts pre-solicitud y post-solicitud en JavaScript, por lo que puedes obtener tokens de autenticación, sembrar datos, transformar cargas útiles o construir aserciones dinámicas en código. La lógica reside en el escenario que soporta, en lugar de en un archivo de hooks separado configurado a través de un archivo de configuración.
¿Dredd hace algo que Apidog no? Un par de cosas. Dredd es completamente autoalojado y de código abierto sin necesidad de cuenta, y lee API Blueprint, el formato de descripción basado en markdown más antiguo, de forma nativa. Si una herramienta completamente local y sin cuenta o un archivo Blueprint heredado son centrales para tu configuración, evalúa eso cuidadosamente antes de cambiar.
¿Qué formatos lee Apidog? OpenAPI 2 y 3, documentos Swagger y colecciones de Postman, todos importables en un solo proyecto. Si quieres entender primero las diferencias de formato, Swagger versus OpenAPI y la descripción general de la especificación OpenAPI los explican ambos.
En resumen
Dredd acertó con la idea central: la descripción de tu API debería ser algo contra lo que pruebas el servicio en ejecución, no un documento que se desvía. Si quieres una CLI autoalojada y de código abierto, y estás contento manteniendo un archivo de especificación y un archivo de hooks, Dredd es una buena elección y deberías seguir usándolo.
El camino integrado es para el caso en que ese mantenimiento es la parte que quieres eliminar. Apidog mantiene la especificación, las pruebas y la validación en un solo proyecto, por lo que el contrato que verificas es el mismo que diseñaste, y ejecuta todo desde apidog run sin necesidad de mantener una base de código de hooks. Descarga Apidog e importa tu archivo OpenAPI existente para ver la verificación de especificación contra implementación ejecutarse desde un solo comando.