Comment migrer de Hoppscotch CLI vers Apidog CLI

La CLI Hoppscotch est un moyen simple et gratuit d'exécuter des collections d'API dans un terminal ou un pipeline CI. La commande hopp test lit un fichier de collection, exécute chaque requête, exécute vos scripts de pré-requête et de test, et se termine avec un code d'erreur non nul en cas d'échec d'une assertion. Pour de nombreuses équipes, cela suffit.

Mais un exécuteur (runner) n'est qu'une facette du travail avec les API. À un certain moment, vous jonglez avec un outil de conception distinct, un serveur de maquette, un site de documentation et l'exécuteur, et aucun d'entre eux ne partage une source de vérité unique. C'est généralement à ce moment-là que les équipes commencent à envisager de migrer de la CLI Hoppscotch vers la CLI Apidog. Apidog intègre la conception, le débogage, le mocking, la documentation et les tests dans une seule plateforme, et sa CLI gère la partie test en CI. L'exécuteur conserve la forme que vous connaissez déjà. Ce qui change, c'est tout ce qui l'entoure.

Quand vous devriez (et ne devriez pas) migrer

Soyez d'abord honnête avec vous-même. Si votre seule exigence est de "exécuter une collection en CI gratuitement, l'héberger vous-même si vous le souhaitez", la CLI Hoppscotch est un très bon outil. C'est open source, l'exécuteur est rapide, et @hoppscotch/cli est livré comme un package npm normal. Il n'y a aucune honte à rester.

Migrez lorsque l'un de ces points commence à vous poser problème :

• Vous concevez des API dans un outil, vous les maquettez dans un autre, et vous écrivez la documentation dans un troisième, et les maintenir synchronisés est un travail manuel.
• Vous souhaitez que les exécutions de tests, les serveurs de maquette et la documentation publiée partagent une définition de projet unique.
• Vous avez besoin de rapports plus riches (rapports HTML pour les parties prenantes, JSON pour les machines) ainsi qu'un historique d'exécution hébergé dans le cloud.
• Vous voulez traiter les points de terminaison, les schémas, les environnements et les branches comme du code que la CLI peut gérer, et pas seulement exécuter.

Si cette liste correspond à votre semaine, la plateforme est la raison de bouger, pas l'exécuteur. Voici comment le faire proprement.

Étape 1 : Exportez votre collection et votre environnement Hoppscotch

Tout dans Hoppscotch est au format JSON, ce qui rend l'exportation indolore.

Depuis l'application Hoppscotch (web ou bureau), ouvrez la collection que vous exécutez en CI. Utilisez le menu de la collection et choisissez Exporter, ce qui vous donnera un fichier .json. Faites de même pour l'environnement que vous passez avec -e : ouvrez le panneau des environnements et exportez-le dans son propre fichier JSON.

Si vous exécutez déjà la CLI avec des fichiers locaux, vous les avez déjà sur votre disque. Une étape CI Hoppscotch typique ressemble à ceci :

npm i -g @hoppscotch/cli
hopp test ./collections/checkout-api.json -e ./environments/staging.json

Conservez les deux fichiers. checkout-api.json est votre collection, staging.json est votre environnement. Ces deux éléments constituent l'ensemble de la charge utile que vous transférez.

Une remarque sur les versions de Node pendant que vous y êtes. La CLI Hoppscotch actuelle nécessite Node.js v22 ou plus récent ; les équipes bloquées sur Node 20 restent sur la CLI v0.26.0. La CLI Apidog ne vous contraint pas à cela, donc une migration est aussi l'occasion de supprimer une contrainte de version.

Étape 2 : Importez la collection dans Apidog

Créez un projet dans Apidog (ou ouvrez un projet existant), puis importez votre exportation Hoppscotch. Apidog lit les formats de collection courants et OpenAPI, vous pouvez donc importer la collection directement. Si votre API possède également une spécification OpenAPI, importez-la aussi. Apidog valide la spécification lors de l'importation, de sorte que les problèmes structurels apparaissent immédiatement au lieu d'échouer silencieusement en cours d'exécution.

Mappez votre environnement Hoppscotch dans un environnement Apidog avec les mêmes noms de variables. Si staging.json définissait base_url et api_token, recréez ces clés sous l'environnement Apidog correspondant. Garder les noms identiques signifie que vos scripts de test et URL de requête n'auront pas besoin de modifications.

C'est aussi le moment où la partie plateforme commence à porter ses fruits. Les points de terminaison que vous avez importés sont désormais des artefacts de conception. Vous pouvez y joindre des schémas, en générer un serveur de maquette et publier de la documentation à partir des mêmes définitions que celles que vous testez. Le guide complet de la CLI Apidog couvre l'ensemble des fonctionnalités une fois que vous êtes configuré, et le guide d'installation gère le binaire de l'exécuteur.

Étape 3 : Mapper hopp test à apidog run

Le modèle mental se transpose directement. Là où Hoppscotch exécute un fichier de collection, Apidog exécute un scénario de test ou une collection à partir de votre projet. Même tâche, source de vérité différente.

# Hoppscotch
hopp test ./collections/checkout-api.json -e ./environments/staging.json

# Apidog
apidog run --access-token $APIDOG_TOKEN -e "Staging"

Les deux commandes exécutent chaque requête dans l'ordre, exécutent les scripts de pré-requête, exécutent vos assertions de test et renvoient un code d'erreur non nul si quelque chose échoue. Ce contrat de code de sortie est la partie sur laquelle la CI s'appuie, et il est préservé, de sorte que la logique de réussite/échec de votre pipeline ne change pas.

L'authentification diffère d'une manière utile. Hoppscotch passe un jeton d'accès personnel avec --token pour les collections hébergées dans le cloud ou auto-hébergées. Apidog s'authentifie avec une connexion ou un jeton d'accès, ce qui permet ensuite à la CLI d'accéder aux ressources de votre projet plutôt qu'à un seul fichier exporté. Si vous avez déjà eu des difficultés avec la gestion des jetons, le guide d'authentification présente les options.

Étape 4 : Convertir les exécutions pilotées par les données

Les deux outils effectuent des tests pilotés par les données, donc l'itération sur un fichier CSV d'entrées survit à la migration.

Dans Hoppscotch, vous passez les données d'itération et un nombre :

hopp test ./collections/checkout-api.json \
  -e ./environments/staging.json \
  --iteration-count 50 \
  --iteration-data ./data/orders.csv

Dans Apidog, l'exécuteur prend un ensemble de données avec -d. Il accepte les formats CSV et JSON, donc le même fichier orders.csv fonctionne après l'importation :

apidog run --access-token $APIDOG_TOKEN \
  -e "Staging" \
  -d ./data/orders.csv

Votre ligne d'en-tête CSV devient les noms de variables que vous référencez dans les requêtes et les assertions, le même modèle qu'utilise Hoppscotch, de sorte que les corps de test n'ont pas besoin d'être réécrits. Si vous êtes nouveau dans la saveur Apidog de cela, le guide de test piloté par les données montre comment lier des colonnes à des variables et exécuter une ligne par itération.

Étape 5 : Convertir vos rapporteurs

Le reporting est l'endroit où la plateforme prend de l'avance, et la conversion est simple.

Hoppscotch émet un fichier XML JUnit avec un seul drapeau, que la plupart des systèmes CI analysent pour les panneaux de test :

hopp test ./collections/checkout-api.json \
  -e ./environments/staging.json \
  --reporter-junit ./reports/results.xml

Apidog vous offre un choix de rapporteurs : un résumé CLI lisible, un rapport HTML que vous pouvez remettre aux parties prenantes, et un rapport JSON pour les machines. Vous pouvez également envoyer les résultats vers le cloud pour un historique d'exécution partageable.

# Rapport HTML lisible par l'homme
apidog run --access-token $APIDOG_TOKEN \
  -e "Staging" \
  -r html \
  --upload-report

Si votre tableau de bord CI attend spécifiquement un fichier XML JUnit, gardez cette intégration à l'esprit pendant le remplacement, car Apidog s'appuie sur ses rapporteurs CLI/HTML/JSON ainsi que sur les rapports cloud plutôt que sur un drapeau JUnit. Pour la plupart des équipes, le rapport HTML plus l'historique cloud téléchargé constitue une amélioration par rapport à un fichier XML brut que personne n'ouvre. Le guide des rapports de test détaille chaque format et quand l'utiliser.

Avant et après : mappage des commandes

Surveillez le drapeau -d dans ce tableau. Dans Hoppscotch, -d est le délai en millisecondes ; dans Apidog, -d est l'ensemble de données pour les exécutions pilotées par les données. Même lettre, fonction différente. C'est le seul piège qui fait trébucher les gens lors du passage de Hoppscotch à Apidog.

Étape 6 : Intégrer dans GitHub Actions

Dernière étape, et l'objectif est une construction verte du début à la fin. Installez d'abord la tâche Apidog à côté de l'ancienne tâche Hoppscotch, confirmez qu'elle passe, puis supprimez l'ancienne étape. Ne jamais basculer à l'aveugle.

name: Tests API
on: [push, pull_request]

jobs:
  apidog-tests:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Installer la CLI Apidog
        run: npm install -g apidog-cli

      - name: Exécuter les tests API
        env:
          APIDOG_TOKEN: ${{ secrets.APIDOG_TOKEN }}
        run: |
          apidog run \
            --access-token "$APIDOG_TOKEN" \
            -e "Staging" \
            -d ./data/orders.csv \
            -r html \
            --upload-report

Stockez votre jeton d'accès en tant que secret de dépôt, jamais directement dans le YAML. Parce que la CLI renvoie un code d'erreur non nul en cas d'échec d'une assertion, la tâche échoue exactement au moment où vos tests échouent, ce qui est le comportement auquel votre équipe fait déjà confiance avec Hoppscotch. Le guide GitHub Actions couvre la mise en cache et les exécutions matricielles, et le guide général des pipelines CI/CD gère GitLab, Jenkins, et le reste.

Une fois que la tâche Apidog est "verte" (réussit) pendant quelques exécutions, supprimez l'étape Hoppscotch et son installation npm. Migration terminée, la construction n'est jamais passée au rouge.

Un mot juste sur Hoppscotch

Rien de tout cela n'est une critique de Hoppscotch. Son exécuteur CLI est rapide et gratuit, le projet est entièrement open source, et vous pouvez auto-héberger toute la pile. Si vous voulez un exécuteur léger et rien de plus, il mérite sa place. La raison de changer est l'étendue : lorsque la conception, les maquettes, la documentation et les tests doivent tous partager une seule définition, un exécuteur autonome ne peut pas vous offrir cela, alors qu'une plateforme intégrée le peut. Comparez les deux exécuteurs directement dans Apidog CLI vs Hoppscotch CLI, et si vous comparez les applications plutôt que les CLI, Postman vs Hoppscotch et le récapitulatif des alternatives à Hoppscotch ajoutent du contexte.