Wenn Sie den Insomnia API-Client verwendet haben, steht Ihnen eine grafische Oberfläche zur Verfügung, um Anfragen zu senden, OpenAPI-Spezifikationen zu entwerfen und Tests zu schreiben. Doch grafische Tools enden an der Grenze Ihrer Maschine. In dem Moment, in dem Sie dieselben Tests in einer CI-Pipeline ausführen oder eine Spezifikation bei jeder Pull-Anfrage linten möchten, benötigen Sie etwas, das im Terminal lebt. Dieses Etwas ist inso.
Dieser Leitfaden erklärt, was inso ist, wie man es installiert, die genauen Befehle, die Sie täglich verwenden werden, wie es Ihre Spezifikationen und Sammlungen findet und wo seine Grenzen liegen. Am Ende wissen Sie, ob die inso CLI zu Ihrem Workflow passt und welche Alternativen es gibt, falls dies nicht der Fall ist.
Was ist inso?
inso ist der Kommandozeilen-Begleiter von Insomnia, dem Open-Source-API-Client, der jetzt von Kong gepflegt wird. Es übernimmt drei Funktionen, die Insomnia in seiner Benutzeroberfläche bietet, und macht sie skriptfähig: das Ausführen von Tests, das Ausführen von Anfragencollections und das Linting von API-Spezifikationen. Das macht es zur Brücke zwischen Insomnia auf Ihrem Desktop und den automatisierten Prüfungen, die Sie in CI/CD wünschen.
Die Kurzversion von „was ist inso“: Es ist die Art und Weise, wie Sie Ihre Insomnia-Arbeit ausführen, ohne Insomnia zu öffnen. Sie verweisen es auf ein Designdokument oder eine Sammlung anhand des Namens, und es wird gegen dieselben Daten ausgeführt, die Ihre App bereits kennt.
Installation der inso CLI
Ihnen stehen mehrere dokumentierte Wege zur Verfügung. Wählen Sie den, der zu Ihrer Vorgehensweise passt.
Homebrew ist die einfachste Methode unter macOS und Linux:
brew install inso
Docker ist die sauberste Wahl für CI-Runner, wo Sie keine lokale Toolchain verwalten möchten:
docker pull kong/inso:latest
Sie können auch einen Direkt-Download nutzen. Kong veröffentlicht Zip-Archive für Windows, Linux und macOS auf der inso CLI Dokumentationsseite, was praktisch ist, wenn Sie eine festgelegte Version in einem Build-Artefakt wünschen.
Historisch wurde inso auch über npm als insomnia-inso vertrieben. Dieser Weg existiert zwar noch, aber die dokumentierten und empfohlenen Wege sind nun Homebrew, Docker und die Direkt-Downloads. Wenn Sie etwas Neues einrichten, bevorzugen Sie diese.
Bestätigen Sie die erfolgreiche Installation:
inso --version
Die wichtigsten inso-Befehle
inso hat eine kleine, fokussierte Oberfläche. Hier sind die Befehle, die Sie tatsächlich verwenden werden, mit echten Beispielen.
inso run test
Führen Sie eine in Insomnia erstellte Unit-Testsuite gegen eine benannte Umgebung aus:
inso run test "Payments API tests" --env "Staging"
Die Suite und die Umgebung werden beide namentlich referenziert, genau so, wie sie in Ihren Insomnia-Daten erscheinen. Der Befehl inso run test beendet sich mit einem Rückgabewert ungleich Null, wenn eine Zusicherung fehlschlägt, was ihn als CI-Gate nutzbar macht.
inso run collection
Führen Sie jede Anfrage in einer Sammlung der Reihe nach aus, wiederum gegen eine benannte Umgebung:
inso run collection "Checkout flow" --env "Staging"
Dies ist das nächste Äquivalent zu „den gesamten Ordner abspielen“ in der Benutzeroberfläche. Es ist nützlich für Smoke-Tests, bei denen Sie überprüfen möchten, ob eine Abfolge von Endpunkten alle wie erwartet antworten.
inso lint spec
Validieren Sie ein OpenAPI-Designdokument:
inso lint spec "Orders API"
Unter der Haube verwendet inso lint spec Spectral, den Open-Source-OpenAPI- und JSON-Linter von Stoplight. Das ist eine echte Stärke, die es hervorzuheben gilt: Sie erhalten eine echte, regelbasierte Spezifikationsprüfung mit einem ausgereiften Regelsatz, keine oberflächliche Syntaxprüfung. Wenn Ihr Team Wert auf die Einhaltung von Stilrichtlinien bei Spezifikationen legt, ist dieser Befehl der Grund, warum viele Leute inso nutzen.
inso export spec
Ziehen Sie ein Designdokument in eine Datei auf der Festplatte:
inso export spec "Orders API" --output orders.yaml
Praktisch, wenn Sie die Spezifikation einem anderen Generator zuführen, einen Schnappschuss festschreiben oder sie einem Tool übergeben möchten, das eine einfache YAML-Datei erwartet.
inso script
Führen Sie ein benanntes Skript aus, das in Ihren Insomnia-Daten definiert ist, und übergeben Sie eine Umgebung anhand der ID:
inso script deploy-smoke --env env_9f2a
Dies ist der Notausgang, um Ihre eigenen benutzerdefinierten Schritte zu verketten.
Wie inso Ihre Spezifikationen und Sammlungen findet
Dieser Teil bereitet den Leuten oft Schwierigkeiten, daher lohnt es sich, präzise zu sein. inso speichert selbst nichts. Es liest aus einem von zwei Orten:
- Ein
.insomnia-Verzeichnis in Ihrem Arbeitsverzeichnis. Dies ist das Ergebnis von Insomnias Git-Synchronisierung. Wenn Sie Ihr API-Projekt also in ein Repository committen, kann inso es direkt aus dem Checkout lesen. Dies ist das Muster, das Sie für CI wünschen. - Das Anwendungsdatenverzeichnis von Insomnia, falls die App auf der Maschine installiert ist. Dies ist lokal praktisch, aber nutzlos auf einem sauberen CI-Runner, auf dem die App noch nie installiert war.
Sie können die Quelle explizit überschreiben:
inso lint spec "Orders API" --workingDir ./api-project
# or point at an exact source
inso run test "Payments API tests" --src ./api-project/.insomnia
Das zentrale Gedankenmodell: inso referenziert alles nach Namen (oder ID), und diese Namen werden gegen die Datenquelle aufgelöst, die es gefunden hat. Wenn ein Name nicht im .insomnia-Verzeichnis oder in den App-Daten vorhanden ist, kann inso ihn nicht ausführen. Es gibt kein Konzept, inso auf eine lose OpenAPI-Datei zu verweisen und zu sagen „teste dies“, es sei denn, diese Datei befindet sich innerhalb einer Insomnia-Projektstruktur.
Ein minimales CI-Beispiel
Hier ist ein GitHub Actions Job, der bei jedem Push eine Spezifikation lintet und eine Testsuite ausführt, wobei das Git-synchronisierte .insomnia-Verzeichnis verwendet wird, das im Repository committet wurde:
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 .
Da beide Befehle bei einem Fehler mit einem Rückgabewert ungleich Null beendet werden, führt eine fehlerhafte Spezifikation oder eine fehlschlagende Zusicherung zum Fehlschlagen des Jobs. Das ist der ganze Sinn, diese Prüfungen aus der GUI zu verlagern.
Ehrliche Einschränkungen
inso ist gut in dem, was es tut, hat aber echte Grenzen.
Es ist an die Datenquellen von Insomnia gebunden. Ihre Spezifikationen, Sammlungen und Suiten müssen in einem Insomnia-Projekt leben, das entweder über Git Sync oder die installierte App zugänglich gemacht wird. Wenn Ihr Team Insomnia nicht als Single Source of Truth verwendet, hat inso nichts zu bearbeiten.
Alles wird namentlich referenziert. Das ist lesbar, aber anfällig. Benennen Sie eine Suite in der Benutzeroberfläche um, und ein CI-Job, der den alten Namen fest codiert hat, schlägt bis zum nächsten Lauf stillschweigend fehl. Namen müssen auch eindeutig genug sein, um sauber aufgelöst zu werden.
Der Umfang ist bewusst eng gefasst. inso führt Tests aus, führt Sammlungen aus, lintet Spezifikationen, exportiert und führt Skripte aus. Es ist keine Design-Mock-Dokumentations-Test-Plattform. Für alles, was über diese Verben hinausgeht, müssen Sie wieder die GUI verwenden oder auf andere Tools zurückgreifen.
inso vs. die integrierte Alternative
inso ist ein starker Terminal-Begleiter, wenn Insomnia bereits Ihr Client ist. Der Kompromiss ist, dass Sie verschiedene Teile zusammenfügen: Insomnia für Design und Debugging, inso für CI, Spectral-Regeln für das Linting und separate Tools für Mocks und Dokumentation.
Apidog vertritt den entgegengesetzten Standpunkt. Es vereint Design, Mock, Dokumentation und Tests in einer einzigen Plattform, und seine Apidog CLI führt Ihre Testszenarien und Sammlungen aus derselben Datenquelle aus, mit datengesteuerten Tests, mehreren Reporterformaten und Ressource-und-Branch-as-Code. Fairerweise sei erwähnt: Die Apidog CLI liefert keinen eigenständigen Spezifikationslinter so wie inso mit Spectral, wenn also die Durchsetzung von Stilrichtlinien im Spectral-Stil Ihre Priorität ist, hat inso hier einen echten Vorteil. Wo Apidog die Nase vorn hat, ist die Integration. Sie müssen nicht fünf Tools zusammenkleben.
Wenn Sie die beiden direkt vergleichen möchten, lesen Sie Apidog CLI vs. inso (Insomnia CLI) oder vertiefen Sie Ihr Wissen in Was ist inso (Insomnia CLI). Wenn Sie entschieden haben, dass inso nicht die richtige Wahl ist, führen Sie die beste inso Alternative Übersicht und der Leitfaden zur Migration von inso zur Apidog CLI Schritt für Schritt durch den Wechsel. Für einen breiteren Kontext zu den GUI-Clients selbst sind Apidog vs. Insomnia und Wie man Insomnia zum Testen einer API verwendet gute Ausgangspunkte.
Sie können Apidog kostenlos herunterladen, wenn Sie den integrierten Ansatz Seite an Seite mit Ihrer inso-Einrichtung sehen möchten.