Blog

Comment exécuter les tests API Apidog CLI dans GitHub Actions (Workflow complet)

Exécutez vos scénarios de test d'API Apidog dans GitHub Actions. Un workflow complet : installez apidog-cli, stockez le jeton d'accès en tant que secret, contrôlez les fusions et publiez les rapports.

Ashley Innocent

Ashley Innocent

15 June 2026

Comment exécuter les tests API Apidog CLI dans GitHub Actions (Workflow complet)

enterprise.banner.title

enterprise.banner.feature1

enterprise.banner.feature2

enterprise.banner.feature3

enterprise.banner.ctaB

Vos tests d'API passent sur votre machine. Ensuite, un coéquipier fusionne un changement qui casse le point d'extrémité de connexion, et personne ne le remarque avant qu'un client ne dépose un ticket. Les tests existaient. Ils n'ont simplement jamais été exécutés au moment où ils comptaient : sur la pull request, avant la fusion.

Cet écart est ce que l'intégration continue comble. Vous déplacez les tests de votre terminal local vers un pipeline qui les exécute automatiquement, à chaque push, contre chaque changement. Pour les tests d'API spécifiquement, la manière la plus propre de le faire est un exécuteur en ligne de commande qui exécute les scénarios exacts que vous avez déjà construits, renvoie un code de sortie de succès/échec, et laisse la CI décider si la construction passe au vert ou au rouge.

bouton

En bref

Pourquoi exécuter des tests d'API en CI

Un test qui ne s'exécute que lorsque vous vous souvenez de l'exécuter est un test auquel vous ne pouvez pas faire confiance. Les exécutions locales sont acceptables pendant que vous écrivez le scénario. Elles échouent dès qu'une équipe est impliquée, car la machine de chaque développeur est légèrement différente et personne n'exécute la suite complète avant chaque push.

La CI résout le problème de confiance en rendant l'exécution automatique et uniforme. Chaque pull request déclenche le même job, sur le même runner propre, contre le même environnement. Lorsqu'un point d'extrémité commence à renvoyer un 500 ou qu'un schéma de réponse dérive, la vérification échoue sur la PR qui l'a causé, avec le nom de la personne qui l'a poussé. Le feedback arrive en quelques minutes, pendant que le changement est encore frais, au lieu de jours plus tard en production.

Les tests d'API sont particulièrement adaptés à cela car ils sont rapides et déterministes. Un scénario atteint de vrais points d'extrémité, effectue des assertions sur les codes de statut et les corps de réponse, et passe ou échoue. Il n'y a pas de navigateur instable, pas de rendu à attendre. Cela les rend idéaux comme barrière de fusion : suffisamment rapides pour être exécutés sur chaque PR, suffisamment décisifs pour bloquer une mauvaise. Si vous voulez un aperçu plus large de ce qu'est la CI/CD et comment les pièces s'assemblent, le guide sur ce qu'est la CI/CD et comment elle fonctionne couvre les fondamentaux.

Ce que fait réellement l'Apidog CLI

Voici la partie qui vous fait gagner le plus de temps : vous n'écrivez pas de code de test pour la CLI.

Vous construisez visuellement vos scénarios de test dans l'application Apidog, avec les requêtes, les assertions, les variables d'environnement et les données dont vous avez besoin. La CLI est un exécuteur. Étant donné un ID de scénario et un jeton d'accès, elle récupère ce scénario de votre projet Apidog et l'exécute, requête par requête, évaluant chaque assertion exactement comme l'application le ferait. Le résultat est un rapport et un code de sortie.

Cette conception est importante pour la CI. La plupart des exécuteurs de tests vous demandent de maintenir une représentation de code séparée de vos tests ; ce que vous exécutez dans le pipeline diverge de ce que vous avez conçu. Avec Apidog, le pipeline exécute le même scénario que votre équipe maintient déjà dans l'application. Mettez à jour une assertion dans l'éditeur visuel et la prochaine exécution CI la prendra en compte. Il n'y a pas de deuxième copie à synchroniser.

Le binaire est apidog, distribué en tant que package npm apidog-cli. Chaque commande commence par apidog run. Si vous voulez voir l'exécuteur intégré dans un flux de travail d'automatisation plus complet, le guide sur l'intégration de l'Apidog CLI avec Claude Skills pour l'automatisation des tests d'API couvre cet aspect ; cet article se concentre sur les drapeaux dont vous avez besoin pour un pipeline GitHub Actions.

Avant de commencer : trois choses dont vous avez besoin

Vous avez besoin de trois informations avant que le workflow ne s'exécute. Deux sont des ID de votre projet Apidog ; une est un jeton.

  1. Un scénario de test. Construisez-le dans l'application Apidog si ce n'est pas déjà fait. C'est ce que la CLI exécute. Un simple scénario de connexion et de récupération de profil est suffisant pour commencer ; vous pourrez l'étendre plus tard.
  2. L'ID du scénario et l'ID de l'environnement. L'ID du scénario indique à la CLI quoi exécuter ; l'ID de l'environnement lui indique où (dev, staging, production). Les deux sont visibles dans l'application.
  3. Un jeton d'accès. Cela authentifie la CLI à votre compte Apidog afin qu'elle puisse récupérer et exécuter le scénario.

La manière la plus propre d'obtenir tout cela en une seule fois est l'onglet CI/CD du scénario. Ouvrez le scénario de test que vous souhaitez automatiser, passez à son onglet CI/CD et choisissez l'option de ligne de commande. Cliquez pour ajouter un jeton d'accès et en générer un. Apidog assemble la commande complète apidog run pour vous, avec le jeton d'accès, l'ID du scénario (-t) et l'ID de l'environnement (-e) déjà renseignés. Copiez cette commande ; c'est la base de votre étape CI.

Une règle à énoncer d'emblée : traitez le jeton d'accès comme un mot de passe. Ne le collez pas dans un fichier de workflow commité. Stockez-le comme un secret GitHub Actions et référencez-le comme une variable d'environnement. Chaque exemple ci-dessous utilise $APIDOG_ACCESS_TOKEN pour exactement cette raison.

Étape 1 : stocker le jeton d'accès en tant que secret GitHub

Ouvrez votre dépôt sur GitHub. Allez dans Paramètres, puis Secrets et variables, puis Actions, et cliquez sur Nouveau secret de dépôt.

Enregistrez-le. Le jeton est maintenant chiffré au repos et exposé uniquement aux exécutions de workflow, jamais imprimé dans les logs. Dans le workflow, vous le référencerez comme ${{ secrets.APIDOG_ACCESS_TOKEN }} et le passerez à la CLI via un bloc env:. L'ID du scénario et l'ID de l'environnement ne sont pas secrets ; ce sont des ID inoffensifs, vous pouvez donc les écrire directement dans le fichier de workflow. Seul le jeton a besoin de protection.

Si votre équipe travaille sur plusieurs dépôts qui accèdent tous au même projet Apidog, définissez le secret une seule fois au niveau de l'organisation et accordez l'accès aux dépôts pertinents. Même nom, un seul endroit pour le renouveler.

Étape 2 : le workflow minimal

Créez .github/workflows/api-tests.yml dans votre dépôt. C'est le plus petit workflow qui fait quelque chose d'utile : il exécute votre scénario sur chaque pull request ciblant main.

name: API tests

on:
  pull_request:
    branches: [main]

jobs:
  api-tests:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Set up Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'

      - name: Install Apidog CLI
        run: npm install -g apidog-cli

      - name: Run API test scenario
        run: |
          apidog run \
            --access-token "$APIDOG_ACCESS_TOKEN" \
            -t 605067 \
            -e 1629989 \
            -r cli
        env:
          APIDOG_ACCESS_TOKEN: ${{ secrets.APIDOG_ACCESS_TOKEN }}

Remplacez 605067 par votre ID de scénario et 1629989 par votre ID d'environnement. Commitez ce fichier, ouvrez une pull request et consultez l'onglet Vérifications. Le job lance un runner Ubuntu, installe Node 20, installe la CLI et exécute votre scénario. Si toutes les assertions passent, la vérification passe au vert. Si l'une échoue, apidog run quitte avec un code non nul, GitHub échoue la vérification et la PR affiche un X rouge.

Ce X rouge est tout l'intérêt. Personne n'a besoin de lire un log pour savoir que quelque chose a cassé ; la vérification échouée est juste là sur la pull request.

Une note sur l'étape d'installation : l'npm install -g apidog-cli global est simple et fonctionne. Si vous préférez ne pas modifier les packages globaux du runner, vous pouvez ignorer l'étape d'installation et appeler la CLI via npx à la place :

      - name: Run API test scenario
        run: npx apidog-cli run --access-token "$APIDOG_ACCESS_TOKEN" -t 605067 -e 1629989 -r cli
        env:
          APIDOG_ACCESS_TOKEN: ${{ secrets.APIDOG_ACCESS_TOKEN }}

Les deux approches exécutent le scénario identique. npx est plus propre sur les runners éphémères ; l'installation globale est légèrement plus rapide si vous mettez en cache node_modules entre les exécutions. Choisissez celle qui correspond à votre style de maison.

Étape 3 : publier un rapport réellement lisible

Une vérification verte ou rouge vous indique le résultat. Lorsqu'un test échoue, vous voulez savoir pourquoi, et pour cela vous voulez le rapport.

Le drapeau -r (ou --reporters) contrôle les formats de rapport. Il accepte cli, html, json, et junit, séparés par des virgules. Pour la CI, deux formats ont leur place :

Gardez cli également si vous voulez une sortie lisible dans le log de build lui-même. Voici l'étape d'exécution mise à niveau pour produire les deux formats de rapport et les écrire dans un répertoire, plus une étape de téléchargement pour que le rapport survive à l'exécution :

      - name: Run API test scenario
        run: |
          apidog run \
            --access-token "$APIDOG_ACCESS_TOKEN" \
            -t 605067 \
            -e 1629989 \
            -n 1 \
            -r html,junit,cli \
            --out-dir ./apidog-reports
        env:
          APIDOG_ACCESS_TOKEN: ${{ secrets.APIDOG_ACCESS_TOKEN }}

      - name: Upload test report
        if: always()
        uses: actions/upload-artifact@v4
        with:
          name: apidog-report
          path: ./apidog-reports

Deux détails font que cela fonctionne comme vous le souhaitez. Le drapeau --out-dir indique à la CLI où écrire les rapports ; ici c'est ./apidog-reports, que l'étape de téléchargement récupère ensuite. Et if: always() sur l'étape de téléchargement est le plus important : par défaut, GitHub ignore les étapes ultérieures une fois qu'une étape échoue, mais vous voulez le rapport le plus souvent lorsque les tests ont échoué. if: always() force le téléchargement à s'exécuter quel que soit le résultat du test. Une fois le job terminé, le rapport apparaît sous Artefacts sur la page de résumé de l'exécution, prêt à être téléchargé.

Le drapeau -n 1 définit le nombre d'itérations à une seule exécution ; augmentez-le si vous voulez que le scénario soit exécuté plusieurs fois de suite.

Si vous voulez que GitHub affiche les résultats JUnit en ligne comme une vérification annotée plutôt que comme un fichier téléchargeable, ajoutez une action published-test-results après l'étape d'exécution et pointez-la vers ./apidog-reports/*.xml. Cela transforme le XML en un résumé de succès/échec attaché à l'exécution, ce qui est pratique pour les suites plus importantes où le défilement du log n'est pas pratique.

Étape 4 : tester le bon environnement au bon moment

Une pull request devrait être testée contre un environnement de staging. Un déploiement en production devrait être vérifié contre la production. Le même scénario peut faire les deux ; il suffit de changer l'ID de l'environnement avec -e.

Une configuration courante et durable utilise deux déclencheurs dans un seul fichier de workflow. Les pull requests exécutent le scénario contre votre environnement de staging comme barrière de fusion. Les push vers main (ce que produit une fusion) exécutent le même scénario contre la production comme test de fumée post-déploiement.

name: API tests

on:
  pull_request:
    branches: [main]
  push:
    branches: [main]

jobs:
  pr-check:
    if: github.event_name == 'pull_request'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
      - run: npm install -g apidog-cli
      - name: Test staging
        run: |
          apidog run \
            --access-token "$APIDOG_ACCESS_TOKEN" \
            -t 605067 \
            -e 1629989 \
            -r junit,cli \
            --out-dir ./apidog-reports
        env:
          APIDOG_ACCESS_TOKEN: ${{ secrets.APIDOG_ACCESS_TOKEN }}
      - uses: actions/upload-artifact@v4
        if: always()
        with:
          name: staging-report
          path: ./apidog-reports

  prod-smoke:
    if: github.event_name == 'push'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
      - run: npm install -g apidog-cli
      - name: Smoke test production
        run: |
          apidog run \
            --access-token "$APIDOG_ACCESS_TOKEN" \
            -t 605067 \
            -e 1730055 \
            -r cli \
            --on-error end
        env:
          APIDOG_ACCESS_TOKEN: ${{ secrets.APIDOG_ACCESS_TOKEN }}

Les deux ID d'environnement (1629989 pour le staging, 1730055 pour la production) sont la seule différence significative. Le job de PR construit et archive un rapport JUnit afin que les relecteurs puissent inspecter les échecs ; le test de fumée de production s'exécute de manière allégée et échoue rapidement avec --on-error end, ce qui s'arrête à la première assertion cassée afin que vous sachiez rapidement qu'un déploiement a mal tourné.

--on-error est une option intéressante. Elle contrôle ce qui se passe lorsqu'une étape échoue au milieu d'un scénario. end arrête l'exécution à la première défaillance (feedback rapide, bon pour les tests de fumée). continue exécute toutes les étapes restantes afin que vous voyiez toutes les défaillances dans un seul rapport (bon pour une vérification PR approfondie). ignore ignore une étape connue pour être instable sans interrompre l'exécution. Quelle que soit votre choix, l'exécution se termine toujours par un code de sortie non nul si quelque chose a échoué, de sorte que la barrière est maintenue dans tous les cas.

Aller plus loin : exécutions matricielles, dossiers et tests pilotés par les données

Une fois la barrière de base en place, quelques drapeaux l'étendent sans beaucoup de YAML supplémentaire.

Exécutez une zone fonctionnelle entière, pas un seul scénario. Remplacez -t <scenarioId> par -f <folderId> pour exécuter chaque scénario dans un dossier, ou --test-suite <testSuiteId> pour exécuter une suite organisée. Les suites sont le bon outil lorsque vous voulez qu'un ensemble spécifique et ordonné de scénarios soit exécuté ensemble comme un seul job logique ; le guide sur l'mise à l'échelle des tests d'API automatisés avec les suites de tests explique quand les utiliser.

Testez plusieurs environnements en parallèle. Une matrice exécute le même job sur plusieurs ID d'environnement à la fois :

jobs:
  api-tests:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        env-id: [1629989, 1730055]
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
      - run: npm install -g apidog-cli
      - name: Run scenario against ${{ matrix.env-id }}
        run: |
          apidog run \
            --access-token "$APIDOG_ACCESS_TOKEN" \
            -t 605067 \
            -e ${{ matrix.env-id }} \
            -r cli
        env:
          APIDOG_ACCESS_TOKEN: ${{ secrets.APIDOG_ACCESS_TOKEN }}

GitHub lance un runner par valeur de matrice, donc le staging et la production sont testés concurremment et chacun rapporte son propre succès/échec.

Pilotez les itérations à partir d'un fichier de données. Le drapeau -d exécute un scénario sur les lignes d'un fichier CSV ou JSON, traitant chaque ligne comme un passage distinct : apidog run --access-token "$APIDOG_ACCESS_TOKEN" -t 605067 -d ./test-data.csv -r junit. C'est ainsi que vous validez le même point d'extrémité avec cinquante entrées sans construire cinquante scénarios.

Exécutez sur une branche. Si votre équipe utilise la fonctionnalité de branche d'Apidog, --branch <branchName> dirige l'exécution vers une branche spécifique au lieu de main, ce qui permet à la PR d'une branche de fonctionnalité de tester les définitions de scénario de cette branche.

Dépannage des échecs courants de la CI

Comparaison avec les alternatives

Vous pourriez écrire des tests d'API sous forme de code avec un framework, les intégrer à un exécuteur de tests et appeler cela depuis Actions. Cela fonctionne, mais vous devez alors maintenir une suite de code qui doit rester synchronisée avec l'API et avec ce que votre équipe conçoit dans son outil d'API. L'approche Apidog évite cette duplication : le scénario que votre équipe maintient déjà dans l'application est le test qui s'exécute en CI.

Vous pourriez également scripter des appels curl bruts dans une étape de workflow. C'est bien pour un simple contrôle de santé, mais pénible au-delà, car vous devriez créer manuellement les assertions, le changement d'environnement et le reporting que la CLI vous offre gratuitement.

GitHub Actions n'est pas non plus le seul endroit pour cela. La même commande apidog run peut être intégrée à GitLab CI, Jenkins, CircleCI, ou tout autre runner capable d'exécuter une commande shell et de lire un code de sortie. Si GitHub Actions n'est pas votre plateforme, les modèles présentés ici se transfèrent directement ; consultez le guide pour l'automatisation des tests d'API en CI/CD pour une vue multiplateforme, ou le guide sur l'intégration des tests automatisés Apidog avec Jenkins si vous utilisez Jenkins.

Pour construire les scénarios que vous exécuterez, téléchargez Apidog, concevez vos tests dans l'application, et récupérez la commande CLI depuis l'onglet CI/CD du scénario. L'exécuteur est un package npm gratuit ; ce que vous pouvez exécuter dépend de votre projet Apidog, mais l'exécuteur en ligne de commande lui-même n'est pas un produit payant séparé.

En résumé

La configuration est plus simple qu'il n'y paraît. Construisez un scénario dans Apidog, stockez un jeton d'accès comme secret GitHub, et ajoutez quelques étapes à un fichier de workflow. À partir de là, chaque pull request exécute automatiquement vos tests d'API, un point d'extrémité défaillant fait passer la vérification au rouge avant la fusion, et le rapport attend dans l'onglet Artefacts chaque fois que vous avez besoin de voir ce qui a échoué.

La raison pour laquelle cela reste simple est la division du travail. L'application Apidog gère les tests ; la CLI les exécute ; GitHub lit le code de sortie. Rien n'a besoin d'être dupliqué ou synchronisé. Lorsque vous mettez à jour une assertion dans l'application, la prochaine exécution CI l'utilise. C'est ce qui fait que cela vaut la peine d'être fait dès le premier jour d'un projet au lieu de l'ajouter après le premier incident de production.

bouton

Pratiquez le Design-first d'API dans Apidog

Découvrez une manière plus simple de créer et utiliser des API

S'inscrire gratuitementTélécharger