Comment exécuter des tests API Apidog CLI dans Harness CI/CD

Vous exécutez des tests Apidog CLI dans Harness en ajoutant une étape CI avec une seule étape "Run" qui installe apidog-cli, exécute apidog run et publie les résultats JUnit. Stockez votre jeton d'accès Apidog en tant que secret Harness, référencez-le avec l'expression <+secrets.getValue("...")> et pointez un bloc de rapport JUnit vers la sortie XML de l'interface CLI. Ce guide vous fournit un YAML de pipeline prêt à l'emploi pour Harness Cloud et un délégué auto-hébergé.

Qu'est-ce que Harness CI/CD ?

Harness CI est le module d'intégration continue de la plateforme Harness. Il construit, teste et valide votre code sur une infrastructure de build gérée ou auto-hébergée, puis transfère les artefacts à Harness CD pour le déploiement.

Vous définissez tout en YAML. Un pipeline contient une ou plusieurs étapes (stages). Chaque étape (stage) a un type, et une étape CI s'exécute sur une infrastructure de build. À l'intérieur de l'étape (stage), un bloc d'exécution contient une liste ordonnée de sous-étapes (steps) qui exécutent vos commandes.

Ce modèle s'adapte parfaitement aux tests d'API. Vous ajoutez une étape CI, y insérez une sous-étape qui exécute votre commande de test, et laissez Harness contrôler la build en fonction du résultat. Si les tests échouent, la sous-étape échoue et le pipeline s'arrête.

Harness lit le XML JUnit pour le rapport de tests. Étant donné que l'Apidog CLI peut émettre du JUnit, vous obtenez un onglet "Tests" natif avec les nombres de réussites et d'échecs pour chaque build. Aucun code de "glue" n'est requis.

Comment fonctionne Harness CI

La hiérarchie YAML est stricte, il est donc utile de visualiser l'imbrication avant d'écrire quoi que ce soit. Un pipeline CI se présente comme suit, de haut en bas :

• pipeline contient des métadonnées et une liste stages.
• Chaque stage a un type: CI et un spec.
• Le spec de l'étape (stage) déclare l'infrastructure de build et un bloc execution.
• execution contient une liste steps.
• Chaque step a un type, name, identifier et son propre spec.

Pour exécuter une commande shell, le type de sous-étape est Run. Le spec de l'étape "Run" contient un champ shell (Bash, Sh, PowerShell, Pwsh ou Python) et un champ command qui contient votre script. Vous écrivez des commandes multi-lignes avec le scalaire de bloc YAML |-.

Cette seule étape "Run" est tout ce dont vous avez besoin pour installer et exécuter l'Apidog CLI. Tout le reste dans ce guide est une configuration autour de cette étape unique.

L'Apidog CLI en une minute

L'Apidog CLI est un exécuteur en ligne de commande pour les scénarios de test que vous construisez visuellement dans Apidog. Vous concevez les tests dans l'application, puis vous les exécutez de manière "headless" dans n'importe quel pipeline, de manière similaire à la façon dont Newman exécute les collections Postman. Si vous souhaitez une comparaison, consultez Apidog CLI vs Newman.

Vous l'installez via npm et exécutez une seule commande :

npm install -g apidog-cli
apidog run --access-token <ACCESS_TOKEN> -t <TEST_SCENARIO_ID> -e <ENVIRONMENT_ID> -r cli,junit --out-dir ./apidog-reports

Quelques drapeaux sont importants pour la CI. Le drapeau `--access-token` authentifie l'exécution dans le cloud et n'a pas de forme courte. Le drapeau `-e` définit l'environnement et est obligatoire. Le drapeau `-t` sélectionne un scénario de test par ID. Le drapeau `-r` choisit les rapporteurs, et `junit` est l'une des valeurs prises en charge (`cli`, `html`, `json`, `junit`). Le drapeau `--out-dir` contrôle l'emplacement des rapports, par défaut `./apidog-reports`.

Ce choix `-r cli,junit` est le pont vers Harness. L'interface CLI écrit le XML JUnit dans le répertoire de sortie, et Harness le lit directement. Pour en savoir plus sur ce que produit l'interface CLI, consultez le guide sur les rapports de test de l'Apidog CLI.

Stockage de votre jeton d'accès Apidog en tant que secret Harness

Ne codez jamais en dur le jeton dans le YAML. Ajoutez-le d'abord au gestionnaire de secrets Harness, puis référencez-le.

Dans l'interface utilisateur de Harness, accédez aux paramètres de votre projet (ou de votre organisation/compte), ouvrez "Secrets" et créez un nouveau secret de type "Texte". Donnez-lui l'identifiant `apidog_token`. L'identifiant est ce que vous référencez dans le YAML, et il diffère du nom d'affichage.

Vous référencez le secret avec cette expression :

<+secrets.getValue("apidog_token")>

Utilisez l'identifiant à l'intérieur des guillemets, et non le nom d'affichage. Pour un secret étendu à l'organisation, préfixez-le par `org.` comme `<+secrets.getValue("org.apidog_token")>`. Pour un secret étendu au compte, utilisez `account.` à la place.

Enveloppez l'expression entre guillemets simples à l'intérieur d'une commande shell. Le jeton pourrait contenir un caractère `$`, et les guillemets simples empêchent le shell de l'interpréter. Vous pouvez en savoir plus sur la configuration des jetons dans les notes d'authentification Apidog CLI.

Pipeline Harness Cloud (point de départ recommandé)

Harness Cloud vous fournit des machines de build gérées par Harness avec Node.js et npm préinstallés. Il n'y a aucune infrastructure à maintenir, et Linux fonctionne immédiatement. C'est le moyen le plus rapide d'obtenir un pipeline fonctionnel.

Sur Harness Cloud, le spec de l'étape (stage) utilise un bloc platform et un bloc runtime de type: Cloud. Vous ne spécifiez pas d'image sur l'étape "Run" ici, car la machine gérée dispose déjà des outils.

pipeline:
  name: Apidog API Tests
  identifier: apidog_api_tests
  projectIdentifier: YOUR_PROJECT
  orgIdentifier: YOUR_ORG
  stages:
    - stage:
        name: API Tests
        identifier: api_tests
        type: CI
        spec:
          cloneCodebase: false
          platform:
            os: Linux
            arch: Amd64
          runtime:
            type: Cloud
            spec: {}
          execution:
            steps:
              - step:
                  type: Run
                  name: Run Apidog CLI Tests
                  identifier: run_apidog_cli_tests
                  spec:
                    shell: Sh
                    command: |-
                      npm install -g apidog-cli
                      apidog run \
                        --access-token '<+secrets.getValue("apidog_token")>' \
                        -t 605067 \
                        -e 1629989 \
                        -n 1 \
                        -r cli,junit \
                        --out-dir ./apidog-reports
                    reports:
                      type: JUnit
                      spec:
                        paths:
                          - apidog-reports/*.xml

Remplacez `605067` par l'ID de votre scénario de test et `1629989` par l'ID de votre environnement. Le drapeau `-n 1` exécute une seule itération. Définissez `cloneCodebase: false` car les tests se trouvent dans le cloud d'Apidog, le pipeline n'a donc pas besoin de votre dépôt.

Publication des résultats de test

Le bloc `reports` de l'étape "Run" est ce qui affiche les résultats dans Harness. Il prend un `type` `JUnit` et un `spec` avec une liste `paths` pointant vers vos fichiers XML.

reports:
  type: JUnit
  spec:
    paths:
      - apidog-reports/*.xml

Harness analyse uniquement le XML JUnit pour le reporting natif. Après la build, vous verrez un onglet "Tests" avec chaque scénario, son statut et son chronométrage. Le glob `apidog-reports/*.xml` correspond aux fichiers que l'interface CLI a écrits avec `-r cli,junit` dans le répertoire de sortie par défaut.

Harness offre également la fonction "Test Intelligence", qui utilise un type de sous-étape `Test` séparé pour n'exécuter que les tests affectés par un changement de code. Cette optimisation cible les tests unitaires au niveau du langage, et non les scénarios d'API "headless". Pour ingérer la sortie de l'Apidog CLI, l'étape "Run" simple avec un bloc `reports` JUnit est le chemin correct.

Si vous changez de rapporteurs, conservez au moins `junit` dans la liste `-r`. Sans cela, l'interface CLI n'écrit aucun XML, et l'onglet "Tests" reste vide même si la sous-étape elle-même réussit.

Alternative avec délégué auto-hébergé

Utilisez une build basée sur un délégué lorsque vous avez besoin d'un accès au réseau privé, d'un runtime personnalisé ou hérité, ou si vous souhaitez éviter les crédits de build de Harness Cloud. Un délégué Kubernetes exécute chaque étape (stage) sous forme de pod.

La structure change de deux manières. Le `spec` de l'étape (stage) utilise un bloc `infrastructure` au lieu de `platform` et `runtime`. Et sur une infrastructure Kubernetes, chaque étape "Run" doit déclarer un `connectorRef` et une `image`, car la sous-étape s'exécute à l'intérieur d'un conteneur que vous spécifiez.

        spec:
          cloneCodebase: false
          infrastructure:
            type: KubernetesDirect
            spec:
              connectorRef: YOUR_K8S_CONNECTOR
              namespace: harness-ci
          execution:
            steps:
              - step:
                  type: Run
                  name: Run Apidog CLI Tests
                  identifier: run_apidog_cli_tests
                  spec:
                    connectorRef: YOUR_DOCKER_CONNECTOR
                    image: node:20
                    shell: Sh
                    command: |-
                      npm install -g apidog-cli
                      apidog run \
                        --access-token '<+secrets.getValue("apidog_token")>' \
                        -t 605067 -e 1629989 -r cli,junit --out-dir ./apidog-reports
                    reports:
                      type: JUnit
                      spec:
                        paths:
                          - apidog-reports/*.xml

La ligne `image: node:20` vous fournit Node.js et npm à l'intérieur du pod. Les valeurs de `connectorRef` pointent vers vos connecteurs Kubernetes et Docker enregistrés. Ne mélangez pas les deux styles d'infrastructure dans une même étape (stage). Une étape est soit Harness Cloud (`platform` plus `runtime`), soit basée sur un délégué (`infrastructure`), jamais les deux.

Choisir entre Harness Cloud et un délégué

Choisissez en fonction de l'emplacement de vos API et de qui possède les machines de build.

Commencez avec Harness Cloud si votre environnement Apidog cible des points d'accès publics. Passez à un délégué lorsque votre environnement de test se trouve derrière un VPN ou nécessite un runtime que vous contrôlez. L'étape "Run" et la commande Apidog restent presque identiques entre les deux.

Exécutions basées sur les données (Data-driven runs)

Vous pouvez alimenter l'exécution avec un fichier CSV ou JSON pour des tests paramétrés. Le drapeau `-d` (nom long `--iteration-data`) prend le chemin du fichier de données, et `-n` définit le nombre d'itérations.

apidog run --access-token <ACCESS_TOKEN> -t <TEST_SCENARIO_ID> -e <ENVIRONMENT_ID> -d ./data.csv -n 5 -r cli,junit --out-dir ./apidog-reports

Dans une étape "Run" de Harness, vous feriez d'abord un `git clone` ou mettrait en scène le fichier de données d'une autre manière, puis pointeriez `-d` vers son chemin. Pour le modèle complet, consultez le guide sur les tests pilotés par les données de l'Apidog CLI et le guide plus large sur les tests d'API automatisés.

Pourquoi concevoir les tests dans Apidog en premier lieu

L'interface CLI n'exécute que des scénarios qui existent déjà dans votre projet Apidog. C'est tout l'intérêt. Apidog est une plateforme API tout-en-un pour la conception, le débogage, les tests, le mocking et la documentation, vous construisez donc votre suite de tests une seule fois et la réutilisez partout.

Vous concevez des tests avec un constructeur visuel, sans nécessiter de script. Vous enchaînez les requêtes, extrayez les valeurs d'une réponse pour les utiliser dans la suivante, et ajoutez des assertions via une interface utilisateur. L'interface CLI exécute ensuite cette suite exacte en mode "headless" dans Harness, de sorte que ce que vous déboguez localement est ce qui s'exécute dans le pipeline.

Parce qu'Apidog est natif OpenAPI avec support de branches et espaces de travail d'équipe, vos ingénieurs QA et développeurs backend partagent une source unique de vérité. Un scénario approuvé dans une branche devient le même scénario que votre commande `apidog run` exécute. Pour des modèles de pipeline plus larges, le guide Qu'est-ce que CI/CD et le guide de workflow GitHub Actions couvrent la même interface CLI dans d'autres systèmes. Le tutoriel Jenkins dans intégrer les tests Apidog avec Jenkins utilise la même forme de commande.

Téléchargez Apidog gratuitement pour construire votre premier scénario de test, puis intégrez-le à Harness avec le YAML ci-dessus.

Foire Aux Questions

Qu'est-ce que Harness CI/CD ?

Harness CI/CD est une plateforme de pipeline pour la construction, les tests et le déploiement de logiciels. Vous définissez les pipelines en YAML, composés d'étapes (stages) et de sous-étapes (steps). Une étape CI s'exécute sur une infrastructure de build, soit des machines Cloud gérées par Harness, soit un délégué auto-hébergé, et une étape CD gère le déploiement.

Comment fonctionne Harness CI ?

Un pipeline contient une liste d'étapes (stages). Chaque étape CI a un "spec" qui déclare l'infrastructure de build et un bloc d'exécution. Le bloc d'exécution exécute une liste ordonnée de sous-étapes (steps). Une étape "Run" exécute une commande shell, c'est là que vous installez et exécutez l'Apidog CLI.

Comment stocker et utiliser des secrets dans Harness ?

Créez un secret de type "Texte" dans le gestionnaire de secrets Harness et notez son identifiant. Référencez-le dans le YAML avec <+secrets.getValue("identifier")>, en utilisant l'identifiant plutôt que le nom d'affichage. Préfixez avec `org.` ou `account.` pour ces portées, et enveloppez l'expression entre guillemets simples à l'intérieur des commandes shell.

Comment publier les résultats de test dans Harness ?

Ajoutez un bloc `reports` à votre étape "Run" avec `type: JUnit` et une liste `paths` pointant vers vos fichiers XML. Harness analyse le XML JUnit et affiche les résultats dans l'onglet "Tests" de la build. L'Apidog CLI émet ce XML lorsque vous passez `-r junit` ou `-r cli,junit`.

Harness CI est-il gratuit ?

Harness propose un niveau gratuit pour la CI, et les builds de Harness Cloud consomment des crédits de build inclus dans votre plan. Les tarifs et les limites de crédits évoluent avec le temps, alors consultez la page de tarification actuelle de Harness pour connaître les chiffres exacts avant de vous engager dans un niveau.

Puis-je exécuter des tests Apidog CLI sans cloner mon dépôt ?

Oui. Définissez `cloneCodebase: false` sur l'étape (stage) lorsque vos tests résident dans le cloud d'Apidog. L'interface CLI s'authentifie avec votre jeton d'accès et récupère le scénario et l'environnement par leur ID, de sorte que le pipeline n'a jamais besoin de votre code source pour l'exécution du test.