Dredd résout un problème réel, et il le fait proprement. Vous le dirigez vers une description d'API, un document OpenAPI ou un fichier API Blueprint, et vers un serveur en fonctionnement. Il lit chaque exemple dans la description, envoie la requête correspondante au backend en direct et vérifie que la réponse réelle correspond à ce que la spécification avait promis. Si votre spécification indique que `GET /orders/{id}` renvoie un `200` avec un champ `id` et un champ `status`, Dredd confirme que le service en cours d'exécution fait réellement cela. La spécification cesse d'être une documentation qui se dégrade silencieusement et devient un test qui échoue bruyamment.
Cette idée, valider l'implémentation par rapport à la description de l'API, est la bonne. Le décalage entre ce qu'une spécification dit et ce qu'un service fait est l'un des bugs silencieux les plus coûteux dans le travail d'API. Une équipe frontend code en fonction du contrat documenté, le backend effectue un renommage de champ, personne ne met à jour la documentation, et la rupture apparaît en production. Dredd détecte exactement cette catégorie d'échecs, et pendant des années, il a été l'outil open-source de référence pour le faire depuis la ligne de commande.
La friction réside dans la configuration et la maintenance, pas dans le concept. Dredd est une CLI Node.js qui nécessite son propre fichier de configuration, un fichier de hooks dans votre langage de choix pour les cas non triviaux, et un artefact de spécification séparé que vous maintenez à la main à côté de tout le reste. Si vous voulez le même résultat que Dredd vous offre, un garde-fou de CI qui échoue lorsque votre implémentation ne correspond plus à son contrat OpenAPI, sans mettre en place une chaîne d'outils de hooks et sans conserver la spécification comme un troisième fichier déconnecté, Apidog est conçu pour ce flux de travail. Il maintient la spécification, les tests et la validation dans un seul projet, et exécute le tout en mode headless depuis une CLI npm. Ce guide est objectif sur ce que Dredd fait bien, et clair sur les avantages du chemin intégré.
Ce que Dredd fait bien
Rendons d'abord à Dredd ce qui lui est dû, car il a gagné sa réputation.
Il teste l'implémentation, pas un mock. C'est le point essentiel. De nombreux outils valident que votre fichier OpenAPI est bien formé, ou qu'un serveur mock se comporte correctement. Dredd fait quelque chose de plus difficile : il interroge le backend réel en fonctionnement et vérifie les octets réels qui reviennent par rapport aux exemples documentés. Un passage réussi de Dredd signifie que votre service déployé et votre spécification sont en accord dès maintenant, pas en théorie.
Il prend en charge à la fois API Blueprint et OpenAPI. Dredd s'est développé aux côtés d'API Blueprint, le format de description basé sur Markdown, et a ensuite ajouté la prise en charge d'OpenAPI 2 et 3. Si vous avez un fichier Blueprint hérité ou un document Swagger, Dredd peut le lire sans étape de conversion.
Hooks agnostiques au langage. Lorsque la boucle de requête et de comparaison par défaut n'est pas suffisante, que vous avez besoin de jetons d'authentification, d'initialiser une base de données avant un test, ou de sauter une transaction, Dredd vous permet d'écrire des hooks. Le gestionnaire de hooks s'exécute en Node par défaut, mais Dredd fournit un support protocolaire pour les hooks en Python, Ruby, Go, PHP, Rust, et plus encore. Votre équipe écrit la logique de configuration dans un langage qu'elle connaît déjà.
Il est open source et compatible CI. Dredd s'installe avec `npm install -g dredd`, s'exécute comme une seule commande et sort avec un code non nul lorsqu'une validation échoue, de sorte que tout système de CI peut bloquer une construction en se basant dessus. Il n'y a pas de compte SaaS, pas de tarification par siège, rien à signer. Pour une équipe qui souhaite une vérification de contrat auto-hébergée et scriptable, cela compte.
Rien de tout cela n'est superflu. Dredd est un outil solide avec un objectif clair. La question est de savoir si son modèle, trois artefacts distincts et un fichier de hooks, correspond à la façon dont vous souhaitez réellement travailler.
Où réside la friction
Trois coûts sont associés au modèle Dredd, et leur impact dépend de votre configuration.
La spécification est un troisième artefact que vous maintenez à la main. Dredd valide l'implémentation par rapport à un fichier de description, ce qui est tout à fait correct, mais cette description vit généralement séparément de l'endroit où vous concevez et testez l'API. Vous modifiez manuellement un `openapi.yaml`, vous conservez vos scénarios de test ailleurs, et vous conservez le service en cours d'exécution encore ailleurs. Dredd vérifie deux de ces trois éléments l'un par rapport à l'autre. Maintenir la spécification elle-même précise reste une tâche manuelle, et une spécification qui s'est discrètement éloignée de la réalité produit une exécution Dredd qui est verte (réussie) et fausse.
Les hooks sont du code que vous écrivez et maintenez. Dès que votre API a besoin d'authentification, d'ordonnancement ou de données de test, la boucle basée sur les exemples ne suffit plus. Vous écrivez un `hooks.js` (ou un équivalent Python ou Ruby), le connectez via `dredd.yml`, et vous possédez maintenant une deuxième base de code dont le seul travail est de rendre la première testable. Pour une API simple en lecture seule, Dredd est presque sans configuration. Pour une API réelle avec des connexions et des points de terminaison à état, le fichier de hooks grossit, et c'est du code de « collage » sous un autre nom.
La couverture basée sur les exemples présente des lacunes. Dredd teste les exemples présents dans votre description. Si un point de terminaison a une réponse d'exemple documentée, c'est ce qui est vérifié. Les cas limites, les chemins d'erreur et les règles de validation qui ne sont pas explicitement définis comme des exemples dans la spécification ne sont pas testés à moins que vous ne les ajoutiez, en étendant la spécification ou en écrivant plus de hooks. La couverture est exactement aussi bonne que les exemples que vous maintenez, sans être meilleure.
La voie intégrée : spécification et tests dans un seul projet
Voici le pari différent qu'Apidog fait. La définition de l'API n'est pas un troisième fichier que vous synchronisez à la main ; c'est la source de vérité qui vit dans le même projet que les tests qui l'exercent et la validation qui garde votre build. Modifiez le schéma, et les tests voient la nouvelle forme. Il n'y a pas de `openapi.yaml` séparé qui dérive dans un coin du dépôt, et pas de fichier de hooks se dressant entre la spécification et un test fonctionnel.
Vous concevez ou importez l'API une seule fois. Apidog lit OpenAPI 2 et 3, importe un document Swagger, et intègre les collections Postman en un clic. Les points de terminaison, les schémas de requête, les schémas de réponse et les exemples de réponses se trouvent tous dans un seul projet. Si vous pensez déjà « spec-first », c'est la même discipline que Dredd encourage, juste sans que la spécification soit un fichier libre. La version plus approfondie de ce flux de travail se trouve dans le développement d'API spec-first, et si vous souhaitez valider le document de spécification lui-même avant toute exécution de test, la validation des spécifications OpenAPI couvre cette étape.
Vous construisez la validation par rapport à ces schémas réels. Lorsqu'un scénario de test appelle `GET /orders/{id}`, vous affirmez la réponse par rapport au schéma qu'Apidog détient déjà pour ce point de terminaison, et non par rapport à un exemple copié à la main. C'est la vérification spécification-versus-implémentation que Dredd effectue, avec une différence : la spécification vérifiée est le même objet à partir duquel vous avez conçu l'API, de sorte qu'elle ne peut pas se désynchroniser silencieusement de votre suite de tests. C'est le test de contrat sans un troisième artefact, et si vous voulez une vue d'ensemble plus large de cette discipline, le test de contrat d'API et le test de contrat bidirectionnel approfondissent tous deux le sujet.
La configuration que Dredd gère avec un fichier de hooks, les jetons d'authentification, l'ordonnancement, l'amorçage (seeding), vous les gérez avec des scripts pré- et post-requête en JavaScript, que la plupart des développeurs web écrivent déjà. Pas de base de code de hooks séparée câblée via un fichier de configuration. La logique vit à côté du test qu'elle prend en charge.
Installation et exécution de l'interface CLI Apidog
Le runner est publié sur npm sous le nom `apidog-cli`. Si vous avez Node.js, vous avez tout ce dont vous avez besoin :
npm install -g apidog-cli
Le binaire est `apidog`, donc chaque exécution commence par `apidog run`. Pour exécuter un scénario de test, vous passez un jeton d'accès, l'ID du scénario et l'ID de l'environnement :
apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e 1629989 -r cli
Vous ne tapez pas ces ID à la main. Ouvrez le scénario de test dans Apidog, allez à son onglet CI/CD, choisissez l'option ligne de commande et générez un jeton d'accès. Apidog construit la commande `apidog run` complète pour vous avec les ID de scénario et d'environnement déjà renseignés. Copiez-la une fois et paramétrez le jeton à partir de là. Traitez le jeton d'accès comme un mot de passe : stockez-le comme un secret dans votre système CI et référencez-le comme `$APIDOG_ACCESS_TOKEN`, comme le fait chaque exemple ici.
Pour exécuter plus d'un scénario, pointez le runner vers un dossier ou une suite de tests au lieu d'un seul ID, et choisissez vos reporters :
apidog run --access-token $APIDOG_ACCESS_TOKEN -f <folderId> -e 1629989 -r html,junit --out-dir ./test-reports
Ce drapeau `-r` sélectionne les reporters. Apidog prend en charge `cli` pour une sortie terminal lisible, `html` pour un rapport autonome que vous archivez comme artefact de build, `junit` pour le XML que presque tous les tableaux de bord CI analysent en un arbre de réussite/échec, et `json` pour les résultats structurés bruts. Si vous souhaitez une exploration plus approfondie du runner, exécutez `apidog run --help` pour la liste complète des drapeaux.
Comparaison
| Dredd | Apidog | |
|---|---|---|
| Idée principale | Valider l'implémentation par rapport à une description d'API | Valider l'implémentation par rapport à la spécification dont elle a été conçue |
| Environnement d'exécution | Node.js (npm install -g dredd) |
Node.js (npm install -g apidog-cli) |
| Format de spécification | API Blueprint, OpenAPI 2/3 | OpenAPI 2/3, importation Swagger, importation Postman |
| Emplacement de la spécification | Fichier séparé, maintenu à la main | Le même projet que les tests exécutent |
| Logique de configuration | Fichier de hooks (hooks.js, plus Python/Ruby/Go/etc.) |
Scripts JavaScript pré/post-requête, dans le test |
| Création de tests | Exemples dans la description | Éditeur visuel par rapport à des schémas réels |
| Couverture | Aussi bonne que les exemples dans la spécification | Assertions de schéma plus scénarios personnalisés |
| Reporters | Intégrés plus add-ons | cli, html, json, junit |
| Hébergement | Auto-hébergé, open source | Projet hébergé, la CLI s'exécute partout |
Lisez ce tableau honnêtement. Si vous voulez un outil entièrement auto-hébergé, open source, sans compte et que votre équipe est à l'aise avec la maintenance d'un fichier de hooks, le modèle de Dredd convient parfaitement et changer pour le simple plaisir de changer ne vous apportera rien. Le cas du chemin intégré est spécifique : vous êtes fatigué que la spécification soit un troisième fichier qui dérive, vous ne voulez pas posséder une base de code de hooks, ou vous voulez que le même projet gère la conception, les tests et la vérification du contrat ensemble.
Intégration dans la CI
L'interface CLI Apidog sort avec zéro en cas de succès et avec un code non nul en cas d'échec, de sorte que tout système CI peut bloquer une construction en se basant dessus, exactement comme Dredd. Un job GitHub Actions minimal nécessite Node et une étape d'exécution :
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 }}
C'est l'ensemble du pipeline. Un job Dredd est similaire : installez la CLI, exécutez une commande, mais vous le dirigez également vers votre fichier de spécification et votre fichier de hooks, et vous maintenez les deux à jour. La validation s'exécute de la même manière ; la différence réside dans le nombre d'artefacts que vous maintenez pour y arriver.
Si votre raison d'opter pour Dredd était vraiment de maintenir une spécification et un service en accord mutuel, la même logique apparaît dans d'autres outils. Les équipes rencontrent ce problème avec Swagger et Postman qui divergent, ce que le test piloté par OpenAPI contre la dérive Swagger et Postman couvre, et les entreprises Java le rencontrent avec Rest Assured, où l'histoire des alternatives rime : un outil puissant dont le modèle ajoute une couche que vous ne souhaitez peut-être pas. Vous pouvez également piloter Apidog depuis votre éditeur avec l'extension VS Code si vous préférez ne pas quitter votre IDE.
FAQ
Apidog est-il un remplacement direct pour une configuration Dredd ? Non, et il ne prétend pas l'être. Il n'y a pas de convertisseur qui lit vos fichiers `dredd.yml` et `hooks.js` et génère des scénarios Apidog. Vous importez votre spécification OpenAPI et reconstruisez la validation dans l'éditeur visuel. L'avantage est que vous cessez de maintenir un fichier de hooks et une spécification libre ; le coût est une reconstruction unique. Si vous avez une suite Dredd importante et mature qui fonctionne, cette reconstruction est une vraie décision, pas un cadeau.
Apidog valide-t-il l'implémentation en direct, comme Dredd ? Oui. L'interface CLI envoie de vraies requêtes à votre service en cours d'exécution et affirme les réponses réelles par rapport aux schémas de votre projet. C'est la même vérification spécification-versus-implémentation que Dredd effectue. La différence est que le schéma vérifié est celui à partir duquel vous avez conçu l'API, de sorte qu'il ne se désynchronise pas de vos tests.
Puis-je toujours gérer l'authentification et la configuration des tests comme les hooks Dredd me le permettent ? Oui. Apidog prend en charge les scripts pré-requête et post-requête en JavaScript, vous pouvez donc récupérer des jetons d'authentification, initialiser des données, transformer des payloads, ou construire des assertions dynamiques dans le code. La logique vit dans le scénario qu'elle prend en charge, plutôt que dans un fichier de hooks séparé configuré via un fichier de configuration.
Dredd fait-il quelque chose qu'Apidog ne fait pas ? Oui, quelques éléments. Dredd est entièrement auto-hébergé et open source sans compte, et il lit nativement API Blueprint, l'ancien format de description Markdown. Si un outil sans compte, entièrement local ou un fichier Blueprint hérité est central à votre configuration, pesez cela attentivement avant de changer.
Quel format Apidog lit-il ? OpenAPI 2 et 3, documents Swagger et collections Postman, tous importables dans un seul projet. Si vous voulez comprendre d'abord les différences de format, Swagger versus OpenAPI et l'aperçu de la spécification OpenAPI les expliquent tous les deux.
En résumé
Dredd a eu la bonne idée fondamentale : votre description d'API devrait être quelque chose par rapport à quoi vous testez le service en cours d'exécution, et non un document qui dérive. Si vous voulez une CLI auto-hébergée et open source et que vous êtes satisfait de maintenir un fichier de spécification et un fichier de hooks, Dredd est un excellent choix et vous devriez continuer à l'utiliser.
La voie intégrée est pour le cas où cette maintenance est la partie que vous voulez éliminer. Apidog maintient la spécification, les tests et la validation dans un seul projet, de sorte que le contrat que vous vérifiez est le même que celui à partir duquel vous avez conçu, et il exécute le tout à partir de `apidog run` sans avoir à posséder de base de code de hooks. Téléchargez Apidog et importez votre fichier OpenAPI existant pour voir la vérification spécification-versus-implémentation s'exécuter à partir d'une seule commande.