Si vous avez utilisé le client API Insomnia, vous disposez d'un environnement graphique pour envoyer des requêtes, concevoir des spécifications OpenAPI et écrire des tests. Mais les outils graphiques s'arrêtent aux limites de votre machine. Dès que vous souhaitez exécuter ces mêmes tests dans un pipeline CI, ou que vous voulez analyser une spécification à chaque pull request, vous avez besoin de quelque chose qui fonctionne dans le terminal. Ce quelque chose, c'est inso.
Ce guide explique ce qu'est inso, comment l'installer, les commandes exactes que vous utiliserez au quotidien, comment il trouve vos spécifications et collections, et où ses limites apparaissent. À la fin, vous saurez si l'interface de ligne de commande inso correspond à votre flux de travail, et vers quoi vous tourner si ce n'est pas le cas.
Qu'est-ce qu'inso ?
inso est le compagnon en ligne de commande d'Insomnia, le client API open-source désormais maintenu par Kong. Il reprend trois des fonctionnalités d'Insomnia dans son interface utilisateur et les rend scriptables : l'exécution de tests, l'exécution de collections de requêtes et l'analyse syntaxique de spécifications API. Cela en fait le pont entre Insomnia sur votre bureau et les vérifications automatisées que vous souhaitez dans le CI/CD.
La version courte de « qu'est-ce qu'inso » : c'est ainsi que vous exécutez votre travail Insomnia sans ouvrir Insomnia. Vous le pointez vers un document de conception ou une collection par son nom, et il s'exécute avec les mêmes données que celles que votre application connaît déjà.
Installation de l'interface de ligne de commande inso
Vous avez plusieurs chemins documentés. Choisissez celui qui correspond à votre mode de distribution.
Homebrew est le plus simple sur macOS et Linux :
brew install inso
Docker est le choix le plus propre pour les agents CI, où vous ne voulez pas gérer une chaîne d'outils locale :
docker pull kong/inso:latest
Vous pouvez également télécharger directement. Kong publie des archives zip pour Windows, Linux et macOS sur le site de documentation de l'interface de ligne de commande inso, ce qui est pratique lorsque vous souhaitez une version spécifique dans un artefact de build.
Historiquement, inso était également distribué sur npm sous le nom insomnia-inso. Cette voie existe toujours, mais les chemins documentés et recommandés sont désormais Homebrew, Docker et les téléchargements directs. Si vous configurez quelque chose de nouveau, préférez ceux-là.
Confirmez que l'installation est réussie :
inso --version
Les commandes inso principales
inso a une surface petite et ciblée. Voici les commandes que vous utiliserez réellement, avec des exemples concrets.
inso run test
Exécutez une suite de tests unitaires que vous avez créée dans Insomnia, contre un environnement nommé :
inso run test "Payments API tests" --env "Staging"
La suite et l'environnement sont tous deux référencés par leur nom, exactement tels qu'ils apparaissent dans vos données Insomnia. La commande inso run test renvoie un code de sortie non nul si une assertion échoue, ce qui la rend utilisable comme porte de contrôle CI.
inso run collection
Exécutez chaque requête d'une collection en séquence, là encore contre un environnement nommé :
inso run collection "Checkout flow" --env "Staging"
C'est l'équivalent le plus proche de « lire tout le dossier » dans l'interface utilisateur. C'est utile pour les tests de fumée où vous voulez confirmer qu'une séquence de points de terminaison répond tous comme prévu.
inso lint spec
Validez un document de conception OpenAPI :
inso lint spec "Orders API"
En coulisses, inso lint spec utilise Spectral, l'outil d'analyse syntaxique OpenAPI et JSON open-source de Stoplight. C'est une véritable force qu'il convient de souligner clairement : vous obtenez une analyse syntaxique de spécifications réelle, basée sur des règles, avec un ensemble de règles mature, et non une simple vérification superficielle de la syntaxe. Si votre équipe se soucie du respect des guides de style sur les spécifications, cette commande est la raison pour laquelle de nombreuses personnes conservent inso.
inso export spec
Extrayez un document de conception vers un fichier sur le disque :
inso export spec "Orders API" --output orders.yaml
Pratique lorsque vous voulez alimenter une autre génération, valider un instantané ou le transmettre à un outil qui s'attend à un fichier YAML simple.
inso script
Exécutez un script nommé défini dans vos données Insomnia, en passant un environnement par son identifiant :
inso script deploy-smoke --env env_9f2a
C'est la porte de sortie pour enchaîner vos propres étapes personnalisées.
Comment inso trouve vos spécifications et collections
C'est la partie qui déroute les gens, il est donc important d'être précis. inso ne stocke rien lui-même. Il lit à partir de deux emplacements :
- Un répertoire
.insomniadans votre répertoire de travail. C'est ce que produit la synchronisation Git d'Insomnia, donc lorsque vous commettez votre projet API dans un dépôt, inso peut le lire directement depuis le checkout. C'est le modèle que vous souhaitez pour la CI. - Le répertoire de données de l'application Insomnia, si l'application est installée sur la machine. C'est pratique localement mais inutile sur un agent CI propre qui n'a jamais eu l'application.
Vous pouvez remplacer la source explicitement :
inso lint spec "Orders API" --workingDir ./api-project
# ou pointer vers une source exacte
inso run test "Payments API tests" --src ./api-project/.insomnia
Le modèle mental clé : inso référence tout par nom (ou id), et ces noms se résolvent par rapport à la source de données qu'il a trouvée. Si un nom n'est pas présent dans le répertoire .insomnia ou les données de l'application, inso ne peut pas l'exécuter. Il n'y a pas de concept de pointer inso vers un fichier OpenAPI isolé et de dire « testez ceci » à moins que ce fichier ne se trouve dans une structure de projet Insomnia.
Un exemple minimal de CI
Voici un job GitHub Actions qui analyse une spécification et exécute une suite de tests à chaque push, en utilisant le répertoire .insomnia synchronisé avec Git et commité dans le dépôt :
name: API checks
on: [push]
jobs:
inso:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Install inso
run: |
curl -sSL https://github.com/Kong/insomnia/releases/latest/download/inso-linux-x64.zip -o inso.zip
unzip inso.zip && sudo mv inso /usr/local/bin/
- name: Lint the spec
run: inso lint spec "Orders API" --workingDir .
- name: Run the test suite
run: inso run test "Payments API tests" --env "CI" --workingDir .
Comme les deux commandes renvoient un code de sortie non nul en cas d'échec, une spécification cassée ou une assertion échouée fait échouer le job. C'est tout l'intérêt de déplacer ces vérifications hors de l'interface graphique.
Limitations honnêtes
inso est bon dans ce qu'il fait, mais il a de réelles limites.
Il est lié aux sources de données d'Insomnia. Vos spécifications, collections et suites doivent vivre dans un projet Insomnia, exposées soit via Git Sync, soit via l'application installée. Si votre équipe n'utilise pas Insomnia comme source de vérité, inso n'a rien sur quoi opérer.
Tout est référencé par nom. C'est lisible, mais c'est fragile. Renommez une suite dans l'interface utilisateur et un job CI qui code en dur l'ancien nom se brisera silencieusement jusqu'à la prochaine exécution. Les noms doivent également être suffisamment uniques pour être résolus proprement.
La portée est étroite par conception. inso exécute des tests, exécute des collections, analyse des spécifications, exporte et exécute des scripts. Ce n'est pas une plateforme de conception, de mock, de documentation et de test. Pour tout ce qui dépasse ces actions, vous êtes de retour dans l'interface graphique ou vous devez utiliser d'autres outils.
inso vs l'alternative intégrée
inso est un excellent compagnon terminal lorsque Insomnia est déjà votre client. Le compromis est que vous assemblez des pièces : Insomnia pour la conception et le débogage, inso pour la CI, les règles Spectral pour l'analyse syntaxique, et des outils séparés pour les mocks et la documentation.
Apidog adopte une position opposée. Il réunit la conception, le mock, la documentation et les tests sur une seule plateforme, et son CLI Apidog exécute vos scénarios de test et collections à partir de la même source de vérité, avec des tests basés sur les données, plusieurs formats de rapport, et des ressources et branches en tant que code. Il est juste de noter ici : le CLI Apidog n'embarque pas un analyseur syntaxique de spécifications autonome comme inso le fait avec Spectral, donc si l'application d'un guide de style à la Spectral est votre priorité, inso a un réel avantage là. Là où Apidog prend l'avantage, c'est l'intégration. Vous n'assemblez pas cinq outils ensemble.
Si vous souhaitez comparer les deux en tête-à-tête, consultez Apidog CLI vs inso (Insomnia CLI), ou lisez les informations plus approfondies dans qu'est-ce qu'inso (Insomnia CLI). Si vous avez décidé qu'inso n'est pas la bonne solution, le récapitulatif des meilleures alternatives à inso et le guide de migration d'inso vers Apidog CLI vous guident étape par étape. Pour un contexte plus large sur les clients GUI eux-mêmes, Apidog vs Insomnia et comment utiliser Insomnia pour tester une API sont de bons points de départ.
Vous pouvez télécharger Apidog gratuitement si vous voulez voir l'approche intégrée côte à côte avec votre configuration inso.