Pour exécuter les tests d'API Apidog CLI dans CircleCI, ajoutez un fichier .circleci/config.yml qui utilise un exécuteur Docker cimg/node, installe apidog-cli avec npm, et exécute apidog run avec votre jeton d'accès, l'ID du scénario de test et l'ID d'environnement. Stockez le jeton et les IDs en tant que variables d'environnement CircleCI, puis publiez les rapports JUnit et HTML avec store_test_results et store_artifacts. Ce guide détaille chaque élément pour que vous puissiez copier, coller et déployer.
Cet article concerne l'exécution de tests, et non le choix d'une plateforme CI. Si vous hésitez encore entre plusieurs outils, la comparaison CircleCI vs Jenkins aborde ce sujet. Ici, nous partons du principe que vous avez déjà choisi CircleCI et que vous souhaitez que votre suite d'API s'exécute à chaque push.
Qu'est-ce que CircleCI et comment ça marche
CircleCI est un service de déploiement et d'intégration continue basé sur le cloud. Il surveille votre dépôt Git et, lorsque vous poussez un commit, il exécute les étapes de build, de test et de déploiement que vous avez définies. Vous décrivez ces étapes dans un seul fichier YAML, de sorte que votre pipeline vit sous contrôle de version aux côtés de votre code.
Tout commence avec le fichier .circleci/config.yml à la racine de votre dépôt. CircleCI lit ce fichier à chaque push et le transforme en pipeline. Le format de configuration actuel est la version 2.1, qui ajoute des blocs de construction réutilisables comme les orbs, les commandes et les paramètres en plus du moteur de base 2.0.
Une configuration CircleCI repose sur trois concepts fondamentaux :
- Les Jobs (Tâches) sont des unités de travail. Chaque tâche exécute une série d'étapes, telles que la récupération du code, l'installation des dépendances ou l'exécution d'une commande de test.
- Les Executors (Exécuteurs) définissent l'endroit où une tâche s'exécute. Un exécuteur Docker exécute vos étapes à l'intérieur d'une image de conteneur que vous choisissez, comme
cimg/nodepour les projets Node.js. - Les Workflows (Flux de travail) orchestrent les tâches. Un flux de travail décide quelles tâches s'exécutent, dans quel ordre, et si elles s'exécutent en parallèle ou en séquence.
Cette séparation est importante pour les tests d'API. Vous définissez une tâche qui installe l'Apidog CLI et exécute vos scénarios, puis un flux de travail qui la déclenche sur les branches qui vous intéressent.
Pourquoi exécuter des tests d'API dans CircleCI
L'exécution de votre suite d'API en CI détecte les ruptures de contrat avant qu'elles n'atteignent la production. Un changement de schéma, un champ renommé ou un flux d'authentification cassé apparaît comme une build rouge au lieu d'un ticket de support.
L'Apidog CLI est conçu précisément pour cela. Vous concevez et déboguez un scénario de test dans l'application Apidog, puis vous exécutez ce même scénario en mode headless en CI avec une seule commande. Pas de réécriture d'assertions dans le code, et pas de harnais de test séparé à maintenir.
Si vous souhaitez avoir une vue d'ensemble de la manière dont les vérifications automatisées s'intègrent dans un pipeline, le guide des 12 meilleures pratiques CI/CD pour les tests d'API est une lecture complémentaire utile.
Prérequis
Avant d'écrire la configuration, préparez ces éléments dans l'application Apidog :
- Un jeton d'accès. Générez-le dans les paramètres de votre compte Apidog. Cela authentifie l'interface de ligne de commande (CLI) dans les environnements headless. Le guide d'authentification de l'Apidog CLI couvre en détail la création de jetons et la gestion des secrets CI.
- Un ID de scénario de test. Ouvrez le scénario de test que vous souhaitez exécuter et copiez son ID depuis l'URL ou les paramètres du scénario.
- Un ID d'environnement. Cela indique à l'interface de ligne de commande (CLI) quelle URL de base et quelles variables utiliser, comme la préproduction ou la production.
Vous aurez également besoin d'un compte CircleCI connecté à votre fournisseur Git, avec le projet activé dans le tableau de bord CircleCI.
Stocker les secrets en tant que variables d'environnement
Ne codez jamais en dur votre jeton d'accès dans config.yml. Le fichier est soumis à Git, donc un jeton y est un jeton divulgué.
CircleCI vous offre deux options sécurisées :
- Variables d'environnement de projet. Dans l'interface utilisateur de CircleCI, ouvrez Paramètres du projet, puis Variables d'environnement, et ajoutez chaque valeur. Elles sont chiffrées et exposées aux tâches en tant que
$VARS. - Contextes. Un contexte est un groupe nommé de variables d'environnement partagées entre plusieurs projets. Vous le créez dans Paramètres de l'organisation, puis Contextes, et le référencez à partir d'un flux de travail. Les contextes sont utiles lorsque plusieurs dépôts partagent le même jeton Apidog.
Pour ce guide, ajoutez trois variables : APIDOG_ACCESS_TOKEN, APIDOG_TEST_SCENARIO_ID et APIDOG_ENVIRONMENT_ID. L'interface de ligne de commande (CLI) les lit à l'exécution, et aucune information sensible ne se trouve dans votre dépôt.
Le fichier config.yml complet
Voici une configuration complète, à copier-coller. Placez-la dans .circleci/config.yml, définissez vos trois variables d'environnement, puis poussez (push).
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 Apidog API tests
command: |
apidog run \
--access-token $APIDOG_ACCESS_TOKEN \
-t $APIDOG_TEST_SCENARIO_ID \
-e $APIDOG_ENVIRONMENT_ID \
-r cli,junit,html \
--out-dir ./reports
- store_test_results:
path: ./reports
- store_artifacts:
path: ./reports
workflows:
test-api:
jobs:
- api-tests
Permettez-moi de détailler ce que chaque partie fait.
L'exécuteur
docker:
- image: cimg/node:20.11
cimg/node est l'image pratique de CircleCI pour Node.js. Elle est livrée avec Node, npm et les outils de build courants préinstallés, de sorte que npm install -g apidog-cli fonctionne sans configuration supplémentaire. L'étiquette :20.11 fixe une version de Node ; utilisez la version sur laquelle votre équipe se standardise.
Les étapes
checkout extrait votre dépôt dans le répertoire de travail de la tâche. La première étape run installe l'interface de ligne de commande (CLI) globalement. La deuxième étape run exécute vos tests.
Examinez attentivement la commande de test :
apidog run \
--access-token $APIDOG_ACCESS_TOKEN \
-t $APIDOG_TEST_SCENARIO_ID \
-e $APIDOG_ENVIRONMENT_ID \
-r cli,junit,html \
--out-dir ./reports
Chaque option (flag) a une fonction :
--access-tokenauthentifie l'exécution. Il n'a pas de forme courte.-tsélectionne le scénario de test par ID.-esélectionne l'environnement. Cette option est obligatoire ; la CLI doit savoir quelle URL de base et quelles variables utiliser.-rdéfinit les rapporteurs. Ici, vous en demandez trois :cliaffiche les résultats en direct dans le journal de build,junitécrit un XML lisible par machine, ethtmlécrit un rapport navigable.--out-dirindique à la CLI où écrire les fichiers de rapport.
Publication des rapports
- store_test_results:
path: ./reports
- store_artifacts:
path: ./reports
store_test_results indique à CircleCI où trouver le XML JUnit dans ./reports. CircleCI l'analyse et affiche un onglet Tests sur la build, de sorte que les échecs sont listés par nom avec les données de temps. C'est ce qui transforme un mur de texte de journal en une vue structurée de succès/échec.
store_artifacts télécharge le même répertoire en tant que fichiers téléchargeables, y compris le rapport HTML. Après une build, vous ouvrez l'onglet Artefacts et visualisez le rapport rendu dans votre navigateur. Le guide des rapports de test Apidog CLI explique les formats CLI, HTML et JSON plus en détail.
Le flux de travail
workflows:
test-api:
jobs:
- api-tests
Ce flux de travail exécute la tâche api-tests à chaque push. Vous pouvez ajouter des filtres pour la restreindre à certaines branches, ou ajouter d'autres tâches qui s'exécutent avant ou après elle. Pour une tâche de test unique, ce bloc minimal est tout ce dont vous avez besoin.
Exécuter les tests uniquement sur la branche principale
Vous ne souhaitez peut-être pas une exécution complète des tests d'API sur chaque branche de fonctionnalité. Ajoutez un filtre de branche au flux de travail :
workflows:
test-api:
jobs:
- api-tests:
filters:
branches:
only:
- main
- develop
Maintenant, la tâche s'exécute uniquement sur les pushes vers main et develop. Les autres branches la ignorent, ce qui permet de concentrer vos minutes de build sur les branches qui sont déployées.
Utiliser un Contexte au lieu de variables de projet
Si plusieurs dépôts partagent un jeton Apidog, un Contexte le conserve en un seul endroit. Créez le Contexte dans Paramètres de l'organisation, ajoutez-y vos variables, puis référencez-le :
workflows:
test-api:
jobs:
- api-tests:
context:
- apidog-secrets
La tâche lit maintenant APIDOG_ACCESS_TOKEN et le reste depuis le Contexte apidog-secrets. Changez le jeton une seule fois, et chaque projet récupérera la nouvelle valeur.
Exécutions basées sur les données et autres options
L'interface de ligne de commande (CLI) possède plus d'options que celles utilisées dans ce guide. Deux d'entre elles méritent d'être connues pour la CI.
Vous pouvez répéter un scénario sur plusieurs lignes de données de test avec -d et -n :
apidog run \
--access-token $APIDOG_ACCESS_TOKEN \
-t $APIDOG_TEST_SCENARIO_ID \
-e $APIDOG_ENVIRONMENT_ID \
-d ./data/users.csv \
-r cli,junit \
--out-dir ./reports
L'option -d prend un chemin de fichier CSV ou JSON, ou un ID numérique d'ensemble de données stockées, et exécute le scénario une fois par ligne. Le guide de test basé sur les données montre comment structurer ces fichiers.
Vous pouvez également contrôler la manière dont l'exécution gère les échecs avec --on-error, qui accepte continue, end ou ignore. Et pour les projets qui utilisent les branches Apidog, --project <id> --branch <name> cible une branche spécifique. Pour envoyer un aperçu du rapport au cloud Apidog, ajoutez --upload-report comme option seule.
Comment cela s'intègre au flux de travail Apidog
L'intérêt de l'Apidog CLI est que vous n'écrivez ni ne maintenez de code de test. Vous construisez un scénario de test depuis la ligne de commande ou dans le constructeur de tests visuel, définissez des assertions sur les codes de statut et les corps de réponse, et l'enregistrez. La CI exécute ensuite ce scénario exact.
Étant donné que le scénario réside dans votre projet Apidog, votre équipe modifie les tests en un seul endroit. La configuration CI change rarement ; elle se contente d'appeler apidog run. Lorsqu'une personne ajoute une assertion dans l'application, la prochaine build CircleCI la prend en compte sans modification de YAML.
Cela maintient une séparation claire. Apidog est responsable de ce qui est testé. CircleCI est responsable de quand et où cela s'exécute. Si vous souhaitez comparer CircleCI à d'autres exécuteurs pour ce type de travail, le récapitulatif des outils d'intégration continue pour les équipes API présente les compromis.
Prêt à lancer votre suite d'API à chaque push ? Téléchargez Apidog, construisez un scénario de test et déposez la configuration ci-dessus dans votre dépôt.
Foire aux questions
Qu'est-ce que CircleCI ?
CircleCI est une plateforme d'intégration et de livraison continues basée sur le cloud. Elle se connecte à votre dépôt Git, lit un fichier .circleci/config.yml et exécute automatiquement les étapes de build, de test et de déploiement à chaque fois que vous poussez du code. Cela élimine la nécessité d'exécuter ces étapes manuellement sur votre propre machine.
À quoi sert CircleCI ?
Les équipes utilisent CircleCI pour automatiser les tests et le déploiement. Les tâches courantes incluent la compilation de code, l'exécution de tests unitaires et d'intégration, la vérification des contrats d'API, la création d'images Docker et la livraison de versions vers la préproduction ou la production. Dans ce guide, la tâche exécute les tests d'API Apidog CLI à chaque push.
CircleCI est-il gratuit ?
CircleCI propose un plan gratuit qui inclut une allocation mensuelle de crédits de build, ce qui est suffisant pour les petits projets et les dépôts personnels. Les équipes plus importantes qui ont besoin de plus de concurrence, de minutes de build plus longues ou de machines plus puissantes passent aux plans payants Performance et Scale. Consultez la page tarifaire actuelle de CircleCI pour connaître les limites exactes.
CircleCI est-il open source ?
Non, CircleCI est un produit commercial hébergé, et non open source. Vous le configurez via un fichier YAML et l'exécutez sur l'infrastructure de CircleCI ou sur un runner auto-hébergé. Si vous avez besoin d'un serveur CI entièrement open source, Jenkins est l'alternative courante, comme l'aborde la comparaison CircleCI vs Jenkins.
Comment fonctionne CircleCI ?
Lorsque vous poussez un commit, CircleCI détecte le changement, lit .circleci/config.yml et lance l'exécuteur que vous avez défini, tel qu'un conteneur Docker cimg/node. Il exécute chaque étape de vos tâches dans l'ordre, puis renvoie les résultats à votre fournisseur Git. Les workflows vous permettent d'enchaîner et de paralléliser les tâches. Pour une vue d'ensemble plus large de la manière dont cela s'intègre à un pipeline de livraison, consultez le guide Qu'est-ce que la CI/CD.