Hoppscotch est un écosystème d'API open-source : application web, application de bureau, CLI et un backend auto-hébergeable, souvent décrit comme une alternative ouverte à Postman et Insomnia. La CLI Hoppscotch est l'outil qui prend les collections que vous créez dans cet écosystème et les exécute depuis un terminal, ce qui est exactement ce dont vous avez besoin pour le CI/CD.
Ce guide explique ce qu'est la CLI Hoppscotch, comment l'installer, et comment la commande hopp test fonctionne réellement, avec les vrais drapeaux et un exemple de CI fonctionnel. Si vous la comparez à d'autres exécuteurs, l'article sur les meilleures alternatives à la CLI Hoppscotch compare les options, et Apidog CLI vs Hoppscotch CLI est la comparaison directe.
Qu'est-ce que la CLI Hoppscotch ?
La CLI Hoppscotch est distribuée sous forme de package npm @hoppscotch/cli. Sa tâche est précise et utile : prendre une collection Hoppscotch, exécuter chaque requête qu'elle contient, exécuter les scripts de test attachés à ces requêtes, et se terminer avec un code de réussite/échec que votre pipeline peut lire.
Cela en fait un exécuteur de collection, de la même catégorie que Newman pour Postman ou inso pour Insomnia. Il ne conçoit pas d'API, ne simule pas de points de terminaison, ni ne génère de documentation. Il exécute des requêtes et vérifie des assertions. Pour un outil gratuit et open-source que vous pouvez également auto-héberger, cette focalisation est essentielle.
Comme Hoppscotch est open source, vous pouvez exécuter toute la pile vous-même et pointer la CLI vers votre propre instance. Les équipes qui ne veulent pas que leurs données de requête résident dans un cloud de fournisseur ont tendance à apprécier cela. L'inconvénient est que vous êtes responsable de l'hébergement.
Installation de la CLI Hoppscotch
Installez-la globalement depuis npm :
npm i -g @hoppscotch/cli
Une exigence à surveiller : la CLI actuelle nécessite Node.js v22 ou plus récent. Si vous êtes toujours sur Node 20, vous pouvez rester sur la CLI v0.26.0, mais les dernières versions supposent v22+. Vérifiez votre version avant de l'intégrer à un agent de build :
node --version
hopp --version
Si votre image CI utilise une ancienne version de Node, épinglez le runtime à v22 dans le pipeline, ou vous rencontrerez une erreur d'installation ou d'exécution qui semblera sans rapport avec vos tests.
La commande hopp test
Tout s'exécute via hopp test. La forme de base la pointe vers un fichier de collection :
hopp test ./my-collection.json
Vous pouvez passer un fichier d'environnement et un délai entre les requêtes :
hopp test ./my-collection.json -e ./staging.env.json -d 500
Ici, -e (ou --env) fournit l'environnement, et -d (ou --delay) attend le nombre de millisecondes donné entre les requêtes, ce qui est utile lorsque vous accédez à une API à débit limité.
Si vos collections résident dans une instance Hoppscotch (cloud ou auto-hébergée) plutôt que dans un fichier local, vous les référencez par ID et vous vous authentifiez avec un jeton d'accès personnel :
hopp test <collection-id> --token <access_token> --server https://hoppscotch.your-company.com
--token transmet votre jeton d'accès personnel, et --server pointe vers votre URL auto-hébergée. Supprimez --server si vous utilisez le cloud Hoppscotch hébergé.
Exécutions basées sur les données et rapports
Deux drapeaux transforment hopp test d'une simple exécution en quelque chose compatible avec le CI.
Pour les tests basés sur les données, alimentez un CSV et définissez le nombre d'itérations à exécuter :
hopp test ./my-collection.json --iteration-data ./users.csv --iteration-count 3
--iteration-data prend un CSV dont les colonnes deviennent des variables à chaque exécution, et --iteration-count contrôle le nombre de fois que la collection se répète. C'est la même idée que le -d de Newman, et cela couvre le cas courant "exécuter ce flux de connexion pour 50 comptes".
Pour les rapports, la CLI écrit du XML JUnit, que la plupart des systèmes CI peuvent ingérer pour afficher les résultats des tests nativement :
hopp test ./my-collection.json --reporter-junit ./report.xml
JUnit est le seul format de rapport structuré que la CLI produit. Si vous avez besoin d'artefacts HTML ou de rapports hébergés et liés, c'est une lacune à connaître avant de vous engager. Des outils comme la CLI Apidog émettent des rapports CLI, HTML et JSON pour comparaison.
Ce qui s'exécute réellement pendant une exécution
Lorsque vous exécutez hopp test, la CLI parcourt la collection dans l'ordre et, pour chaque requête :
- exécute le script de pré-requête,
- envoie la requête,
- exécute le script de test et évalue chaque assertion.
Les scripts de test utilisent l'API de script de Hoppscotch : pw.test() définit un bloc de test et pw.expect() effectue des assertions à l'intérieur. Un petit exemple attaché à une requête ressemble à ceci :
pw.test("Status is 200", () => {
pw.expect(pw.response.status).toBe(200);
});
Si une assertion échoue, la commande se termine avec un code non nul. Si tout réussit, elle se termine avec 0. Ce comportement de code de sortie est le contrat entier avec le CI : une sortie non nulle fait échouer la build, ce qui est exactement ce que vous voulez.
Un exemple GitHub Actions
L'intégration de hopp test dans le CI est rapide. Ce workflow installe la CLI sur un exécuteur Node 22 et exécute une collection à chaque push :
name: API tests
on: [push]
jobs:
hopp:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: 22
- run: npm i -g @hoppscotch/cli
- run: hopp test ./collection.json -e ./ci.env.json --reporter-junit ./report.xml
L'étape setup-node épinglant la version 22 est la partie que les gens oublient. Sans elle, le Node par défaut de l'exécuteur peut être trop ancien pour la CLI actuelle.
Limitations à prendre en compte
La CLI Hoppscotch est performante dans ce qu'elle fait, et honnête quant à son champ d'application :
- C'est un exécuteur de collection, pas une plateforme. Pas de conception, de mocking ou de documentation. Vous les apportez d'ailleurs.
- Vous exportez ou hébergez vous-même les collections. La CLI exécute un fichier de collection ou en récupère un depuis une instance que vous lui indiquez.
- JUnit est le seul rapport structuré. Pas de HTML intégré ou de rapport hébergé.
- Node v22+. Une exigence stricte sur les versions actuelles.
Rien de tout cela n'est une critique ; c'est le coût d'un petit outil gratuit et open-source. Si vos besoins dépassent "exécuter une collection en CI" pour inclure la conception, le mocking, les exécutions basées sur les données avec des rapports plus riches, et la gestion des ressources API en tant que code, c'est là qu'une plateforme intégrée entre en jeu. Apidog couvre l'ensemble du cycle de vie des API, et le guide complet de la CLI Apidog montre le côté terminal. Vous pouvez télécharger Apidog et importer une collection Hoppscotch pour comparer directement, ou lire la procédure de migration.
FAQ
La CLI Hoppscotch est-elle gratuite ? Oui. C'est un projet open source sous Hoppscotch, et vous pouvez auto-héberger tout l'écosystème. Consultez la documentation officielle de la CLI et le dépôt GitHub.
Quelle est la différence entre hopp test et Newman ? Les deux sont des exécuteurs de collection avec des itérations basées sur les données. Newman exécute des collections Postman ; hopp test exécute des collections Hoppscotch. Les concepts se recoupent étroitement, y compris les données d'itération CSV et le succès/échec basé sur le code de sortie.
La CLI Hoppscotch peut-elle exécuter des collections depuis un serveur auto-hébergé ? Oui. Utilisez hopp test <collection-id> --token <access_token> --server <votre-url> pour récupérer et exécuter une collection depuis votre propre instance.
Produit-elle des rapports HTML ? Pas directement. Elle écrit du XML JUnit via --reporter-junit. Pour des rapports CLI, HTML et JSON combinés, comparez avec les rapports de test de la CLI Apidog.
La CLI Hoppscotch est un moyen propre et gratuit d'exécuter des collections d'API en CI, surtout si vous utilisez déjà Hoppscotch ou si vous l'auto-hébergez. Connaissez son champ d'application, épinglez Node v22, et utilisez la sortie JUnit, et elle fait très bien son travail unique.