Vos tests d'API réussissent lorsque vous cliquez sur Exécuter sur votre ordinateur portable. Cela ne prouve rien. Le test qui compte est celui qui se déclenche à chaque pull request, à chaque fusion et à chaque build nocturne, sans qu'aucun humain ne soit présent pour cliquer sur quoi que ce soit. La tâche d'intégrer vos tests dans cette boucle incombe à un exécuteur en ligne de commande. Il prend les tests que vous avez déjà écrits, les exécute sans interface graphique dans votre pipeline, se termine avec un code de statut que votre CI peut lire, et rédige un rapport qui apparaît sur le tableau de bord de build.
Deux exécuteurs reviennent constamment lorsque les équipes mettent cela en place : le CLI Postman et le CLI Apidog. Ils visent la même cible à partir de points de départ différents. Le CLI Postman exécute les collections que vous créez dans Postman. Le CLI Apidog exécute les scénarios de test visuels que vous créez dans Apidog. Les deux s'installent en une seule étape, les deux s'intègrent à GitHub Actions, GitLab CI et Jenkins, et les deux mettent la build en échec (rouge) lorsqu'un test échoue. Les vraies différences se situent en amont de la commande d'exécution : comment vous rédigez les tests, comment vous vous authentifiez en CI, et où réside réellement la définition du test.
En bref
- CLI Postman (binaire `postman`) exécute les collections stockées dans votre espace de travail Postman. Il est basé sur Newman, signé et supporté par Postman, et s'authentifie avec une clé API Postman. Lorsque vous êtes connecté, il envoie automatiquement les résultats d'exécution au cloud Postman.
- CLI Apidog (`apidog-cli`, binaire `apidog`) exécute les scénarios de test que vous concevez visuellement dans Apidog. Vous le dirigez vers un scénario par ID avec un jeton d'accès, et il exécute ce scénario sans interface graphique.
- Les deux génèrent des rapports JUnit, JSON, HTML et terminal. Les deux font échouer la build en cas de test échoué. Le XML JUnit est ce qui s'intègre à un tableau de bord CI dans les deux cas.
- Choisissez le CLI Postman lorsque vos tests résident déjà dans les collections Postman et que votre équipe s'engage à utiliser le cloud Postman pour les rapports et l'historique.
- Choisissez le CLI Apidog lorsque vous souhaitez une création de scénarios visuelle, un chaînage de requêtes, une gestion d'environnement et des exécutions basées sur des données à partir d'une source unique de vérité, avec un contrôle total sur le fait que les rapports restent locaux ou aillent dans le cloud.
Le vrai problème : des tests qui existent mais ne sont jamais exécutés
Un test que vous exécutez manuellement est un test qui pourrit. Quelqu'un l'a écrit, il a réussi une fois, puis il est resté intouché pendant que l'API s'éloignait de lui. Trois mois plus tard, le test est erroné et personne ne l'a remarqué, car personne ne l'a exécuté. La solution n'est pas d'écrire plus de tests. C'est de faire en sorte que les tests que vous avez s'exécutent automatiquement à chaque changement, avec un signal de réussite ou d'échec sur lequel le pipeline peut agir.
Un exécuteur CLI est l'outil qui comble cette lacune. Pour mériter sa place en CI, il doit faire trois choses. Il doit s'exécuter sans interface graphique, car votre exécuteur CI n'a pas d'écran. Il doit se terminer avec un code de sortie non nul en cas d'échec, afin que la build devienne rouge et qu'une fusion défectueuse soit bloquée. Et il doit écrire un rapport lisible par machine, afin que le réviseur voie ce qui a échoué sans rien réexécuter localement. Le CLI Postman et le CLI Apidog franchissent tous deux cette barre sans problème. Là où ils divergent, c'est dans tout ce qui se passe avant `run` : comment le test a été écrit, et où il réside lorsque la CI le recherche.
Si vous mettez en place des tests automatisés à partir de zéro, les schémas plus larges de l'automatisation des tests API en CI/CD méritent d'être lus en parallèle de cet article. Ici, l'accent reste mis sur les deux exécuteurs.
Ce que le CLI Postman fait bien
Tout d'abord, un point de clarté qui déroute beaucoup de gens : le CLI Postman n'est pas Newman. Newman est l'ancien exécuteur open-source basé sur npm que la communauté utilise depuis des années. Le CLI Postman est un outil plus récent, construit sur la base de Newman, mais signé et officiellement supporté par l'entreprise Postman. Si vous utilisiez Newman, les deux ne sont pas interchangeables, et la différence est importante en CI. Nous avons détaillé cette distinction exacte dans Postman CLI vs Newman si vous hésitez entre les deux options côté Postman.
La plus grande force du CLI Postman est qu'il reste dans l'univers que votre équipe connaît déjà. Si vos collections, environnements et variables partagées résident déjà dans un espace de travail Postman, le CLI les exécute avec presque aucune traduction. Vous ne reconstruisez rien. Vous vous authentifiez, nommez la collection, et il exécute les requêtes et les tests exactement comme l'application le ferait.
Son installation est une seule commande. Sur macOS et Linux, vous exécutez le script d'installation officiel :
curl -o- "https://dl-cli.pstmn.io/install/unix.sh" | sh
Sous Windows, vous utilisez l'installateur PowerShell signé, et il existe également un paquet npm si vous préférez l'épingler comme dépendance de développement :
npm install -g postman-cli
Le binaire est `postman`. En CI, vous vous authentifiez avec une clé API Postman, ce qui est la méthode recommandée par Postman pour les pipelines :
postman login --with-api-key $POSTMAN_API_KEY
Ensuite, vous exécutez une collection par son ID, ou par un chemin de fichier local si vous l'avez exportée :
postman collection run $POSTMAN_COLLECTION_ID -e $POSTMAN_ENV_ID
La partie qui vaut au CLI Postman une grande loyauté est ce qui se passe après l'exécution. Lorsque vous êtes connecté, il envoie les résultats de l'exécution directement au cloud Postman, où ils apparaissent dans votre espace de travail à côté de la collection. L'historique des tests, les comparaisons d'exécutions et le tableau de bord visible par l'équipe sont tous là sans aucun effort supplémentaire. Pour une équipe qui vit déjà dans Postman, cet aller-retour est vraiment utile, et c'est une bonne raison de rester.
Ce que le CLI Apidog fait bien
Apidog emprunte une voie différente vers le même pipeline. Vous construisez des tests visuellement dans l'application Apidog : chaînez plusieurs requêtes en un seul scénario de test, ajoutez des assertions sur chaque réponse, extrayez une valeur d'une réponse et alimentez la requête suivante, et bouclez l'ensemble du scénario sur un fichier de données. Le CLI est l'exécuteur sans interface graphique pour ces scénarios. Il n'a pas son propre format de test. Il accède à votre projet Apidog, trouve le scénario que vous nommez par ID, et l'exécute exactement comme l'application le ferait, puis rend compte.
L'avantage est que personne ne maintient deux copies du même test. Le scénario que vous avez construit dans l'éditeur visuel est le test qui s'exécute en CI. Il n'y a pas d'étape où vous retranscrivez un test fonctionnel en script, puis déboguez le script. La boucle de création rapide et la boucle d'automatisation partagent une seule source de vérité. Pour les flux en plusieurs étapes (connexion, création, lecture, suppression), ce chaînage visuel économise une grande partie du code 'glue' que vous écririez autrement manuellement. Les mécanismes de construction de ces flux sont couverts dans le guide sur les scénarios de test pour l'automatisation des tests API.
L'installation est une seule commande npm :
npm install -g apidog-cli
Le binaire est `apidog`. Une exécution typique nomme un scénario par ID, sélectionne un environnement, définit un nombre d'itérations et s'authentifie avec un jeton d'accès :
apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e 1629989 -n 1 -r html,junit
Vous ne tapez pas ces ID à la main. Ouvrez le scénario de test dans Apidog, passez à son onglet CI/CD, cliquez pour générer un jeton d'accès, et Apidog construit la commande complète pour vous avec l'ID du scénario et l'ID de l'environnement déjà renseignés. Vous le copiez une fois, déplacez le jeton dans un secret CI, et le référencez comme `$APIDOG_ACCESS_TOKEN` dans votre workflow.
Le modèle basé sur le jeton et l'ID est la scission la plus claire avec le CLI Postman. Apidog exécute des tests stockés dans un projet que le CLI récupère sur le réseau, authentifié par le jeton. Il n'y a pas non plus d'option d'adhésion distincte au cloud pour les rapports : vous choisissez `--out-dir` pour les artefacts locaux et ajoutez `--upload-report` uniquement lorsque vous souhaitez qu'un aperçu soit poussé vers le cloud Apidog. Les rapports restent là où vous les placez.
Comparaison côte à côte
| Dimension | CLI Postman (`postman`) | CLI Apidog (`apidog`) |
|---|---|---|
| Paquet / installation | Script d'installation, installateur signé, ou `npm i -g postman-cli` | `npm i -g apidog-cli` |
| Commande d'exécution | `postman collection run <id|fichier>` | `apidog run -t <idScénario>` |
| Source des tests | Collections dans votre espace de travail Postman (ou fichier exporté) | Scénarios de test dans votre projet Apidog, récupérés par ID |
| Création | Éditeur de collection et l'application Postman | Constructeur de scénarios visuels dans l'application Apidog |
| Authentification en CI | Clé API Postman (`postman login --with-api-key`) | Jeton d'accès (`--access-token`) |
| Sélectionner ce qui s'exécute | ID de collection ou chemin de fichier | scénario `-t`, dossier `-f`, `--test-suite` |
| Environnement | `-e, --environment` | `-e, --environment <idEnvironnement>` |
| Piloté par les données | `-d, --iteration-data` (JSON ou CSV) | `-d, --iteration-data` (JSON ou CSV) |
| Itérations | `-n, --iteration-count` | `-n, --iteration-count` |
| Rapporteurs | `cli`, `json`, `junit`, `html` | `cli`, `html`, `json`, `junit` |
| Échec rapide | `--bail` | `--on-error end` (par défaut s'arrête à la première défaillance) |
| Rapports cloud | Envoie automatiquement les résultats une fois connecté | Optionnel via `--upload-report` |
| Basé sur | Newman | Moteur propre à Apidog |
Deux choses ressortent de ce tableau. Premièrement, les deux exécuteurs couvrent les éléments essentiels de la CI de manière presque identique : sélection d'environnement, itération pilotée par les données, les quatre formats de rapport importants, et une sortie non nulle en cas d'échec. Si tout ce dont vous avez besoin est un exécuteur qui passe au rouge lors d'une mauvaise fusion, l'un ou l'autre fait l'affaire. Deuxièmement, la vraie division concerne l'endroit où le test réside et comment vous l'avez écrit. Le CLI Postman exécute une collection qui se trouve dans votre espace de travail Postman. Le CLI Apidog exécute un scénario visuel qui se trouve dans votre projet Apidog.
Rapporteurs et codes de sortie : les éléments que la CI lit réellement
Un exécuteur prouve sa valeur dans un pipeline par deux comportements : le rapport qu'il écrit et le code de sortie qu'il renvoie. Maîtrisez ces deux aspects et tout le reste est une question de câblage.
Le CLI Postman accepte une liste de rapporteurs séparés par des virgules, et lorsque vous êtes connecté, il envoie également les résultats au cloud Postman :
postman collection run $POSTMAN_COLLECTION_ID \
-e $POSTMAN_ENV_ID \
--reporters cli,junit \
--bail
Le rapporteur `junit` est celui que votre tableau de bord CI analyse pour en faire un arbre de réussite ou d'échec. Le drapeau `--bail` arrête l'exécution à la première requête, test ou assertion échouée, ce qui permet un feedback rapide sur un test de fumée. Supprimez `--bail` et il exécute tout, puis rapporte toutes les défaillances ensemble. Le CLI se termine avec un code non nul en cas d'échec, de sorte que la build passe au rouge d'elle-même.
Le CLI Apidog utilise la même idée de rapporteur `-r` et écrit tout dans un seul répertoire de sortie :
apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 \
-r html,junit --out-dir ./apidog-reports
Son drapeau `--on-error` façonne le comportement en milieu de scénario : `end` s'arrête à la première défaillance et est le comportement par défaut, `continue` exécute chaque étape afin que vous puissiez collecter toutes les défaillances dans un seul rapport, et `ignore` passe outre une étape connue pour être instable sans faire dérailler l'exécution. Dans tous les cas, le processus se termine avec un code non nul si quelque chose a échoué, et le XML JUnit atterrit dans `./apidog-reports`, prêt à être récupéré par votre tableau de bord.
En pratique : les deux écrivent du XML JUnit, les deux font échouer correctement la build, et les deux archivent un rapport HTML que vous pouvez ouvrir plus tard. La différence dans la production de rapports est l'aller-retour vers le cloud. Postman pousse les résultats vers son cloud par défaut lorsque vous êtes authentifié. Apidog conserve les rapports localement, sauf si vous lui demandez de les télécharger. Aucun n'est intrinsèquement meilleur ; l'un convient aux équipes qui veulent un historique hébergé sans y penser, l'autre convient aux équipes qui veulent décider exactement ce qui quitte l'exécuteur.
Intégration de chacun dans GitHub Actions
La structure d'une tâche GitHub Actions est la même pour les deux : cloner le dépôt, configurer Node, installer le CLI, exécuter les tests, et le code de sortie en cas d'échec bloque la fusion. Stockez le secret dans les paramètres de votre dépôt, jamais dans le fichier de workflow.
Voici la version CLI Postman :
- name: Run API tests (Postman CLI)
run: |
curl -o- "https://dl-cli.pstmn.io/install/unix.sh" | sh
postman login --with-api-key ${{ secrets.POSTMAN_API_KEY }}
postman collection run $POSTMAN_COLLECTION_ID -e $POSTMAN_ENV_ID --reporters cli,junit --bail
Et la version CLI Apidog :
- name: Run API tests (Apidog CLI)
run: |
npm install -g apidog-cli
apidog run --access-token ${{ secrets.APIDOG_ACCESS_TOKEN }} -t 605067 -e 1629989 -r cli,junit
Les deux sont courts, les deux sont lisibles, et les deux se comportent de la même manière au niveau qui intéresse votre pipeline : une exécution réussie se termine avec un code zéro et la fusion se poursuit, une exécution échouée se termine avec un code non nul et la fusion est bloquée. Si vous souhaitez une présentation plus approfondie de l'exécution des tests API dans un workflow GitHub, l'automatisation des tests API avec GitHub Actions décrit les étapes une par une. Pour les utilisateurs de Jenkins, la même idée est exposée dans l'intégration des tests automatisés Apidog avec Jenkins.
Alors, lequel l'emporte en CI ?
Il n'y a pas de gagnant unique, car la bonne réponse dépend de l'endroit où vos tests résident déjà et de la manière dont votre équipe souhaite les créer et les stocker.
Le CLI Apidog l'emporte lorsque vous privilégiez la création visuelle et une source unique de vérité plutôt qu'un historique cloud hébergé. Vous construisez un scénario une fois dans l'éditeur visuel, avec le chaînage des requêtes et les assertions gérées pour vous, et le même scénario s'exécute en CI par référence. Vous décidez si les rapports restent locaux ou sont téléchargés. Et parce qu'Apidog couvre la conception, le mocking et la documentation dans le même espace de travail, le scénario de test se trouve à côté du contrat API qu'il vérifie, ce qui empêche les tests et les spécifications de diverger. Les équipes évaluant les plateformes plus largement peuvent lire la comparaison complète Apidog vs Postman.
Le CLI Postman l'emporte lorsque votre équipe est déjà dans Postman. Vos collections y sont, vos environnements y sont, et vous voulez l'historique des exécutions dans le cloud Postman sans rien configurer. L'aller-retour vers le cloud à chaque exécution est une réelle commodité pour cette configuration, et l'outil est officiellement signé et supporté. Si cela décrit votre équipe, changer d'exécuteur vous apportera peu.
Si vous vous sentez déjà enfermé par le modèle cloud de Postman, ou si vous voulez simplement créer des tests une seule fois et les exécuter partout, la voie est claire. Téléchargez Apidog, construisez un scénario, ouvrez son onglet CI/CD, et copiez la commande `apidog run` générée dans votre pipeline. C'est toute la configuration.
FAQ
- Le CLI Postman est-il le même que Newman ? Non. Newman est l'ancien exécuteur npm open-source. Le CLI Postman est un outil plus récent construit sur la base de Newman, signé et supporté par Postman, avec des rapports intégrés vers le cloud Postman. Si vous choisissez entre les deux du côté de Postman, Postman CLI vs Newman détaille les différences.
- Ai-je besoin d'un compte ou d'un jeton pour l'un ou l'autre CLI en CI ? Oui pour les deux, mais la forme diffère. Le CLI Postman s'authentifie avec une clé API Postman via `postman login --with-api-key`. Le CLI Apidog s'authentifie avec un jeton d'accès passé en tant que `--access-token`. Stockez l'un ou l'autre comme un secret CI, jamais dans le fichier de workflow.
- Les deux exécuteurs font-ils échouer la build en cas de test échoué ? Oui. Les deux se terminent avec un code de statut non nul en cas de test ou d'assertion échouée, ce qui indique à votre système CI de marquer la build en rouge et de bloquer la fusion. Le CLI Postman utilise `--bail` pour s'arrêter à la première défaillance ; le CLI Apidog utilise `--on-error end`, qui est son comportement par défaut.
- Puis-je conserver mes rapports localement au lieu de les envoyer à un cloud ? Le CLI Apidog conserve les rapports localement par défaut et les écrit dans `--out-dir` ; vous ne les téléchargez qu'avec `--upload-report`. Le CLI Postman écrit également des rapports locaux, mais lorsque vous êtes connecté, il envoie aussi automatiquement les résultats d'exécution au cloud Postman.
- Comment obtenir la commande d'exécution Apidog exacte pour mon scénario ? Ouvrez le scénario de test dans Apidog, passez à son onglet CI/CD, générez un jeton d'accès, et Apidog construira la commande `apidog run` complète avec l'ID du scénario et l'ID de l'environnement déjà renseignés. Copiez-la, déplacez le jeton dans un secret CI, et c'est fait. Pour chaque drapeau disponible, exécutez `apidog run --help`.
- Lequel une équipe migrant du cloud Postman devrait-elle choisir ? Si la raison de votre départ est le modèle centré sur le cloud ou la tarification, le CLI Apidog convient, car il exécute un seul scénario visuel de votre projet et vous permet de décider ce qui quitte l'exécuteur. Commencez par la comparaison Apidog vs Postman pour voir comment les plateformes s'alignent au-delà de l'exécuteur.