Vous avez écrit les tests d'API. Ils passent sur votre machine. Et c'est exactement là qu'ils restent, car les exécuter est une chose dont quelqu'un doit se souvenir. Un coéquipier déploie un changement le vendredi après-midi, le point de terminaison d'authentification commence discrètement à renvoyer une erreur 500 sur un chemin de code, et la première personne à le découvrir est un utilisateur le lundi. La couverture était là tout le temps. Personne ne l'a exécutée au moment où elle aurait pu détecter la régression.
La solution consiste à déplacer les tests de votre éditeur vers le pipeline, afin qu'ils s'exécutent à chaque `push` sans intervention humaine. Cela signifie que vous avez besoin d'une commande qui exécute vos tests d'API sans interface graphique, renvoie un succès ou un échec clair, et s'intègre dans le système CI que vous utilisez déjà. L'interface de ligne de commande (CLI) Apidog fait cela. Vous construisez vos scénarios de test visuellement dans Apidog, puis vous les exécutez à partir d'une simple commande de terminal que tout exécuteur CI avec Node.js peut exécuter. Pas d'interface graphique, pas de réécriture des tests sous forme de code, pas de service supplémentaire à héberger.
Ceci est un guide de copier-coller. Vous trouverez ci-dessous des fichiers de pipeline prêts à l'emploi pour GitHub Actions, GitLab CI, Jenkins, CircleCI et Azure Pipelines, ainsi que les quelques modèles qui garantissent l'intégrité d'une `build` verte. Prenez le bloc correspondant à votre plateforme, remplacez vos ID et un secret, et vous aurez des tests d'API bloquant chaque fusion d'ici la fin de la journée. Si vous préférez la référence exhaustive des drapeaux, le sujet plus vaste de l'automatisation des tests d'API en CI/CD couvre la stratégie ; cette page concerne l'intégration d'un pipeline fonctionnel par copier-coller.
Ce que vous connectez
L'interface de ligne de commande (CLI) Apidog est un package npm, apidog-cli. Elle exécute les scénarios de test que vous créez dans l'application Apidog : requêtes enchaînées, assertions, valeurs extraites d'une réponse à l'autre, itération basée sur les données. La CLI n'invente pas son propre format de test. Elle accède à votre projet, trouve le scénario par son ID, l'exécute de la même manière que l'application et renvoie un code de sortie.
Ce code de sortie est l'essentiel. Lorsque toutes les assertions réussissent, l'exécution se termine avec le code 0. Si quelque chose échoue, elle se termine avec un code non-nul. Les systèmes CI lisent ce code de sortie, marquent l'étape comme échouée et bloquent la fusion ou le déploiement. Vous ne configurez pas de 'gate' (barrière) ; la barrière est le code de sortie. Tant que l'étape apidog run est dans votre pipeline, une assertion échouée arrête le processus.
Trois éléments sont nécessaires pour qu'une exécution fonctionne, et vous les verrez dans chaque bloc ci-dessous :
- Un jeton d'accès, qui prouve que l'exécution est autorisée à exécuter votre scénario. Traitez-le comme un mot de passe. Stockez-le comme un secret CI, jamais dans un fichier commité.
- Un ID de scénario (ou ID de dossier, ou ID de suite de tests), qui indique ce qu'il faut exécuter.
- Un ID d'environnement, qui indique où l'exécuter : dev, staging, ou production.
Vous ne tapez pas ces ID à la main. Ouvrez le scénario de test dans Apidog, passez à son onglet CI/CD, choisissez l'option de ligne de commande et générez un jeton d'accès. Apidog vous fournit la commande complète apidog run avec l'ID de scénario et l'ID d'environnement déjà renseignés. Copiez-la une fois, puis déplacez le jeton dans un secret. Si vous n'avez pas encore construit de scénario, commencez par comment écrire des scénarios de test avec Apidog et revenez lorsque vous en aurez un qui passe.
La commande unique sur laquelle tout est construit
Voici l'exécution canonique. Chaque fichier de pipeline est un wrapper autour de cette ligne :
apidog run \
--access-token $APIDOG_ACCESS_TOKEN \
-t 605067 \
-e 1629989 \
-n 1 \
-r html,junit \
--out-dir ./apidog-reports
Ce que chaque élément fait :
--access-tokenauthentifie l'exécution. Il lit la variable d'environnement$APIDOG_ACCESS_TOKEN, que vous renseignez à partir d'un secret.-t 605067exécute le scénario de test avec cet ID. Remplacez-tpar-f <folderId>pour exécuter un dossier entier, ou--test-suite <id>pour exécuter une suite personnalisée.-e 1629989cible un environnement. C'est ainsi que le même scénario touche le `staging` lors d'une vérification de PR et la production lors d'un test de fumée post-déploiement.-n 1exécute le scénario une fois. Augmentez-le pour boucler, ou associez-le à-d <file>pour piloter des itérations à partir d'un fichier de données CSV ou JSON.-r html,junitchoisit les formats de rapport.junitémet le XML que votre tableau de bord CI analyse en une arborescence de succès/échec ;htmlest un rapport consultable que vous enregistrez comme artéfact de `build`. Ajoutezclisi vous souhaitez également une sortie lisible dans le journal.--out-dir ./apidog-reportsest l'endroit où les rapports sont enregistrés.
Les rapporteurs font la différence entre « la `build` est passée au rouge » et « voici l'assertion qui a échoué et la réponse qui l'a cassée ». Le XML JUnit est celui que presque toutes les plateformes comprennent nativement, il apparaît donc dans les cinq blocs ci-dessous.
GitHub Actions
Déposez ceci dans .github/workflows/api-tests.yml. Il exécute votre scénario à chaque demande de tirage (`pull request`) sur main, télécharge le rapport comme artéfact, et échoue la vérification si une assertion échoue.
name: API tests
on:
pull_request:
branches: [main]
jobs:
api-tests:
runs-on: ubuntu-latest
steps:
- name: Checkout
uses: actions/checkout@v4
- name: Set up Node.js
uses: actions/setup-node@v4
with:
node-version: '20'
- name: Install Apidog CLI
run: npm install -g apidog-cli
- name: Run API test scenario
run: |
apidog run \
--access-token "$APIDOG_ACCESS_TOKEN" \
-t 605067 \
-e 1629989 \
-n 1 \
-r html,junit \
--out-dir ./apidog-reports
env:
APIDOG_ACCESS_TOKEN: ${{ secrets.APIDOG_ACCESS_TOKEN }}
- name: Upload report
if: always()
uses: actions/upload-artifact@v4
with:
name: apidog-report
path: ./apidog-reports
Deux détails importants. Le jeton se trouve dans Paramètres → Secrets et variables → Actions sous le nom APIDOG_ACCESS_TOKEN et est accessible à l'étape via env:. Et if: always() sur l'étape de téléchargement signifie que vous obtenez toujours le rapport lorsque les tests échouent, ce qui est le seul moment où vous avez réellement besoin de le lire. Si un scénario échoue, l'étape apidog run se termine avec un code non-nul, le `job` passe au rouge, et la `PR` affiche une vérification échouée. Pour une exploration plus approfondie de cette plateforme spécifiquement, consultez comment automatiser les tests d'API dans GitHub Actions.
GitLab CI
Même idée dans .gitlab-ci.yml. L'image node:20 possède déjà l'environnement d'exécution, donc la seule configuration est l'installation.
stages:
- test
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
Stockez APIDOG_ACCESS_TOKEN sous Paramètres → CI/CD → Variables comme une variable masquée et protégée afin qu'elle n'apparaisse jamais dans un journal. Le bloc reports: junit: est la partie que les utilisateurs de GitLab ont tendance à manquer : il indique à GitLab d'analyser le XML et d'afficher les résultats directement dans le widget de demande de fusion (`merge request`). Un réviseur voit quelles assertions ont échoué sans rien télécharger.
Jenkins
Pour un pipeline déclaratif, stockez le jeton comme une information d'identification Jenkins et intégrez-le dans l'environnement, puis appelez la CLI dans une étape. Le bloc post alimente les graphiques de tendances de test de Jenkins avec le XML JUnit et conserve le rapport HTML sur la `build`.
pipeline {
agent any
environment {
APIDOG_ACCESS_TOKEN = credentials('apidog-access-token')
}
stages {
stage('API tests') {
steps {
sh 'npm install -g apidog-cli'
sh '''
apidog run \
--access-token $APIDOG_ACCESS_TOKEN \
-t 605067 \
-e 1629989 \
-n 1 \
-r html,junit \
--out-dir apidog-reports
'''
}
}
}
post {
always {
junit 'apidog-reports/*.xml'
archiveArtifacts artifacts: 'apidog-reports/**', allowEmptyArchive: true
}
}
}
Si vos agents de `build` ont déjà la CLI en cache, supprimez la ligne npm install et appelez apidog run directement. Apidog propose également un guide d'intégration spécifique à Jenkins si vous préférez la voie du plugin plutôt qu'une étape `shell` : intégrer les tests automatisés Apidog avec Jenkins pour la CI/CD.
CircleCI
Dans .circleci/config.yml, utilisez l'image pratique de Node et stockez le jeton comme variable d'environnement de projet sous Paramètres du projet → Variables d'environnement.
version: 2.1
jobs:
api-tests:
docker:
- image: cimg/node:20.11
steps:
- checkout
- run:
name: Install Apidog CLI
command: npm install -g apidog-cli
- run:
name: Run API test scenario
command: |
apidog run \
--access-token "$APIDOG_ACCESS_TOKEN" \
-t 605067 \
-e 1629989 \
-r junit,cli \
--out-dir ./apidog-reports
- store_test_results:
path: ./apidog-reports
- store_artifacts:
path: ./apidog-reports
destination: apidog-reports
workflows:
test:
jobs:
- api-tests
store_test_results est l'équivalent du bloc JUnit de GitLab pour CircleCI ; dirigez-le vers le répertoire de rapport et CircleCI affichera les assertions échouées dans son onglet Tests. store_artifacts maintient le rapport HTML attaché afin que vous puissiez l'ouvrir depuis la page de `build`.
Azure Pipelines
Dans azure-pipelines.yml, installez Node avec la tâche, exécutez la CLI et publiez les résultats JUnit. Ajoutez APIDOG_ACCESS_TOKEN comme variable secrète dans le pipeline (ou extrayez-la d'un groupe de variables Azure Key Vault), puis mappez-la dans l'env de l'étape de script.
trigger:
- main
pool:
vmImage: ubuntu-latest
steps:
- task: NodeTool@0
inputs:
versionSpec: '20.x'
displayName: 'Install Node.js'
- script: npm install -g apidog-cli
displayName: 'Install Apidog CLI'
- script: |
apidog run \
--access-token "$APIDOG_ACCESS_TOKEN" \
-t 605067 \
-e 1629989 \
-r junit,html \
--out-dir ./apidog-reports
displayName: 'Run API test scenario'
env:
APIDOG_ACCESS_TOKEN: $(APIDOG_ACCESS_TOKEN)
- task: PublishTestResults@2
condition: always()
inputs:
testResultsFormat: 'JUnit'
testResultsFiles: 'apidog-reports/*.xml'
testRunTitle: 'Apidog API tests'
La macro $(APIDOG_ACCESS_TOKEN) lit la variable secrète du pipeline ; son mappage via env la maintient hors de la ligne de commande visible. PublishTestResults@2 avec condition: always() fait apparaître les résultats dans l'onglet Tests, que l'exécution ait réussi ou échoué. Pour un traitement plus complet de cette plateforme, Apidog propose un guide détaillé sur les tests d'API de pipeline Azure DevOps.
Modèles qui maintiennent l'intégrité de la barrière
Un pipeline qui exécute vos tests est la base. Ces recettes sont ce qui le rend utile au quotidien.
Test de fumée juste après un déploiement. Exécutez un scénario rapide sur la production dès qu'une version est déployée, ciblant l'environnement de production, et arrêtez-vous à la première défaillance :
apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e <prodEnvId> -r cli --on-error end
Régression complète pendant la nuit. Exécutez un dossier entier de scénarios selon un calendrier et rassemblez chaque échec dans un seul rapport au lieu de vous arrêter au premier :
apidog run --access-token $APIDOG_ACCESS_TOKEN -f <folderId> -r html,junit --on-error continue --out-dir ./nightly-reports
--on-error est le réglage ici. end échoue rapidement, ce que vous voulez pour une barrière de déploiement. continue exécute chaque étape afin qu'un rapport nocturne montre toutes les défaillances en même temps. Dans tous les cas, l'exécution se termine toujours avec un code non-nul si quelque chose a échoué, donc la barrière est maintenue.
Exécutez un scénario avec de nombreuses entrées. Pilotez les itérations à partir d'un fichier de données et traitez chaque ligne comme sa propre exécution réussie :
apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -d ./test-data.csv -r junit
Testez une branche de fonctionnalité (`feature branch`), pas main. Exécutez les scénarios exactement tels qu'ils existent sur une branche :
apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 --branch feature-payments -e 1629989 -r cli
Déboguer un échec spécifique à la CI. Lorsqu'un scénario passe localement mais échoue dans le pipeline, ajoutez --verbose. Cela affiche la requête exacte envoyée par l'exécuteur et la réponse exacte qu'il a reçue, ce qui est presque toujours la façon de trouver la différence d'environnement qui cause l'écart.
Quand la `build` vous ment
Quelques modes d'échec apparaissent assez souvent pour être signalés, car chacun d'eux contourne discrètement la barrière.
La `build` reste verte alors qu'un test devrait échouer. C'est le cas le plus dangereux. Cela signifie presque toujours que le code de sortie est ignoré. Si vous avez enveloppé la commande dans un pipeline `shell`, ou ajouté || true pour « l'empêcher de casser la `build` », vous l'avez également empêchée de détecter quoi que ce soit. Supprimez tout ce qui masque le code de sortie non-nul. L'étape apidog run doit être ce que l'étape CI lit.
Erreurs d'authentification. Le jeton est incorrect, expiré ou n'a jamais atteint la commande. Confirmez que le secret CI est réellement renseigné (un écho masqué de sa longueur, jamais sa valeur), et régénérez-le depuis l'onglet CI/CD du scénario si nécessaire.
« Scénario non trouvé. » L'ID du scénario, l'ID du projet ou la branche ne correspondent pas. Recopiez la commande depuis l'onglet CI/CD pour vous assurer que les ID sont à jour, et vérifiez que --branch pointe là où vous le pensez.
Passe localement, échoue en CI. Presque toujours une différence d'environnement. L'exécuteur peut cibler un environnement -e différent, être derrière un pare-feu qui ne peut pas atteindre votre hôte, ou manquer une variable dont le scénario a besoin. Exécutez avec --verbose et comparez la requête produite par l'exécuteur à celle que vous envoyez localement.
Échecs TLS contre des hôtes internes. Si votre point de terminaison utilise une autorité de certification (CA) interne, transmettez le certificat CA supplémentaire plutôt que de désactiver la vérification. N'utilisez -k (ignorer la vérification SSL) qu'en dernier recours sur un hôte interne de confiance avec un certificat auto-signé, jamais contre quoi que ce soit de public.
Pourquoi construire visuellement et exécuter sans interface graphique
Il y a un véritable choix de conception derrière tout cela, et cela vaut la peine d'en parler. Avec les exécuteurs basés sur des scripts, le test et son exécution sont le même fichier, donc un script fragile est à la fois votre test et votre goulot d'étranglement. Avec Apidog, le scénario de votre projet est le test, et la CLI l'exécute simplement là où une personne ne peut pas être. Personne ne maintient deux représentations de la même vérification. Vous créez rapidement dans le constructeur visuel, vous exécutez automatiquement dans le pipeline, et les deux restent synchronisés car ils sont le même artefact. C'est une grande partie de la raison pour laquelle les équipes considèrent Apidog comme une alternative à Postman pour les tests d'API une fois que la CI entre en jeu, et pourquoi des assertions d'API solides sont plus importantes que l'exécuteur dans lequel vous les enveloppez.
La boucle est simple une fois qu'elle est en marche. Concevez et déboguez les requêtes dans l'application. Enchaînez-les dans un scénario avec des assertions. Poussez votre code, et la CLI exécute ce scénario en CI à chaque changement. Quand quelque chose se casse, le rapport nomme l'assertion et le code de sortie arrête le déploiement. Vous corrigez, poussez à nouveau, et la même barrière confirme la correction.
Si vos tests résident toujours dans l'éditeur de quelqu'un, c'est l'écart à combler cette semaine. Téléchargez Apidog, faites passer un scénario, copiez la commande apidog run depuis son onglet CI/CD, et collez le bloc ci-dessus pour votre plateforme. Vous aurez des tests d'API bloquant chaque fusion le même après-midi.
Questions fréquemment posées
L'interface de ligne de commande (CLI) Apidog est-elle gratuite pour une utilisation en CI ? La CLI est un package npm gratuit : npm install -g apidog-cli. Elle exécute les scénarios de votre projet Apidog, donc ce que vous pouvez exécuter dépend de votre plan Apidog, mais l'exécuteur en ligne de commande lui-même n'est pas un produit payant séparé.
Dois-je réécrire mes tests sous forme de code ? Non. Vous construisez des scénarios visuellement dans Apidog et la CLI les exécute par ID. Le scénario est le test ; la CLI n'est que l'exécuteur. C'est la principale différence avec les exécuteurs basés sur des scripts.
Comment un test échoué fait-il échouer ma `build` ? Par le code de sortie. Lorsqu'une assertion échoue, apidog run se termine avec un code non-nul. Votre système CI le lit, marque l'étape comme échouée et bloque la fusion ou le déploiement. Vous n'ajoutez aucune configuration supplémentaire pour que la barrière fonctionne.
Quel format de rapport dois-je utiliser ? Utilisez junit pour le XML lisible par machine que votre tableau de bord CI analyse en résultats de succès/échec, et ajoutez html si vous souhaitez un rapport consultable enregistré comme artéfact de `build`. Un couplage courant est -r junit,html. Gardez également cli activé si vous souhaitez une sortie lisible dans le journal de `build`.
Dois-je installer Apidog sur le serveur CI ? Non. L'exécuteur CI n'a besoin que de Node.js (v16 ou ultérieure) et du package apidog-cli. Pas d'application de bureau, pas d'interface graphique, pas de fichier de licence sur la machine. Le package plus un jeton d'accès suffisent.
Puis-je l'exécuter sans installation globale ? Oui. Utilisez npx apidog-cli run ... pour l'exécuter sans installation globale persistante, ce qui est plus propre sur les exécuteurs éphémères qui sont supprimés après chaque tâche.
En quoi cela diffère-t-il de Newman ? Newman exécute les collections Postman depuis la ligne de commande. La CLI Apidog exécute les scénarios de test Apidog. Les rôles sont parallèles, mais l'exécuteur Apidog exécute les scénarios que vous avez créés dans l'application et est livré sous forme de package unique apidog-cli. Voir Postman CLI vs Newman pour la partie Postman de cette comparaison.
Où puis-je obtenir le jeton d'accès et les ID ? Tout depuis l'onglet CI/CD du scénario de test dans Apidog. Choisissez l'option de ligne de commande, générez un jeton d'accès et copiez la commande complète apidog run qu'Apidog construit avec les ID de scénario et d'environnement déjà renseignés. Déplacez ensuite le jeton dans un secret CI et référencez-le comme $APIDOG_ACCESS_TOKEN.