Comment exécuter des tests API paramétrés depuis CSV et JSON

Vous avez écrit un test de connexion. Il passe. Ensuite, un coéquipier pose la question évidente : passe-t-il pour le compte verrouillé, l'e-mail non vérifié, le mot de passe avec un espace de fin, la chaîne d'injection SQL que quelqu'un finira par coller dans le champ ? Vous avez maintenant un choix. Copier ce test cinq fois et modifier une valeur dans chaque copie, ou trouver un moyen de fournir au même test de nombreuses lignes d'entrée et de les exécuter toutes.

La méthode du copier-coller est la façon dont la plupart des suites de tests se corrompent. Cinq tests quasi-identiques divergent en un an. L'un reçoit une nouvelle assertion, les autres non. Un renommage de champ en casse quatre silencieusement. Vous finissez par maintenir cinq choses qui auraient dû n'en être qu'une. Les tests paramétrés corrigent cela à la racine : vous écrivez le test une fois, puis vous le dirigez vers une table d'entrées et de sorties attendues. Un scénario, des centaines de cas, un seul endroit à éditer.

bouton

Ce que signifient réellement les tests paramétrés

Les tests paramétrés, parfois appelés tests pilotés par les données, séparent la logique d'un test des données sur lesquelles il s'exécute. La logique est la séquence d'étapes : envoyer une requête, vérifier le code de statut, valider un champ dans la réponse. Les données sont l'ensemble des entrées et des attentes sur lesquelles vous souhaitez que cette logique s'exécute.

Imaginez un scénario de test unique pour un endpoint de code de réduction. La logique est toujours la même. Envoyer POST /api/orders avec un code, puis faire une assertion sur la réponse. Les données changent pour chaque cas :

code	total_commande	statut_attendu	remise_attendue
WELCOME10	100	200	10
WELCOME10	5	422	0
EXPIRED	100	410	0
(vide)	100	400	0
FAKE123	100	404	0

Cinq lignes, cinq comportements distincts, un seul test. L'exécuteur itère sur les lignes. À chaque passage, il lie les valeurs des colonnes à des variables, déclenche la requête et vérifie les assertions par rapport aux attentes de cette ligne. Si la ligne 3 échoue parce que le code expiré a renvoyé 200 au lieu de 410, vous obtenez un échec clair pointant vers une seule ligne. Vous n'avez pas à chercher dans cinq fichiers de test distincts pour comprendre quelle copie a échoué.

Ce modèle est particulièrement important aux limites. La couverture des cas nominaux est facile à écrire et attrape rarement le bug qui vous réveille à 2 heures du matin. Les bugs se trouvent dans les cas limites : la chaîne vide, le nombre négatif, le nom Unicode, le jeton expiré, la valeur qui dépasse d'un centime la limite. La paramétrisation rend l'ajout d'un cas limite aussi simple que l'ajout d'une ligne à une feuille de calcul.

Pourquoi un fichier de données séparé est préférable aux valeurs codées en dur

Vous pourriez coder en dur chaque cas directement dans le test. La plupart des gens commencent par là. Le problème apparaît plus tard.

Lorsque les données se trouvent dans le test, un non-ingénieur ne peut pas contribuer à des cas. Votre responsable QA connaît quinze entrées délicates qui ont déjà cassé ce endpoint, mais il ne peut pas les ajouter sans modifier le code et ouvrir une pull request. Lorsque les données se trouvent dans un CSV, il modifie une feuille de calcul et la valide. La barrière tombe à presque zéro.

Un fichier séparé rend également votre scénario de test lisible. Un test qui boucle sur un fichier externe est court : une requête, quelques assertions, terminé. Un test avec trente cas en ligne est un mur de répétition que personne ne veut toucher. Et lorsque vous devez générer des cas par programme, par exemple un millier de lignes extraites des journaux de production, un fichier est la seule option sensée. Vous ne pouvez pas coller un millier de cas dans le corps d'un test.

Le format que vous choisissez dépend de la forme de vos données. Les cas plats et tabulaires conviennent au CSV. Les charges utiles imbriquées ou structurées conviennent au JSON. Les deux sont des entrées de première classe dans le moteur d'exécution d'Apidog, le choix dépend donc de vos données, et non des limitations de l'outil.

Configuration de votre fichier de données

Commencez par le CSV pour les cas tabulaires. La ligne d'en-tête nomme vos variables ; chaque ligne en dessous est une itération. Voici le tableau des codes de réduction sous forme de fichier réel, discount-cases.csv :

code,order_total,expected_status,expected_discount
WELCOME10,100,200,10
WELCOME10,5,422,0
EXPIRED,100,410,0
,100,400,0
FAKE123,100,404,0

Chaque en-tête de colonne devient une variable que vous référencez à l'intérieur du test. Dans le corps de la requête, vous écrivez {{code}} et {{order_total}} ; dans les assertions, vous comparez avec {{expected_status}} et {{expected_discount}}. L'exécuteur effectue la liaison ligne par ligne.

Lorsque vos entrées sont imbriquées, utilisez le JSON. Un tableau d'objets, un objet par itération, permet à chaque cas de transporter des données structurées qui seraient difficiles à aplatir en colonnes. Voici user-cases.json pour un endpoint de création d'utilisateur où la charge utile a des champs imbriqués :

[
  {
    "scenario": "valid full profile",
    "user": {
      "email": "ada@example.com",
      "roles": ["admin", "billing"],
      "profile": { "country": "US", "timezone": "America/New_York" }
    },
    "expected_status": 201
  },
  {
    "scenario": "missing email",
    "user": {
      "email": "",
      "roles": ["viewer"],
      "profile": { "country": "GB", "timezone": "Europe/London" }
    },
    "expected_status": 400
  },
  {
    "scenario": "unknown role",
    "user": {
      "email": "grace@example.com",
      "roles": ["wizard"],
      "profile": { "country": "CA", "timezone": "America/Toronto" }
    },
    "expected_status": 422
  }
]

À l'intérieur du test, vous référencez les valeurs structurées avec la même syntaxe {{user}}, {{expected_status}}, et Apidog transmet les champs de chaque objet à l'itération. La colonne scenario est une étiquette pour vous-même ; elle apparaît dans le rapport afin qu'une itération échouée affiche "rôle inconnu" au lieu de "itération 3".

Quelques règles permettent d'éviter que les fichiers de données ne vous posent problème :

Gardez une seule préoccupation par fichier. Un fichier de codes de réduction et un fichier de création d'utilisateurs sont deux fichiers, pas un seul avec des colonnes mélangées.
Placez le résultat attendu dans les données, pas dans le test. Tout l'intérêt est que la ligne 2 attend un 422 tandis que la ligne 1 attend un 200. Si l'attente est codée en dur, vous revenez à un test par cas.
Mettez entre guillemets tout ce qui contient une virgule dans un CSV, ou passez ce fichier au format JSON. Un champ de texte libre avec des virgules est le piège classique du CSV.
Stockez ces fichiers dans votre dépôt à côté du reste de votre configuration de test afin qu'ils soient versionnés en même temps que le code qu'ils exercent.

Création du scénario paramétré dans Apidog

Dans l'application Apidog, créez le scénario de test une seule fois, comme n'importe quel autre. Ajoutez la requête à votre endpoint. Dans le corps, remplacez les valeurs littérales par des références de variables : {{code}}, {{order_total}}, etc. Ce sont les colonnes de votre fichier de données.

Ajoutez ensuite les assertions qui lisent à partir du même fichier. Pour l'exemple de la réduction, vous affirmeriez que le statut de la réponse est égal à {{expected_status}} et que le champ de réduction dans le corps JSON est égal à {{expected_discount}}. Parce que l'entrée et la sortie attendue proviennent de la ligne, la même logique d'assertion valide correctement chaque cas. Si vous n'avez jamais écrit d'assertions dans Apidog auparavant, Assertions API : un guide pratique couvre les modèles, et comment définir des assertions et extraire des variables d'une réponse JSON montre le côté JSONPath en détail.

Pour intégrer les données, ouvrez les paramètres d'exécution du scénario de test et attachez votre fichier CSV ou JSON comme source de données d'itération. Apidog lit le fichier, compte les lignes et exécute le scénario une fois par ligne, en liant les colonnes de chaque ligne aux variables correspondantes. Exécutez-le dans l'application et vous obtiendrez un aperçu par itération : quelles lignes ont réussi, quelles ont échoué, et la valeur réelle par rapport à la valeur attendue pour chaque assertion échouée.

C'est aussi là que la paramétrisation se compose avec le reste de votre suite. Un scénario paramétré est toujours un scénario, vous pouvez donc en regrouper plusieurs dans une suite de tests et exécuter l'ensemble comme une seule tâche. La boucle pilotée par les données gère l'étendue au sein d'un seul endpoint ; la suite de tests gère la couverture sur l'ensemble des endpoints.

Exécution depuis la ligne de commande

L'application est l'endroit où vous construisez et déboguez. La CI est l'endroit où le test prend tout son sens, s'exécutant sur chaque pull request sans que personne n'ait à cliquer sur un bouton. Cette transition est ce à quoi sert l'Apidog CLI. Il prend le scénario que vous avez construit dans l'application et l'exécute sans interface graphique depuis un terminal, avec les mêmes données d'itération.

Le CLI est fourni en tant que package npm. Installez-le globalement :

npm install -g apidog-cli

L'exécutable est apidog, donc chaque commande commence par apidog run. Une exécution de base pointe vers un scénario par ID et un environnement par ID :

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

Pour piloter ce scénario à partir d'un fichier de données, ajoutez l'option d'itération de données. Il accepte un chemin vers un fichier JSON ou CSV :

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

L'option -d (forme longue --iteration-data) est le cœur des exécutions paramétrées depuis la ligne de commande. Apidog lit le fichier, exécute le scénario une fois par ligne et rapporte chaque itération. Remplacez discount-cases.csv par user-cases.json et la même option gère le tableau JSON ; l'exécuteur détecte le format à partir du fichier. Traitez le jeton d'accès comme un mot de passe et stockez-le comme un secret CI, jamais dans un fichier validé. C'est pourquoi chaque exemple fait référence à $APIDOG_ACCESS_TOKEN plutôt qu'à une valeur littérale.

Quelques options se combinent naturellement avec les exécutions paramétrées :

-d, --iteration-data <chemin> pointe l'exécution vers votre fichier CSV ou JSON. C'est celle qui transforme une exécution en un seul passage en une exécution pilotée par les données.
-n, --iteration-count <n> exécute le scénario un nombre fixe de fois. Lorsque vous fournissez un fichier de données, le nombre de lignes pilote généralement les itérations, vous utilisez donc -n principalement pour les cas de répétition sans données, comme les tests de charge.
-r, --reporters <liste> choisit les formats de sortie. Utilisez cli pour une sortie lisible dans les journaux de build et junit pour émettre le XML que les tableaux de bord CI analysent en un arbre de réussite/échec par itération.
--out-dir <chemin> définit l'emplacement des rapports afin que vous puissiez les archiver en tant qu'artefacts de build.

Si vous souhaitez la liste actuelle et officielle des options pour votre version installée, exécutez apidog run --help. Le CLI imprime chaque option avec sa forme courte et longue.

Intégration des exécutions paramétrées dans la CI

La raison d'investir dans les tests paramétrés est qu'ils rapportent automatiquement. Voici un job GitHub Actions qui installe le CLI et exécute un scénario piloté par CSV sur chaque pull request :

name: 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 parameterized API tests
        env:
          APIDOG_ACCESS_TOKEN: ${{ secrets.APIDOG_ACCESS_TOKEN }}
        run: |
          apidog run --access-token $APIDOG_ACCESS_TOKEN \
            -t 605067 -e 1629989 \
            -d ./tests/discount-cases.csv \
            -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 de votre dépôt. Le rapporteur junit écrit du XML que la plupart des tableaux de bord CI transforment en un arbre de résultats par itération, de sorte qu'une ligne défaillante apparaît comme un test défaillant nommé plutôt qu'un mur de texte de journal. Le if: always() sur l'étape de téléchargement signifie que vous conservez le rapport même en cas d'échec de l'exécution, ce qui est exactement ce que vous voulez. Pour une présentation plus approfondie du côté Actions, consultez comment automatiser les tests API dans GitHub Actions.

Le même scénario et le même fichier de données s'exécutent dans n'importe quel système CI. GitLab CI, Jenkins, CircleCI et les autres se réduisent tous aux trois mêmes étapes : installer Node et le CLI, exposer le jeton en tant que variable d'environnement, appeler apidog run avec -d. Il n'y a pas de réécriture de vos tests par plateforme.

Comparaison des approches de tests paramétrés

Apidog n'est pas la seule façon d'exécuter des tests API pilotés par les données. Il est utile de connaître le paysage pour choisir la bonne solution.

Postman et ses exécuteurs prennent également en charge les fichiers de données. Avec le Collection Runner de Postman ou l'outil en ligne de commande Newman, vous attachez un fichier CSV ou JSON et référencez les variables {{colonne}} dans les requêtes, un peu comme le modèle ici. C'est une approche performante et bien documentée. L'inconvénient est que votre logique de test réside dans les scripts JavaScript de pré-requête et de test, de sorte qu'à mesure que vos assertions augmentent, vous maintenez plus de code. Si vous comparez spécifiquement les exécuteurs en ligne de commande, Postman CLI vs Newman expose les différences.

Les frameworks axés sur le code comme pytest avec @pytest.mark.parametrize, @ParameterizedTest de JUnit, ou REST Assured vous donnent un contrôle total sur le langage de programmation. Ce sont les bons choix lorsque votre logique de test a véritablement besoin de code : configuration complexe, génération de données personnalisée, couplage étroit avec une base de code de test existante. Le coût est que chaque cas vit dans le code, de sorte que les non-ingénieurs ne peuvent pas contribuer, et vous maintenez vous-même la plomberie HTTP.

L'angle d'Apidog est que le scénario est visuel et les données sont externes, de sorte que la logique reste lisible et les cas restent accessibles à quiconque peut modifier une feuille de calcul, tandis que le même scénario s'exécute toujours sans interface graphique en CI. Si vous choisissez spécifiquement un outil pour les exécutions pilotées par les données CSV et JSON, la comparaison dans quel outil pour les tests API pilotés par les données avec CSV ou JSON approfondit les compromis. Aucune de ces approches n'est mauvaise. Adaptez l'approche à qui écrit les cas et à la quantité de logique personnalisée dont chaque cas a besoin.

Un flux de travail pratique qui s'adapte

Voici à quoi cela ressemble une fois que cela fait partie de la routine de votre équipe.

Commencez par un champ d'action limité. Choisissez un endpoint qui vous a déjà posé problème. Écrivez le scénario unique dans Apidog avec des références de variables dans la requête et le résultat attendu dans les assertions. Construisez un CSV avec trois lignes : un cas nominal, un échec connu, un cas limite. Exécutez-le dans l'application jusqu'à ce que les trois itérations se comportent comme prévu.

Ensuite, développez les données, pas le test. Chaque fois qu'un rapport de bug arrive, ajoutez l'entrée qui l'a causé comme une nouvelle ligne avec son résultat attendu correct. Le bug devient un cas de régression permanent et vous n'avez jamais écrit un nouveau test, vous avez ajouté une ligne à un fichier. En quelques mois, le fichier accumule les bizarreries du monde réel auxquelles votre endpoint est réellement confronté.

Enfin, automatisez-le. Intégrez la commande apidog run -d dans la CI afin que l'ensemble du tableau s'exécute à chaque pull request. Désormais, un changement qui rompt le chemin du code expiré fait échouer le build au moment où il est poussé, avec une itération nommée pointant directement vers la ligne défaillante.

L'avantage cumulatif est la maintenance. Lorsque la forme de la réponse de l'endpoint change, vous corrigez l'assertion une seule fois et chaque cas bénéficie de la correction. Lorsque vous avez besoin de cinquante cas supplémentaires, vous ajoutez cinquante lignes. La logique de test reste une chose unique, petite et lisible, quelle que soit l'étendue de votre couverture.

Foire aux questions

Quelle est la différence entre les tests paramétrés et les tests pilotés par les données ? Ils décrivent la même idée et les gens utilisent les termes de manière interchangeable. Les deux signifient exécuter un test de manière répétée avec différentes entrées et sorties attendues fournies de l'extérieur du test. "Paramétré" met l'accent sur le mécanisme de liaison des paramètres ; "piloté par les données" met l'accent sur la source de données externe. En pratique, traitez-les comme des synonymes.

Dois-je utiliser CSV ou JSON pour mon fichier de données ? Adaptez le format à la forme de vos données. Les cas plats et tabulaires où chaque ligne a les mêmes colonnes simples conviennent au CSV, et le CSV est plus facile à éditer dans une feuille de calcul pour les non-ingénieurs. Les charges utiles imbriquées ou structurées, comme un corps de requête avec des tableaux et des sous-objets, conviennent au JSON. Apidog lit les deux comme des données d'itération, alors choisissez celui qui représente vos cas sans contorsion.

Des centaines d'itérations vont-elles ralentir mon pipeline ? Chaque ligne est une exécution du scénario, donc le temps total est proportionnel au nombre de lignes multiplié par la latence par requête. Pour la plupart des tests API, cela représente des secondes, pas des minutes. Si un grand ensemble de données étend votre build, divisez-le : exécutez un sous-ensemble rapide de tests de fumée sur chaque pull request et le tableau complet sur une tâche nocturne ou de pré-publication. Le même scénario et le même fichier alimentent les deux ; seul le sous-ensemble de données change.

Comment garder les secrets hors de mes fichiers de données et de ma configuration de test ? Gardez les identifiants entièrement hors du fichier de données. Les jetons et les mots de passe appartiennent aux variables d'environnement ou au stockage de secrets de votre système CI, référencés comme $APIDOG_ACCESS_TOKEN et similaires. Le fichier de données doit contenir les entrées de test et les résultats attendus, pas les informations d'authentification. Quiconque peut lire le dépôt peut lire le CSV, alors traitez-le comme tel.

Puis-je exécuter le même scénario paramétré sur la pré-production et la production ? Oui. Gardez le scénario et le fichier de données fixes, et changez d'environnement avec l'option -e. Pointez une vérification de pull request vers la pré-production et un test de fumée post-déploiement vers la production en utilisant le même ID de scénario et les mêmes données, juste un ID d'environnement différent. C'est la raison pour laquelle l'environnement et les données sont des entrées séparées.

En résumé

Les tests API paramétrés transforment la couverture d'une tâche de copier-coller en une tâche de saisie de données. Vous écrivez le test une fois, décrivez chaque cas comme une ligne dans un fichier CSV ou JSON, et laissez l'exécuteur faire le reste. La logique reste petite et lisible, les cas restent accessibles à tous les membres de l'équipe, et la CI exécute l'ensemble du tableau à chaque changement.

Apidog vous offre le constructeur de scénarios visuel pour l'édition, des fichiers CSV et JSON externes pour les données, et la commande apidog run -d pour l'exécution sans interface graphique dans n'importe quel système CI. Créez un scénario, pointez-le vers une table de cas croissante, et votre couverture de test s'élargit chaque fois que quelqu'un ajoute une ligne. Téléchargez Apidog et transformez votre prochain test ponctuel et instable en un scénario paramétré qui s'adapte.

bouton