Migration von Insomnia CLI (inso) zu Apidog CLI

Wenn Sie API-Tests mit inso, der Insomnia CLI von Kong, ausführen und über eine Änderung nachgedacht haben, führt Sie dieser Leitfaden vollständig durch den Prozess. Sie erfahren, wie Sie Ihre Spezifikationen und Testsuiten aus Insomnia exportieren, sie in Apidog importieren und Ihre inso run-Befehle in apidog run-Befehle umschreiben. Es gibt eine Vorher-/Nachher-Befehlstabelle, damit Sie Ihre bestehenden CI-Skripte Zeile für Zeile zuordnen können.

Warum Teams von inso zur Apidog CLI migrieren

inso ist ein solides Werkzeug. Es bringt die Ausführung von Anfragen, Spectral-Linting und Komponententests in das Terminal und liest aus einem .insomnia-Verzeichnis, das von Insomnias Git Sync erstellt wurde. Wenn dieser Workflow zu Ihnen passt, gibt es keinen Grund, ihn zu verlassen.

Die Reibung beginnt normalerweise mit der Insomnia-App, nicht mit der CLI. Zwei Dinge treiben die meisten Migrationssuchen an:

• Das erforderliche Cloud-Konto. Insomnia 8, veröffentlicht im Jahr 2023, führte eine obligatorische Anmeldung/Cloud-Konto ein, die viele Teams überraschte. Viele Entwickler wollten einen lokalen Client und bekamen stattdessen eine Anmeldemauer.
• Datenverlust und Migrationsschwierigkeiten. Einige Benutzer erlitten während dieses Übergangs Datenverluste und Migrationsvorfälle. Wenn Sie so etwas durchgemacht haben, kennen Sie bereits die Kosten. Wenn Sie sich jetzt davon erholen, helfen diese Anleitungen: Wiederherstellen und Exportieren von Insomnia-Daten und der ausführlichere Leitfaden zur Datenverlustwiederherstellung und Migration in Insomnia 8.

Der andere Grund ist die Konsolidierung. Mit inso ist die CLI ein Teil eines Stacks: Insomnia für Anfragen, Spectral für Linting, separate Tools für Mocks und Docs. Apidog fasst Design, Debug, Test, Mock und Dokumentation in einer Plattform zusammen, und die CLI betreibt die Testseite dieser Plattform. Weniger bewegliche Teile, eine einzige Quelle der Wahrheit.

Wenn Sie den breiteren Kontext wünschen, bevor Sie sich festlegen, legen Apidog vs Insomnia und die Wahl zwischen Insomnia und Apidog die Kompromisse für die vollständigen Apps dar, nicht für die CLIs.

Bevor Sie beginnen: Was umgezogen wird und was nicht

Legen Sie die Erwartungen im Voraus fest, damit Sie während der Migration nichts überrascht.

Der ehrliche Hinweis: inso lint spec führt Spectral aus, Stoplights OpenAPI-Linter, und das ist eine echte Stärke. Die Apidog CLI liefert keinen eigenständigen Spec-Linter, Style-Guide, Split-, Join- oder Bundle-Befehl. Apidog validiert Ihre Spezifikation, wenn Sie sie importieren, sodass strukturelle Probleme zum Zeitpunkt des Imports sichtbar werden. Wenn Ihre Pipeline jedoch von benutzerdefinierten Spectral-Regelsätzen als Gate abhängt, behalten Sie Spectral in Ihrer CI neben Apidog bei. Erwarten Sie kein apidog lint. Es ist nicht vorhanden, und so zu tun, als ob, würde Sie später nur enttäuschen.

Schritt 1: Spezifikationen und Tests aus Insomnia exportieren

inso kann Ihr Designdokument direkt in eine Datei schreiben. Die Spezifikation wird über den Namen referenziert, denselben Namen, den Sie in der Insomnia-App sehen:

# Ein OpenAPI-Designdokument in eine YAML-Datei exportieren
inso export spec "My API Design" --output my-api.yaml

Wenn inso Ihre Daten nicht finden kann, weisen Sie es auf die richtige Quelle hin. Standardmäßig liest es aus einem .insomnia-Verzeichnis im Arbeitsverzeichnis oder dem Datenverzeichnis der Insomnia-App. Überschreiben Sie dies mit --workingDir oder --src:

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

Für Anfragesammlungen und alles, was inso nicht sauber exportiert, verwenden Sie die Insomnia-App selbst: Öffnen Sie die App, wählen Sie Ihren Arbeitsbereich aus und verwenden Sie Exportieren, um eine OpenAPI- oder Insomnia v4-Datei zu erstellen. Behalten Sie sowohl das Designdokument als auch den Sammlungs-Export. Sie werden diese separat importieren.

Wenn Sie sich mitten in der Wiederherstellung befinden und die App nicht kooperiert, behandelt die Anleitung zum Export und zur Wiederherstellung das Herausbekommen von Daten, wenn Git Sync oder das Cloud-Konto Schwierigkeiten bereiten.

Schritt 2: Importieren in Apidog

Öffnen Sie Apidog, erstellen Sie ein Projekt und importieren Sie die soeben exportierte YAML- oder JSON-Datei. Apidog liest OpenAPI nativ, sodass Ihre Endpunkte, Schemas und Beispieldaten als strukturierte Ressourcen landen, die Sie bearbeiten, mocken und testen können.

Sie können auch über die CLI als Teil einer automatisierten Einrichtung importieren, was praktisch ist, wenn Sie eine teamweite Migration skripten, anstatt sich durch die Benutzeroberfläche zu klicken. Apidog importiert OpenAPI und verwaltet Endpunkte, Schemas, Umgebungen, Branches und Merge-Anfragen als Code vom Terminal aus, wobei die Authentifizierung über Login oder einen Access Token erfolgt. Wenn Sie die CLI zum ersten Mal einrichten, decken die Apidog CLI Installationsanleitung und der vollständige CLI-Leitfaden die Einrichtung und den Authentifizierungsfluss ab.

Beim Import validiert Apidog die Spezifikation. Wenn Ihre OpenAPI strukturelle Probleme aufweist, erfahren Sie dies jetzt und nicht erst zur Laufzeit. Dies ist die engste Analogie zu inso lint spec, mit einem Unterschied, der wiederholt werden sollte: Es ist eine Validierung, kein konfigurierbarer Spectral-Regelsatz.

Schritt 3: Befehle zuordnen (der Teil, für den Sie gekommen sind)

Dies ist der Kern der Migration. So werden inso-Befehle in apidog run übersetzt.

Einige Anmerkungen zur Zuordnung:

• Umgebungen. inso verwendet --env "Name". Apidog verwendet -e (--env). Beide wählen die Basis-URL und die Variablen der anzuwendenden Umgebung aus. Erstellen Sie Ihre Insomnia-Umgebungen zuerst als Apidog-Umgebungen neu und referenzieren Sie sie dann anhand ihres Namens oder ihrer ID.
• Testsuiten werden zu Testszenarien. Wo inso run test eine Insomnia-Unit-Testsuite ausführt, führt Apidog Testszenarien aus. Das Konzept lässt sich sauber abbilden: geordnete Anfragen mit Assertions. Sie bauen die Suite einmal in Apidog neu auf, dann läuft sie bei jedem apidog run.
• inso script war eine Indirektion. Wenn Sie Befehle hinter benannten Skripten verpackt haben, rufen Sie apidog run einfach direkt in Ihrem CI-Schritt auf oder verpacken Sie es in Ihrem eigenen npm-/Make-Skript.

Für einen tiefergehenden Befehlsvergleich geht Apidog CLI vs. inso (Insomnia CLI) Flag für Flag durch. Wenn Sie in einem früheren Leben von Newman oder der Postman CLI kamen, behandeln Apidog CLI vs. Newman und Apidog CLI vs. Postman CLI diese ebenfalls.

Schritt 4: Ihre Reporter verschieben

inso stützt sich auf seine Testausgabe und JUnit-ähnliche Berichterstattung für CI. Apidog bietet Ihnen Reporter in CLI-, HTML- und JSON-Formaten, sodass Ihr Build gleichzeitig menschenlesbare Ergebnisse in der Konsole ausgeben und ein maschinenlesbares Artefakt erzeugen kann:

# Ein Szenario ausführen und sowohl eine CLI-Zusammenfassung als auch einen HTML-Bericht ausgeben
apidog run --test-scenario "Smoke Suite" -e staging -r cli,html

Wählen Sie json, wenn ein nachgeschaltetes Tool Ergebnisse parsen muss, html, wenn ein Mensch den Build überprüft, und cli für die Live-Konsolenausgabe. Sie können Ergebnisse auch mit --upload-report an Apidogs Cloud-Testberichte senden, damit das gesamte Team den Lauf sehen kann, ohne die CI-Logs durchsuchen zu müssen. Der Leitfaden zu Testberichten behandelt die Formate im Detail.

Schritt 5: Datengetriebene Tests übernehmen

Wenn Ihre Insomnia-Suiten Daten durchlaufen haben, unterstützt Apidog datengetriebenes Testen nativ. Füttern Sie ein CSV- oder JSON-Dataset mit -d, und das Szenario läuft einmal pro Zeile:

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

Dies ist ein Bereich, in dem sich Apidog weniger "angeschraubt" anfühlt als das Verketten externer Daten über inso. Der Leitfaden für datengetriebenes Testen führt durch Dataset-Formate und Variablenbindung.

Schritt 6: In CI integrieren

Der letzte Schritt ist das Austauschen des Befehls in Ihrer Pipeline. Ihr alter GitHub Actions- oder GitLab-Schritt sah wahrscheinlich so aus:

# Vorher: inso in CI
inso run test "Smoke Suite" --env "CI" --reporter junit

Das Apidog-Äquivalent:

# Nachher: Apidog CLI in CI
apidog run --test-scenario "Smoke Suite" -e ci -r cli,json --upload-report

Authentifizieren Sie den Runner mit einem Access Token, das als CI-Geheimnis gespeichert ist, genauso wie Sie jeden authentifizierten Schritt handhaben würden. Der CI/CD-Pipeline-Leitfaden und der GitHub Actions-Leitfaden enthalten Workflow-Dateien zum Kopieren und Einfügen. Für Details zu Token und Login siehe Apidog CLI-Authentifizierung.

Wenn Sie Spectral für das Linting beibehalten haben (empfohlen, wenn Sie benutzerdefinierte Regeln hatten), hat Ihre Pipeline jetzt zwei Gates: Spectral lintet die Spezifikation, Apidog führt die Tests aus. Das ist ein absolut vernünftiger Endzustand und ehrlich darüber, was jedes Tool am besten kann.

Spectral weiterhin im Prozess behalten

Um klarzustellen, was nicht portiert wird: Wenn Linting Teil Ihres Vertrags ist, geben Sie es nicht auf. Spectral ist Open Source und läuft gut außerhalb von Insomnia. Eine typische hybride CI sieht so aus:

# Mit Spectral linten (aus Ihrer inso-Einrichtung beibehalten)
npx @stoplight/spectral-cli lint my-api.yaml

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

Sie verlieren nichts auf der Linting-Seite und gewinnen Apidogs integrierte Design-, Mock-, Test- und Dokumentationsplattform für alles andere. Das ist der genaue Kompromiss, und er ist für die meisten Teams ein guter.

inso vs. Apidog CLI auf einen Blick

Häufig gestellte Fragen

• Wird meine Insomnia OpenAPI-Spezifikation ohne Bearbeitung in Apidog importiert? Normalerweise ja. Apidog liest OpenAPI nativ und validiert beim Import. Wenn die Validierung etwas kennzeichnet, handelt es sich in der Regel um ein echtes strukturelles Problem in der Spezifikation, und eine einmalige Behebung kommt jedem nachgeschalteten Tool zugute.
• Hat die Apidog CLI einen lint-Befehl wie inso lint spec? Nein. Apidog validiert Spezifikationen beim Import, aber es gibt keinen eigenständigen CLI-Linter oder Style-Guide-Befehl. Wenn Sie sich auf benutzerdefinierte Spectral-Regelsätze verlassen, behalten Sie Spectral in Ihrer Pipeline neben apidog run bei. Für einen Vergleich sehen Sie Apidog CLI vs. Redocly CLI, da Redocly CLI einen Linter enthält.
• Kann ich die Apidog CLI in CI auf die gleiche Weise ausführen wie inso? Ja. Tauschen Sie den Befehl aus, authentifizieren Sie sich mit einem Access Token aus einem CI-Geheimnis und wählen Sie Ihre Reporter. Der CI/CD-Leitfaden enthält vollständige Workflow-Beispiele.
• Was passiert mit meinen Insomnia-Unit-Testsuiten? Sie bauen sie als Apidog-Testszenarien neu auf. Die Struktur wird direkt übernommen: geordnete Anfragen plus Assertions. Es ist ein einmaliger Neuaufbau, danach laufen sie bei jedem apidog run.
• Ich migriere von Insomnia wegen eines Datenverlusts. Wo fange ich an? Stellen Sie Ihre Daten zuerst mit dem Wiederherstellungs- und Exportleitfaden wieder her und folgen Sie dann Schritt 2 oben, um den bereinigten Export in Apidog zu importieren.

Zusammenfassung

Die Migration von inso zur Apidog CLI ist größtenteils eine Übersetzungsaufgabe: Exportieren Sie Ihre Spezifikationen und Suiten, importieren Sie sie in Apidog, schreiben Sie inso run test und inso run collection als apidog run um, ändern Sie --env in -e und richten Sie Ihre Reporter auf die CLI-/HTML-/JSON-Ausgabe von Apidog aus. Behalten Sie Spectral bei, wenn Sie linten, da Apidog beim Import validiert, aber keinen benutzerdefinierten Regelsatz ersetzt.

Der Lohn ist eine Plattform anstelle eines Stacks, den Sie immer wieder zusammenflicken müssen. Bereit, es auszuprobieren? Laden Sie Apidog herunter und führen Sie Ihren ersten apidog run gegen die soeben exportierte Spezifikation aus.