Comment migrer de inso (Insomnia CLI) vers Apidog CLI

Si vous exécutez des tests d'API à partir d'inso, l'interface de ligne de commande (CLI) d'Insomnia de Kong, et que vous envisagez un changement, ce guide vous accompagnera de bout en bout. Vous verrez comment exporter vos spécifications et suites de tests d'Insomnia, les importer dans Apidog, et réécrire vos commandes inso run en commandes apidog run. Un tableau comparatif des commandes avant/après est inclus pour que vous puissiez adapter vos scripts CI existants ligne par ligne.

Pourquoi les équipes migrent d'inso vers Apidog CLI

inso est un outil robuste. Il permet l'exécution de requêtes, le linting Spectral et les tests unitaires dans le terminal, et il lit à partir d'un répertoire .insomnia créé par la synchronisation Git d'Insomnia. Si ce flux de travail vous convient, rien ne vous oblige à partir.

La friction commence généralement avec l'application Insomnia, et non la CLI. Deux éléments motivent la plupart des recherches de migration :

• Le compte cloud obligatoire. Insomnia 8, sorti en 2023, a introduit une connexion/un compte cloud obligatoire qui a pris de nombreuses équipes par surprise. De nombreux développeurs souhaitaient un client local avant tout et ont obtenu un mur de connexion à la place.
• Perte de données et difficultés de migration. Certains utilisateurs ont rencontré des incidents de perte de données et de migration pendant cette transition. Si vous en avez vécu un, vous en connaissez déjà le coût. Si vous vous en remettez actuellement, ces guides vous aideront : récupérer et exporter les données Insomnia et le guide plus détaillé sur la récupération et la migration des données perdues d'Insomnia 8.

L'autre raison est la consolidation. Avec inso, la CLI n'est qu'un élément d'une pile : Insomnia pour les requêtes, Spectral pour le linting, des outils distincts pour les mocks et la documentation. Apidog intègre la conception, le débogage, les tests, les mocks et la documentation dans une seule plateforme, et la CLI gère la partie test de cette plateforme. Moins de pièces mobiles, une seule source de vérité.

Si vous souhaitez un contexte plus large avant de vous engager, Apidog vs Insomnia et choisir entre Insomnia et Apidog exposent les compromis pour les applications complètes, pas les CLI.

Avant de commencer : ce qui migre et ce qui ne migre pas

Définissez vos attentes dès le départ afin que rien ne vous surprenne en cours de migration.

La note honnête : inso lint spec exécute Spectral, le linter OpenAPI de Stoplight, et c'est une véritable force. Apidog CLI ne fournit pas de commande autonome pour un linter de spécifications, un guide de style, de division, de fusion ou de regroupement. Apidog valide votre spécification lorsque vous l'importez, de sorte que les problèmes structurels apparaissent au moment de l'importation, mais si votre pipeline dépend de jeux de règles Spectral personnalisés comme garde-fou, conservez Spectral dans votre CI aux côtés d'Apidog. N'attendez pas d'apidog lint. Il n'existe pas, et prétendre le contraire ne ferait que vous nuire plus tard.

Étape 1 : exporter vos spécifications et tests depuis Insomnia

inso peut écrire votre document de conception directement dans un fichier. La spécification est référencée par son nom, le même nom que vous voyez dans l'application Insomnia :

# Exporter un document de conception OpenAPI vers un fichier YAML
inso export spec "My API Design" --output my-api.yaml

Si inso ne trouve pas vos données, dirigez-le vers la bonne source. Par défaut, il lit à partir d'un répertoire .insomnia dans le répertoire de travail ou le répertoire de données de l'application Insomnia. Passez outre avec --workingDir ou --src :

inso export spec "My API Design" --workingDir ./design --output my-api.yaml

Pour les collections de requêtes et tout ce que inso n'exportera pas proprement, utilisez l'application Insomnia elle-même : ouvrez l'application, sélectionnez votre espace de travail et utilisez Exporter pour produire un fichier OpenAPI ou Insomnia v4. Conservez à la fois le document de conception et l'exportation de la collection. Vous les importerez séparément.

Si vous êtes en pleine récupération et que l'application ne coopère pas, le guide d'exportation et de récupération explique comment extraire les données lorsque la synchronisation Git ou le compte cloud vous posent problème.

Étape 2 : importer dans Apidog

Ouvrez Apidog, créez un projet et importez le fichier YAML ou JSON que vous venez d'exporter. Apidog lit OpenAPI nativement, de sorte que vos points de terminaison, schémas et exemples de données sont importés en tant que ressources structurées que vous pouvez éditer, simuler et tester.

Vous pouvez également importer depuis la CLI dans le cadre d'une configuration automatisée, ce qui est pratique lorsque vous scriptiez un mouvement à l'échelle de l'équipe plutôt que de cliquer dans l'interface utilisateur. Apidog importe OpenAPI et gère les points de terminaison, les schémas, les environnements, les branches et les demandes de fusion sous forme de code depuis le terminal, en s'authentifiant via un identifiant ou un jeton d'accès. Si vous configurez la CLI pour la première fois, le guide d'installation d'Apidog CLI et le guide complet de la CLI couvrent la configuration et le flux d'authentification.

Lors de l'importation, Apidog valide la spécification. Si votre OpenAPI présente des problèmes structurels, vous le découvrirez maintenant plutôt qu'à l'exécution. C'est l'analogue le plus proche d'inso lint spec, avec une différence qu'il est bon de répéter : c'est de la validation, pas un jeu de règles Spectral configurable.

Étape 3 : mapper vos commandes (la partie pour laquelle vous êtes venu)

C'est le cœur de la migration. Voici comment les commandes inso se traduisent en apidog run.

Quelques notes sur le mappage :

• Environnements. inso utilise --env "name". Apidog utilise -e (--env). Les deux sélectionnent l'URL de base et les variables de l'environnement à appliquer. Recréez d'abord vos environnements Insomnia en tant qu'environnements Apidog, puis référencez-les par nom ou par ID.
• Les suites de tests deviennent des scénarios de test. Là où inso run test exécute une suite de tests unitaires Insomnia, Apidog exécute des scénarios de test. Le concept se transpose proprement : requêtes ordonnées avec assertions. Vous reconstruirez la suite une fois dans Apidog, puis elle s'exécutera à chaque apidog run.
• inso script était une indirection. Si vous avez encapsulé des commandes derrière des scripts nommés, appelez simplement apidog run directement dans votre étape CI, ou encapsulez-le dans votre propre script npm/make.

Pour une comparaison plus approfondie commande par commande, Apidog CLI vs inso (Insomnia CLI) détaille chaque option. Si vous veniez de Newman ou de Postman CLI auparavant, Apidog CLI vs Newman et Apidog CLI vs Postman CLI les couvrent également.

Étape 4 : déplacer vos reporters

inso s'appuie sur sa sortie de test et son reporting de style JUnit pour la CI. Apidog vous propose des reporters aux formats CLI, HTML et JSON, afin que votre build puisse afficher des résultats lisibles par l'homme dans la console et émettre un artefact lisible par machine en même temps :

# Exécuter un scénario et émettre à la fois un résumé CLI et un rapport HTML
apidog run --test-scenario "Smoke Suite" -e staging -r cli,html

Choisissez json lorsqu'un outil en aval doit analyser les résultats, html lorsqu'un humain examine le build, et cli pour le flux de la console en direct. Vous pouvez également envoyer les résultats aux rapports de test cloud d'Apidog avec --upload-report afin que toute l'équipe voie l'exécution sans avoir à parcourir les logs CI. Le guide des rapports de test couvre les formats en détail.

Étape 5 : transférer les tests basés sur les données

Si vos suites Insomnia parcouraient des données en boucle, Apidog prend en charge nativement les tests basés sur les données. Alimentez un jeu de données CSV ou JSON avec -d et le scénario s'exécute une fois par ligne :

apidog run --test-scenario "Login Matrix" -e staging -d ./users.csv -r cli,json

C'est l'un des domaines où Apidog semble moins "bricolé" que d'enchaîner des données externes via inso. Le guide des tests basés sur les données explique les formats de jeux de données et la liaison de variables.

Étape 6 : l'intégrer dans la CI

La dernière étape consiste à échanger la commande dans votre pipeline. Votre ancienne étape GitHub Actions ou GitLab ressemblait probablement à ceci :

# Avant : inso dans la CI
inso run test "Smoke Suite" --env "CI" --reporter junit

L'équivalent Apidog :

# Après : Apidog CLI dans la CI
apidog run --test-scenario "Smoke Suite" -e ci -r cli,json --upload-report

Authentifiez l'exécuteur avec un jeton d'accès stocké en tant que secret CI, de la même manière que vous géreriez toute étape nécessitant des identifiants. Le guide du pipeline CI/CD et le guide GitHub Actions contiennent des fichiers de workflow prêts à l'emploi. Pour les détails sur les jetons et la connexion, consultez l'authentification Apidog CLI.

Si vous avez conservé Spectral pour le linting (recommandé si vous aviez des règles personnalisées), votre pipeline dispose désormais de deux portes : Spectral linter la spécification, Apidog exécute les tests. C'est un état final parfaitement raisonnable, et il est honnête quant à ce que chaque outil fait de mieux.

Garder Spectral dans la boucle

Pour être clair sur la seule chose qui ne se transpose pas : si le linting fait partie de votre contrat, ne l'abandonnez pas. Spectral est open source et fonctionne très bien en dehors d'Insomnia. Une CI hybride typique ressemble à ceci :

# Linter avec Spectral (conservé de votre configuration inso)
npx @stoplight/spectral-cli lint my-api.yaml

# Tester avec Apidog CLI
apidog run --test-scenario "Smoke Suite" -e ci -r cli,json

Vous ne perdez rien du côté du linting et gagnez la plateforme intégrée de conception-simulation-test-documentation d'Apidog pour tout le reste. C'est un échange juste et avantageux pour la plupart des équipes.

inso vs Apidog CLI en un coup d'œil

FAQ

Ma spécification Insomnia OpenAPI s'importera-t-elle dans Apidog sans modifications ? Généralement oui. Apidog lit OpenAPI nativement et valide à l'importation. Si la validation signale quelque chose, il s'agit généralement d'un véritable problème structurel dans la spécification, et le corriger une fois bénéficie à chaque outil en aval.

Apidog CLI a-t-il une commande lint comme inso lint spec ? Non. Apidog valide les spécifications à l'importation, mais il n'y a pas de linter CLI autonome ou de commande de guide de style. Si vous utilisez des jeux de règles Spectral personnalisés, conservez Spectral dans votre pipeline à côté d'apidog run. Pour une comparaison côte à côte, consultez Apidog CLI vs Redocly CLI, car Redocly CLI inclut un linter.

Puis-je exécuter Apidog CLI en CI de la même manière que j'exécutais inso ? Oui. Échangez la commande, authentifiez-vous avec un jeton d'accès provenant d'un secret CI, et choisissez vos reporters. Le guide CI/CD contient des exemples complets de workflow.

Qu'advient-il de mes suites de tests unitaires Insomnia ? Vous les reconstruisez en tant que scénarios de test Apidog. La structure se transpose directement : requêtes ordonnées avec assertions. C'est une reconstruction unique, après quoi elles s'exécutent à chaque apidog run.

Je migre d'Insomnia en raison d'un incident de perte de données. Par où commencer ? Récupérez d'abord vos données en utilisant le guide de récupération et d'exportation, puis suivez l'Étape 2 ci-dessus pour importer l'exportation nettoyée dans Apidog.

En résumé

La migration d'inso vers Apidog CLI est principalement un travail de traduction : exportez vos spécifications et suites, importez-les dans Apidog, réécrivez inso run test et inso run collection en apidog run, passez de --env à -e, et dirigez vos reporters vers la sortie CLI/HTML/JSON d'Apidog. Conservez Spectral si vous faites du linting, car Apidog valide à l'importation mais ne remplace pas un jeu de règles personnalisé.

Le bénéfice est une seule plateforme au lieu d'une pile que vous devez assembler constamment. Prêt à l'essayer ? Téléchargez Apidog et exécutez votre premier apidog run sur la spécification que vous venez d'exporter.