Tests API basés sur les données avec l'Apidog CLI : Itérations CSV et JSON

Vous avez élaboré un scénario de test robuste pour votre point de terminaison de paiement. Il enchaîne trois requêtes, effectue des assertions sur chaque réponse et réussit chaque fois que vous cliquez sur Exécuter. Ensuite, votre pipeline a besoin qu'il couvre quarante combinaisons d'entrée, qu'il extrait les données d'un fichier géré par votre responsable AQ, et qu'il exécute le même scénario sur les environnements de staging et de production avec des identifiants différents. L'exécution en mode "pointer-cliquer" qui fonctionnait sur votre ordinateur portable ne s'y prête pas, et vous ne voulez pas cloner le scénario quarante fois.

Ce dernier kilomètre est ce que la ligne de commande gère. Avec Apidog, vous créez un scénario de test une seule fois dans l'éditeur visuel, puis vous l'exécutez depuis un terminal avec le package apidog-cli. L'option qui transforme un scénario en une exécution basée sur les données est -d, abréviation de --iteration-data. Elle prend un fichier CSV, un fichier JSON ou un ensemble de données que vous avez stocké dans votre projet Apidog, et exécute le scénario une fois par ligne, en liant les valeurs de chaque ligne aux variables référencées par vos requêtes.

button

Comment l'option `-d` lit un fichier

Toute la fonctionnalité réside dans une seule option. Voici la forme longue et courte, directement issue de apidog run --help :

-d, --iteration-data <path|testDataId>   Define the data which use for iterations (either JSON or CSV)

Ce <path|testDataId> est le détail que la plupart des gens manquent. L'argument est surchargé. Passez-lui un chemin et la CLI lit un fichier local depuis le disque. Passez-lui un ID de jeu de données de test et la CLI extrait un jeu de données que vous avez enregistré dans votre projet Apidog. Même option, deux sources, et l'exécuteur détermine celle que vous lui avez fournie.

La forme de fichier local est le point de départ courant. Pointez-la vers un fichier relatif à l'endroit où vous exécutez la commande :

apidog run --access-token $APIDOG_ACCESS_TOKEN \
  -t 605067 -e 1629989 \
  -d ./test-data/checkout-cases.csv -r cli

La CLI ouvre checkout-cases.csv, compte les lignes sous l'en-tête et exécute le scénario 605067 une fois par ligne. À chaque passage, elle lie les colonnes aux variables correspondantes dans vos requêtes, exécute le scénario et enregistre le résultat de cette itération. Quarante lignes, quarante passages, un scénario.

Le format suit le fichier. La même option accepte le JSON sans aucune option supplémentaire :

apidog run --access-token $APIDOG_ACCESS_TOKEN \
  -t 605067 -e 1629989 \
  -d ./test-data/checkout-cases.json -r cli

Vous n'indiquez pas à la CLI le format que vous utilisez. Elle lit l'extension et la forme du fichier. Cela signifie que vous pouvez remplacer un CSV par un tableau JSON en cours de projet sans toucher à la commande, tant que les noms de colonne et les clés JSON correspondent aux variables que votre scénario attend.

Ce que la CLI attend dans chaque fichier

Le CSV est le format pour les cas tabulaires simples. La ligne d'en-tête nomme vos variables. Chaque ligne en dessous représente une itération. Voici un exemple réel de checkout-cases.csv pour un point de terminaison de réduction :

sku,quantity,coupon,expected_status,expected_total
DESK-01,1,SAVE10,200,89.10
DESK-01,0,SAVE10,422,0
CHAIR-09,3,,200,447.00
DESK-01,1,EXPIRED,410,0
GHOST-99,1,SAVE10,404,0

Cinq colonnes deviennent cinq variables. Dans le corps de la requête, vous écrivez {{sku}} et {{quantity}} ; dans les assertions, vous comparez la réponse à {{expected_status}} et {{expected_total}}. L'exécuteur les lie par ligne. La cellule vide coupon de la troisième ligne devient une chaîne vide, ce qui correspond exactement au cas sans coupon que vous souhaitez couvrir.

Le JSON est le format à utiliser lorsque vos cas comportent une structure imbriquée qui se prête mal à un aplatissement en colonnes. Le fichier est un tableau d'objets, un objet par itération :

[
  {
    "label": "valid order, two items",
    "order": {
      "items": [
        { "sku": "DESK-01", "qty": 1 },
        { "sku": "CHAIR-09", "qty": 2 }
      ],
      "shipping": { "country": "US", "method": "ground" }
    },
    "expected_status": 200
  },
  {
    "label": "unshippable country",
    "order": {
      "items": [{ "sku": "DESK-01", "qty": 1 }],
      "shipping": { "country": "ZZ", "method": "ground" }
    },
    "expected_status": 422
  }
]

Dans le scénario, vous référencez {{order}} et {{expected_status}} de la même manière, et l'exécuteur transmet les champs de chaque objet à l'itération. Le champ label est pour vous. Il apparaît dans le rapport afin qu'un échec d'exécution indique « pays non livrable » au lieu de « itération 2 », ce qui fait la différence entre un diagnostic de cinq secondes et un de cinq minutes.

Quelques règles pour éviter que ces fichiers ne vous posent problème en CI :

Maintenez les noms d'en-tête identiques aux noms de variables dans votre scénario. Une colonne nommée qty ne se liera pas à une requête qui lit {{quantity}}. Cette incompatibilité est la raison la plus courante pour laquelle une exécution basée sur les données réussit localement et produit des valeurs vides dans le pipeline.
Mettez entre guillemets tout champ CSV contenant une virgule, ou convertissez ce fichier en JSON. Un champ de texte libre contenant une virgule se divise en deux colonnes et décale toutes les valeurs suivantes.
Placez le résultat attendu dans les données, pas dans le scénario. La ligne un attend 200, la ligne quatre attend 410. Si vous codez en dur l'attente dans l'assertion, vous revenez à un scénario par cas.
Commitez ces fichiers à côté de votre configuration de test afin qu'ils soient versionnés avec le code qu'ils testent. Le fichier de données fait partie du test, et non un artefact isolé.

Pour le côté JSONPath de l'écriture d'assertions qui lisent ces valeurs liées, la définition des assertions et l'extraction de variables à partir d'une réponse JSON explique la syntaxe en détail.

Exécuter à partir d'un jeu de données stocké au lieu d'un fichier

La deuxième forme de -d est celle qui n'apparaît pas dans la plupart des tutoriels. Au lieu d'un chemin, vous passez un ID de données de test :

apidog run --access-token $APIDOG_ACCESS_TOKEN \
  -t 605067 -e 1629989 \
  -d 38291 -r cli

Désormais, la CLI récupère le jeu de données avec cet ID depuis votre projet Apidog plutôt que de lire un fichier sur le disque de l'exécuteur. C'est utile lorsque les données résident avec l'équipe, et non avec le dépôt. Votre responsable AQ gère la table des cas dans Apidog, la modifie dans l'application, et chaque exécution CI récupère la version actuelle sans que personne n'ait à commettre un CSV. Le scénario, l'environnement et les données sont tous côté serveur ; la commande les nomme simplement par leur ID.

Le compromis est l'emplacement de votre source de vérité. Un CSV commité vous donne un jeu de données qui peut être comparé dans les requêtes de tirage et est lié au commit testé. Un ID de données de test stocké vous offre une table partagée unique que tout le monde modifie au même endroit. Aucune des deux n'est fausse. Choisissez le fichier commité lorsque les données doivent évoluer en même temps que le code, et l'ID stocké lorsque les données sont gérées par des personnes qui ne touchent pas au dépôt.

Exécuter hors ligne à partir d'un fichier exporté

Il existe une troisième façon d'alimenter la CLI, et cela modifie la forme de toute la commande. Vous pouvez exporter un cas de test depuis Apidog sous forme de fichier autonome et exécuter ce fichier directement, sans ID de scénario et sans aller-retour réseau pour récupérer le scénario :

apidog run ./checkout.apidog-cli.json -r cli,html

Ici, le premier argument est une file-source, le cas de test exporté lui-même, et non une option. La CLI exécute ce qui se trouve dans le fichier. Vous superposez toujours les données d'itération avec -d :

apidog run ./checkout.apidog-cli.json -d ./checkout-cases.csv -r cli,junit

Cela est important dans deux situations. La première est un exécuteur CI isolé ou verrouillé qui ne peut pas atteindre le cloud Apidog pour résoudre un ID de scénario ; le fichier exporté contient tout ce dont l'exécution a besoin. La seconde est la reproductibilité : le fichier exporté est un instantané figé du scénario au moment de l'exportation, de sorte qu'une exécution à partir de celui-ci n'est pas affectée par une modification ultérieure du scénario dans l'application. Pour les mécanismes d'installation et de première exécution, le guide d'installation de la CLI Apidog explique comment mettre en place le binaire, et la référence complète de la CLI Apidog documente chaque option dans un tableau.

Associer `-d` avec `-n` et les surcharges de variables

Les exécutions basées sur les données voyagent rarement seules. Trois options s'associent constamment à -d.

-n, --iteration-count définit le nombre de fois où le scénario s'exécute. Lorsque vous fournissez un fichier de données, le nombre de lignes détermine déjà les itérations, vous omettez donc généralement -n et laissez le fichier décider. Vous utilisez -n principalement lorsque vous souhaitez exécuter la table plus d'une fois, ou lorsque vous exécutez sans fichier de données du tout, comme un test de robustesse qui répète un scénario fixe :

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

--env-var et --global-var injectent des paires clé=valeur au moment de l'exécution sans toucher à l'environnement de votre projet. C'est ainsi que vous gardez les secrets et la configuration par pipeline hors du scénario et du fichier de données. Le fichier de données contient les cas de test ; les surcharges contiennent les éléments qui changent à chaque exécution :

apidog run --access-token $APIDOG_ACCESS_TOKEN \
  -t 605067 -e 1629989 \
  -d ./test-data/checkout-cases.csv \
  --env-var "base_url=https://staging.internal" \
  --global-var "api_key=$RUNTIME_API_KEY" \
  -r cli,junit

La séparation est délibérée. Les données d'itération sont la partie de l'exécution qui est la même partout : les cas que votre point de terminaison doit gérer. Les surcharges de variables sont la partie qui change par environnement : l'hôte, la clé, le locataire. Conservez les identifiants dans votre magasin de secrets CI et transmettez-les via --global-var à partir d'une variable d'environnement, comme le fait $RUNTIME_API_KEY ci-dessus. Ne les intégrez jamais dans le CSV, où toute personne ayant accès au dépôt pourrait les lire.

Lire les résultats par itération

Une exécution basée sur les données n'est utile que si vous pouvez identifier quelle ligne a échoué. Les options du rapporteur décident de ce que vous obtenez en retour.

apidog run --access-token $APIDOG_ACCESS_TOKEN \
  -t 605067 -e 1629989 \
  -d ./test-data/checkout-cases.csv \
  -r cli,junit --out-dir ./test-reports

-r cli imprime une ventilation lisible par itération dans le terminal, que vous scannez dans un journal de build. -r junit écrit un fichier XML JUnit, le format que presque tous les tableaux de bord CI analysent en un arbre de réussite/échec, de sorte qu'une ligne échouée apparaît comme un test échoué nommé au lieu d'un texte de journal enfoui. Vous pouvez également passer html et json ; html fournit un rapport navigable à archiver en tant qu'artefact de build, et json donne une sortie structurée brute si vous post-traitez les résultats. --out-dir contrôle l'emplacement où les fichiers sont enregistrés afin que vous puissiez les conserver en tant qu'artefacts.

Par défaut, l'exécution s'arrête à la première assertion échouée. Pour une large table de données, c'est généralement la mauvaise approche, car vous voulez voir toutes les lignes échouées en une seule passe, plutôt que d'en corriger une et de relancer pour trouver la suivante. Modifiez le comportement avec --on-error :

apidog run --access-token $APIDOG_ACCESS_TOKEN \
  -t 605067 -e 1629989 \
  -d ./test-data/checkout-cases.csv \
  --on-error continue \
  -r cli,junit --out-dir ./test-reports

--on-error continue exécute chaque itération même lorsque les précédentes échouent, de sorte qu'un seul rapport vous montre que les lignes deux, sept et dix-neuf sont défectueuses en une seule fois. L'exécution se termine toujours avec un code de sortie non nul si quelque chose a échoué, donc cela reste une véritable porte d'accès. --on-error end est le comportement par défaut de 'fail-fast' pour une vérification rapide ; ignore est pour l'étape rare et connue comme instable que vous ne voulez pas faire dérailler l'exécution.

Débugger une liaison qui ne fait rien discrètement

Le mode de défaillance qui fait perdre le plus de temps lors des exécutions basées sur les données n'est pas une assertion rouge. C'est une exécution verte qui n'a rien testé, car les données n'ont jamais été liées à la requête. La requête a été envoyée avec des valeurs vides, le point de terminaison a renvoyé un 200 pour une charge utile vide, et l'assertion a réussi par hasard. La couverture semble bonne ; ce n'est pas le cas.

Lorsqu'une exécution basée sur les données se comporte étrangement, ajoutez --verbose :

apidog run --access-token $APIDOG_ACCESS_TOKEN \
  -t 605067 -e 1629989 \
  -d ./test-data/checkout-cases.csv \
  --verbose -r cli

--verbose affiche la requête et la réponse complètes pour chaque itération. Examinez le corps de la requête réellement envoyé par l'exécuteur. Si vous voyez {{sku}} non substitué, ou une valeur vide alors que la cellule CSV ne l'était pas, la liaison a échoué. Trois causes habituelles, par ordre de fréquence :

Le nom de la colonne et le nom de la variable ne correspondent pas. L'en-tête CSV est product_sku et la requête lit {{sku}}. Renommez l'un des deux pour qu'ils soient identiques.
Une virgule mal placée a divisé une ligne CSV. Un champ de texte libre non mis entre guillemets a décalé toutes les colonnes suivantes, de sorte que expected_status contient maintenant ce qui devrait être dans la colonne suivante. Mettez le champ entre guillemets ou convertissez le fichier en JSON.
Le chemin d'accès au fichier de données est incorrect par rapport au répertoire de travail en CI. Il se résout correctement sur votre ordinateur portable et ne lit rien discrètement dans le pipeline. Utilisez un chemin relatif à la racine du dépôt produit par l'étape de checkout, et confirmez l'existence du fichier dans une étape précédant l'exécution.

Règle générale : lorsque les itérations réussissent mais que vous suspectez qu'elles ne devraient pas, lisez une requête détaillée avant de faire confiance au vert. Un test qui s'exécute sur une entrée vide est pire qu'aucun test, car il vous dit que tout va bien alors que le point de terminaison n'est pas testé.

Intégrer cela dans la CI

L'avantage est que toute la table s'exécute à chaque modification sans que personne n'ait à cliquer sur Exécuter. Voici une tâche GitHub Actions qui installe la CLI et exécute un scénario basé sur CSV à chaque pull request :

name: Data-driven API tests
on: [pull_request]

jobs:
  api-tests:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
      - name: Install Apidog CLI
        run: npm install -g apidog-cli
      - name: Run data-driven scenario
        env:
          APIDOG_ACCESS_TOKEN: ${{ secrets.APIDOG_ACCESS_TOKEN }}
        run: |
          apidog run --access-token $APIDOG_ACCESS_TOKEN \
            -t 605067 -e 1629989 \
            -d ./test-data/checkout-cases.csv \
            --on-error continue \
            -r cli,junit --out-dir ./test-reports
      - name: Upload report
        if: always()
        uses: actions/upload-artifact@v4
        with:
          name: api-test-report
          path: ./test-reports

Le jeton provient de secrets.APIDOG_ACCESS_TOKEN, défini une seule fois dans les paramètres du dépôt. --on-error continue rassemble toutes les lignes échouées dans un seul rapport au lieu de s'arrêter à la première. Le if: always() sur le téléchargement conserve le rapport même lorsque l'exécution échoue, ce qui est le moment où vous souhaitez le plus le lire. Remplacez le chemin CSV par un fichier JSON, ou par un ID de données de test stocké, et rien d'autre ne change.

Les trois mêmes étapes s'appliquent à n'importe quel système de CI : installer Node.js et la CLI, exposer le jeton en tant que variable d'environnement, appeler apidog run avec -d. GitLab CI, Jenkins, CircleCI et les autres n'ont pas besoin d'une réécriture de vos tests pour chaque plateforme. Pour une présentation plus approfondie du côté Actions, consultez l'automatisation des tests API dans GitHub Actions, et pour la surface complète des options de la CLI concernant les rapporteurs, la gestion des erreurs et TLS, le guide complet de la CLI Apidog détaille chaque option.

Un flux de travail qui s'adapte sans augmenter le test

Commencez avec un scénario et trois lignes. Construisez le scénario dans l'application avec des références de variables dans les requêtes et le résultat attendu dans les assertions. Rédigez un CSV avec un cas nominal, un échec connu et un cas limite. Exécutez-le localement avec -d jusqu'à ce que les trois itérations se comportent correctement.

Ensuite, développez les données, pas le scénario. Chaque rapport de bogue devient une nouvelle ligne avec le résultat attendu correct. Le bogue se transforme en un cas de régression permanent, et vous n'avez jamais écrit de nouveau test ; vous avez ajouté une ligne à un fichier. En quelques mois, ce fichier collecte les vrais problèmes que votre point de terminaison rencontre en production.

Enfin, intégrez la commande apidog run -d dans votre CI avec --on-error continue et le rapporteur junit. Désormais, une modification qui casse la ligne du coupon expiré fait échouer le build dès qu'elle est poussée, avec une itération nommée pointant directement vers le cas défectueux. Le scénario reste une chose petite et lisible, quelle que soit la taille de la table. C'est la victoire cumulée : la couverture augmente par l'entrée de données, et la maintenance reste stable.

Si vous hésitez encore à savoir si un exécuteur CLI comme celui-ci convient à votre pile par rapport à un framework basé sur le code, l'analyse dans quel outil choisir pour les tests API basés sur les données avec CSV ou JSON compare les approches, et Apidog CLI vs Newman couvre l'analogue de ligne de commande le plus proche du monde Postman.

Questions fréquemment posées

L'option -d peut-elle prendre à la fois un chemin de fichier et un jeu de données stocké ? L'option -d accepte l'un ou l'autre par exécution : un chemin de fichier CSV ou JSON local, ou un ID de données de test qui pointe vers un jeu de données enregistré dans votre projet Apidog. Vous passez une seule valeur. Utilisez le chemin du fichier lorsque les données doivent être versionnées avec votre dépôt, et l'ID stocké lorsque l'application contient une table partagée et que vous ne souhaitez pas commettre une copie.

Dois-je indiquer à la CLI si mon fichier est CSV ou JSON ? Non. L'exécuteur lit le format directement à partir du fichier, donc la même option -d gère les deux. Assurez-vous que les noms de vos colonnes (CSV) ou les clés de vos objets (JSON) correspondent aux noms de variables référencés par votre scénario, et vous pourrez changer de format sans modifier la commande.

Que se passe-t-il si j'utilise -d et -n ensemble ? Le nombre de lignes du fichier de données détermine le nombre d'itérations, donc -n est généralement superflu avec -d. Utilisez -n lorsque vous souhaitez répéter une exécution sans fichier de données, comme un test de robustesse, ou lorsque vous souhaitez spécifiquement exécuter toute la table plus d'une fois.

Pourquoi mon exécution basée sur les données a-t-elle réussi sans rien tester ? La cause la plus fréquente est une liaison qui n'a jamais eu lieu : un nom de colonne qui ne correspond pas au nom de variable, ou un chemin de fichier incorrect en CI qui n'a rien lu. Exécutez une fois avec --verbose et inspectez le corps de la requête envoyée par la CLI. Si vous voyez des {{variables}} non substituées ou des valeurs vides, corrigez l'incompatibilité de nom ou le chemin avant de faire confiance au résultat vert.

Comment puis-je garder les identifiants hors de mon fichier de données ? Gardez les jetons et les clés entièrement hors du CSV ou du JSON. Passez-les au moment de l'exécution avec --global-var ou --env-var depuis votre magasin de secrets CI, de la même manière que vous passeriez --global-var "api_key=$RUNTIME_API_KEY". Le fichier de données doit contenir les entrées de test et les résultats attendus, rien qui n'authentifie l'exécution.

Puis-je exécuter les mêmes données sur les environnements de staging et de production ? Oui. Gardez le scénario et le fichier de données fixes et changez la cible avec -e. Dirigez une vérification de pull request vers un ID d'environnement de staging et un test de fumée post-déploiement vers la production en utilisant le même scénario et les mêmes données, juste une valeur -e différente. Séparer l'environnement des données est la raison principale pour laquelle cela fonctionne.

En résumé

L'option -d représente l'intégralité de la fonctionnalité basée sur les données pour la CLI Apidog, et elle est plus flexible qu'il n'y paraît au premier abord. Elle lit un fichier CSV ou JSON local, ou un jeu de données stocké dans votre projet par ID. Elle s'associe à -n pour les répétitions, à --env-var et --global-var pour la configuration par exécution, et à --on-error continue afin qu'une seule exécution révèle chaque ligne en échec. Exécutez-la à partir d'un ID de scénario en ligne ou à partir d'un fichier exporté hors ligne, et lisez les résultats par itération via les rapporteurs junit et cli.

Créez le scénario une seule fois, décrivez chaque cas comme une ligne, et laissez l'exécuteur étendre votre couverture chaque fois que quelqu'un ajoute une ligne au fichier. Téléchargez Apidog, pointez apidog run vers votre premier fichier de données, et transformez un scénario unique en une table de cas qui s'exécute à chaque poussée.

Comment l'option -d lit un fichier