Vous exécutez des tests API Apidog CLI dans Drone CI en ajoutant une étape de pipeline Docker qui utilise une image Node, installe apidog-cli et exécute apidog run sur un environnement. Votre jeton d'accès Apidog réside dans un secret Drone et est injecté via from_secret. Ce guide présente un fichier .drone.yml à copier-coller, la gestion des secrets, le filtrage par branche et comment exposer le rapport de test puisque Drone n'a pas de magasin d'artefacts intégré.
Qu'est-ce que Drone CI et comment ça marche
Drone est une plateforme CI/CD open source, native des conteneurs, faisant maintenant partie de Harness. CI/CD signifie intégration continue et livraison continue, la pratique consistant à compiler et tester le code automatiquement à chaque modification. Si vous souhaitez une piqûre de rappel sur le concept lui-même, consultez qu'est-ce que le CI/CD.
La caractéristique distinctive de Drone est simple : chaque étape du pipeline s'exécute à l'intérieur de son propre conteneur Docker. Il n'y a pas d'agent de build partagé avec une multitude d'outils préinstallés. Vous choisissez une image pour chaque étape, et Drone exécute vos commandes à l'intérieur. Cela rend les builds reproductibles et faciles à comprendre.
Vous définissez un pipeline dans un fichier .drone.yml à la racine de votre dépôt. Un pipeline Docker possède trois clés de premier niveau : kind, type et name. Le travail se déroule sous steps, où chaque étape déclare un name, une image et une liste de commands.
kind: pipeline
type: docker
name: api-tests
steps:
- name: greeting
image: alpine
commands:
- echo hello
- echo world
Drone exécute les commands comme un script shell avec set -e et set -x, de sorte que le build échoue rapidement au premier code de sortie non nul et affiche chaque commande avant de l'exécuter. Les commandes remplacent le point d'entrée du conteneur, et le répertoire de travail est la racine de votre dépôt.
Pourquoi exécuter des tests API dans une étape de conteneur
Les tests API protègent contre la dérive de contrat. Une modification du backend qui altère discrètement la forme d'une réponse ou un code de statut peut casser tous les clients en aval. L'exécution de ces tests à chaque push détecte la régression avant son déploiement.
Apidog s'adapte bien à ce modèle. Vous construisez et maintenez vos tests visuellement dans l'application Apidog, puis exécutez les mêmes scénarios de test depuis la ligne de commande avec Apidog CLI. Pas de réécriture de script, pas de banc de test séparé. Pour des conseils plus larges sur l'intégration des tests API dans les pipelines, lisez les meilleures pratiques CI/CD pour les tests API.
Apidog est une plateforme API tout-en-un pour la conception, le débogage, les tests, le mocking et la documentation. Le CLI est l'élément qui transforme vos scénarios de test sauvegardés en une seule commande reproductible, ce qui est exactement ce dont une étape Drone a besoin.
La commande Apidog CLI que vous allez exécuter
Installez le CLI avec npm, puis exécutez un scénario de test. En CI, vous lancez l'exécution sur un scénario enregistré avec des drapeaux (flags), il n'y a donc pas de fichier de collection local à gérer.
npm install -g apidog-cli
apidog run --access-token $APIDOG_ACCESS_TOKEN -t 1234567 -e 89012 -r cli
Voici ce que fait chaque drapeau (flag) :
--access-tokentransmet votre jeton d'accès Apidog. Il n'y a pas de forme courte.-test l'ID du scénario de test que vous souhaitez exécuter.-eest l'ID de l'environnement, et il est obligatoire. Cela sélectionne l'URL de base et les variables que l'exécution utilise.-rliste les rapporteurs. Les valeurs valides sontcli,html,jsonetjunit.
Vous pouvez ajouter d'autres drapeaux (flags) si nécessaire :
-nou--iteration-countrépète l'exécution un nombre défini de fois.-dou--iteration-dataprend un chemin de fichier CSV ou JSON, ou un ID de jeu de données numérique stocké, pour les exécutions basées sur les données.--out-dirdéfinit le répertoire de sortie du rapport.--upload-reportenvoie un aperçu du rapport vers le cloud Apidog, où vous pouvez le consulter dans l'application. Vous pouvez l'utiliser comme un simple drapeau.--on-errorcontrôle le comportement en cas d'échec aveccontinue,endouignore.--project <id>et--branch <name>ciblent une branche de projet spécifique.
Pour un aperçu complet de la commande et de ses options, consultez le guide complet d'Apidog CLI et le tutoriel sur le test d'une API REST depuis la ligne de commande.
Un fichier .drone.yml complet pour les tests Apidog
Voici un pipeline fonctionnel. Il utilise une image Node, installe le CLI et exécute votre scénario. Le jeton provient d'un secret Drone plutôt que d'être codé en dur.
kind: pipeline
type: docker
name: apidog-api-tests
steps:
- name: run-api-tests
image: node:20-alpine
environment:
APIDOG_ACCESS_TOKEN:
from_secret: apidog_access_token
commands:
- npm install -g apidog-cli
- apidog run --access-token $APIDOG_ACCESS_TOKEN -t 1234567 -e 89012 -r cli
trigger:
branch:
- main
event:
- push
- pull_request
Remplacez 1234567 par l'ID de votre scénario de test et 89012 par l'ID de votre environnement. Les deux sont visibles dans l'application Apidog. Parce que l'étape utilise le rapporteur cli, la ventilation complète des succès/échecs est directement imprimée dans le journal de build de Drone, où toute personne examinant le build peut la lire.
Stockage des secrets dans Drone CI
Ne commettez jamais un jeton API dans votre dépôt. Drone garde les secrets hors du fichier YAML et les injecte au moment de l'exécution.
Vous référencez un secret à l'intérieur du bloc environment d'une étape (ou du bloc settings d'un plugin) avec from_secret. La valeur que vous écrivez est le nom du secret, pas le jeton lui-même.
environment:
APIDOG_ACCESS_TOKEN:
from_secret: apidog_access_token
Il existe deux façons courantes de créer le secret. La première est l'interface utilisateur de Drone : ouvrez votre dépôt, accédez à Paramètres (Settings), puis Secrets, et ajoutez un secret nommé apidog_access_token avec votre jeton comme valeur. La seconde est l'outil en ligne de commande de Drone.
drone secret add \
--repository your-org/your-repo \
--name apidog_access_token \
--data your-apidog-token
Confirmez les noms exacts des drapeaux (flags) par rapport à la documentation CLI de Drone pour votre version, car les drapeaux CLI peuvent changer entre les versions. Drone prend également en charge une variante de secret crypté dans le dépôt où drone encrypt produit un blob crypté que vous intégrez comme document YAML kind: secret séparé. Pour la plupart des équipes, les secrets de dépôt ajoutés via l'interface utilisateur ou drone secret add sont plus simples et le point de départ recommandé.
Garder le jeton dans un secret est la même discipline que vous appliqueriez partout ailleurs. Pour en savoir plus sur la façon dont le CLI gère les informations d'identification, consultez le guide sur l'authentification Apidog CLI.
Filtrage des exécutions par branche et par événement
Drone vous offre deux leviers pour contrôler le moment où le travail s'exécute : trigger au niveau du pipeline et when au niveau de l'étape.
Un bloc trigger décide si tout le pipeline s'exécute. Toutes les conditions doivent être évaluées comme vraies, donc l'exemple ci-dessous ne s'exécute que sur les pushes et les pull requests ciblant main.
trigger:
branch:
- main
event:
- push
- pull_request
Un bloc when se trouve à l'intérieur d'une seule étape et ne filtre que cette étape. C'est utile lorsque vous voulez que la majeure partie du pipeline s'exécute partout, mais que vous réservez un passage de test plus lourd pour une seule branche.
steps:
- name: run-api-tests
image: node:20-alpine
commands:
- npm install -g apidog-cli
- apidog run --access-token $APIDOG_ACCESS_TOKEN -t 1234567 -e 89012 -r cli
when:
branch:
- main
event:
- push
Les deux blocs supportent les motifs glob et les sous-clés include/exclude. Les types d'événements supportés incluent push, pull_request, tag, promote, rollback, cron et custom.
Exposition des rapports de test sans magasin d'artefacts
Drone n'a pas d'hébergement d'artefacts natif. Cela modifie la façon dont vous gérez les rapports, mais vous avez deux options claires.
La première est la plus simple : utilisez le rapporteur cli pour que les résultats soient imprimés dans le journal de build. Pour la plupart des équipes, c'est suffisant, car le journal montre déjà quelles assertions ont réussi et lesquelles ont échoué.
La deuxième option consiste à générer un rapport HTML et à le télécharger quelque part de durable. Drone publie un plugin S3 officiel, plugins/s3, qui télécharge des fichiers vers S3 ou tout autre magasin compatible S3. Générez le rapport avec le rapporteur html et --out-dir, puis ajoutez une étape de téléchargement.
steps:
- name: run-api-tests
image: node:20-alpine
environment:
APIDOG_ACCESS_TOKEN:
from_secret: apidog_access_token
commands:
- npm install -g apidog-cli
- apidog run --access-token $APIDOG_ACCESS_TOKEN -t 1234567 -e 89012 -r cli,html --out-dir reports
- name: upload-report
image: plugins/s3
settings:
bucket: my-bucket
region: us-east-1
source: reports/**/*
target: /apidog-reports
access_key:
from_secret: aws_access_key
secret_key:
from_secret: aws_secret_key
Le plugin lit ses identifiants AWS à partir de secrets via from_secret, le même mécanisme que vous avez utilisé pour le jeton Apidog. La clé source est un glob de fichiers à télécharger, et target est le préfixe de destination dans le bucket.
Si vous souhaitez un aperçu plus détaillé du contenu du rapport et de la manière de le lire, consultez la décomposition des rapports de test Apidog CLI.
Ajout d'exécutions basées sur les données
Parfois, un scénario doit s'exécuter sur de nombreuses lignes d'entrée : dix ID d'utilisateur, une douzaine de charges utiles, un ensemble de cas limites. Le CLI gère cela avec -d, qui accepte un chemin de fichier CSV ou JSON ou un ID de jeu de données stocké.
commands:
- npm install -g apidog-cli
- apidog run --access-token $APIDOG_ACCESS_TOKEN -t 1234567 -e 89012 -d ./data.csv -r cli
Chaque ligne dans data.csv devient une itération, avec les valeurs des colonnes liées à vos variables de scénario. Le modèle complet est couvert dans les tests basés sur les données Apidog CLI.
Comparaison avec d'autres outils CI
Le modèle Drone, installer le CLI dans un conteneur propre et exécuter une commande, s'applique à presque tous les systèmes CI. La syntaxe d'encapsulation diffère, mais l'étape Apidog est la même.
Si vous exécutez également des pipelines ailleurs, Apidog propose des guides correspondants pour GitHub Actions et Azure Pipelines. L'idée partagée est que vos tests résident dans Apidog et que l'outil CI les déclenche simplement.
Une note honnête sur la portée : l'Apidog CLI exécute des tests fonctionnels et de contrat, pas des tests de charge à grande échelle. Si vous avez besoin de milliers d'utilisateurs virtuels simultanés pour solliciter un endpoint, optez pour un outil de test de charge dédié. Pour vérifier que votre API se comporte correctement à chaque commit, le CLI dans une étape Drone fait bien le travail.
Construisez les tests visuellement, exécutez-les avec une seule commande
Le flux de travail qui rend cela agréable est la séparation entre la création et l'exécution. Vous concevez des endpoints et assemblez des scénarios de test visuellement dans Apidog, en chaînant les requêtes, en affirmant sur les codes de statut et les champs de réponse, et en réutilisant les variables d'environnement. Aucun code n'est requis pour construire la suite.
Ensuite, la CI exécute cette même suite avec une seule commande CLI à l'intérieur d'une étape de conteneur. Lorsqu'un coéquipier met à jour un test dans l'application Apidog, la prochaine build Drone le récupère automatiquement. Il n'y a pas de deuxième copie des tests à maintenir synchronisée.
Téléchargez Apidog gratuitement pour construire votre premier scénario de test, puis déposez le .drone.yml ci-dessus dans votre dépôt pour l'exécuter à chaque push.
Foire aux questions
Qu'est-ce que Drone CI ?
Drone est une plateforme CI/CD open source, native des conteneurs, faisant maintenant partie de Harness. Il exécute chaque étape du pipeline à l'intérieur de son propre conteneur Docker, avec des pipelines définis dans un fichier .drone.yml. Cela rend les builds reproductibles et évite la prolifération d'outils préinstallés des agents de build traditionnels.
Drone CI est-il gratuit ?
Le projet Drone de base est open source et gratuit à auto-héberger. Après l'acquisition par Harness, Drone est devenu Harness CI Community Edition, avec des niveaux d'entreprise payants disponibles. Pour la plupart des équipes, la version open source auto-hébergée couvre l'exécution de tests API comme ceux de ce guide.
Drone CI est-il open source ?
Oui. Drone est l'un des outils CI natifs des conteneurs d'origine et reste open source. Lorsque Harness l'a acquis en 2020, la société s'est engagée à maintenir le projet open source, et vous pouvez toujours l'auto-héberger.
Comment Drone CI est-il utilisé ?
Les équipes utilisent Drone pour compiler, tester et livrer automatiquement du code à chaque push ou pull request. Vous commettez un fichier .drone.yml dans votre dépôt, Drone le lit et exécute chaque étape dans un conteneur. Les étapes courantes incluent la compilation de code, l'exécution de tests unitaires, l'exécution de tests API et le téléchargement d'artefacts vers un stockage externe.
Comment stocker des secrets dans Drone CI ?
Vous ajoutez des secrets via l'écran Paramètres (Settings) puis Secrets du dépôt dans l'interface utilisateur de Drone, ou avec drone secret add depuis le CLI. Vous référencez ensuite chaque secret à l'intérieur du bloc environment d'une étape ou du bloc settings d'un plugin en utilisant from_secret, où la valeur est le nom du secret. Le jeton lui-même n'apparaît jamais dans votre fichier YAML.
Puis-je exécuter des tests Apidog en CI sans écrire de scripts ?
Oui. Vous construisez des scénarios de test visuellement dans l'application Apidog, puis vous les exécutez en CI avec une seule commande apidog run. L'étape Drone n'a besoin que d'une image Node, d'une ligne npm install -g apidog-cli et de la commande d'exécution pointant vers les ID de votre scénario et de votre environnement.