Comment exécuter des tests API en CI avec apidog run

Vous avez copié une commande à partir d'un onglet CI/CD, l'avez collée dans un pipeline, et cela a fonctionné. Puis un coéquipier vous demande pourquoi la build reste au vert alors qu'un test a clairement échoué, ou si vous pouvez pointer la même exécution vers l'environnement de staging au lieu de la production, ou comment obtenir un rapport que votre tableau de bord CI pourra réellement analyser. Soudain, la commande d'une seule ligne ne suffit plus. Vous avez besoin de savoir ce que chaque partie de celle-ci fait.

apidog run est la commande unique au cœur de l'exécuteur de ligne de commande Apidog. Elle exécute les scénarios de test API que vous avez créés dans Apidog sans interface graphique, depuis un terminal, sans GUI et sans intervention humaine pour cliquer sur un bouton. Tout ce que l'exécuteur peut faire, il le fait via des drapeaux sur cette seule commande : quel scénario exécuter, quel environnement cibler, combien de fois répéter, quels rapports émettre, et ce qui constitue un échec. Apprenez la surface des drapeaux une fois et vous cesserez de copier-coller à l'aveuglette.

Qu'est-ce que apidog run

L'Apidog CLI est livré sous forme de package npm appelé apidog-cli. Vous l'installez une fois et vous obtenez un seul binaire, apidog, dont la sous-commande principale est run. Cette sous-commande prend l'un de vos scénarios de test Apidog et l'exécute comme le ferait l'application de bureau, puis renvoie un code de sortie et tous les fichiers de rapport que vous avez demandés.

Installez-le globalement :

npm install -g apidog-cli

Confirmez qu'il est résolu :

apidog -v

Ce qu'il faut comprendre avant les drapeaux, c'est sur quoi apidog run opère. Il ne définit pas son propre format de test. Le test est le scénario que vous avez créé dans l'application Apidog : requêtes enchaînées, assertions, valeurs extraites d'une réponse à l'autre, itération pilotée par les données facultative. L'interface CLI accède à votre projet, trouve le scénario par ID et l'exécute. La plupart des drapeaux servent donc à indiquer à l'exécuteur quoi récupérer et comment se comporter pendant l'exécution, et non à écrire des tests directement.

Une commande réelle minimale ressemble à ceci :

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

Cela signifie : authentifiez-vous avec ce jeton, exécutez le scénario de test 605067, contre l'environnement 1629989, une fois, et produisez un rapport HTML plus une sortie terminale lisible. Chaque drapeau de cette ligne est expliqué ci-dessous, ainsi que ceux que cette commande omet.

La surface complète des options en un coup d'œil

Voici l'ensemble complet des options regroupées par fonction. Utilisez-le comme tableau de référence ; les sections suivantes expliquent celles qui nécessitent plus d'une phrase.

Les noms des drapeaux et leurs valeurs par défaut peuvent changer entre les versions de l'interface CLI. En cas de doute, l'exécuteur est sa propre source de vérité : exécutez apidog run --help sur la version que vous avez installée et faites-lui confiance plutôt qu'à tout article, y compris celui-ci.

Choisir ce qu'il faut exécuter

Trois drapeaux décident de la portée d'une exécution, et vous en choisissez exactement un par commande.

-t, --test-scenario <id> exécute un seul scénario. C'est le cas quotidien : un test de fumée ciblé, un scénario de régression, une chose que vous voulez bloquer sur une demande de fusion.

-f, --test-scenario-folder <id> exécute tous les scénarios à l'intérieur d'un dossier. Utilisez-le lorsque vous avez organisé une zone fonctionnelle dans un dossier et que vous souhaitez exécuter l'ensemble du groupe comme un seul travail, comme un balayage de régression nocturne.

--test-suite <id> exécute une suite de tests organisée, qui est un ensemble de scénarios que vous avez assemblés pour être exécutés ensemble comme une unité logique. Une suite est le bon outil lorsque les scénarios que vous souhaitez ne sont pas tous dans un même dossier mais appartiennent toujours à la même passe de test.

Deux sélecteurs supplémentaires affinent l'endroit où l'exécuteur recherche. --project <id> nomme le projet dans lequel un scénario se trouve, utile lorsque votre jeton a accès à plus d'un projet. --branch <name> exécute le scénario tel qu'il existe sur une branche spécifique au lieu de main, ce qui vous permet de valider les modifications de test sur une branche de fonctionnalité avant leur fusion.

# un scénario
apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e 1629989 -r cli

# un dossier entier
apidog run --access-token $APIDOG_ACCESS_TOKEN -f 88012 -r html,junit

# une suite organisée
apidog run --access-token $APIDOG_ACCESS_TOKEN --test-suite 40231 -r junit

Authentifier l'exécution

--access-token <token> est le seul drapeau dont chaque exécution en ligne a besoin. Il prouve que l'exécution est autorisée à récupérer et à exécuter votre scénario. Vous générez le jeton dans l'onglet CI/CD d'un scénario de test dans Apidog, où l'application construit également la commande complète apidog run pour vous avec l'ID du scénario et l'ID de l'environnement déjà renseignés.

Traitez le jeton comme un mot de passe. Ne le collez pas dans un fichier de pipeline commité ou un script partagé. Stockez-le comme un secret dans votre système CI et transmettez-le via une variable d'environnement, c'est pourquoi chaque exemple ici fait référence à $APIDOG_ACCESS_TOKEN plutôt qu'à une chaîne littérale. Si un jeton est divulgué, régénérez-le depuis le même onglet CI/CD et l'ancien cessera de fonctionner.

Cibler un environnement et itérer

Le drapeau d'environnement est ce qui permet à un scénario de servir à de nombreuses fins. -e, --environment <id> pointe l'exécution vers un environnement spécifique, de sorte que le même scénario peut vérifier le staging dans une porte de demande de fusion et la production dans un test de fumée post-déploiement sans que vous ayez à dupliquer quoi que ce soit. Si vous gérez des valeurs dans différents environnements, le guide sur la gestion des environnements et des secrets pour les clients API explique comment ces valeurs circulent.

-n, --iteration-count <n> exécute le scénario n fois de suite. Utile pour une vérification rapide de la stabilité ou pour répéter un flux qui devrait être idempotent.

-d, --iteration-data <path> est le drapeau piloté par les données. Pointez-le vers un fichier JSON ou CSV et l'exécuteur exécute le scénario une fois par ligne, traitant chaque ligne comme sa propre passe avec ses propres valeurs d'entrée. C'est ainsi que vous exécutez un scénario de connexion sur cinquante comptes, ou un flux de création de commande sur un tableau de charges utiles. Le modèle plus profond se trouve dans les tests API pilotés par les données avec CSV et JSON.

Trois drapeaux injectent des valeurs sans modifier le scénario. --variables <path> charge les variables à partir d'un fichier local. --global-var key=value définit une variable globale en ligne. --env-var key=value surcharge une seule variable d'environnement pour cette exécution uniquement. Ceux-ci sont utiles en CI lorsque une valeur (une URL de base, un drapeau de fonctionnalité) diffère par pipeline et que vous ne voulez pas un environnement séparé pour chacun. Si les variables dans Apidog sont nouvelles pour vous, maîtriser les variables dans Apidog explique les portées.

# exécuter un scénario 50 fois sur un fichier CSV d'entrées
apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -d ./accounts.csv -r junit

# surcharger une variable d'environnement pour cette exécution uniquement
apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e 1629989 --env-var baseUrl=https://staging.internal -r cli

Rapporteurs : tous les formats de sortie que apidog run peut produire

C'est le groupe que les gens recherchent le plus, voici donc chaque rapporteur et à quoi il sert. Vous les sélectionnez avec -r, --reporters et vous pouvez en passer plusieurs à la fois, séparés par des virgules. La valeur par défaut est cli.

cli affiche un résumé lisible dans le terminal. C'est ce qu'un humain scanne dans le journal de build pour voir les nombres de succès/échecs et les assertions qui ont échoué. Gardez-le activé même à côté des formats machine pour que le journal reste utile.

html écrit un rapport HTML autonome. Archivez-le comme artefact de build et ouvrez-le dans un navigateur pour voir l'exécution complète avec les détails des requêtes et des réponses. C'est le format que vous donnez à quelqu'un qui ne surveillait pas le pipeline.

junit émet du XML au format standard JUnit. Presque tous les tableaux de bord CI savent comment analyser le XML JUnit en un arbre de succès/échecs, afficher les échecs dans un widget de demande de fusion et suivre les résultats au fil du temps. Si vous ne choisissez qu'un seul format machine pour la CI, choisissez celui-ci.

json produit le résultat structuré brut. Utilisez-le lorsque vous souhaitez post-traiter le résultat vous-même : alimentez-le à un script, poussez des métriques quelque part ou construisez un résumé personnalisé.

Une combinaison CI courante est HTML pour les humains plus JUnit pour le tableau de bord :

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

Les drapeaux de rapport restants contrôlent où la sortie est placée et ce qu'elle inclut en plus :

• --out-dir <dir> définit le répertoire dans lequel les rapports sont écrits. La valeur par défaut est ./apidog-reports.
• --out-file <name> définit le nom du fichier de rapport et accepte les placeholders {FOLDER_NAME}, {SCENARIO_NAME}, et {GENERATE_TIME}, afin que vous puissiez estampiller les fichiers avec le nom du scénario et un horodatage au lieu d'écraser un fichier à chaque exécution.
• --out-json-failures-separated <value> sépare les échecs dans leur propre fichier JSON, ce qui facilite la lecture d'un diff ne contenant que les échecs.
• --upload-report [value] télécharge un aperçu du rapport sur le cloud Apidog afin que l'exécution apparaisse dans l'historique de votre projet à côté des fichiers locaux.

Contrôler les échecs : gestion des erreurs et codes de sortie

Un exécuteur n'est utile dans un pipeline que s'il indique au pipeline si les tests ont réussi. apidog run le fait comme les outils en ligne de commande bien conçus : il se termine avec le code 0 lorsque toutes les assertions réussissent et un code non nul lorsque quelque chose échoue. Ce comportement unique est l'intégralité du contrôle qualité. La CI lit le code de sortie, marque l'étape comme échouée et bloque la fusion ou le déploiement. Vous ne configurez pas de porte ; le code de sortie est la porte.

--on-error <behavior> façonne ce qui se passe lorsqu'une étape échoue au milieu d'un scénario, et il a trois valeurs :

• end arrête l'exécution à la première étape échouée. Utilisez-le pour un test de fumée à échec rapide où vous voulez un feedback instantané dès que quelque chose se casse.
• continue exécute toutes les étapes restantes afin que vous puissiez collecter tous les échecs dans un seul rapport. Utilisez-le pour un balayage de régression où voir toutes les ruptures en une seule fois évite un aller-retour.
• ignore permet à l'exécution de se poursuivre au-delà d'une étape connue pour être fragile sans la traiter comme fatale. Utilisez-le avec parcimonie ; une étape ignorée ne devrait pas cacher une véritable régression.

De toute façon, si une assertion a échoué, l'exécution se termine toujours avec un code non nul, donc la porte tient quel que soit le comportement que vous avez choisi. Une chose qui brise discrètement la porte : envelopper la commande dans quelque chose qui avale son code de sortie, comme ajouter || true dans un shell. Ne le faites pas. La sortie non nulle est tout l'intérêt.

Quatre drapeaux ajustent le comportement des requêtes pendant l'exécution :

• --ignore-redirects empêche l'exécuteur de suivre automatiquement les redirections HTTP, ce qui vous permet d'effectuer des assertions sur la réponse de redirection elle-même.
• --delay-request [n] attend n millisecondes entre les requêtes, ce qui aide contre les limites de débit ou les points de terminaison sensibles à la charge.
• --timeout-request [n] plafonne le temps qu'une seule requête peut prendre, en millisecondes.
• --timeout-script [n] plafonne le temps qu'un script de pré- ou post-requête peut s'exécuter, en millisecondes.

# test de fumée : s'arrêter au premier échec
apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e 1629989 -r cli --on-error end

# régression : tout exécuter, collecter tous les échecs
apidog run --access-token $APIDOG_ACCESS_TOKEN -f 88012 -r html,junit --on-error continue --out-dir ./nightly-reports

TLS et certificats

Lorsque vous testez des points de terminaison derrière un TLS mutuel ou une autorité de certification interne, ce groupe est la façon dont vous établissez la connexion.

-k, --insecure désactive entièrement la vérification des certificats SSL. Utilisez-le uniquement contre un hôte interne de confiance avec un certificat auto-signé ; ne le pointez jamais vers quoi que ce soit de public, car cela désactive la vérification qui protège la connexion.

Pour un TLS mutuel correct, fournissez plutôt les identifiants client : --ssl-client-cert <path> pour le certificat PEM, --ssl-client-key <path> pour sa clé privée, et --ssl-client-passphrase <passphrase> si la clé est chiffrée. Lorsque différents hôtes nécessitent différents certificats, --ssl-client-cert-list <path> pointe vers un fichier de configuration qui les mappe. Et --ssl-extra-ca-certs <path> ajoute des certificats CA de confiance supplémentaires, ce qui est la solution propre pour une chaîne CA interne que l'exécuteur ne reconnaîtrait pas autrement, mieux que d'utiliser -k.

Sortie et diagnostics

Le dernier groupe contrôle ce que l'exécuteur affiche et quelques détails d'exécution.

--verbose affiche la requête et la réponse complètes pour chaque étape. C'est votre premier pas lorsqu'un scénario réussit localement mais échoue en CI : il montre les octets exacts que l'exécuteur a envoyés et reçus, afin que vous puissiez comparer avec ce que vous envoyez manuellement. --silent fait le contraire, supprimant la sortie console pour les travaux planifiés bruyants où vous ne vous souciez que du code de sortie et du rapport sauvegardé. --color <value> force la sortie colorée à être activée ou désactivée, utile lorsqu'un visualiseur de journaux CI corrompt les codes ANSI.

Les autres sont pour des fonctionnalités de scénario spécifiques :

• --external-program-path <path> pointe vers un fichier de programmes externes pour la logique personnalisée à laquelle un scénario fait appel.
• --database-connection <path> fournit une configuration de base de données pour les scénarios avec des étapes qui interrogent directement une base de données.
• --preferred-http-version <version> définit la version du protocole HTTP préférée par l'exécuteur.
• -b, --bigint active la gestion des BigInt pour que les grandes valeurs numériques ne perdent pas en précision.
• --lang <language> définit la langue d'affichage de l'interface CLI.
• -h, --help affiche le texte d'aide, qui est la liste faisant autorité pour votre version installée.

Assemblage : les commandes que vous exécuterez réellement

Test de fumée contre la production juste après un déploiement, en échec rapide :

apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e $PROD_ENV_ID -r cli --on-error end

Régression complète nocturne sur un dossier, tous les échecs dans un seul rapport HTML et JUnit :

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

Exécution pilotée par les données sur un CSV, sortie lisible par machine pour la CI :

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

Valider les modifications de test sur une branche de fonctionnalité avant leur fusion :

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

Déboguer un échec spécifique à la CI en affichant les détails du flux :

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

Si vous exécutez l'interface CLI sur un exécuteur CI éphémère et préférez ne pas l'installer globalement, remplacez l'installation par npx :

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

Cela couvre la même surface. Le choix entre une installation globale et npx concerne l'hygiène de l'exécuteur, et non ses capacités. Pour configurer le scénario que l'interface CLI exécute, Téléchargez Apidog, créez un scénario dans l'application, puis copiez la commande générée à partir de son onglet CI/CD et paramétrez le jeton.