Insomnia ist ein API-Client, der von Kong entwickelt wurde, um Anfragen zu senden und Antworten zu überprüfen. Es ist bekannt für eine saubere, ablenkungsfreie Oberfläche und Unterstützung für HTTP, REST, GraphQL, gRPC, SOAP und WebSocket an einem Ort. Entwickler greifen darauf zurück, wenn sie etwas Leichteres als ein schwerfälliges IDE-ähnliches Tool wünschen, das aber dennoch zu echten Testarbeiten fähig ist.
Dieser Leitfaden zeigt, wie man eine API in Insomnia von Anfang bis Ende testet. Sie erstellen eine Anfragesammlung, senden und überprüfen eine Antwort, richten Umgebungen ein, um Basis-URLs und Token wechseln zu können, und verwenden die Test-Suites-Funktion, um automatisch ausgeführte Assertionen zu schreiben. Die Beispiele verwenden eine öffentliche API, sodass Sie sofort mitmachen können.
Insomnia installieren und eine Anfrage erstellen
Laden Sie Insomnia von der offiziellen Kong-Website herunter und installieren Sie es für Ihre Plattform. Beim ersten Start fragt Insomnia, ob Sie sich anmelden möchten. Sie können wählen, ob Sie lieber lokal ohne Konto arbeiten möchten, und Insomnia speichert Ihre Daten auf Ihrem eigenen Computer. Die Cloud-Synchronisierung ist optional und war die Änderung in Version 8, die wir weiter unten behandeln.
Insomnia organisiert die Arbeit in Sammlungen und Dokumenten. Klicken Sie im Dashboard auf Erstellen und wählen Sie Anfragesammlung (Request Collection). Geben Sie ihr einen klaren Namen wie „User API tests“. Innerhalb der Sammlung klicken Sie auf die Schaltfläche + und wählen HTTP-Anfrage (HTTP Request).
Eine Anfrage benötigt eine Methode und eine URL. Wählen Sie GET und geben Sie einen echten Endpunkt ein. Der JSONPlaceholder-Dienst eignet sich gut zum Üben:
GET https://jsonplaceholder.typicode.com/users/1
Klicken Sie auf Senden. Der rechte Bereich zeigt den Antworttext, den Statuscode, die Antwortzeit und die Größe. Insomnia formatiert JSON automatisch lesbar und ermöglicht es Ihnen, den Text mit einer JSONPath- oder XPath-Abfrage zu filtern, was praktisch ist, wenn eine Antwort groß ist.
Methoden, Parameter und Authentifizierung konfigurieren
Für alles, was über ein einfaches Lesen hinausgeht, müssen Sie mehr für die Anfrage einstellen. Insomnia gruppiert diese unter Registerkarten unterhalb der URL-Leiste.
Die Registerkarte Body (Textkörper) verarbeitet Anfragenutzdaten. Für eine POST-Anfrage wählen Sie JSON und geben die Daten ein:
{
"name": "Daniel Okafor",
"email": "daniel.okafor@example.com"
}
Insomnia setzt den Content-Type-Header für Sie, wenn Sie einen Body-Typ auswählen. Die Registerkarte Query (Abfrage) ermöglicht es Ihnen, Abfrageparameter hinzuzufügen, ohne die URL manuell bearbeiten zu müssen, was eine lange URL lesbar hält und es Ihnen ermöglicht, einzelne Parameter ein- und auszuschalten. Die Registerkarte Headers (Header) ist für alles andere, was die API erwartet, wie einen benutzerdefinierten X-Request-Id oder einen Accept-Header zur Aushandlung des Antwortformats.
Die Registerkarte Auth (Authentifizierung) verarbeitet Anmeldeinformationen. Insomnia unterstützt eine lange Liste von Schemata: Bearer Token, Basic Auth, API Key, OAuth 1.0 und 2.0, AWS IAM und andere. Wählen Sie das Schema, das Ihre API verwendet, und füllen Sie die Felder aus. Für eine Token-geschützte API wählen Sie Bearer Token und fügen das Token ein, oder besser, verweisen Sie auf eine Umgebungsvariable, damit das Token nicht fest kodiert ist. Wenn Sie unsicher sind, welche Statuscodes Sie erwarten sollten, ist die Referenz zu HTTP-Statuscodes, die REST-APIs verwenden sollten, eine gute Ergänzung.
Umgebungen und Variablen einrichten
Umgebungen ermöglichen es Ihnen, sich wiederholende Werte zu vermeiden und erleichtern das Wechseln von Zielen. In Insomnia ist eine Umgebung ein JSON-Objekt von Variablen, das an eine Sammlung angehängt ist.
Klicken Sie auf das Umgebungs-Dropdown oben in der Seitenleiste und öffnen Sie Umgebungen verwalten (Manage Environments). Die Basisumgebung (Base Environment) enthält gemeinsam genutzte Werte. Fügen Sie Unterumgebungen für jedes Ziel hinzu:
{
"base_url": "https://jsonplaceholder.typicode.com",
"auth_token": "your-token-here"
}
Erstellen Sie eine zweite Unterumgebung für die Produktion mit anderen Werten. Verweisen Sie in jeder Anfrage auf eine Variable mit der Vorlagensyntax {{ _.base_url }}, sodass eine URL wie folgt aussieht:
GET {{ _.base_url }}/users/1
Wechseln Sie die aktive Umgebung im Dropdown-Menü und jede Anfrage, die die Variable verwendet, wird aktualisiert. Insomnia unterstützt auch Vorlagen-Tags (template tags), kleine Funktionen, die Sie in ein Feld einfügen können, um einen Zeitstempel, eine UUID zu generieren oder einen Wert aus einer vorherigen Antwort zu ziehen. Letzteres ermöglicht es Ihnen, Anfragen zu verketten, zum Beispiel ein Token aus einer Anmeldeantwort zu erfassen und es in spätere Anfragen einzuspeisen.
Der Antwort-Vorlagen-Tag ist einen genaueren Blick wert, da Insomnia damit Anfragenabhängigkeiten ohne Skripte verarbeitet. Sie fügen einen Tag hinzu, der besagt „verwende den Textkörper der Anmeldeanfrage, unter dem JSONPath $.token“, und fügen ihn in den Authorization-Header jeder geschützten Anfrage ein. Wenn Sie eine geschützte Anfrage ausführen, führt Insomnia bei Bedarf zuerst die Anmeldeanfrage aus, extrahiert das Token und ersetzt es. Die Kette bleibt deklarativ, sodass kein „Glue Code“ (Klebecode) gewartet werden muss. Für die umfassendere Idee der Gruppierung verwandter Überprüfungen siehe die Schritt-für-Schritt-Anleitung im Beispiel für API-Testfälle.
Test-Suites mit Assertionen schreiben
Das Senden einer Anfrage zeigt Ihnen die Antwort. Um die Richtigkeit der Antwort automatisch zu überprüfen, verwenden Sie die Funktion Test-Suites von Insomnia, die manchmal als Registerkarte Unit Tests (Komponententests) in einer Sammlung angezeigt wird.
Öffnen Sie Ihre Sammlung und wechseln Sie zur Ansicht Tests. Erstellen Sie eine Test-Suite und fügen Sie dann einzelne Tests darin hinzu. Jeder Test ist ein kleines Stück JavaScript. Insomnia verwendet die Chai-Assertionsbibliothek und bietet Ihnen eine Hilfsfunktion, um eine Anfrage zu senden und deren Antwort zu erhalten. Ein Test sieht so aus:
const response = await insomnia.send();
expect(response.status).to.equal(200);
Sie können spezifischer sein, indem Sie den Textkörper parsen und Felder überprüfen:
const response = await insomnia.send();
const body = JSON.parse(response.data);
expect(response.status).to.equal(200);
expect(body.email).to.equal("daniel.okafor@example.com");
expect(body).to.have.property("id");
Jeder Test in der Suite zielt auf eine Anfrage aus Ihrer Sammlung ab, die aus einem Dropdown-Menü ausgewählt wird, sodass der Test weiß, was zu senden ist. Klicken Sie auf Tests ausführen (Run Tests) und Insomnia führt jeden Test in der Suite aus, wobei jeder als bestanden oder fehlgeschlagen mit der benötigten Zeit angezeigt wird. Dies ist Ihre Regressionsprüfung: Führen Sie die Suite nach einer Änderung aus und Sie sehen sofort, ob die API sich noch wie erwartet verhält.
Wie Sie Suiten organisieren, wird mit zunehmender Anzahl wichtig. Ein gängiges Muster ist eine Suite pro Ressource, sodass alle Artikeltests zusammen und alle Benutzertests zusammen sind. Innerhalb einer Suite sollte jeder Test auf ein einziges Verhalten konzentriert sein: ein Test für den „Happy Path“ (erfolgreichen Fall), separate Tests für den „Not-Found“-Fall (nicht gefunden) und den „Validation-Error“-Fall (Validierungsfehler). Wenn ein Test fehlschlägt, sollten Ihnen sein Name und sein enger Geltungsbereich mitteilen, was kaputt ist, ohne dass Sie den Assertion-Code lesen müssen. Für einen tieferen Einblick in das Schreiben guter Prüfungen erklärt der Leitfaden zu API-Assertionen, was zu asserten und was zu überspringen ist, und der Artikel Test-Suites für die API-Testautomatisierung behandelt die Strukturierung von Suiten, wenn diese wachsen.
Aus der Befehlszeile mit Inso ausführen
Eine GUI ist für die Entwicklung in Ordnung, aber die Automatisierung benötigt etwas „Headless“. Insomnia liefert einen Befehlszeilen-Begleiter namens Inso. Nach dem Exportieren oder Synchronisieren Ihrer Sammlung führen Sie Ihre Test-Suite von einem Terminal aus aus:
inso run test "User API tests"
Inso beendet sich mit einem Statuscode ungleich Null, wenn ein Test fehlschlägt, was genau das ist, was eine CI-Pipeline benötigt, um einen Build als fehlerhaft zu kennzeichnen. Sie können dies in GitHub Actions oder einen anderen Runner integrieren, sodass Ihre Insomnia-Tests bei jedem Push ausgeführt werden und einen defekten Endpunkt abfangen, bevor er einen Teamkollegen oder die Produktion erreicht. Inso kann auch Ihre API-Spezifikation linten und Testberichte in Standardformaten generieren, was es über das bloße Ausführen von Suiten hinaus nützlich macht. Der Artikel über das Automatisieren von API-Tests in CI/CD zeigt das allgemeine Muster, das sich sauber auf Inso anwenden lässt.
Die Cloud-Änderung in Version 8 und eine Alternative
Insomnia 8 orientierte sich an einem Cloud-First-Modell. Standardmäßig drängte es Benutzer dazu, ein Kong-Konto zu erstellen und Projekte in der Cloud zu speichern. Diese Entscheidung frustrierte einen Teil der Community, da frühere Versionen vollständig lokal und offline-freundlich waren. Spätere Veröffentlichungen stellten eine klarere Option für rein lokale Nutzung oder „Scratch Pad“ wieder her, aber die Episode veranlasste einige Teams, nach Alternativen zu suchen, insbesondere in Umgebungen, in denen Daten das Gebäude nicht verlassen dürfen.
Wenn das auf Sie zutrifft, ist Apidog einen Blick wert. Es ist eine All-in-One-API-Plattform, die Design, Debugging, Mocking, Testen und Dokumentation abdeckt, und es importiert Insomnia-Exporte, sodass Sie nicht von vorne anfangen müssen. Mit Apidog können Sie Assertionen visuell erstellen, ohne JavaScript schreiben zu müssen, und unterstützt dennoch Skripte, wenn Sie diese wünschen. Da die API-Spezifikation, die Testdaten und der Mock-Server ein Projekt teilen, bleiben Ihre Tests mit dem tatsächlichen Vertrag abgestimmt, anstatt auseinanderzudriften. Sie können Apidog herunterladen und eine Insomnia-Sammlung importieren, um sie nebeneinander zu vergleichen. Für einen breiteren Überblick listet die Liste der kostenlosen Online-API-Testwerkzeuge verschiedene Optionen auf.
Insomnia ist immer noch ein starker, fokussierter Client, insbesondere für Einzelentwickler und kleine Teams, die seine minimalistische, ablenkungsfreie Benutzeroberfläche und den schnellen Start schätzen. Die richtige Wahl hängt davon ab, wie Ihr Team arbeitet und wie viel des API-Lebenszyklus Sie an einem Ort handhaben möchten, anstatt ihn auf verschiedene Tools zu verteilen.
Häufig gestellte Fragen
Ist Insomnia kostenlos nutzbar?
Insomnia bietet eine kostenlose Stufe, die die individuelle Nutzung abdeckt, einschließlich des Sendens von Anfragen und des lokalen Ausführens von Test-Suites. Kostenpflichtige Pläne fügen Teamzusammenarbeit und größere Cloud-Sync-Limits hinzu. Sie können den Kern-Client ohne Bezahlung nutzen, und neuere Versionen ermöglichen es Ihnen, vollständig lokal zu arbeiten, wenn Sie keine Cloud-Synchronisierung verwenden möchten.
Welche Protokolle unterstützt Insomnia?
Insomnia unterstützt HTTP, REST, GraphQL, gRPC, SOAP und WebSocket. Die Anfrageeinrichtung unterscheidet sich je nach Protokoll, aber die Überprüfung der Antwort und, bei HTTP-basierten Anfragen, die Assertionen der Test-Suite funktionieren durchweg konsistent.
Wie schreibe ich Assertionen in Insomnia?
Verwenden Sie die Funktion für Test-Suites. Öffnen Sie die Ansicht „Tests“ in einer Sammlung, erstellen Sie eine Suite und fügen Sie Tests hinzu. Jeder Test ist JavaScript, das insomnia.send() aufruft, um eine Anfrage auszuführen, und dann Chai-ähnliche expect-Assertionen für den Status, die Header oder den geparsten Textkörper verwendet. Führen Sie die gesamte Suite mit der Schaltfläche „Tests ausführen“ aus.
Was hat sich in Insomnia 8 geändert?
Insomnia 8 wechselte zu einer Cloud-First-Standardeinstellung, die Benutzer dazu aufforderte, sich bei einem Kong-Konto anzumelden und Projekte mit der Cloud zu synchronisieren. Einige Benutzer missbilligten den obligatorischen Anmeldefluss und die Abkehr von einer rein lokalen App. Spätere Updates fügten klarere Optionen für die rein lokale Nutzung hinzu, aber die Änderung veranlasste einige Teams, Alternativen zu evaluieren.
Kann ich Insomnia-Tests in einer CI-Pipeline ausführen?
Ja. Verwenden Sie Inso, den Befehlszeilen-Begleiter. Exportieren oder synchronisieren Sie Ihre Sammlung und führen Sie dann inso run test "<suite name>" in Ihrer Pipeline aus. Inso gibt im Fehlerfall einen Exit-Code ungleich Null zurück, sodass CI den Build automatisch fehlschlagen lassen kann, wenn ein API-Test fehlschlägt.