Vous exécutez des tests API automatisés dans Buildkite en définissant une étape de commande dans .buildkite/pipeline.yml qui installe la CLI Apidog, exécute apidog run contre un environnement et télécharge le rapport HTML en tant qu'artefact de build. Ce guide vous accompagne tout au long du pipeline complet, y compris la manière dont Buildkite gère les secrets afin que votre jeton d'accès Apidog ne fuite jamais dans les journaux. Nous supposons que vos tests Apidog existent déjà ; vous les construisez visuellement une fois, puis les exécutez à partir d'une seule commande en CI.
Une clarification rapide avant de commencer. Buildkite est une plateforme CI/CD. Ce n'est pas la même chose que Docker BuildKit, le backend de construction d'images à l'intérieur de Docker. Les noms se ressemblent, mais ce sont des produits sans rapport. Cet article porte entièrement sur Buildkite, la plateforme CI/CD.
button
Qu'est-ce que Buildkite
Buildkite est une plateforme CI/CD construite autour d'un modèle hybride. Elle dispose d'un plan de contrôle hébergé, le tableau de bord et l'orchestration des builds que vous voyez dans votre navigateur, et d'agents qui exécutent réellement vos tâches.
La séparation est importante. Le plan de contrôle planifie le travail, mais le travail s'exécute sur des agents. Vous pouvez héberger vous-même des agents sur votre propre infrastructure ou dans le cloud, ou vous pouvez utiliser des agents hébergés par Buildkite, qui sont des ressources de calcul gérées que Buildkite exécute pour vous.
C'est ce qui distingue principalement Buildkite des systèmes CI entièrement hébergés. Votre code et vos secrets peuvent rester sur vos propres machines tandis que Buildkite coordonne les builds. Pour les tests d'API, cela signifie que vos tests s'exécutent là où vos services et l'accès réseau existent déjà.
L'agent Buildkite lui-même est open source. Il est écrit en Go et publié sous licence MIT, avec son code source sur GitHub. La plateforme et le plan de contrôle qui l'entourent sont un produit SaaS commercial.
À quoi sert Buildkite
Les équipes utilisent Buildkite pour exécuter tout type de tâche automatisée déclenchée par des changements de code : création d'artefacts, exécution de tests unitaires et d'intégration, déploiement de services et exécution de vérifications de bout en bout. Parce que les agents peuvent s'exécuter sur votre propre matériel, c'est courant dans les équipes qui ont besoin de contrôler le calcul, les limites réseau ou le matériel comme les GPU.
Les tests API s'y prêtent bien. Vous voulez que vos tests atteignent un environnement de staging ou de test, qu'ils affirment les réponses réelles et qu'ils bloquent un déploiement si un contrat est rompu. Buildkite vous offre les types d'étapes pour modéliser exactement ce flux, que nous utiliserons ci-dessous.
Si vous comparez Buildkite à d'autres options, notre tour d'horizon des meilleurs outils d'intégration continue pour les équipes API couvre la comparaison de plusieurs plateformes pour ce cas d'utilisation.
Comment les pipelines Buildkite sont définis
Un pipeline Buildkite est une liste d'étapes. L'emplacement par défaut pour les définir est un fichier à .buildkite/pipeline.yml dans votre dépôt. Lorsqu'un build démarre, Buildkite recherche un répertoire nommé .buildkite contenant un fichier nommé pipeline.yml. Un répertoire non caché buildkite/ à la racine du dépôt fonctionne également.
La clé de niveau supérieur est steps:, et elle contient une liste. Les types d'étapes que vous utiliserez le plus pour les tests API sont les suivants :
- Les étapes de commande exécutent des commandes shell sur un agent. C'est là que vos tests s'exécutent.
- Les étapes d'attente mettent le pipeline en pause jusqu'à ce que toutes les étapes précédentes soient terminées. Vous les écrivez comme un élément de liste
- waitnu. - Les étapes de blocage créent une porte d'approbation manuelle, écrite comme
- block: "Label". Un humain clique pour continuer, ce qui est utile avant un déploiement en production.
Les étapes de commande prennent en charge un ensemble de clés que vous utiliserez souvent : label et key pour la nomination et les références, command ou commands pour le script, env pour les variables d'environnement, agents pour le ciblage, secrets pour l'injection de valeurs secrètes, artifact_paths pour les fichiers à conserver, parallelism pour la parallélisation, et matrix pour exécuter la même étape sur un ensemble de valeurs.
La clé agents est un hachage de paires de balises. Vous l'utilisez pour acheminer une étape vers le bon agent, par exemple queue: "tests". Les balises vous permettent de conserver les tâches de test sur des agents disposant de l'accès réseau ou des outils appropriés.
Un pipeline prêt à l'emploi qui exécute des tests API
Voici un .buildkite/pipeline.yml minimal qui installe la CLI Apidog, exécute un scénario de test contre un environnement et télécharge le rapport HTML. La CLI Apidog est un outil Node.js qui exécute vos scénarios de test Apidog depuis la ligne de commande.
steps:
- label: ":test_tube: Tests API (Apidog)"
key: "api-tests"
command: |
npm install -g apidog-cli
apidog run \
--access-token "$APIDOG_ACCESS_TOKEN" \
-t 637132 \
-e 358171 \
-r html,cli
buildkite-agent artifact upload "apidog-reports/**/*"
agents:
queue: "default"
secrets:
- APIDOG_ACCESS_TOKEN
Quelques notes sur les drapeaux. -t est l'ID du scénario de test ou du répertoire de scénarios que vous souhaitez exécuter. -e est l'ID de l'environnement d'exécution, qui sélectionne l'URL de base et les variables utilisées par vos tests. -r html,cli demande à la fois un résumé lisible dans le terminal et un fichier de rapport HTML. --access-token transmet votre jeton Apidog afin que la CLI puisse atteindre votre projet.
L'hôte de l'agent Buildkite dispose déjà du binaire buildkite-agent, car c'est lui qui exécute la tâche. Vous n'installez que apidog-cli vous-même. Pour un aperçu plus approfondi de chaque drapeau, consultez le guide complet de la CLI Apidog.
Si vous souhaitez d'abord un aperçu étape par étape de l'exécution d'une seule API depuis le terminal, le tutoriel de test en ligne de commande de la CLI Apidog est un bon échauffement avant de l'intégrer à votre CI.
Transmission du jeton d'accès Apidog avec les secrets Buildkite
Votre jeton d'accès Apidog est une information d'identification. Il ne doit jamais figurer dans votre pipeline.yml ou être imprimé dans le journal de build. Buildkite vous offre une fonctionnalité native pour cela appelée Buildkite secrets.
Buildkite secrets est un magasin clé-valeur chiffré. Les valeurs sont chiffrées au repos et en transit via TLS, déchiffrées sur les serveurs Buildkite et scoped par cluster, où chaque cluster a sa propre clé de chiffrement. Il fonctionne avec les agents hébergés par Buildkite et les agents auto-hébergés. Toute valeur secrète apparaissant dans vos journaux est automatiquement masquée.
Il existe deux façons d'utiliser un secret stocké. La première est la clé secrets: sur une étape de commande. Dans sa forme de liste la plus simple, le nom de la variable d'environnement correspond à la clé secrète :
steps:
- command: |
apidog run --access-token "$APIDOG_ACCESS_TOKEN" -t 637132 -e 358171 -r html,cli
secrets:
- APIDOG_ACCESS_TOKEN
Si votre secret stocké a un nom différent de la variable d'environnement que vous souhaitez, utilisez la forme hachée. La clé est le nom de la variable d'environnement et la valeur est la clé du secret :
steps:
- command: |
apidog run --access-token "$APIDOG_ACCESS_TOKEN" -t 637132 -e 358171 -r html,cli
secrets:
APIDOG_ACCESS_TOKEN: apidog_token # nom de la variable d'environnement : clé secrète Buildkite
La deuxième méthode consiste à récupérer le secret de manière impérative dans votre script avec la CLI de l'agent. C'est pratique lorsque vous voulez contrôler exactement quand la valeur est lue :
APIDOG_ACCESS_TOKEN="$(buildkite-agent secret get apidog_token)"
apidog run --access-token "$APIDOG_ACCESS_TOKEN" -t 637132 -e 358171 -r html,cli
Les secrets Buildkite ne sont pas votre seule option. Sur les agents auto-hébergés, vous pouvez utiliser un hook d'agent environment, un script qui s'exécute au début de chaque tâche et exporte des valeurs dans l'environnement. Vous pouvez le conditionner à des variables comme $BUILDKITE_PIPELINE_SLUG ou $BUILDKITE_STEP_KEY afin qu'un secret ne soit chargé que pour les bonnes tâches. Vous pouvez également extraire des secrets de magasins externes tels qu'AWS Secrets Manager, HashiCorp Vault ou GCP via des plugins Buildkite, auquel cas le secret n'est jamais stocké ni envoyé à Buildkite.
Les valeurs env: simples sont acceptables pour une configuration non sensible, mais n'y mettez pas de jetons. Pour plus de détails sur la façon dont le jeton circule de votre magasin de secrets vers la CLI, consultez le guide sur l'authentification CLI Apidog.
Téléchargement du rapport HTML en tant qu'artefact
Le rapport -r html écrit un rapport HTML sur un chemin local dans l'espace de travail de l'agent. Ce fichier disparaît lorsque la tâche se termine, sauf si vous le sauvegardez. La commande buildkite-agent artifact upload le conserve.
buildkite-agent artifact upload "apidog-reports/**/*"
Les guillemets autour du motif glob sont importants. Ils empêchent votre shell d'étendre le motif avant que l'agent ne le voie, de sorte que l'agent effectue lui-même la correspondance. Les artefacts téléchargés vont par défaut dans le stockage géré par Buildkite, avec une fenêtre de rétention de 6 mois et une limite de 5 Go par artefact. Vous pouvez passer une destination comme deuxième argument si vous souhaitez les envoyer ailleurs.
Après l'exécution d'un build, le rapport apparaît sous l'onglet "Artifacts" du build. Toute personne qui examine le build peut le télécharger et voir quelles assertions ont réussi ou échoué. Si vous souhaitez comprendre les formats de rapport d'abord, le guide des rapports de test CLI Apidog couvre les sorties CLI, HTML et JSON.
Exécuter des tests en parallèle sur plusieurs environnements
Lorsque vous souhaitez que la même suite s'exécute simultanément sur plusieurs environnements, utilisez une matrix. Buildkite étend une définition d'étape en une tâche par valeur de matrice, et elles s'exécutent en parallèle.
steps:
- label: ":test_tube: Tests API {{matrix.env}}"
command: |
npm install -g apidog-cli
apidog run --access-token "$APIDOG_ACCESS_TOKEN" -t 637132 -e "{{matrix.env}}" -r html,cli
buildkite-agent artifact upload "apidog-reports/**/*"
secrets:
- APIDOG_ACCESS_TOKEN
matrix:
setup:
env:
- "358171" # id de l'environnement de staging
- "358172" # id de l'environnement de production
Ici, {{matrix.env}} est substitué à la fois dans le libellé et dans l'option -e, de sorte que chaque tâche cible un environnement Apidog différent. Si vous voulez uniquement répartir des copies identiques d'une seule tâche, définissez parallelism: 5 sur l'étape au lieu d'une matrice.
Pour les exécutions basées sur les données, où un scénario itère sur des lignes d'un fichier CSV ou JSON, la CLI Apidog gère cela avec son propre drapeau -d plutôt qu'avec la matrice Buildkite. Le guide de test piloté par les données de la CLI Apidog montre comment alimenter un fichier de données dans un scénario.
Verrouiller un déploiement derrière des tests
Une séquence courante est la suivante : exécuter les tests, attendre qu'ils se terminent, demander une approbation humaine, puis déployer. Buildkite modélise cela avec les étapes wait et block.
steps:
- label: ":test_tube: Tests API"
command: "npm install -g apidog-cli && apidog run --access-token \"$APIDOG_ACCESS_TOKEN\" -t 637132 -e 358171 -r html,cli"
secrets:
- APIDOG_ACCESS_TOKEN
- wait
- block: ":rocket: Déployer ?"
branches: "main"
- label: ":rocket: Déployer"
command: "scripts/deploy.sh"
L'étape wait maintient le pipeline jusqu'à ce que les tests soient terminés. L'étape block met en pause pour un clic manuel et est restreinte à la branche main avec branches:. Ce n'est qu'après l'approbation de quelqu'un que l'étape de déploiement s'exécute. Cela empêche une suite de tests défaillante d'atteindre la production. Pour des modèles plus larges à ce sujet, consultez nos bonnes pratiques CI/CD pour les tests d'API.
Ajout d'une annotation de résumé
Les journaux de build sont longs. Une annotation place un court résumé formaté en haut de la page de build. Vous en créez une en pipant du markdown dans buildkite-agent annotate.
cat << 'EOF' | buildkite-agent annotate --style "success" --context "apidog"
### Résultats des tests API
Tous les scénarios Apidog ont réussi. [Télécharger le rapport HTML complet](artifact://apidog-reports/index.html)
EOF
L'option --style contrôle la couleur et l'icône, avec les valeurs info, warning, error et success. L'option --context donne à l'annotation un identifiant unique, de sorte qu'une étape ultérieure avec le même contexte met à jour la même annotation au lieu d'en ajouter une nouvelle. Le lien artifact:// dirige les réviseurs directement vers le rapport HTML téléchargé.
Où s'inscrit Apidog
Le pipeline ci-dessus est court à dessein. Le gros du travail de rédaction et de maintenance des tests se fait dans Apidog, et non dans YAML.
Apidog est une plateforme API tout-en-un pour la conception, le débogage, les tests, le mocking et la documentation des API. Vous construisez des scénarios de test dans un éditeur visuel : chaînez les requêtes, transférez des données entre les étapes et ajoutez des assertions sans écrire de scripts. Parce que les scénarios résident dans votre projet Apidog, votre équipe les modifie en un seul endroit et les versionne avec la prise en charge des branches.
La CLI est le pont vers la CI. Vous construisez un scénario une fois, récupérez son scénario et ses ID d'environnement, et l'intégration CI entière est une simple commande apidog run. Lorsque vous mettez à jour un test dans Apidog, le prochain build Buildkite prend en compte le changement sans aucune modification YAML. Cette propriété de commande unique fait qu'Apidog s'intègre proprement dans Buildkite, GitHub Actions ou tout autre système. Nous couvrons la même commande sur d'autres plateformes dans le guide du pipeline CI/CD de la CLI Apidog et la présentation de la CLI Apidog avec GitHub Actions.
Pour l'essayer d'abord sur votre propre machine, avant de câbler quoi que ce soit en CI, exécutez la même commande localement avec votre jeton :
apidog run --access-token "$APIDOG_ACCESS_TOKEN" -t 637132 -e 358171 -r cli,html
Téléchargez Apidog gratuitement, construisez un scénario de test, et déposez la commande apidog run d'une seule ligne dans votre pipeline Buildkite.
button
Questions fréquemment posées
Qu'est-ce que Buildkite ?
Buildkite est une plateforme CI/CD avec une conception hybride. Un plan de contrôle hébergé exécute le tableau de bord et orchestre les builds, tandis que les agents exécutent les tâches réelles. Les agents peuvent fonctionner sur votre propre infrastructure ou sur des ressources de calcul hébergées par Buildkite. Il n'a aucun rapport avec Docker BuildKit, qui est un outil distinct de construction d'images qui se trouve avoir un nom similaire.
À quoi sert Buildkite ?
Les équipes utilisent Buildkite pour automatiser les tâches déclenchées par les changements de code : création d'artefacts, exécution de tests et déploiement. C'est courant lorsque les équipes souhaitent que leurs builds s'exécutent sur leur propre matériel ou au sein de leur propre réseau. Pour les équipes API, il exécute des tests automatisés sur des environnements de staging et de production et peut bloquer un déploiement lorsque les tests échouent.
Buildkite est-il open source ?
L'agent Buildkite est open source. Il est écrit en Go et publié sous licence MIT, avec son code source sur GitHub. La plateforme et le plan de contrôle autour de l'agent sont un produit SaaS commercial, donc seul l'agent lui-même est open source.
Buildkite est-il gratuit ?
Oui, Buildkite propose un plan gratuit appelé Personal. Il coûte 0 € sans carte de crédit ni date d'expiration. Il inclut 3 tâches concurrentes, 1 utilisateur, une rétention de 90 jours, 500 minutes d'agent hébergé Linux par mois et 50 000 exécutions de tests par mois. Il existe également un essai "All Access" de 30 jours pour évaluer les fonctionnalités payantes.
Comment téléchargez-vous des artefacts dans Buildkite ?
Vous exécutez buildkite-agent artifact upload "<pattern>" dans une étape de commande. Mettez le motif glob entre guillemets pour que l'agent le corresponde plutôt que le shell. Les fichiers vont par défaut dans le stockage géré par Buildkite, avec une rétention de 6 mois et une limite de 5 Go par artefact. Pour les tests API, vous téléchargez le rapport HTML afin que les réviseurs puissent l'ouvrir depuis l'onglet Artifacts du build.
Comment exécutez-vous des tests API dans un pipeline Buildkite ?
Ajoutez une étape de commande à .buildkite/pipeline.yml qui installe la CLI Apidog avec npm install -g apidog-cli, puis exécute apidog run avec un ID de scénario de test, un ID d'environnement via -e, et -r html,cli pour les rapports. Transmettez votre jeton d'accès via un secret Buildkite et téléchargez le rapport HTML avec buildkite-agent artifact upload pour que les résultats persistent après le build.