Une exécution de test qui n'affiche rien d'utile est une exécution de test à laquelle personne ne fait confiance. Votre pipeline devient rouge, quelqu'un ouvre le journal de construction, et tout ce qu'il trouve est un mur d'horodatages et un code de sortie non nul. Quelle assertion a échoué ? Contre quel environnement ? Sur quelle ligne du fichier de données ? L'exécution le savait. Elle n'a simplement jamais rien écrit là où vous auriez pu le lire plus tard.
C'est cette lacune qu'un rapporteur comble. Lorsque vous exécutez des tests d'API en ligne de commande, le rapport est la partie avec laquelle vous vivez réellement : l'artefact que vous archivez, le fichier que votre tableau de bord CI analyse, la chose que vous donnez à un coéquipier à 9 heures du matin qui ne surveillait pas le pipeline à 2 heures du matin. Le verdict du test n'est que la moitié du travail. L'autre moitié consiste à rendre ce verdict lisible à la fois pour un humain et pour une machine.
L'exécuteur en ligne de commande Apidog gère les deux. Apidog fournit une CLI qui exécute les scénarios de test que vous avez construits visuellement dans l'application, et un seul drapeau contrôle chaque rapport qu'il produit : -r, --reporters. Vous lui passez une liste séparée par des virgules, l'exécuteur écrit chaque format sur le disque, et vous décidez qui lit quoi. Ce guide porte sur ce drapeau et les fichiers qu'il produit : à quoi sert chaque rapporteur, ce qui est écrit sur le disque, où il est écrit, et comment l'intégrer dans un flux de travail réel. Si vous souhaitez un aperçu plus large de tous les drapeaux acceptés par l'exécuteur, la référence de la commande apidog run couvre l'ensemble des fonctionnalités ; cette page se concentre sur les rapports.
Pourquoi le rapport est plus important que l'exécution
Exécutez un scénario localement et vous le voyez se dérouler. Vous voyez chaque requête se déclencher, chaque assertion passer au vert, le résumé à la fin. La boucle de rétroaction est le terminal devant vous, en direct.
En CI, cette boucle a disparu. L'exécution se déroule sur une machine que vous ne voyez jamais, à un moment où vous ne surveilliez pas, et le seul enregistrement est ce qui a été écrit sur le disque avant que l'exécuteur ne se termine. Si l'exécution n'a produit aucun rapport, un échec vous indique seulement que quelque chose a mal tourné. Il ne vous reste plus qu'à tout réexécuter localement en espérant que cela échoue de la même manière.
Un bon rapport réduit cette distance. Il capture quel scénario a été exécuté, contre quel environnement, combien d'itérations, quelles assertions ont réussi, lesquelles ont échoué, et les détails des requêtes et réponses derrière chaque échec. Obtenez cela sur le disque et un échec à 2 heures du matin devient une lecture de cinq minutes le lendemain matin au lieu d'une chasse à la reproduction. C'est la raison d'être du drapeau des rapporteurs, et c'est pourquoi choisir le bon format pour chaque public vaut la peine d'y consacrer quelques minutes de réflexion.
Le seul drapeau qui contrôle tous les rapports
L'interface de ligne de commande (CLI) d'Apidog est un package npm appelé apidog-cli. Installez-le une seule fois et vous obtenez un seul exécutable, apidog, dont la sous-commande principale est run. Installez-le globalement :
npm install -g apidog-cli
Chaque rapport que l'exécuteur peut produire provient d'un seul drapeau sur cette commande : -r, --reporters. Il prend une liste séparée par des virgules, et les quatre valeurs qu'il accepte sont cli, html, json et junit. La valeur par défaut, si vous ne passez rien, est cli.
Une exécution complète avec deux rapporteurs ressemble à ceci :
apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e 1629989 -n 1 -r html,cli
Cela authentifie avec un jeton, exécute le scénario de test 605067 contre l'environnement 1629989 une fois, et émet à la fois un fichier HTML et une sortie de terminal lisible. Les ID sont l'ID du scénario et l'ID de l'environnement ; vous copiez les deux, ainsi que le jeton d'accès, depuis l'onglet CI/CD du scénario dans Apidog plutôt que de les taper à la main. Si cette configuration ne vous est pas familière, le guide complet de l'Apidog CLI vous guide à travers l'installation, les jetons et votre première exécution de bout en bout.
L'idée clé : une seule exécution peut produire plusieurs rapports à la fois. Vous ne choisissez pas un format unique. Vous choisissez un public pour chaque sortie et les listez ensemble. Une ligne CI typique émet un fichier HTML lisible par un humain et un fichier JUnit lisible par une machine à partir de la même exécution, de sorte que la même exécution sert à la fois une personne et un tableau de bord.
cli : le rapport que vous lisez dans le journal de construction
Le rapporteur cli affiche un résumé lisible directement dans le terminal. C'est la valeur par défaut, et c'est celui qu'un humain scanne en premier.
apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e 1629989 -r cli
Ce qu'il vous donne est le verdict en direct : combien de requêtes ont été exécutées, combien d'assertions ont réussi et échoué, et quelles assertions spécifiques ont cassé. Dans un journal de construction CI, c'est le bloc que quelqu'un lit lorsqu'il clique sur un travail ayant échoué. Cela lui indique d'un coup d'œil si l'échec est dû à une assertion cassée ou à cinquante, et quel point de terminaison est impliqué, avant même de se donner la peine de télécharger quoi que ce soit.
Gardez cli activé même lorsque vous écrivez des formats machine. Cela ne coûte rien et cela maintient le journal de construction utile en soi. Un pipeline qui n'émet que du XML JUnit produit un tableau de bord parfait et un journal inutile ; quiconque lit la sortie brute ne voit rien d'autre que le démarrage et l'arrêt de l'exécuteur. L'ajout de cli à la liste corrige cela :
apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e 1629989 -r cli,junit --out-dir ./apidog-reports
Deux autres drapeaux modifient ce que cli affiche. --verbose l'étend à la requête et à la réponse complètes pour chaque étape, ce qui est votre première action lorsqu'un scénario passe sur votre ordinateur portable mais échoue dans le pipeline ; le détail du protocole réseau vous montre exactement ce que l'exécuteur a envoyé et reçu. --silent fait l'inverse et supprime entièrement la sortie de la console, ce qui convient à un travail planifié bruyant où vous ne vous souciez que du code de sortie et du fichier enregistré.
html : le rapport que vous donnez à un humain
Le rapporteur html écrit un fichier HTML autonome. Ouvrez-le dans n'importe quel navigateur et vous obtenez l'exécution complète présentée visuellement : chaque requête, les assertions qui lui sont associées, le statut de succès ou d'échec, et les détails de la requête et de la réponse derrière chaque étape. Rien à installer, aucun serveur à exécuter ; c'est un seul fichier sur lequel vous double-cliquez.
C'est le format que vous archivez et partagez. Enregistrez-le comme artefact de construction et le rapport survivra à l'exécution du pipeline, de sorte qu'une semaine plus tard, vous pourrez toujours ouvrir le rapport exact du déploiement qui a échoué. C'est aussi ce que vous envoyez à la personne qui demande « Qu'est-ce qui a échoué ? » sans la forcer à installer la CLI ou à réexécuter quoi que ce soit. Elle ouvre le fichier, voit l'étape rouge, lit le corps de la réponse qui a déclenché l'assertion, et c'est terminé.
L'HTML prend toute sa place lors d'une exécution axée sur les données. Lorsqu'un scénario boucle sur un fichier CSV de cinquante lignes, le rapport HTML vous montre le résultat par itération, afin que vous puissiez voir que les lignes 1 à 49 ont réussi et que la ligne 50 a échoué parce qu'un compte avait un jeton périmé. Un simple décompte de succès ou d'échec ne peut pas vous dire cela. Si vous exécutez des scénarios avec des fichiers de données, le modèle est couvert dans le test d'API piloté par les données avec CSV et JSON.
Le compromis : l'HTML est pour les yeux, pas pour l'analyse. N'essayez pas de l'analyser pour obtenir le statut de succès/échec dans un script. C'est à cela que servent JSON et JUnit.
junit : le rapport que votre tableau de bord CI analyse
Le rapporteur junit émet du XML au format standard JUnit. Ce format est important car c'est la lingua franca du reporting de tests CI. Presque tous les systèmes CI, GitHub Actions, GitLab CI, Jenkins, CircleCI, Azure Pipelines, savent lire le XML JUnit et le transformer en un arbre de succès/échec, afficher les échecs dans un widget de demande de fusion, et suivre les tendances des résultats à travers les builds au fil du temps.
apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e 1629989 -r junit --out-dir ./apidog-reports
Si vous choisissez un seul format machine pour la CI, choisissez celui-ci. L'avantage est que vos résultats de test ne vivent plus seulement dans un fichier journal et commencent à vivre dans le tableau de bord que votre équipe consulte déjà. Un réviseur ouvre une demande de fusion et voit quelles assertions ont échoué rendues en ligne, pas de fouille de journal, pas de téléchargement d'artefact.
La mise en œuvre se fait en deux étapes : produire le XML, puis indiquer à votre système CI où le trouver. Dans GitLab CI, cette deuxième étape est le bloc reports: junit: :
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
Dans Jenkins, l'équivalent est l'étape junit dans un bloc post pointant vers les mêmes fichiers. Dans GitHub Actions, vous téléchargez le répertoire en tant qu'artefact et laissez une action compatible JUnit le rendre. Le flux de travail GitHub complet, y compris le téléchargement d'artefacts qui s'exécute même lorsque les tests échouent, se trouve dans l'exécution des tests Apidog CLI dans GitHub Actions.
json : le rapport que vos scripts post-traitent
Le rapporteur json produit le résultat structuré brut. Là où l'HTML est pour les yeux et JUnit pour les tableaux de bord, JSON est pour le code que vous écrivez vous-même.
apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e 1629989 -r json --out-dir ./apidog-reports
Utilisez-le lorsque les formats intégrés ne correspondent pas à ce que vous voulez faire avec le résultat. Poussez les métriques de taux de réussite vers un système de surveillance. Créez un résumé Slack personnalisé. Alimentez le résultat dans un script qui décide de revenir en arrière sur un déploiement. Comparez l'exécution d'aujourd'hui avec celle d'hier. Tout ce qui est programmable commence par le JSON, car c'est le format que vous pouvez analyser sans deviner la structure.
Un drapeau de rapport est conçu spécifiquement pour la sortie JSON. --out-json-failures-separated <value> sépare les échecs dans leur propre fichier JSON. Cela vous donne un document ne contenant que les échecs, ce qui est beaucoup plus facile à lire et à comparer que de scanner un résultat complet pour les quelques étapes qui ont échoué. Lors d'un balayage de régression important où la plupart des étapes réussissent, un fichier ne contenant que les échecs fait la différence entre un coup d'œil rapide et une recherche par grep.
Où les fichiers sont déposés : --out-dir, --out-file et les espaces réservés
Choisir les formats n'est qu'une partie du tableau. L'autre moitié consiste à contrôler où les fichiers sont déposés et comment ils sont nommés, ce qui est important dès que vous conservez plus d'un rapport d'exécution.
--out-dir <dir> définit le répertoire dans lequel les rapports sont écrits. La valeur par défaut est ./apidog-reports. En CI, pointez-le vers un endroit que votre étape d'artefact peut trouver, et maintenez-le cohérent afin que votre configuration de téléchargement n'ait jamais à changer :
apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e 1629989 -r html,junit --out-dir ./apidog-reports
--out-file <name> définit le nom du fichier de rapport, et c'est là que cela devient utile. Sans cela, chaque exécution a tendance à écraser la précédente, de sorte que vous ne conservez toujours que le rapport le plus récent. Le drapeau accepte des espaces réservés que l'exécuteur remplit au moment de l'écriture :
{SCENARIO_NAME}devient le nom du scénario exécuté.{FOLDER_NAME}devient le nom du dossier lorsque vous exécutez un dossier de scénarios.{GENERATE_TIME}devient un horodatage.
Estampillez un nom de fichier avec le nom du scénario et un horodatage, et chaque exécution écrira un fichier distinct et auto-descriptif au lieu d'écraser le précédent :
apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e 1629989 -r html --out-file "{SCENARIO_NAME}-{GENERATE_TIME}"
Maintenant, votre répertoire de rapports se lit comme un historique. Vous pouvez savoir quel rapport provient de quel scénario et quand il a été exécuté sans ouvrir un seul fichier, ce qui est exactement ce que vous voulez lorsque vous parcourez un dossier d'exécutions nocturnes pour trouver celle où les choses ont commencé à mal tourner.
Un autre drapeau de rapport complète le côté cloud. --upload-report [value] télécharge un aperçu du rapport vers le cloud Apidog, de sorte que l'exécution apparaît également dans l'historique de votre projet à côté des fichiers locaux. C'est l'option à choisir lorsque vous souhaitez que le résultat soit visible à l'intérieur d'Apidog lui-même, et pas seulement comme un fichier sur le runner CI.
Une stratégie de rapporteur par public
La meilleure façon de décider est d'associer chaque rapporteur à son lecteur, puis de passer ceux dont vous avez besoin ensemble.
- Une personne consultant le journal de construction lit
cli. Incluez-le toujours. - Une personne ouvrant un rapport enregistré plus tard lit
html. Archivez-le comme un artefact. - Le tableau de bord CI lit
junit. C'est ce qui affiche les échecs dans la demande de fusion et les tendances des résultats sur les builds. - Un script que vous avez écrit lit
json. C'est le seul format destiné à être analysé par votre propre code.
Pour la plupart des pipelines CI, la combinaison la plus efficace est l'HTML pour les humains et JUnit pour le tableau de bord, avec CLI maintenu activé pour que le journal brut reste lisible :
apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e 1629989 -r cli,html,junit --out-dir ./apidog-reports
Cette seule exécution produit un journal lisible, un artefact consultable et un fichier XML analysable. Trois publics, une exécution, aucune duplication.
Une mise en garde mérite d'être clairement formulée : le rapport vous dit ce qui s'est passé, mais le code de sortie est ce qui fait agir le pipeline. L'Apidog CLI se termine avec un code non nul lorsqu'une assertion échoue, et c'est ce code de sortie, et non le rapport, qui fait échouer la construction et bloque la fusion. Le rapport explique l'échec ; le code de sortie l'applique. N'encapsulez pas la commande dans quoi que ce soit qui avale ce code, comme ajouter || true dans un shell, ou vous obtiendrez un rapport rouge parfait attaché à une construction qui est quand même passée au vert. La version plus approfondie de cette logique de porte de qualité se trouve dans le guide sur l'automatisation des tests API en CI/CD.
Mise en œuvre
Exécutez un scénario en CI et émettez les trois artefacts utiles pour trois publics :
apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e 1629989 -n 1 -r cli,html,junit --out-dir ./apidog-reports
Exécutez un balayage de dossier nocturne, collectez chaque échec dans un seul rapport et donnez à chaque fichier un nom auto-descriptif :
apidog run --access-token $APIDOG_ACCESS_TOKEN -f 88012 -r html,junit --on-error continue --out-dir ./nightly-reports --out-file "{FOLDER_NAME}-{GENERATE_TIME}"
Exécutez un scénario piloté par les données et conservez un JSON ne contenant que les échecs pour des comparaisons rapides :
apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -d ./accounts.csv -r json --out-json-failures-separated true --out-dir ./apidog-reports
Si vous préférez ne pas installer la CLI globalement sur un exécuteur éphémère, remplacez l'installation par npx et conservez les mêmes drapeaux de rapporteur :
npx apidog-cli run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e 1629989 -r html,junit --out-dir ./apidog-reports
Le comportement du rapporteur est identique dans les deux cas ; le choix entre une installation globale et npx concerne l'hygiène de l'exécuteur, et non les rapports que vous obtenez.
Les noms des drapeaux, les valeurs par défaut et les rapporteurs peuvent changer entre les versions de la CLI, donc l'exécuteur est toujours sa propre source de vérité. Exécutez apidog run --help sur la version que vous avez installée et fiez-vous à cela plutôt qu'à n'importe quel article, y compris celui-ci. Pour configurer le scénario que la CLI exécute en premier lieu, Téléchargez Apidog, construisez un scénario dans l'application, puis copiez la commande générée depuis son onglet CI/CD et ajoutez les rapporteurs dont vous avez besoin.