Comment exécuter des tests API depuis la CLI Apidog

Vos tests d'API passent sur votre ordinateur portable. Puis quelqu'un fusionne un changement à 2 heures du matin, le point de terminaison de staging commence à retourner une charge utile mal formée, et personne ne le remarque avant qu'un client ne dépose un ticket le lendemain matin. Les tests existaient. Ils n'ont simplement jamais été exécutés là où c'était important : à l'intérieur de la pipeline, à chaque push, sans aucune intervention humaine.

Cet écart entre "tests qui existent" et "tests qui s'exécutent automatiquement" est précisément ce qu'un exécuteur en ligne de commande comble. L'Apidog CLI prend les scénarios de test que vous avez déjà construits dans l'application de bureau ou web Apidog et les exécute sans interface graphique depuis un terminal. Pas d'interface graphique, pas de clics manuels. Vous l'installez avec une seule commande npm, vous le pointez vers un scénario de test, et il se termine avec un code de statut propre et un rapport que vous pouvez publier dans n'importe quel système de CI. Cela en fait le pont entre le constructeur de tests visuel et votre plateforme CI/CD.

En bref

• L'Apidog CLI est un package npm appelé apidog-cli. Installez-le globalement avec npm install -g apidog-cli, puis exécutez les scénarios avec la commande apidog run.
• Il exécute les scénarios de test que vous concevez dans Apidog. Vous ne réécrivez pas les tests sous forme de code ; la CLI exécute le même scénario par ID, en utilisant un jeton d'accès pour l'authentification.
• Exécution de base : apidog run --access-token $APIDOG_ACCESS_TOKEN -t <scenarioId> -e <environmentId> -n 1 -r html,cli.
• Les reporters couvrent cli, html, json et junit. Le format JUnit XML s'intègre directement dans les tableaux de bord de test CI.
• Un code de sortie non nul en cas d'échec de test fait de la CLI une véritable porte de qualité. Les tests échoués font échouer la construction par défaut.
• Il fonctionne dans n'importe quel exécuteur CI disposant de Node.js : GitHub Actions, GitLab CI, Jenkins, CircleCI, Azure Pipelines, et bien d'autres.

Ce qu'est réellement l'Apidog CLI

Apidog est une plateforme API tout-en-un : vous concevez le schéma, déboguez les requêtes, construisez des scénarios de test automatisés, simulez des points de terminaison et publiez de la documentation dans un seul espace de travail. La majeure partie de ce travail se déroule dans une interface visuelle. Vous enchaînez les requêtes dans un scénario de test, ajoutez des assertions, extrayez des valeurs d'une réponse à l'autre et parcourez un fichier de données.

La CLI est l'exécuteur sans interface graphique pour ces scénarios. Elle n'a pas son propre format de test. Elle accède à votre projet Apidog, trouve le scénario que vous nommez par ID, l'exécute exactement comme l'application le ferait, puis rend compte. Considérez-le comme la relation entre un outil de construction et votre code source : la source de vérité réside dans le projet, et la CLI est ce qui l'exécute sans qu'une personne soit présente.

C'est important car cela élimine la raison la plus courante pour laquelle les tests d'API pourrissent. Lorsque les tests n'existent que sous forme d'étapes cliquables dans une application de bureau, ils sont exécutés lorsque quelqu'un s'en souvient. Lorsqu'ils sont exécutés à partir d'une commande d'une ligne, vous pouvez les intégrer dans une pipeline et ils s'exécutent à chaque commit, chaque fusion, chaque planification nocturne. Le constructeur visuel vous offre une création rapide ; la CLI vous offre l'automatisation. Vous obtenez les deux sans avoir à choisir.

Si vous venez du monde Postman, le modèle mental correspond parfaitement. L'Apidog CLI joue le rôle que le Postman CLI ou Newman joue pour les collections Postman, sauf qu'il exécute les scénarios de test Apidog et est livré sous forme de package unique. Nous avons couvert cette comparaison en profondeur dans Postman CLI vs Newman, et la question plus large de l'exécution de collections en CI sans Newman si vous migrez.

Prérequis

Avant d'exécuter une seule commande, vous avez besoin de trois choses :

1. Node.js v16 ou version ultérieure. La CLI est livrée sous forme de package npm, donc un environnement d'exécution Node est la seule dépendance système. Vérifiez la vôtre avec node -v. Toute image CI avec Node 16+ est déjà qualifiée.
2. Un scénario de test Apidog. La CLI exécute des scénarios, pas des requêtes isolées. Construisez-en un d'abord dans l'application Apidog : enchaînez vos requêtes, ajoutez des assertions, configurez toute itération pilotée par les données dont vous avez besoin. Si vous débutez dans la création d'assertions, API assertions: a practical guide explique comment valider les réponses.
3. Un jeton d'accès. Cela authentifie la CLI auprès de votre compte Apidog afin qu'elle puisse récupérer et exécuter le scénario. Vous le générez dans l'onglet CI/CD du scénario de test ; plus d'informations ci-dessous.

C'est tout. Pas d'installation Apidog séparée sur la machine CI, pas d'interface graphique, pas de fichier de licence. Le package et un jeton suffisent.

Installation de l'Apidog CLI

Installez-le globalement avec npm :

npm install -g apidog-cli

Puis confirmez que tout s'est résolu correctement :

node -v && apidog -v && which node && which npm && which apidog

Si cela affiche les numéros de version et les chemins, vous avez terminé. L'exécutable est apidog, donc chaque commande commence par apidog run.

Sur une machine de développeur, une installation globale est correcte. En CI, vous avez deux schémas raisonnables. Le premier consiste à l'installer à neuf à chaque exécution de pipeline, ce qui garantit que vous utilisez la dernière version :

npm install -g apidog-cli
apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e 1629989 -r cli

Le second consiste à l'exécuter sans installation globale persistante via npx, ce qui évite de modifier les packages globaux de l'exécuteur :

npx apidog-cli run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e 1629989 -r cli

Les deux fonctionnent. L'approche npx est plus propre pour les exécuteurs CI éphémères ; l'installation globale est légèrement plus rapide si vous la mettez en cache entre les exécutions.

Obtenir votre jeton d'accès et l'ID de scénario

La CLI a besoin de savoir deux choses : quel scénario exécuter, et qu'elle est autorisée à l'exécuter. Apidog génère les deux pour vous afin que vous n'ayez pas à les chercher dans l'interface utilisateur.

Ouvrez le scénario de test que vous souhaitez automatiser. Passez à son onglet CI/CD. Choisissez l'option de ligne de commande, puis cliquez sur Ajouter un jeton d'accès et Générer un jeton. Apidog construit pour vous la commande apidog run complète, avec le jeton d'accès, l'ID du scénario et l'ID de l'environnement déjà remplis. Cliquez sur la commande pour la copier.

Cette commande générée est le point de départ canonique. Elle ressemble à ceci :

apidog run --access-token YOUR_ACCESS_TOKEN -t 605067 -e 1629989 -n 1 -r html,cli

Les nombres sont des identifiants réels de votre projet. 605067 est l'ID du scénario de test. 1629989 est l'ID de l'environnement. Vous ne les taperez presque jamais à la main ; vous les copiez une fois depuis l'onglet CI/CD, puis vous paramétrez le jeton.

Une règle à énoncer dès le début : traitez le jeton d'accès comme un mot de passe. Ne le collez pas dans un fichier de configuration commité ou une définition de pipeline publique. Stockez-le comme un secret dans votre système CI et référencez-le comme une variable d'environnement. Tous les exemples ci-dessous utilisent $APIDOG_ACCESS_TOKEN pour cette raison précise.

La commande apidog run, option par option

L'ensemble de la CLI tourne autour d'une seule commande. Voici la surface d'options complète, regroupée par ce que chaque groupe contrôle.

Sélectionner ce qui doit être exécuté

Vous choisissez l'une des options -t, -f, ou --test-suite en fonction de la portée. Un seul scénario pour un test de fumée ciblé, un dossier pour une zone de fonctionnalité, une suite de tests lorsque vous souhaitez qu'un ensemble de scénarios sélectionnés soit exécuté ensemble comme un seul travail logique.

Authentification

C'est la seule option dont chaque commande CI a besoin. Passez-la depuis un secret, jamais en ligne.

Environnement et itération

L'option d'environnement vous permet de pointer le même scénario vers l'environnement de staging lors d'une vérification de pull-request et vers la production lors d'un test de fumée après déploiement, sans dupliquer le scénario. Les données d'itération vous permettent d'exécuter un scénario sur cinquante lignes d'entrée et de traiter chaque ligne comme un passage distinct. Nous couvrons le modèle piloté par les données plus en détail dans le guide sur la mise à l'échelle des tests API automatisés avec des suites de tests.

Rapports

C'est ici que la CLI gagne sa place dans une pipeline. Passez plusieurs formats à la fois, séparés par des virgules :

apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -r html,junit --out-dir ./test-reports

cli vous donne une sortie de terminal lisible pour les humains qui lisent le journal de construction. html produit un rapport autonome que vous pouvez archiver comme artefact de construction et ouvrir dans un navigateur. junit émet du XML au format JUnit standard, que presque tous les tableaux de bord CI savent analyser en une arborescence de réussite/échec. json vous donne le résultat structuré brut si vous souhaitez le post-traiter.

Gestion des erreurs et comportement de sortie

--on-error contrôle ce qui se passe au milieu d'un scénario. end arrête l'exécution à la première défaillance, ce qui est généralement souhaitable pour un test de fumée à échec rapide. continue exécute chaque étape afin que vous voyiez toutes les défaillances dans un seul rapport. ignore est pour le cas rare où une étape est connue pour être instable et que vous ne voulez pas qu'elle perturbe l'exécution.

TLS et certificats

Utilisez-les lorsque vous testez des points de terminaison derrière un TLS mutuel ou avec des chaînes d'AC internes. N'utilisez -k que contre des hôtes internes de confiance où le certificat est auto-signé ; jamais contre quoi que ce soit de public.

Sortie et diagnostics

--verbose est votre premier réflexe lorsqu'un test réussit localement mais échoue en CI ; il vous montre la requête exacte envoyée par l'exécuteur et la réponse exacte qu'il a reçue. --silent est pour les tâches nocturnes bruyantes où vous ne vous souciez que du code de sortie et du rapport enregistré.

Codes de sortie : la partie qui fait fonctionner la CI

Un exécuteur de tests n'est utile dans une pipeline que s'il indique à la pipeline si les tests ont réussi. L'Apidog CLI le fait comme tout outil en ligne de commande bien conçu : il se termine avec le code 0 lorsque toutes les assertions passent et un code non nul lorsque quelque chose échoue.

Ce seul comportement transforme apidog run en une porte de qualité. Les systèmes CI lisent le code de sortie de chaque étape. Une sortie non nulle marque l'étape comme ayant échoué, ce qui fait échouer le travail, ce qui bloque la fusion ou le déploiement. Vous ne configurez rien de plus. Tant que l'étape apidog run est dans votre pipeline, un test échoué arrête la ligne.

Vous pouvez ajuster cela avec --on-error. Le comportement par défaut échoue à la première assertion brisée, ce qui permet un feedback rapide. Passez à --on-error continue lorsque vous préférez voir tous les échecs dans un seul rapport avant que la construction ne devienne rouge. Dans tous les cas, l'exécution se termine toujours par une sortie non nulle si quelque chose a échoué, donc la porte tient.

Exécution dans GitHub Actions

Un workflow complet qui exécute un scénario Apidog à chaque pull request et publie le rapport en tant qu'artefact.

name: API tests

on:
 pull_request:
 branches: [main]

jobs:
 api-tests:
 runs-on: ubuntu-latest
 steps:
 - name: Checkout
 uses: actions/checkout@v4

 - name: Set up Node.js
 uses: actions/setup-node@v4
 with:
 node-version: '20'

 - name: Install Apidog CLI
 run: npm install -g apidog-cli

 - name: Run API test scenario
 run: |
 apidog run \
 --access-token "$APIDOG_ACCESS_TOKEN" \
 -t 605067 \
 -e 1629989 \
 -n 1 \
 -r html,junit \
 --out-dir ./apidog-reports
 env:
 APIDOG_ACCESS_TOKEN: ${{ secrets.APIDOG_ACCESS_TOKEN }}

 - name: Upload report
 if: always()
 uses: actions/upload-artifact@v4
 with:
 name: apidog-report
 path: ./apidog-reports

Le jeton se trouve dans les secrets du dépôt et parvient à l'étape en tant que variable d'environnement. Le if: always() sur l'étape de téléchargement signifie que vous obtenez toujours le rapport même lorsque les tests échouent, ce qui est précisément le moment où vous voulez le lire. Si un test échoue, l'étape apidog run se termine avec un code non nul, le travail passe au rouge et la PR affiche une vérification échouée.

Exécution dans GitLab CI

Le même schéma dans .gitlab-ci.yml :

stages:
 - test

api-tests:
 stage: test
 image: node:20
 script:
 - npm install -g apidog-cli
 - >
 apidog run
 --access-token "$APIDOG_ACCESS_TOKEN"
 -t 605067
 -e 1629989
 -r junit,cli
 --out-dir ./apidog-reports
 artifacts:
 when: always
 paths:
 - apidog-reports/
 reports:
 junit: apidog-reports/*.xml

Deux choses à noter. Stockez APIDOG_ACCESS_TOKEN comme une variable CI/CD masquée et protégée sous Paramètres, pas dans le fichier. Et le bloc reports: junit: indique à GitLab d'analyser le XML JUnit et d'afficher les résultats dans le widget de la demande de fusion, de sorte qu'un relecteur voit quelles assertions ont échoué sans rien télécharger.

Exécution dans Jenkins

Dans une pipeline déclarative, stockez le jeton comme une information d'identification Jenkins ou une variable d'environnement globale, puis appelez la CLI dans une étape :

pipeline {
 agent any
 environment {
 APIDOG_ACCESS_TOKEN = credentials('apidog-access-token')
 }
 stages {
 stage('API tests') {
 steps {
 sh 'npm install -g apidog-cli'
 sh 'apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e 1629989 -n 1 -r html,junit --out-dir apidog-reports'
 }
 }
 }
 post {
 always {
 junit 'apidog-reports/*.xml'
 archiveArtifacts artifacts: 'apidog-reports/', allowEmptyArchive: true
 }
 }
}

Si vos agents de build ont déjà la CLI installée et mise en cache, supprimez la ligne npm install et appelez apidog run directement. L'étape junit dans le bloc post alimente le XML dans les graphiques de tendance des tests de Jenkins ; archiveArtifacts maintient le rapport HTML attaché à la build. Si vous comparez Jenkins à d'autres exécuteurs, la comparaison dans Configuration ReadyAPI Jenkins CI, et une alternative plus simple couvre les compromis.

Schémas et recettes courantes

Test de fumée après déploiement. Exécutez un scénario rapide contre la production juste après une publication, en ciblant l'environnement de production :

apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e <prodEnvId> -r cli --on-error end

Régression complète nocturne. Exécutez un dossier entier de scénarios selon un calendrier, avec toutes les défaillances collectées dans un seul rapport :

apidog run --access-token $APIDOG_ACCESS_TOKEN -f <folderId> -r html,junit --on-error continue --out-dir ./nightly-reports

Exécution basée sur les données. Parcourez un scénario sur un fichier CSV de cas de test :

apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -d ./test-data.csv -r junit

Vérification spécifique à la branche. Exécutez les scénarios tels qu'ils existent sur une branche de fonctionnalité, pas main :

apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 --branch feature-payments -e 1629989 -r cli

Déboguer un échec en CI uniquement. Lorsqu'un scénario réussit localement mais échoue dans la pipeline, ajoutez --verbose pour voir la requête et la réponse exactes au niveau du fil envoyées par l'exécuteur.

Dépannage

Erreurs d'authentification. Si l'exécution échoue avec une erreur d'authentification, le jeton est incorrect, expiré ou n'atteint pas la commande. Effectuez une vérification masquée (jamais le jeton complet) et confirmez que votre secret CI est bien rempli. Régénérez le jeton à partir de l'onglet CI/CD du scénario si nécessaire.

"Scénario non trouvé." L'ID du scénario, l'ID du projet ou la branche ne correspondent pas. Recopiez la commande depuis l'onglet CI/CD pour garantir que les ID sont à jour, et confirmez que --branch pointe vers ce que vous attendez.

Les tests réussissent localement mais échouent en CI. Presque toujours une différence d'environnement. L'exécuteur CI peut cibler un environnement -e différent, atteindre un hôte inaccessible ou manquer une variable dont votre scénario dépend. Exécutez avec --verbose et comparez la requête envoyée par l'exécuteur CI à celle que vous envoyez localement.

Échecs réseau ou TLS contre des hôtes internes. Si votre point de terminaison utilise une AC interne, passez --ssl-extra-ca-certs. Utilisez -k uniquement en dernier recours sur des hôtes internes de confiance où le certificat est auto-signé.

La build reste verte même si un test devrait échouer. Confirmez que le code de sortie de l'étape apidog run atteint réellement la CI. Si vous l'avez encapsulé dans une pipeline shell ou ajouté || true, la sortie non nulle est ignorée et la porte cesse de fonctionner. Supprimez tout ce qui masque le code de sortie.

Comment l'Apidog CLI s'intègre dans un flux de travail réel

La CLI est une pièce d'une boucle. Vous concevez et déboguez les requêtes dans l'application Apidog. Vous les enchaînez dans un scénario avec des assertions. Vous commitez votre travail et la CLI exécute ce scénario en CI à chaque changement. Quand quelque chose se casse, le rapport vous indique quelle assertion a échoué et le code de sortie arrête le déploiement. Vous le réparez, poussez à nouveau, et la même porte confirme la correction.

L'avantage de construire des tests visuellement et de les exécuter sans interface graphique est que personne n'a à maintenir deux représentations du même test. Le scénario dans le projet est le test. La CLI l'exécute simplement là où un humain ne peut pas être. C'est un modèle différent des exécuteurs basés sur des scripts, où le test et son exécution sont le même fichier fragile, et c'est une grande partie de la raison pour laquelle les équipes se tournent vers Apidog comme alternative à Postman pour les tests d'API.

Si vous n'avez pas encore construit les tests, commencez dans l'application, faites passer un scénario, puis connectez la commande CLI depuis son onglet CI/CD. Téléchargez Apidog pour configurer votre premier scénario automatisé, et vous l'aurez intégré à votre pipeline le même après-midi.

Questions fréquemment posées

L'Apidog CLI est-il gratuit ? La CLI elle-même est un package npm gratuit. Vous l'installez avec npm install -g apidog-cli. Elle exécute les scénarios de test de votre projet Apidog, donc ce que vous pouvez exécuter dépend de votre plan Apidog, mais l'exécuteur en ligne de commande n'est pas un produit payant séparé.

Dois-je réécrire mes tests sous forme de code pour utiliser la CLI ? Non. C'est la principale différence avec les exécuteurs basés sur des scripts. Vous construisez visuellement des scénarios dans Apidog, et la CLI les exécute par ID. Le scénario est le test ; la CLI n'est que l'exécuteur.

Quelle est la différence entre l'Apidog CLI et Newman ? Newman exécute les collections Postman en ligne de commande. L'Apidog CLI exécute les scénarios de test Apidog. Les rôles sont parallèles, mais l'exécuteur Apidog exécute les scénarios que vous avez créés dans l'application Apidog et est livré sous forme de package unique apidog-cli. Voir Postman CLI vs Newman pour la partie Postman de cette comparaison.

Quel format de rapport dois-je utiliser en CI ? Utilisez junit pour le résultat lisible par machine que votre tableau de bord CI analyse en une arborescence de réussite/échec, et ajoutez html si vous souhaitez un rapport navigable enregistré comme artefact de build. Un choix courant est -r html,junit. Gardez cli également si vous souhaitez une sortie lisible dans le journal de build.

Comment la CLI fait-elle échouer une build ? Par son code de sortie. Lorsqu'une assertion échoue, apidog run se termine avec un code non nul. Les systèmes CI lisent ce code de sortie, marquent l'étape comme ayant échoué et bloquent la fusion ou le déploiement. Vous ne configurez rien de plus pour que cela fonctionne.

Puis-je exécuter la CLI sans l'installer globalement ? Oui. Utilisez npx apidog-cli run ... pour l'exécuter sans installation globale persistante, ce qui est pratique sur les exécuteurs CI éphémères.

De quelle version de Node.js ai-je besoin ? Node.js v16 ou version ultérieure. Toute image CI moderne avec Node 16+ satisfait déjà l'exigence.

Où puis-je obtenir le jeton d'accès et l'ID du scénario ?** Les deux proviennent de l'onglet CI/CD du scénario de test dans Apidog. Choisissez l'option de ligne de commande, générez un jeton d'accès et copiez la commande apidog run complète qu'Apidog construit pour vous avec les ID déjà remplis. Déplacez ensuite le jeton vers un secret CI.