Comment exécuter des tests API automatisés dans Azure Pipelines (Guide étape par étape)

Votre API fonctionne sur votre ordinateur portable. Elle passe toutes les vérifications dans votre client de test local. Ensuite, un coéquipier fusionne une branche, le déploiement est effectué, et un point de terminaison qui renvoyait auparavant 200 commence à renvoyer 500 en production. Personne ne l'a remarqué, car personne n'a exécuté les tests sur cette branche. Ils les ont exécutés sur une machine, une fois, manuellement.

Cet écart, entre « les tests existent » et « les tests s'exécutent à chaque changement », est précisément ce qu'un pipeline CI comble. Si votre code réside déjà dans Azure Repos ou GitHub et que votre équipe développe sur Azure DevOps, Azure Pipelines est l'endroit naturel pour installer ce filet de sécurité. La partie difficile est rarement le YAML. Il s'agit de mettre votre suite de tests API sous une forme que le pipeline peut exécuter sans interface, avec le bon environnement, contre une version fraîchement déployée, puis de faire échouer la construction bruyamment lorsque quelque chose ne va pas.

TL;DR

• Azure Pipelines exécute automatiquement vos tests d'API à chaque commit ou PR, de sorte que les régressions sont détectées avant le déploiement.
• Créez vos scénarios de test visuellement dans Apidog, puis exécutez-les en CI avec l'Apidog CLI (apidog-cli) au lieu d'écrire et de maintenir des scripts de test manuellement.
• Le pipeline a besoin de quatre choses : Node.js installé sur l'agent, l'interface de ligne de commande (CLI) installée, votre scénario de test accessible via un lien ou un fichier exporté, et un jeton d'accès stocké comme secret.
• Un code de sortie non nul de la CLI fait échouer la construction automatiquement. C'est ce qui vous donne une véritable barrière.
• Publiez le rapport HTML ou JUnit comme artefact de pipeline (ou via PublishTestResults) afin que n'importe qui puisse lire les succès/échecs sans ouvrir les journaux.

Ce que signifie réellement « test d'API automatisé dans Azure Pipelines »

Azure Pipelines est le service CI/CD au sein d'Azure DevOps. Vous décrivez une construction dans un fichier YAML (azure-pipelines.yml) qui réside dans votre dépôt, et Azure exécute ce fichier sur un agent hébergé ou auto-hébergé chaque fois qu'un déclencheur se déclenche ; un push, une pull request, une planification, ou une exécution manuelle.

Pour les tests d'API, la tâche est simple dans sa forme :

1. Démarrer un agent (une VM propre).
2. Installer tout ce dont votre exécuteur de tests a besoin.
3. Exécuter les tests d'API contre un environnement cible.
4. Rapporter les résultats et définir l'état de la construction en fonction de ceux-ci.

Le détail qui pose problème aux gens est l'étape 3. Un client API local est interactif ; vous cliquez sur « Envoyer », vous examinez la réponse, vous voyez une coche verte. Un pipeline n'a personne pour cliquer et personne pour examiner. Vous avez besoin d'un moyen d'exécuter les mêmes assertions sans humain et sans interface graphique. C'est la raison pour laquelle un exécuteur en ligne de commande existe.

Si vous souhaitez une introduction plus large aux concepts de CI ici, la différence entre intégration continue, livraison continue et déploiement continu vaut la peine d'être lue rapidement avant de configurer votre premier pipeline.

Pourquoi concevoir des tests dans Apidog et les exécuter avec la CLI

Vous pourriez écrire des tests d'API en code brut. Choisir un langage, importer une bibliothèque HTTP et un framework d'assertion, créer manuellement des corps de requête, analyser les réponses, gérer les jetons d'authentification, et maintenir tout cela en synchronisation avec une API qui change à chaque sprint. Les équipes le font. Elles passent également une quantité de temps disproportionnée à le maintenir.

Apidog adopte une approche différente. Vous construisez des scénarios de test visuellement : enchaîner les requêtes, passer des données d'une réponse à la requête suivante, ajouter des assertions sur les codes de statut, les en-têtes et les champs JSON, et piloter le même scénario avec plusieurs lignes de données. Parce qu'Apidog détient déjà vos définitions d'API, les tests restent proches de la spécification. Lorsque le schéma change, vous voyez la dérive au lieu de la découvrir en production.

L'élément qui relie ce travail visuel à la CI est l'Apidog CLI, un exécuteur en ligne de commande publié sur npm. Il exécute un scénario de test enregistré sans interface graphique et se termine avec un code de statut qui reflète le résultat : 0 si tout a réussi, non nul si une assertion a échoué. Ce code de sortie est le contrat que chaque système CI comprend. Azure Pipelines le lit et décide si la construction est verte ou rouge. Vous concevez une fois dans l'interface graphique, et le même scénario s'exécute sans modification dans le pipeline.

C'est le même modèle qui fonctionne pour GitHub Actions, GitLab CI et Jenkins. Azure Pipelines n'est qu'un autre hôte pour la même commande CLI, ce qui signifie que les connaissances sont transférables si votre équipe change un jour de plateforme.

Prérequis

• Un projet Apidog avec au moins un scénario de test. Ouvrez la section Scénarios de test, créez un scénario, ajoutez quelques requêtes et associez des assertions. Exécutez-le une fois localement et confirmez qu'il passe. S'il est instable sur votre machine, il le sera en CI.
• Un jeton d'accès Apidog. La CLI s'authentifie avec un jeton d'accès personnel de vos paramètres de compte Apidog. Traitez-le comme un mot de passe ; vous le stockerez comme secret de pipeline, jamais dans le YAML.
• Un projet Azure DevOps avec un dépôt. Votre azure-pipelines.yml se trouvera à la racine du dépôt.
• Familiarité avec Node.js (légère). La CLI fonctionne sur Node, donc l'agent a besoin de Node installé. Les agents hébergés d'Azure l'ont déjà ; vous choisirez simplement une version.
• Un environnement cible accessible. Vos tests doivent interroger une API en cours d'exécution ; une URL de staging, un déploiement de prévisualisation, ou un service que le pipeline démarre lui-même. Décidez lequel avant d'écrire le déclencheur.

Une note rapide sur la cible à tester. Exécuter la suite contre la production à chaque commit est risqué et souvent impossible (vous ne voulez pas de données de test en production). La plupart des équipes dirigent les tests CI vers un environnement de staging ou un déploiement de prévisualisation par branche. Les environnements Apidog facilitent cela : maintenez un environnement Staging avec sa propre URL de base et ses variables, et indiquez à la CLI lequel utiliser au moment de l'exécution.

Étape 1 : Mettre votre scénario de test sous une forme exécutable

La CLI doit savoir quel scénario exécuter. Apidog vous offre deux façons de le lui fournir.

Option A, exécuter à partir d'un lien en ligne partagé. Dans Apidog, ouvrez votre scénario de test, choisissez de l'exécuter via la CLI, et Apidog génère une commande qui pointe vers le scénario sur le réseau. C'est l'option nécessitant moins de maintenance : le pipeline exécute toujours la version actuelle du scénario, et vous ne commitez pas de fichiers de test dans le dépôt. L'inconvénient est que le pipeline dépend de la capacité de ce lien à être accessible au moment de l'exécution.

Option B, exporter le scénario vers un fichier et le commiter. Exportez le scénario (et son environnement) vers un fichier local, commitez-le à côté de votre code, et dirigez la CLI vers le chemin du fichier. Cela lie le test à un commit spécifique, ce que vous voulez si la reproductibilité vous importe ; les tests exécutés sont exactement les tests de ce commit. L'inconvénient est que vous devez réexporter le scénario lorsqu'il change.

Pour la plupart des équipes qui débutent, l'Option A est plus rapide à mettre en œuvre. Pour un travail réglementé ou soumis à des audits rigoureux, la reproductibilité de l'Option B est un avantage. Vous pouvez également mélanger : basé sur les liens pour les branches de fonctionnalités qui évoluent rapidement, basé sur les fichiers pour les branches de publication.

Dans tous les cas, notez la commande d'exécution exacte qu'Apidog vous donne. Elle ressemblera à ceci :

apidog run https://api.apidog.com/api/v1/test-scenarios/<scenario-id> \
 -t <access-token> \
 -e <environment-id>

Les drapeaux sur lesquels vous vous appuierez le plus :

• la référence du scénario (un lien en ligne ou un chemin de fichier local),
• -t / jeton d'accès pour l'authentification,
• -e pour l'environnement contre lequel exécuter,
• une option de rapport pour contrôler le format de sortie (texte CLI, HTML, ou un résumé lisible par machine),
• un nombre d'itérations lorsque vous souhaitez que le scénario parcourt un ensemble de données.

Confirmez les noms exacts des drapeaux par rapport à la commande d'exécution qu'Apidog génère pour votre scénario ; l'exécuteur affiche l'utilisation avec apidog run --help. Ne devinez pas les drapeaux ; copiez ceux qu'Apidog vous fournit et paramétrez les secrets.

Étape 2 : Vérifier d'abord que la CLI fonctionne localement

Ne déboguez jamais un nouvel outil à l'intérieur de la CI. Les boucles de rétroaction des pipelines sont lentes et les journaux sont plus bruyants que votre terminal. Obtenez d'abord une exécution réussie sur votre propre machine.

Installez la CLI :

npm install -g apidog-cli

Ensuite, exécutez votre scénario :

apidog run https://api.apidog.com/api/v1/test-scenarios/<scenario-id> \
 -t "$APIDOG_ACCESS_TOKEN" \
 -e "<staging-environment-id>"

Vous vérifiez trois choses :

1. La commande se termine et affiche un résumé succès/échec.
2. Le code de sortie correspond au résultat. Exécutez echo $? juste après ; il doit être 0 en cas de succès et non nul en cas d'échec.
3. L'environnement a été résolu correctement ; les requêtes ont atteint votre URL de staging, et non une URL locale obsolète.

Cette vérification du code de sortie est plus importante qu'il n'y paraît. Si la CLI se termine avec 0 même lorsqu'une assertion échoue, votre pipeline sera vert sur du code cassé, ce qui est pire que de n'avoir aucun test du tout. Forcez un échec une fois (cassez une assertion exprès) et confirmez que vous obtenez un code non nul. Ensuite, remettez l'assertion en place.

Étape 3 : Créer le fichier YAML d'Azure Pipelines

Ajoutez un fichier nommé azure-pipelines.yml à la racine de votre dépôt. Point de départ complet et fonctionnel pour un agent Ubuntu hébergé :

trigger:
 branches:
 include:
 - main
 - develop

pr:
 branches:
 include:
 - main

pool:
 vmImage: ubuntu-latest

variables:
 NODE_VERSION: '20.x'

steps:
 - task: NodeTool@0
 inputs:
 versionSpec: $(NODE_VERSION)
 displayName: 'Install Node.js'

 - script: npm install -g apidog-cli
 displayName: 'Install Apidog CLI'

 - script: |
 apidog run https://api.apidog.com/api/v1/test-scenarios/$(SCENARIO_ID) \
 -t $(APIDOG_ACCESS_TOKEN) \
 -e $(STAGING_ENV_ID)
 displayName: 'Run API tests'

En le parcourant :

• trigger exécute le pipeline à chaque push sur main et develop. Adaptez aux noms de vos branches.
• pr l'exécute sur les pull requests ciblant main. C'est la barrière qui empêche la fusion d'une branche défectueuse.
• pool / vmImage sélectionne un agent Ubuntu hébergé par Microsoft. Aucune infrastructure à gérer.
• NodeTool@0 installe une version spécifique de Node, rendant vos exécutions reproductibles.
• L'étape d'installation télécharge la CLI à chaque exécution. Pour des constructions plus rapides, vous pouvez mettre en cache node_modules ou épingler une version, mais commencez simplement.
• L'étape d'exécution est celle qui compte. Si une assertion échoue, apidog run sort avec un code non nul, la tâche de script échoue, et toute la construction devient rouge.

Les références $(...) sont des variables de pipeline. SCENARIO_ID, STAGING_ENV_ID, et surtout APIDOG_ACCESS_TOKEN proviennent de l'étape suivante, ils ne sont pas codés en dur ici.

Étape 4 : Stocker les secrets correctement

Votre jeton d'accès ne doit jamais apparaître en clair dans le fichier YAML. Toute personne ayant un accès en lecture au dépôt le verrait, et il donne accès à votre projet Apidog.

Utilisez une variable de pipeline secrète :

1. Dans Azure DevOps, ouvrez votre pipeline et choisissez Modifier, puis Variables (ou Bibliothèque pour un groupe de variables partagé).
2. Ajoutez APIDOG_ACCESS_TOKEN et collez le jeton.
3. Activez l'icône de cadenas pour le marquer comme secret. Azure le chiffre et le masque dans les journaux.

Les variables secrètes ne sont pas injectées automatiquement dans l'environnement shell ; vous les mappez explicitement dans l'étape. Mettez à jour l'étape d'exécution pour passer le secret via env :

 - script: |
 apidog run https://api.apidog.com/api/v1/test-scenarios/$(SCENARIO_ID) \
 -t $(APIDOG_ACCESS_TOKEN) \
 -e $(STAGING_ENV_ID)
 displayName: 'Run API tests'
 env:
 APIDOG_ACCESS_TOKEN: $(APIDOG_ACCESS_TOKEN)

SCENARIO_ID et STAGING_ENV_ID n'ont pas besoin d'être secrets ; traitez-les comme des variables simples pour la lisibilité, ou déplacez-les dans un groupe de variables que vous réutilisez dans différents pipelines. Pour les équipes gérant de nombreux secrets, appuyez le groupe de variables sur Azure Key Vault afin que la rotation se fasse en un seul endroit.

Étape 5 : Publier un rapport de test lisible

Une construction rouge vous indique que quelque chose est cassé. Cela ne vous dit pas quoi. La solution consiste à faire en sorte que la CLI émette un rapport et qu'Azure l'affiche.

L'Apidog CLI peut écrire ses résultats dans un fichier de rapport. Indiquez-lui un format de sortie (HTML pour les humains, un XML de style JUnit si vous voulez la vue de test native d'Azure) et un répertoire de sortie, puis publiez ce répertoire.

Pour un artefact lisible par l'homme :

 - script: |
 apidog run https://api.apidog.com/api/v1/test-scenarios/$(SCENARIO_ID) \
 -t $(APIDOG_ACCESS_TOKEN) \
 -e $(STAGING_ENV_ID) \
 -r html \
 --out-dir $(Build.ArtifactStagingDirectory)/api-report
 displayName: 'Run API tests'
 env:
 APIDOG_ACCESS_TOKEN: $(APIDOG_ACCESS_TOKEN)

 - task: PublishBuildArtifacts@1
 condition: always()
 inputs:
 pathToPublish: $(Build.ArtifactStagingDirectory)/api-report
 artifactName: api-test-report
 displayName: 'Publish API test report'

Deux choses à noter. Premièrement, condition: always() fait en sorte que l'étape de publication s'exécute même lorsque l'étape de test échoue ; c'est tout l'intérêt, car vous voulez le rapport surtout quand quelque chose s'est cassé. Deuxièmement, vérifiez le drapeau exact du rapporteur (-r, --reporter, ou similaire) et l'option de sortie par rapport à apidog run --help pour votre version de CLI, puis ajustez l'exemple en conséquence.

Si vous préférez voir les résultats dans l'onglet Tests intégré d'Azure avec des graphiques de tendance, demandez à la CLI d'émettre du XML JUnit et ajoutez une tâche PublishTestResults@2 pointant vers le XML. Cela vous donne un historique par assertion sur les constructions, et pas seulement un fichier ponctuel.

Étape 6 : Rendre la barrière réelle

Configurer le pipeline n'est pas la même chose que de l'appliquer. Par défaut, une construction échouée n'empêche personne de fusionner, sauf si vous indiquez à Azure DevOps de l'exiger.

Mettez en place une politique de branche sur main :

1. Allez dans Dépôts, puis Branches, trouvez main, et ouvrez les Politiques de branche.
2. Ajoutez une validation de construction et sélectionnez votre pipeline.
3. Définissez-la comme obligatoire.

Maintenant, une pull request ne peut pas fusionner dans main tant que le pipeline de tests d'API n'est pas passé. C'est la différence entre des tests qui s'exécutent et des tests qui protègent. Tant que vous n'activez pas cela, vous avez un tableau de bord ; après, vous avez une barrière.

Un exemple réaliste basé sur les données

Les scénarios à un seul coup détectent les pannes évidentes. Les API réelles nécessitent que le même point de terminaison soit exercé avec de nombreuses entrées ; des charges utiles valides, des cas limites, la requête mal formée qui devrait renvoyer 400 au lieu de 500.

Apidog prend en charge les tests basés sur les données : attachez un jeu de données CSV ou JSON à un scénario, et il s'exécute une fois par ligne, en substituant les valeurs de la ligne dans les requêtes et les assertions. Un scénario de connexion, par exemple, pourrait exécuter des lignes pour un utilisateur valide, un mot de passe erroné, un compte bloqué et un corps vide, chacun avec son propre code de statut attendu.

Dans le pipeline, rien ne change quant à la forme de la commande ; vous appelez toujours apidog run sur le même scénario. Le jeu de données voyage avec le scénario, donc une seule invocation de la CLI couvre chaque ligne. Lorsque vous ajoutez un nouveau cas limite dans Apidog, la prochaine exécution du pipeline le prend en compte sans modification du YAML. C'est le bénéfice de maintenir la logique de test dans l'outil plutôt que dans le pipeline : le pipeline reste ennuyeux pendant que votre couverture augmente.

Problèmes courants et comment les résoudre

La construction passe même si un point de terminaison est cassé. Presque toujours un problème de code de sortie. Confirmez que la CLI renvoie un code non nul en cas d'échec (Étape 2), et assurez-vous que vous ne l'étouffez pas ; un || true à la fin ou un script multi-commandes qui se termine par une commande différente masquera l'échec. Gardez l'appel apidog run comme dernière commande significative dans son bloc de script.

apidog: command not found. L'étape d'installation ne s'est pas exécutée, s'est exécutée après l'étape de test, ou s'est installée dans un chemin que le shell de l'agent ne peut pas voir. Confirmez que npm install -g apidog-cli apparaît avant l'étape d'exécution. Sur certains agents auto-hébergés, le bin npm global n'est pas dans le PATH ; installez localement et appelez-le via npx apidog run ... à la place.

L'authentification échoue en CI mais fonctionne localement. Le secret n'atteint pas l'étape. Les variables secrètes doivent être mappées via env: (Étape 4) ; elles ne sont pas injectées automatiquement. Vérifiez également que le jeton n'a pas été collé avec un saut de ligne ou une citation finale.

Les tests ciblent le mauvais environnement. La valeur -e pointe vers le mauvais environnement Apidog, ou l'URL de base de l'environnement fait toujours référence à localhost. Maintenez un environnement Staging dédié dont les variables se résolvent en URLs accessibles et sûres pour la CI, et passez son ID explicitement.

Réussite/échec aléatoire entre les exécutions. Généralement un état mutable partagé ; un test qui crée un enregistrement, et une exécution ultérieure qui entre en collision avec lui. Rendez les scénarios autonomes : créez ce dont vous avez besoin, affirmez, puis nettoyez, ou utilisez des identifiants uniques par exécution afin que les réexécutions ne butent pas sur les données d'hier. Si vous migrez depuis un autre outil, les modèles dans comment exécuter des tests d'API en CI sans Newman couvrent les mêmes pièges d'isolation.

Au-delà des bases

Une fois le pipeline principal solide, quelques extensions s'avèrent payantes :

• Planifiez une exécution nocturne. Ajoutez un déclencheur schedules pour exécuter la suite complète à 2 heures du matin sur l'environnement de staging, afin de détecter les dérives dues aux changements de données ou aux modifications d'API tierces, même les jours où personne ne pousse de code.
• Séparez les suites rapides et lentes. Exécutez un scénario de fumée rapide sur chaque PR pour un retour d'information rapide, et la suite de régression complète sur les fusions vers main. Deux définitions de pipeline, la même CLI.
• Testez plusieurs environnements dans une matrice. Utilisez une matrice de pipeline pour exécuter le même scénario sur l'environnement de staging et un environnement de pré-production en parallèle, chacun avec son propre ID d'environnement.
• Protégez le déploiement, pas seulement la fusion. Placez l'étape de test API avant votre étape de déploiement dans un pipeline multi-étapes, afin qu'un test échoué arrête la publication, et pas seulement la fusion.

Chacune de ces extensions est un petit ajout à la même fondation : une CLI qui se termine proprement et un pipeline qui respecte le code de sortie.

Questions fréquemment posées

Ai-je besoin d'écrire du code pour exécuter des tests d'API dans Azure Pipelines ? Non. Vous construisez les scénarios de test visuellement dans Apidog et le pipeline les exécute avec une seule commande CLI. Le seul « code » est le fichier azure-pipelines.yml lui-même, qui est une configuration, pas une logique de test. Si vous préférez des tests entièrement basés sur des scripts, vous pouvez toujours le faire, mais l'objectif de ce flux de travail est de l'éviter.

Puis-je exécuter mes collections Postman existantes dans Azure Pipelines à la place ? Oui, généralement avec Newman ou un exécuteur similaire. Si vous évaluez les options, Apidog importe directement les collections Postman, vous pouvez donc importer les tests existants et les exécuter via la même CLI sans maintenir une chaîne d'outils séparée. Voir comment exécuter des tests d'API en CI sans Newman pour la comparaison.

Où les tests doivent-ils pointer ; staging ou production ? Staging ou un environnement de prévisualisation par branche, presque toujours. L'exécution de tests à forte écriture sur la production pollue les données réelles et peut déclencher de réels effets secondaires. Maintenez un environnement Apidog dédié à la CI avec des URLs de base sûres, et passez son ID à la CLI avec -e.

Comment le pipeline sait-il qu'un test a échoué ? Grâce au code de sortie. apidog run renvoie 0 lorsque toutes les assertions passent et un code non nul lorsqu'une d'elles échoue. Azure Pipelines fait échouer la tâche de script sur une sortie non nulle, ce qui fait échouer la construction. Vérifiez cela une fois localement avec echo $? pour vous assurer de la fiabilité de la barrière.

Cela fonctionne-t-il avec les pipelines classiques d'Azure DevOps (UI), et pas seulement YAML ? Oui. Les mêmes étapes s'appliquent ; ajoutez une tâche « Utiliser Node », une tâche en ligne de commande qui exécute npm install -g apidog-cli, et une autre tâche en ligne de commande qui exécute apidog run .... YAML est recommandé car il réside dans votre dépôt et est géré en version, mais l'exécuteur ne se soucie pas de la façon dont les étapes sont définies.

Puis-je utiliser un agent auto-hébergé au lieu d'un agent hébergé par Microsoft ? Oui. Les agents auto-hébergés fonctionnent de la même manière ; assurez-vous simplement que Node.js est installé et que le bin npm global est dans le PATH de l'agent, ou appelez la CLI via npx. Les agents auto-hébergés sont utiles lorsque votre API de staging n'est accessible que depuis un réseau privé.

En résumé

Une construction CI verte devrait signifier que votre API fonctionne réellement, et pas seulement que le code a été compilé. Y parvenir dans Azure Pipelines se résume à quatre étapes : concevoir de véritables scénarios de test dans Apidog, les exécuter sans interface avec l'Apidog CLI, laisser le code de sortie déterminer l'état de la construction, et exiger que la construction passe avant toute fusion. Une fois que cette boucle est en place, chaque push reçoit le même examen minutieux que votre coéquipier le plus prudent lui accorderait, automatiquement, à chaque fois.

La raison pour laquelle cela reste maintenable est la séparation. La logique de test réside dans Apidog, où elle est proche de votre spécification d'API et facile à étendre. Le pipeline reste un simple enrobage : installer, exécuter, rapporter. Lorsque votre API évolue, vous ajoutez des scénarios et des lignes de données dans l'outil, et le pipeline continue de faire son travail sans modifications.

Prêt à le configurer ? Téléchargez Apidog, construisez un scénario de test, prenez la commande d'exécution CLI, et déposez-la dans votre azure-pipelines.yml. Votre prochaine régression sera détectée par une machine au lieu d'un client.