Votre build est vert. Les tests unitaires passent, le JAR est packagé, l'artefact est déployé. Puis la première vraie requête arrive sur l'API de staging et un service en aval renvoie une erreur 500 car quelqu'un a modifié un champ de réponse deux commits plus tôt. Le build indiquait que tout allait bien. Ce n'était pas le cas. Il n'a tout simplement jamais vérifié l'API.
C'est la lacune que la plupart des pipelines CI de Bamboo présentent. Atlassian Bamboo est efficace pour compiler du code, exécuter des suites JUnit et livrer des artefacts. Ce qu'il ne fait pas de lui-même, c'est vérifier que vos points de terminaison HTTP se comportent toujours comme votre contrat le promet. Si vous voulez ce filet de sécurité, vous devez ajouter des tests d'API automatisés comme étape dans le pipeline. Ce guide explique exactement comment procéder, en utilisant Apidog pour créer les tests et l'interface de ligne de commande Apidog pour les exécuter dans une tâche Bamboo.
À la fin, vous aurez un plan Bamboo qui, à chaque push, interroge vos points de terminaison, vérifie les codes de statut, valide les corps de réponse par rapport à votre schéma, et fait échouer le build dès qu'un contrat est rompu. Pas de licence Postman par siège, pas de scripts d'assertion écrits à la main à maintenir, et un véritable rapport de test HTML joint à chaque build. Téléchargez Apidog si vous souhaitez suivre ; la partie CLI est gratuite et open source.
Pourquoi les tests d'API doivent être dans Bamboo, et non après
Beaucoup d'équipes testent leurs API manuellement, ou pire, en production. Quelqu'un clique sur une collection de requêtes enregistrées avant une publication et examine les réponses. Cela fonctionne jusqu'à ce que ça ne fonctionne plus. Les gens oublient. Les mises en production ont lieu un vendredi. Le seul point de terminaison que personne n'a pensé à revérifier est celui qui tombe en panne.
La CI existe pour éliminer cette variable humaine. Tout l'intérêt d'un serveur de build est que les mêmes vérifications s'exécutent de la même manière à chaque fois, automatiquement, sans que personne n'ait à se souvenir de les lancer. Vos tests unitaires y sont déjà. Vos tests d'intégration probablement aussi. Les tests d'API méritent le même traitement, et ce pour quelques raisons concrètes :
- Les contrats se rompent silencieusement. Un développeur backend renomme un champ JSON de
userIdenuser_id. Les tests unitaires passent toujours car ils testent la fonction, pas le format de transmission. L'équipe mobile le découvre trois jours plus tard. Un test d'API qui effectue une assertion sur le corps de la réponse le détecte dans le même build qui l'a introduit. - Les codes de statut mentent lorsque personne ne surveille. Un point de terminaison qui devrait renvoyer
201 Createdcommence à renvoyer200 OKaprès une refactorisation. Fonctionnellement proche, techniquement incorrect, et un client strict le rejettera. Une assertion de pipeline signale cela en quelques secondes. - Les régressions d'authentification sont coûteuses. Un flux de rafraîchissement de jeton mal configuré qui renvoie
401sur des informations d'identification valides est le genre de bug qui fait tomber un écran de connexion. Exécuter une requête authentifiée sur chaque build signifie que vous le trouvez avant vos utilisateurs. - Les environnements dérivent. La staging reçoit un changement de configuration, un feature flag bascule, une dépendance est mise à jour. L'exécution de la même suite d'API sur la staging après chaque déploiement vous indique immédiatement si l'environnement est toujours sain.
Le contexte plus profond est la même raison pour laquelle les équipes adoptent la CI/CD en premier lieu : détecter les problèmes tôt, quand ils sont faciles à corriger, au lieu de tard, quand ils sont coûteux et embarrassants. Le test d'API n'est que la couche de cette stratégie que la plupart des pipelines ignorent.
Comment les tests d'API s'intègrent dans un plan Bamboo
Avant le pas à pas, il est utile de comprendre où cela s'inscrit dans le modèle de Bamboo. Bamboo organise le travail en plans, et chaque plan contient une ou plusieurs étapes qui s'exécutent dans l'ordre. Chaque étape contient des tâches, et chaque tâche est une séquence de commandes. Les tâches sont les commandes réelles : extraction, compilation, exécution d'un script.
Vos tests d'API deviennent une tâche au sein d'une tâche au sein d'une étape. Le placement naturel est une étape dédiée qui s'exécute une fois que votre application est construite et déployée dans un environnement de test, car vous avez besoin de quelque chose de "vivant" pour envoyer des requêtes. Un plan typique se présente comme suit :
Plan: payments-service
├── Stage: Build
│ └── Job: Compile & Unit Test
│ ├── Task: Source Code Checkout
│ └── Task: Maven, clean package
├── Stage: Deploy to Staging
│ └── Job: Deploy
│ └── Task: Deploy artifact to staging
└── Stage: API Tests <- c'est ce que vous ajoutez
└── Job: Run API Suite
├── Task: Source Code Checkout
├── Task: Script, install & run Apidog CLI
└── Task: Final, publish test report
Si une tâche de l'étape "API Tests" se termine avec un code non nul, Bamboo signale l'étape comme ayant échoué et l'ensemble du build devient rouge. C'est exactement le comportement que vous souhaitez ; un contrat rompu devrait arrêter la chaîne, et non passer inaperçu.
L'outil qui effectue le travail réel dans cette tâche de script est l'interface de ligne de commande Apidog, un exécuteur en ligne de commande qui exécute les scénarios de test que vous concevez visuellement dans Apidog. Vous construisez le test une fois, dans une interface graphique, sans code, et le même test s'exécute inchangé dans votre terminal et dans Bamboo. C'est le même modèle que les équipes utilisent pour automatiser les tests d'API sur n'importe quel système CI/CD ; Bamboo est une cible parmi tant d'autres.
Étape 1 : Créez vos tests d'API dans Apidog
Vous ne pouvez pas exécuter de tests en CI tant que vous n'avez pas de tests. Apidog est l'endroit où vous les concevez, et la conception est visuelle, de sorte qu'un ingénieur QA qui ne code pas peut construire la même suite qu'un développeur backend.
Ouvrez Apidog et créez un scénario de test. Un scénario est une séquence ordonnée de requêtes API, exécutées de haut en bas, où chaque étape peut réutiliser les données des étapes précédentes. Un scénario réaliste pour un service de paiement pourrait être :
POST /auth/loginavec des identifiants valides, puis extrayez le jeton bearer de la réponse.POST /ordersen utilisant ce jeton, en créant une nouvelle commande, puis enregistrez l'orderIdretourné.GET /orders/{orderId}et confirmez que la commande apparaît avec le bon statut.DELETE /orders/{orderId}pour nettoyer.
Pour chaque requête, ajoutez des assertions. C'est la partie qui transforme une requête en un test. Apidog vous permet d'effectuer des assertions visuellement, sans script requis :
- Le code de statut est égal à
200(ou201, selon ce que dit le contrat). - Un champ JSON existe et correspond :
$.data.statusest égal à"pending". - La réponse est validée par rapport au schéma OpenAPI du point de terminaison, de sorte que tout type de champ inattendu ou toute propriété requise manquante fait échouer l'étape.
- Le temps de réponse reste en dessous d'un seuil, disons 800 ms, de sorte qu'une régression de lenteur apparaît également.
Les assertions basées sur le schéma méritent d'être soulignées. Parce qu'Apidog est "schema-first", il connaît déjà la forme que votre point de terminaison a promise dans sa définition d'API. Vous pouvez affirmer "cette réponse correspond à son schéma" en un seul clic, et cette vérification unique protège contre toute une catégorie de dérives de contrat, de champs renommés, de types incorrects, de propriétés supprimées, sans que vous n'ayez à écrire une seule ligne. Si vous venez d'un outil très scripté, cela seul supprime beaucoup de maintenance. C'est le même modèle d'assertion visuelle qui fait d'Apidog une alternative courante à Postman pour les tests d'API.
Regroupez les scénarios liés dans une suite de tests si vous en avez beaucoup. Une suite est simplement une collection de scénarios que vous pouvez exécuter ensemble, ce qui simplifie votre commande CI ; vous pointez l'exécuteur vers une suite au lieu de lister vingt scénarios.
Utilisez des variables d'environnement pour tout ce qui change entre le local, le staging et la production : URL de base, identifiants, clés d'API. Définissez un environnement de staging dans Apidog avec baseUrl défini sur votre hôte de staging. Vous indiquerez à la CLI quel environnement utiliser au moment de l'exécution, de sorte que le même scénario s'exécute sur le staging dans Bamboo et sur localhost sur votre ordinateur portable.
Étape 2 : Générez un jeton d'accès Apidog et récupérez les identifiants
Bamboo s'exécute sans interface graphique sur un agent de build. Il ne peut pas se connecter à votre compte Apidog via un navigateur, c'est pourquoi la CLI s'authentifie avec un jeton d'accès à la place.
Dans votre scénario de test, ouvrez l'onglet CI/CD. Cliquez sur "Add access token", puis sur "Generate token". Copiez la valeur en lieu sûr un instant ; vous la stockerez comme variable Bamboo sous peu, et non en la collant dans un script. Le jeton permet à un agent de build de récupérer et d'exécuter les tests de votre projet privé.
Pendant que vous êtes dans cet onglet CI/CD, Apidog génère la commande d'exécution complète pour vous. Sélectionnez "Command line" comme fournisseur et il affichera quelque chose que vous pourrez copier directement, avec votre ID de scénario de test et votre ID de projet déjà remplis. Cette commande copiée est la base de votre tâche Bamboo. Les éléments qui vous intéressent :
- Jeton d'accès : authentification, passé en tant que
--access-token. - ID du scénario de test : l'ID numérique après
-t, identifiant le scénario à exécuter. - ID de l'environnement : l'ID numérique après
-e, indiquant à la CLI de s'exécuter sur l'environnement de staging.
Gardez cette commande générée à portée de main. Les étapes suivantes l'adaptent pour Bamboo.
Étape 3 : Stockez le jeton en tant que variable de plan Bamboo
Ne codez jamais en dur un jeton dans une tâche de script. Toute personne ayant un accès en lecture au plan, et toute personne lisant les journaux de build, le verrait.
Dans Bamboo, accédez à votre plan, ouvrez la "Plan Configuration", et trouvez l'onglet "Variables". Ajoutez une nouvelle variable. Nommez-la clairement, par exemple APIDOG_ACCESS_TOKEN, et collez le jeton comme valeur. Bamboo masque les variables dont les noms contiennent password, secret ou token, alors nommez-la en conséquence et la valeur sera masquée dans les journaux et l'interface utilisateur.
Au moment de l'exécution, Bamboo expose les variables de plan aux scripts en tant que variables d'environnement, préfixées et en majuscules, les points devenant des underscores. Une variable nommée APIDOG_ACCESS_TOKEN est disponible pour votre tâche shell en tant que $bamboo_APIDOG_ACCESS_TOKEN. Vous ferez référence à cela, jamais au jeton brut, dans le script de build.
Cette même hygiène s'applique à tout autre secret dont vos tests ont besoin ; mots de passe de bases de données, clés API tierces, secrets de signature. Définissez-les comme des variables Bamboo masquées et lisez-les via le préfixe d'environnement bamboo_.
Étape 4 : Ajoutez l'étape de test d'API et une tâche de script
Maintenant, intégrez-le au plan. Dans la "Plan Configuration", ajoutez une nouvelle étape et nommez-la "API Tests". Ajoutez-y une tâche, puis ajoutez des tâches à cette tâche dans cet ordre.
Tâche 1, "Source Code Checkout". Même si les tests résident dans le cloud d'Apidog, l'extraction de votre dépôt donne à l'agent un répertoire de travail propre et vous permet de commettre tous les fichiers de données locaux (données d'itération CSV, par exemple) à côté de votre code.
Tâche 2, Script. C'est le cœur de l'opération. Choisissez une tâche de script, définissez l'interpréteur sur "Shell" (ou /bin/sh), et utilisez un corps de script en ligne. Le script installe l'interface de ligne de commande Apidog sur l'agent et exécute votre scénario.
L'interface de ligne de commande Apidog est un package npm, l'agent a donc besoin de Node.js v16 ou d'une version ultérieure. Si vos agents ont déjà Node, vous pouvez ignorer la ligne d'installation ; sinon, provisionnez-le via les capacités de Bamboo ou un agent basé sur Docker. Voici un corps de script complet :
#!/bin/sh
set -e
# Installe l'interface de ligne de commande Apidog globalement sur l'agent
npm install -g apidog-cli
# Exécute le scénario de test sur le staging, génère un rapport HTML + CLI
apidog run \
--access-token "$bamboo_APIDOG_ACCESS_TOKEN" \
-t 637132 \
-e 358171 \
-r cli,html \
--out-dir ./apidog-reports
Remplacez 637132 par votre véritable ID de scénario de test et 358171 par votre ID d'environnement de staging, les valeurs de la commande Apidog générée à l'étape 2. Quelques notes sur ce que fait chaque drapeau :
--access-tokenlit la variable Bamboo masquée, de sorte que le secret n'apparaît jamais dans le script.-t(abréviation de--test-scenario) sélectionne le scénario à exécuter. Pour exécuter une suite entière à la place, utilisez--test-suite <id>; pour exécuter un dossier entier de scénarios, utilisez-f <folderId>.-e(--environment) sélectionne l'environnement de staging que vous avez défini dans Apidog, de sorte que les requêtes soient envoyées au bon hôte avec les bonnes variables.-r cli,html(--reporters) produit à la fois un rapport console que vous verrez dans le journal de build de Bamboo et un rapport HTML que vous pouvez publier en tant qu'artefact. La CLI prend également en charge les formatsjsonetjunitici.--out-dircontrôle l'emplacement des rapports. La valeur par défaut est./apidog-reports; le fait de la définir explicitement rend le chemin de l'artefact prévisible.
Le set -e en haut est important. Il fait sortir le shell à la première commande échouée. L'interface de ligne de commande Apidog renvoie déjà un code de sortie non nul lorsqu'une assertion échoue, et ce code non nul est ce qui indique à Bamboo d'échouer le build. Ensemble, ils garantissent qu'un contrat d'API rompu fait passer le build au rouge au lieu d'être enfoui dans les logs.
Si vous avez déjà intégré des tests d'API dans GitHub Actions, cela vous semblera familier ; l'exécuteur et les drapeaux sont identiques, seule l'enveloppe YAML contre l'interface utilisateur de Bamboo diffère.
Étape 5 : Publiez le rapport de test en tant qu'artefact Bamboo
Un build rouge vous indique que quelque chose a cassé. Le rapport HTML vous dit quoi a cassé. Configurez-le pour que chaque build conserve le rapport.
Dans la même tâche, allez dans l'onglet "Artifacts" et définissez un nouvel artefact partagé :
- Nom :
Rapport de test Apidog - Emplacement :
apidog-reports - Modèle de copie :
**/*
Après chaque build, Bamboo collecte tout ce qui se trouve dans le répertoire apidog-reports et l'attache au résultat du build. Ouvrez n'importe quel build, allez dans l'onglet "Artifacts", et vous pouvez télécharger ou visualiser le rapport HTML ; les résultats requête par requête, les assertions exécutées et le corps de réponse exact pour tout ce qui a échoué. Cette dernière partie permet de gagner un temps de débogage considérable. Au lieu de réexécuter la requête échouée à la main, vous lisez la réponse capturée directement à partir du build.
Pour un affichage plus riche dans Bamboo, le rapporteur junit est également utile. Ajoutez junit à la liste -r, puis ajoutez une tâche "JUnit Parser" pointant vers le fichier XML JUnit. Bamboo affiche alors nativement le nombre de tests, les ventilations réussite/échec et les tendances d'échec sur le résumé du build, de la même manière qu'il affiche les résultats de vos tests unitaires.
Étape 6 : Exécutez-le et lisez le résultat
Déclenchez le plan manuellement pour la première exécution ; dans Bamboo, "Run plan" depuis la page du plan. Surveillez le journal de build pour l'étape "API Tests". Vous verrez npm installer la CLI, puis le flux de sortie d'exécution d'Apidog, nom du scénario, chaque requête, chaque assertion, et une ligne de résumé finale avec les totaux.
Deux issues possibles :
Toutes les assertions passent. La CLI se termine avec 0, l'étape passe au vert, le build réussit, et le rapport HTML est de toute façon joint en tant qu'artefact, vous avez donc un enregistrement. Bien. Maintenant, rendez-le automatique ; configurez le plan pour qu'il se déclenche à chaque commit sur votre branche principale (Plan Configuration, Triggers, Repository polling ou un webhook). À partir de là, chaque push exécute votre suite d'API sans aucune intervention humaine.
Une assertion échoue. La CLI se termine avec un code non nul, set -e arrête le script, l'étape passe au rouge et le build échoue. Ouvrez l'artefact, trouvez la requête échouée et lisez la réponse capturée. Peut-être qu'un champ a changé. Peut-être que le staging a renvoyé un 502 parce qu'une dépendance est en panne. Dans tous les cas, vous le savez dans la minute ou les deux minutes qui suivent le commit qui l'a introduit, ce qui est le gain principal.
┌──────────────┬──────────┬──────────┐
│ │ exécuté │ échoué │
├──────────────┼──────────┼──────────┤
│ itérations │ 1 │ 0 │
├──────────────┼──────────┼──────────┤
│ requêtes │ 4 │ 0 │
├──────────────┼──────────┼──────────┤
│ assertions │ 11 │ 1 │
└──────────────┴──────────┴──────────┘
1 assertion a échoué :
GET /orders/{orderId}
attendu $.data.status égal à "pending" mais a obtenu "failed"
Cette assertion échouée est la seule raison de l'existence de cette étape. Elle a détecté une régression de contrat qui avait compilé correctement et passé tous les tests unitaires.
Rendre la suite fiable en CI
Un test d'API instable est pire qu'aucun test, car il habitue l'équipe à ignorer les builds rouges. Quelques habitudes permettent de maintenir la fiabilité de la suite.
Isolez les données de test. Chaque exécution doit créer ce dont elle a besoin et nettoyer après elle-même, comme le flux de création-suppression de commande ci-dessus. Les tests qui dépendent d'un enregistrement créé mardi dernier échoueront dès que cet enregistrement changera. Exécutez-vous sur un environnement de staging ou de test dédié, jamais en production.
Utilisez des exécutions basées sur les données pour une couverture sans duplication. Si vous devez tester le même point de terminaison avec vingt entrées différentes, ne construisez pas vingt scénarios. Utilisez un seul scénario avec --iteration-data path/to/data.csv (ou -d), et la CLI l'exécutera une fois par ligne. Committez le CSV dans votre dépôt afin qu'il soit extrait avec le code. C'est le même modèle de test basé sur les données que vous utiliseriez localement, mais simplement piloté à partir d'un fichier en CI.
Épinglez la version de la CLI. npm install -g apidog-cli télécharge la dernière version. Pour des builds reproductibles, épinglez une version connue, npm install -g apidog-cli@<version>, afin qu'une mise à jour de la CLI ne modifie pas silencieusement le comportement entre deux builds du même commit.
Définissez des délais d'attente raisonnables. Ajoutez --timeout-request 10000 pour échouer rapidement sur un point de terminaison bloqué au lieu de laisser le build bloqué jusqu'à ce que le propre délai d'attente de Bamboo le tue. Un message clair "requête expirée" vaut mieux qu'un build vague et bloqué.
Verrouillez les déploiements sur l'étape API. Étant donné que l'étape "API Tests" s'exécute avant toute étape de déploiement en production, et qu'une étape échouée arrête le plan, un contrat rompu ne peut pas atteindre la production. Cet ordre est votre porte de libération. C'est la version pratique de la construction d'un véritable pipeline CI/CD plutôt qu'un build qui ne fait que compiler.
Gardez les scénarios rapides et ciblés. Une suite CI qui prend vingt minutes ne s'exécutera pas à chaque commit ; les gens la déplaceront en exécution nocturne et perdront le feedback rapide. Limitez la suite par commit à vos chemins critiques, l'authentification, les opérations CRUD de base, le flux de paiement, et exécutez la suite exhaustive des cas limites selon un calendrier.
En résumé
Bamboo vous protège déjà du code qui ne compile pas et des tests unitaires qui ne passent pas. L'ajout d'une étape de test d'API étend cette protection aux contrats que vos services exposent réellement sur le réseau, la couche où se produisent la plupart des incidents du type "mais ça marchait en local".
La configuration est simple : construisez des tests visuels et conscients des schémas dans Apidog, générez un jeton d'accès, stockez-le en tant que variable Bamboo masquée, et ajoutez une tâche de script qui exécute apidog run avec vos identifiants de scénario et d'environnement. Publiez le rapport en tant qu'artefact, sécurisez votre étape de déploiement derrière celui-ci, et déclenchez le plan à chaque commit. Après cela, c'est automatique. Chaque push vérifie votre API, et un contrat rompu fait passer le build au rouge avant qu'il ne puisse se transformer en panne.
Téléchargez Apidog et créez votre premier scénario de test, puis insérez la commande CLI générée dans une tâche de script Bamboo. La première fois qu'il détectera une régression qui avait compilé correctement, l'étape aura rentabilisé les dix minutes nécessaires à sa mise en place.