La plupart des tests API commencent leur vie dans une interface utilisateur graphique (GUI). Vous cliquez ici et là, ajoutez quelques assertions, et les exécutez manuellement. Cela fonctionne jusqu'à ce que vous ayez besoin que les mêmes tests s'exécutent à chaque "push", chaque nuit, ou au sein d'un pipeline où personne ne regarde. À ce moment-là, vous voulez une commande unique que vous pouvez taper, scripter et "piper" dans l'intégration continue (CI).
Cette commande est l'Apidog CLI. Ce tutoriel vous guidera à travers le test d'une API REST réelle de bout en bout depuis votre terminal : installer l'outil, importer une API, configurer un environnement, construire un scénario de test, l'exécuter avec des assertions, lui fournir des données et collecter des rapports. Chaque commande et sortie ci-dessous provient d'une exécution réelle sur Apidog CLI version 2.2.2 contre une API publique en direct, vous pouvez donc suivre et obtenir les mêmes résultats.
Si vous souhaitez le côté visuel de la même plateforme, vous pouvez télécharger Apidog et concevoir les tests dans l'application en premier. Mais tout ce qui est présenté ici reste en ligne de commande.
Ce que vous allez construire
Vous testerez restful-api.dev, une API REST publique gratuite avec de réelles opérations CRUD sur une ressource /objects. À la fin, vous aurez :
- Un projet Apidog initialisé à partir d'un fichier OpenAPI
- Un scénario de test en trois étapes qui crée un objet, le relit, et le supprime, avec des assertions à chaque étape
- Une exécution basée sur les données qui répète une requête une fois par ligne de données de test
- Des rapports CLI, HTML, JSON et JUnit, ainsi qu'un rapport cloud partageable
Le même flux s'adapte à votre propre API, et c'est la base pour exécuter des tests API dans un pipeline CI/CD.
Avant de commencer
Vous avez besoin de Node.js 16 ou plus récent et d'un compte Apidog. Si vous comparez d'abord les runners, la version courte est que l'Apidog CLI exécute des scénarios de test complets et gère les ressources API comme du code, ce qui le distingue de Newman et du Postman CLI.
Étape 1 : Installer et se connecter
Installez le CLI globalement depuis npm :
npm install -g apidog-cli@latest
Confirmez qu'il est là :
apidog --version
# 2.2.2
Maintenant, authentifiez-vous. Récupérez un jeton depuis l'application Apidog sous votre avatar, Paramètres du compte, Jeton d'accès API, puis exécutez :
apidog login --with-token <YOUR_TOKEN>
Le jeton est enregistré dans ~/.apidog/config.toml, vous ne faites donc cela qu'une seule fois par machine. Vérifiez qui vous êtes :
Chaque commande renvoie un JSON structuré avec un indicateur success et des agentHints utiles, ce qui facilite l'écriture de scripts ou l'envoi vers jq.
Étape 2 : Créer un projet
Choisissez l'équipe sous laquelle créer le projet, puis créez-le :
apidog team list
apidog project create --team 329562 --name "CLI Field Test"
Vous récupérez l'ID du nouveau projet.
Enregistrez-le dans une variable shell pour que le reste de ce tutoriel puisse être copié-collé :
PID=1314366 # remplacer par l'id de votre projet
apidog project get $PID
Étape 3 : Importer votre API REST
Vous pourriez créer des endpoints à la main, mais importer un fichier OpenAPI est plus rapide et reflète la manière dont les projets réels démarrent. Voici une petite spécification décrivant les endpoints CRUD /objects (enregistrez-le sous objects-api.openapi.json) :
{
"openapi": "3.0.3",
"info": { "title": "Objects API", "version": "1.0.0" },
"servers": [{ "url": "https://api.restful-api.dev" }],
"paths": {
"/objects": {
"get": { "summary": "List objects" },
"post": { "summary": "Create object" }
},
"/objects/{id}": {
"get": { "summary": "Get object by id" },
"put": { "summary": "Update object" },
"delete": { "summary": "Delete object" }
}
}
}
Importez-le :
apidog import --project $PID --format openapi --file ./objects-api.openapi.json
# "createCount": 5 (5 endpoints créés, 0 erreurs)
L'importateur lit également les formats openapi, postman, har, insomnia, jmeter, et plus encore. Listez ce qui a été importé :
apidog endpoint list --project $PID
# 37921721 get /objects
# 37921722 post /objects
# 37921723 get /objects/{id}
# 37921724 put /objects/{id}
# 37921725 delete /objects/{id}
Étape 4 : Configurer un environnement
Un environnement contient l'URL de base et toutes les variables que vos tests réutilisent. Créez-en un et enregistrez son ID :
apidog environment create "Production" --project $PID --base-url "https://api.restful-api.dev"
apidog environment list --project $PID
# { "id": 6334917, "name": "Production", "baseUrls": { "default": "https://api.restful-api.dev" } }
ENV=6334917 # remplacer par l'id de votre environnement
Vous passerez -e $ENV à la commande d'exécution plus tard afin que le test sache où envoyer les requêtes.
Étape 5 : Franchir la barrière d'écriture d'automatisation
Voici la première chose qui déroute les gens. Les scénarios de test et les données de test sont des ressources d'automatisation, et leur écriture sur votre branche principale depuis un outil externe est bloquée par défaut :
apidog test-scenario create --project $PID --name "x" --description "" --folder-id 0 --priority 1
# "error": { "code": "403075", "message": "Automation caller branch required" }
Ceci est un garde-fou, pas un bug. Vous avez deux façons de passer outre :
- Activez la permission d'édition directe dans l'application de bureau Apidog sous Paramètres du projet, Paramètres des fonctionnalités, Paramètres des fonctionnalités d'IA, Permissions d'édition d'IA externe.
- Travaillez sur une branche IA, ce qui isole les changements d'automatisation jusqu'à ce que vous choisissiez de fusionner. Ce chemin reste entièrement en ligne de commande, c'est donc ce que nous utiliserons.
Créez la branche à partir de main :
apidog branch create --project $PID --type ai \
--name "ai/20260616-from-main-cli-field-test" --from main
BR="ai/20260616-from-main-cli-field-test"
Le modèle de nommage ai/AAAAJJ-from-<source>-<feature> est la convention attendue par le CLI. Notez que l'import, la création d'environnement et les modifications d'endpoints ne sont pas bloquées ; seules les ressources d'automatisation le sont.
Étape 6 : Construire un scénario de test
Un scénario est un flux ordonné de requêtes avec des assertions entre elles. Vous créez d'abord l'enveloppe, puis ajoutez les étapes. Créez-le sur votre branche IA :
apidog test-scenario create --project $PID --branch "$BR" \
--name "Cycle de vie CRUD d'objet" \
--description "Créer, lire, puis supprimer un objet et affirmer chaque étape" \
--folder-id 0 --priority 1
SID=1836498 # l'id du scénario retourné
Les étapes sont ajoutées via update avec un fichier JSON. La règle d'or avec toute écriture JSON est de valider avant d'envoyer, afin de ne jamais envoyer une charge utile mal formée :
apidog cli-schema get test-scenario-update # voir la forme exacte
apidog cli-schema validate test-scenario-update --file ./steps-crud.json
# "le fichier de données est valide"
Chaque étape est une requête plus un petit script qui affirme la réponse et transmet les données à l'étape suivante. Voici la forme de l'étape de création, qui poste un nouvel objet et enregistre son id pour les étapes ultérieures :
{
"type": "customHttp",
"name": "Create object",
"customHttpRequest": {
"path": "https://api.restful-api.dev/objects",
"method": "post",
"requestBody": { "type": "json", "data": "{\"name\":\"Apidog CLI Field Test\",\"data\":{\"price\":42}}" },
"postProcessors": [{
"type": "customScript",
"data": "pm.test('create returns 200', function () { pm.response.to.have.status(200); });\nvar body = pm.response.json();\npm.globals.set('objId', body.id);",
"enable": true
}],
"projectId": 1314366
}
}
Les étapes suivantes réutilisent {{objId}} dans l'URL pour récupérer puis supprimer le même objet. Appliquez le fichier complet en trois étapes :
apidog test-scenario update $SID --project $PID --branch "$BR" --file ./steps-crud.json
# "success": true
Vous n'êtes pas obligé de créer des scénarios en JSON. Les construire visuellement dans Apidog et les exécuter depuis le CLI est tout aussi valable. Le chemin JSON est important lorsque vous voulez que vos tests soient versionnés et révisés comme tout autre code.
Étape 7 : Exécutez-le depuis la ligne de commande
C'est la récompense. Exécutez le scénario avec le rapporteur CLI :
apidog run -t $SID --project $PID --branch "$BR" -e $ENV -r cli
❏ Cycle de vie CRUD d'objet
↳ Créer objet POST .../objects [200 OK]
✓ la création renvoie 200 ✓ la réponse a un id ✓ le nom a été renvoyé
↳ Obtenir l'objet créé GET .../objects/ff80...3de [200 OK]
✓ l'obtention renvoie 200 ✓ l'id correspond à l'objet créé ✓ le prix a persisté dans les données
↳ Supprimer l'objet DELETE .../objects/ff80...3de [200 OK]
✓ la suppression renvoie 200
Requêtes HTTP 3 / 0 échecs
Assertions 7 / 0 échecs
Trois requêtes, sept assertions, zéro échec, et l'id créé est passé de la première étape aux deux suivantes. C'est un test API complet qui s'exécute sans un seul clic.
Vous voulez des fichiers au lieu d'une sortie console ? Demandez plusieurs rapporteurs à la fois et dirigez-les vers un dossier :
apidog run -t $SID --project $PID --branch "$BR" -e $ENV \
-r cli,html,json,junit --out-dir ./reports --out-file "rapport-crud"
ls ./reports
# rapport-crud.html rapport-crud.json rapport-crud.xml
Le XML JUnit est ce que votre serveur CI lit pour afficher le succès/l'échec par build. Le rapport HTML est celui que vous partagez avec vos coéquipiers.
Étape 8 : Exécutez le même test avec plusieurs entrées
Les suites de tests réelles couvrent plus d'un cas. Les exécutions basées sur les données répètent un scénario une fois par ligne de données, de sorte que vous testez dix entrées sans écrire dix scénarios. C'est la même idée que le test API paramétré à partir de CSV et JSON.
Placez vos lignes dans un fichier :
[
{ "name": "Pixel 8 Pro", "price": 999 },
{ "name": "iPhone 15", "price": 899 },
{ "name": "Galaxy S24", "price": 799 }
]
Référencez les données avec -d, et laissez le scénario lire {{name}} et {{price}} de chaque ligne :
apidog run -t $SID --project $PID --branch "$BR" -e $ENV -d ./objects-data.json -r cli
Itération 1/3 … ✓ ligne créée (200) ✓ le nom correspond à la ligne de données
Itération 2/3 … ✓ ligne créée (200) ✓ le nom correspond à la ligne de données
Itération 3/3 … ✓ ligne créée (200) ✓ le nom correspond à la ligne de données
Itérations 3 / 0 échecs Assertions 6 / 0 échecs
Trois lignes entrées, trois itérations sorties. Remplacez le fichier par un CSV et rien d'autre ne change.
Étape 9 : Collecter les rapports
Les exécutions locales écrivent des fichiers. Pour obtenir un rapport que toute votre équipe peut ouvrir dans un navigateur, ajoutez --upload-report :
apidog run -t $SID --project $PID --branch "$BR" -e $ENV -r cli --upload-report
# Les données d'exécution de l'Apidog CLI ont été téléchargées avec succès sur le cloud.
# https://app.apidog.com/link/project/1314366/api-test/test-report/2605398
Une mise en garde à connaître : un rapport cloud est marqué avec la branche sur laquelle il a été exécuté. Puisque cette exécution a eu lieu sur votre branche IA, un simple apidog test-report list --project $PID (qui cible main) ne l'affichera pas. Récupérez-le par son ID à partir du lien de téléchargement à la place :
apidog test-report get 2605398 --project $PID
apidog test-report download 2605398 --project $PID --format json --output ./cloud-report.json
Étape 10 : Exporter votre API en tant que documentation ou spécification
Le CLI exporte également des données. Exportez le projet en tant que fichier OpenAPI, Markdown ou documentation HTML :
apidog export --project $PID --format openapi --oas-version 3.0 --output ./openapi-export.json
apidog export --project $PID --format markdown --output ./api-docs.md
apidog export --project $PID --format html --output ./api-docs.html
C'est pratique pour valider une nouvelle spécification à chaque modification ou pour publier des documents statiques depuis un pipeline.
Étape 11 : Intégrez-le dans le CI/CD
Tout ce que vous avez exécuté manuellement devient trois lignes dans un pipeline. Le cœur est l'installation, puis l'exécution avec le rapporteur JUnit afin que le serveur CI puisse lire les résultats :
- run: npm install -g apidog-cli@latest
- run: apidog login --with-token $APIDOG_TOKEN
- run: apidog run -t $SID --project $PID -e $ENV -r junit --out-dir ./reports
Stockez le jeton en tant que secret, et faites échouer la construction quand un test échoue (le CLI renvoie un code de sortie non nul en cas d'échec). Pour un workflow complet et copiable-collable, consultez le guide sur l'exécution des tests Apidog CLI dans GitHub Actions, ou parcourez les outils d'automatisation des tests API qui s'intègrent à un pipeline.
En résumé
Vous êtes passé d'un terminal vide à un test API réussi, basé sur les données et avec des rapports partageables, sans jamais quitter la ligne de commande. Le modèle est toujours le même : importez ou concevez votre API, créez un environnement, construisez un scénario avec des assertions, puis exécutez-le avec apidog run. Une fois que cette commande fonctionne localement, l'intégrer dans le CI est un changement de trois lignes.
Appliquez les mêmes étapes à votre propre API, validez les fichiers de scénario avec votre code, et vos tests s'exécuteront partout où un shell fonctionne. Téléchargez Apidog pour commencer, et gardez les alternatives à curl pour les tests d'API REST à portée de main pour les vérifications ponctuelles pour lesquelles le CLI est superflu.