DEV Community

Cover image for API Testen mit Insomnia: Eine Anleitung
Emre Demir
Emre Demir

Posted on • Originally published at apidog.com

API Testen mit Insomnia: Eine Anleitung

Insomnia ist ein API-Client von Kong, mit dem Sie API-Anfragen senden, Antworten prüfen und einfache Regressionstests aufbauen können. Das Tool unterstützt HTTP, REST, GraphQL, gRPC, SOAP und WebSocket und eignet sich besonders, wenn Sie einen schlanken Client ohne IDE-ähnliche Oberfläche suchen.

Apidog noch heute ausprobieren

In diesem Leitfaden testen Sie eine API in Insomnia Schritt für Schritt: Sammlung erstellen, Anfrage senden, Antwort prüfen, Umgebungen konfigurieren und Test-Suites mit Assertions ausführen. Die Beispiele nutzen JSONPlaceholder, damit Sie direkt mitmachen können.

Insomnia installieren und eine Anfrage erstellen

Laden Sie Insomnia von der offiziellen Kong-Website herunter und installieren Sie es für Ihr Betriebssystem.

Beim ersten Start können Sie entscheiden, ob Sie sich anmelden oder lokal arbeiten möchten. Wenn Sie ohne Konto arbeiten, speichert Insomnia Ihre Daten lokal auf Ihrem Rechner. Cloud-Synchronisierung ist optional.

So erstellen Sie Ihre erste Anfrage:

  1. Öffnen Sie das Dashboard.
  2. Klicken Sie auf Erstellen.
  3. Wählen Sie Anfragesammlung.
  4. Geben Sie der Sammlung einen Namen, z. B. User API tests.
  5. Klicken Sie innerhalb der Sammlung auf +.
  6. Wählen Sie HTTP-Anfrage.
  7. Setzen Sie die Methode auf GET.
  8. Verwenden Sie diesen Endpunkt: 
GET https://jsonplaceholder.typicode.com/users/1
Enter fullscreen mode Exit fullscreen mode

Klicken Sie auf Senden.

Insomnia zeigt rechts:

  • Statuscode
  • Antwortzeit
  • Antwortgröße
  • Response Body
  • formatierte JSON-Ausgabe

Für große Antworten können Sie JSONPath oder XPath verwenden, um gezielt Teile der Antwort zu filtern.

Methoden, Parameter und Authentifizierung konfigurieren

Für produktivere Tests konfigurieren Sie Body, Query-Parameter, Header und Authentifizierung über die Tabs unterhalb der URL-Leiste.

JSON-Body für POST-Anfragen setzen

Erstellen Sie eine neue Anfrage mit POST und wählen Sie im Tab Body den Typ JSON.

Beispiel:

{
  "name": "Daniel Okafor",
  "email": "daniel.okafor@example.com"
}
Enter fullscreen mode Exit fullscreen mode

Insomnia setzt den passenden Content-Type-Header automatisch, wenn Sie einen Body-Typ auswählen.

Query-Parameter verwalten

Nutzen Sie den Tab Query, statt Parameter manuell an die URL anzuhängen.

Beispiel:

GET https://jsonplaceholder.typicode.com/posts?userId=1
Enter fullscreen mode Exit fullscreen mode

Besser in Insomnia:

Key Value
userId 1

Vorteil: Sie können einzelne Parameter aktivieren, deaktivieren oder ändern, ohne die URL neu zu schreiben.

Header hinzufügen

Im Tab Headers konfigurieren Sie zusätzliche Header, z. B.:

Header Wert
Accept application/json
X-Request-Id test-001

Authentifizierung einrichten

Im Tab Auth wählen Sie das Authentifizierungsschema Ihrer API aus. Insomnia unterstützt unter anderem:

  • Bearer Token
  • Basic Auth
  • API Key
  • OAuth 1.0
  • OAuth 2.0
  • AWS IAM

Für eine API mit Bearer Token:

  1. Öffnen Sie den Tab Auth.
  2. Wählen Sie Bearer Token.
  3. Fügen Sie das Token ein.

Besser: Verwenden Sie eine Umgebungsvariable, damit Tokens nicht fest in der Anfrage stehen.

Wenn Sie unsicher sind, welche Statuscodes Sie für REST-APIs prüfen sollten, hilft die Referenz zu HTTP-Statuscodes, die REST-APIs verwenden sollten.

Umgebungen und Variablen einrichten

Umgebungen verhindern duplizierte Werte und erleichtern den Wechsel zwischen lokalen, Staging- und Produktionssystemen.

Eine Umgebung ist in Insomnia ein JSON-Objekt mit Variablen, das an eine Sammlung gebunden ist.

Öffnen Sie oben in der Seitenleiste das Umgebungs-Dropdown und wählen Sie Umgebungen verwalten.

Beispiel für eine Umgebung:

{
  "base_url": "https://jsonplaceholder.typicode.com",
  "auth_token": "your-token-here"
}
Enter fullscreen mode Exit fullscreen mode

Verwenden Sie die Variablen anschließend in Ihren Anfragen:

GET {{ _.base_url }}/users/1
Enter fullscreen mode Exit fullscreen mode

Für geschützte Endpunkte können Sie den Authorization-Header ebenfalls variabel halten:

Authorization: Bearer {{ _.auth_token }}
Enter fullscreen mode Exit fullscreen mode

Erstellen Sie weitere Unterumgebungen, z. B.:

{
  "base_url": "https://api.example.com",
  "auth_token": "production-token"
}
Enter fullscreen mode Exit fullscreen mode

Wenn Sie die aktive Umgebung im Dropdown wechseln, aktualisieren sich alle Anfragen, die diese Variablen verwenden.

Werte aus vorherigen Antworten wiederverwenden

Insomnia unterstützt Vorlagen-Tags. Damit können Sie dynamische Werte in Feldern verwenden, z. B.:

  • Zeitstempel
  • UUIDs
  • Werte aus vorherigen Antworten

Das ist praktisch für Login-Flows.

Beispielablauf:

  1. Eine Login-Anfrage gibt ein Token zurück.
  2. Insomnia extrahiert das Token per JSONPath.
  3. Eine geschützte Anfrage verwendet dieses Token im Authorization-Header.

Angenommen, die Login-Antwort sieht so aus:

{
  "token": "abc123"
}
Enter fullscreen mode Exit fullscreen mode

Dann können Sie in geschützten Anfragen einen Response-Template-Tag verwenden, der aus der Login-Antwort den Wert unter $.token liest.

Der Vorteil: Sie müssen keinen zusätzlichen JavaScript-Code schreiben, um Login und Folgeanfragen zu verketten.

Für die allgemeine Struktur von API-Prüfungen ist das Beispiel für API-Testfälle eine sinnvolle Ergänzung.

Test-Suites mit Assertions schreiben

Eine manuell gesendete Anfrage zeigt nur die aktuelle Antwort. Für wiederholbare Prüfungen nutzen Sie in Insomnia Test-Suites.

Je nach Version finden Sie diese Funktion als Tests oder Unit Tests innerhalb einer Sammlung.

So erstellen Sie eine Test-Suite:

  1. Öffnen Sie Ihre Sammlung.
  2. Wechseln Sie zur Ansicht Tests.
  3. Erstellen Sie eine neue Test-Suite.
  4. Fügen Sie einen Test hinzu.
  5. Wählen Sie die Anfrage aus, die der Test ausführen soll.
  6. Schreiben Sie Assertions in JavaScript.

Insomnia verwendet Chai-ähnliche Assertions.

Ein minimaler Test:

const response = await insomnia.send();

expect(response.status).to.equal(200);
Enter fullscreen mode Exit fullscreen mode

Ein Test mit geparstem JSON-Body:

const response = await insomnia.send();
const body = JSON.parse(response.data);

expect(response.status).to.equal(200);
expect(body).to.have.property("id");
expect(body.email).to.equal("Sincere@april.biz");
Enter fullscreen mode Exit fullscreen mode

Für den JSONPlaceholder-Endpunkt:

GET https://jsonplaceholder.typicode.com/users/1
Enter fullscreen mode Exit fullscreen mode

liefert die API unter anderem:

{
  "id": 1,
  "name": "Leanne Graham",
  "email": "Sincere@april.biz"
}
Enter fullscreen mode Exit fullscreen mode

Dazu passende Assertions:

const response = await insomnia.send();
const body = JSON.parse(response.data);

expect(response.status).to.equal(200);
expect(body.id).to.equal(1);
expect(body.name).to.equal("Leanne Graham");
expect(body.email).to.include("@");
Enter fullscreen mode Exit fullscreen mode

Klicken Sie anschließend auf Tests ausführen. Insomnia führt die Tests der Suite aus und zeigt für jeden Test an:

  • bestanden oder fehlgeschlagen
  • Laufzeit
  • Fehlermeldung bei fehlgeschlagener Assertion

Test-Suites sinnvoll strukturieren

Mit steigender Anzahl an Tests wird Struktur wichtig.

Ein praktikables Muster:

  • eine Suite pro Ressource
  • ein Test pro Verhalten
  • klare Namen für Fehlerdiagnose

Beispielstruktur:

User API tests
├── GET /users/1 returns 200
├── GET /users/1 returns expected user fields
├── GET /users/999 returns not found
└── POST /users validates required fields
Enter fullscreen mode Exit fullscreen mode

Vermeiden Sie Tests, die zu viele Dinge gleichzeitig prüfen. Wenn ein Test fehlschlägt, sollte der Name bereits erklären, welches Verhalten defekt ist.

Beispiel für einen fokussierten Test:

const response = await insomnia.send();
const body = JSON.parse(response.data);

expect(response.status).to.equal(200);
expect(body).to.have.property("email");
Enter fullscreen mode Exit fullscreen mode

Statt:

const response = await insomnia.send();
const body = JSON.parse(response.data);

expect(response.status).to.equal(200);
expect(body.id).to.equal(1);
expect(body.name).to.equal("Leanne Graham");
expect(body.email).to.equal("Sincere@april.biz");
expect(body.address.city).to.equal("Gwenborough");
expect(body.company.name).to.equal("Romaguera-Crona");
Enter fullscreen mode Exit fullscreen mode

Der zweite Test ist nicht falsch, aber schwieriger zu warten, weil mehrere unabhängige Annahmen gleichzeitig geprüft werden.

Für bessere Assertions siehe den Leitfaden zu API-Assertionen. Wenn Ihre Suites wachsen, hilft der Artikel über Test-Suites für die API-Testautomatisierung.

Aus der Befehlszeile mit Inso ausführen

Für lokale Entwicklung reicht die GUI. Für CI/CD benötigen Sie eine Headless-Ausführung.

Dafür gibt es Inso, den CLI-Begleiter von Insomnia.

Eine Test-Suite führen Sie aus dem Terminal aus:

inso run test "User API tests"
Enter fullscreen mode Exit fullscreen mode

Wenn ein Test fehlschlägt, beendet sich Inso mit einem Exit-Code ungleich Null. Genau das braucht eine CI-Pipeline, um einen Build fehlschlagen zu lassen.

Beispiel für GitHub Actions:

name: API tests

on:
  push:
    branches:
      - main
  pull_request:

jobs:
  insomnia-tests:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout repository
        uses: actions/checkout@v4

      - name: Install Inso
        run: npm install -g insomnia-inso

      - name: Run Insomnia tests
        run: inso run test "User API tests"
Enter fullscreen mode Exit fullscreen mode

Je nach Projektstruktur müssen Sie zusätzlich den Pfad zu Ihrer exportierten oder synchronisierten Insomnia-Konfiguration angeben.

Inso kann außerdem API-Spezifikationen linten und Testberichte erzeugen. Das allgemeine CI/CD-Muster wird im Artikel zum Automatisieren von API-Tests in CI/CD beschrieben.

Die Cloud-Änderung in Version 8 und eine Alternative

Insomnia 8 verschob den Standard stärker in Richtung Cloud-First. Nutzer wurden stärker dazu geführt, ein Kong-Konto zu erstellen und Projekte in der Cloud zu speichern.

Das störte Teile der Community, weil frühere Versionen stärker lokal und offline-freundlich waren. Spätere Versionen brachten klarere Optionen für rein lokale Nutzung oder Scratch Pad zurück. Trotzdem begannen manche Teams, Alternativen zu prüfen, besonders wenn API-Daten das eigene Netzwerk nicht verlassen dürfen.

Wenn das für Ihr Team relevant ist, ist Apidog eine mögliche Alternative. Apidog bündelt API-Design, Debugging, Mocking, Testing und Dokumentation in einer Plattform und kann Insomnia-Exporte importieren, sodass Sie nicht bei null starten müssen.

Praktischer Vergleichsablauf:

  1. Exportieren Sie Ihre Insomnia-Sammlung.
  2. Installieren Sie Apidog.
  3. Importieren Sie die Sammlung.
  4. Vergleichen Sie Debugging, Assertions, Mocking und Dokumentation im selben Projekt.

Apidog erlaubt visuelle Assertions ohne JavaScript, unterstützt aber weiterhin Skripte, wenn Sie mehr Kontrolle benötigen. Da API-Spezifikation, Testdaten und Mock-Server in einem Projekt liegen, bleiben Tests näher am tatsächlichen API-Vertrag.

Eine breitere Tool-Übersicht finden Sie in der Liste der kostenlosen Online-API-Testwerkzeuge.

Insomnia bleibt trotzdem ein starker, fokussierter API-Client, besonders für Einzelentwickler und kleine Teams, die eine schnelle, reduzierte Oberfläche bevorzugen. Die richtige Wahl hängt davon ab, ob Sie nur Requests debuggen oder den gesamten API-Lebenszyklus in einem Tool abbilden möchten.

Häufig gestellte Fragen

Ist Insomnia kostenlos nutzbar?

Ja. Insomnia bietet eine kostenlose Stufe für individuelle Nutzung, darunter das Senden von Anfragen und das lokale Ausführen von Test-Suites. Kostenpflichtige Pläne ergänzen Teamfunktionen und höhere Cloud-Sync-Limits. Neuere Versionen ermöglichen auch rein lokale Nutzung, wenn Sie keine Cloud-Synchronisierung verwenden möchten.

Welche Protokolle unterstützt Insomnia?

Insomnia unterstützt HTTP, REST, GraphQL, gRPC, SOAP und WebSocket. Die Einrichtung unterscheidet sich je nach Protokoll. Für HTTP-basierte APIs können Sie Antworten konsistent prüfen und Test-Suite-Assertions verwenden.

Wie schreibe ich Assertions in Insomnia?

Öffnen Sie in einer Sammlung die Ansicht Tests, erstellen Sie eine Test-Suite und fügen Sie Tests hinzu. Jeder Test ist JavaScript. Mit insomnia.send() führen Sie die zugeordnete Anfrage aus. Anschließend prüfen Sie Status, Header oder Body mit expect.

Beispiel:

const response = await insomnia.send();
const body = JSON.parse(response.data);

expect(response.status).to.equal(200);
expect(body).to.have.property("id");
Enter fullscreen mode Exit fullscreen mode

Was hat sich in Insomnia 8 geändert?

Insomnia 8 führte eine Cloud-First-Standardeinstellung ein, bei der Nutzer stärker zur Anmeldung bei einem Kong-Konto und zur Cloud-Synchronisierung geführt wurden. Einige Nutzer kritisierten diesen Wechsel weg von einer rein lokalen App. Spätere Updates ergänzten klarere lokale Optionen, aber die Änderung führte dazu, dass manche Teams Alternativen evaluierten.

Kann ich Insomnia-Tests in einer CI-Pipeline ausführen?

Ja. Verwenden Sie Inso, den CLI-Begleiter von Insomnia. Exportieren oder synchronisieren Sie Ihre Sammlung und führen Sie dann in der Pipeline aus:

inso run test "<suite name>"
Enter fullscreen mode Exit fullscreen mode

Wenn ein Test fehlschlägt, gibt Inso einen Exit-Code ungleich Null zurück. Dadurch kann CI den Build automatisch fehlschlagen lassen.

Top comments (0)