API Testfälle schreiben: Vorlage und Beispiel

Eine fehleranfällige API fällt selten aus, weil jemand vergessen hat, sie zu testen. Sie fällt aus, weil der durchgeführte Test das Falsche überprüft hat oder überhaupt nichts außer einem 200er-Statuscode. Ein gut geschriebener API-Testfall ist der Unterschied zwischen dem frühzeitigen Erkennen eines gebrochenen Vertrags vor der Veröffentlichung und dem Erklären des Ausfalls danach.

Dieser Leitfaden erklärt, was ein API-Testfall ist, welche Felder ein guter benötigt und wie man einen von Grund auf neu schreibt. Sie werden ein vollständiges durchgespieltes Beispiel für einen Login-Endpunkt sehen und dann denselben Test in Apidog ohne Skripting erstellen.

Was ein API-Testfall eigentlich ist

Ein API-Testfall ist eine definierte Menge an Eingaben, Aktionen und erwarteten Ergebnissen, die verwendet wird, um zu bestätigen, dass ein Endpunkt unter einer bestimmten Bedingung korrekt funktioniert. Er ist enger gefasst als ein Testszenario. Ein Szenario sagt „Benutzeranmeldung überprüfen.“ Ein Testfall sagt „POST gültige Anmeldeinformationen an /auth/login senden und eine 200-Antwort mit einem JWT im Body innerhalb von 800 ms bestätigen.“

Jeder Fall zielt auf ein einzelnes Verhalten ab. Dieser Fokus ist wichtig. Wenn ein breiter, vielseitiger Test fehlschlägt, müssen Sie immer noch untersuchen, welcher Teil defekt ist. Wenn ein fokussierter Fall fehlschlägt, gibt Ihnen der Fehlername die Antwort. Wenn Sie immer noch die Beziehung zwischen Testfällen, Szenarien und Skripten klären, ziehen Testszenario vs. Testfall und Testfall vs. Testskript die Grenzen klar.

API-Tests decken in der Regel fünf Bereiche ab, und Ihre Fälle sollten sich auf alle von ihnen verteilen:

• Funktional: Gibt der Endpunkt die richtigen Daten für eine gültige Eingabe zurück?
• Negativ: Lehnt er fehlerhafte Eingaben mit dem richtigen Fehler und Statuscode ab?
• Performance: Reagiert er innerhalb eines akzeptablen Zeitbudgets?
• Sicherheit: Erzwingt er Authentifizierung, Autorisierung und Eingabegrenzen?
• Vertrag: Entspricht die Antwort dem dokumentierten Schema?

Eine Testsuite, die nur den „Happy Path“ überprüft, wird so lange bestehen, bis ein echter Benutzer ein leeres Passwortfeld sendet.

Warum Sie eine Testfallvorlage benötigen

Das Schreiben jedes Falls von einem leeren Blatt führt zu inkonsistenter Abdeckung. Ein Ingenieur zeichnet erwartete Statuscodes auf; ein anderer zeichnet Antwortkörper auf; ein dritter schreibt „sollte funktionieren.“ Eine Vorlage behebt dies, indem sie jedes Mal die gleiche Struktur erzwingt.

Eine gemeinsame Vorlage bringt vier konkrete Vorteile. Die Abdeckung wird nachvollziehbar, da jeder Fall die gleichen Felder hat und Lücken sichtbar sind. Das Onboarding beschleunigt sich, da ein neuer Tester ein Format anstelle von fünf liest. Fälle werden über Releases hinweg wiederverwendbar, da ein strukturierter Fall leicht zu klonen und anzupassen ist. Und die Nachverfolgbarkeit bleibt erhalten, da jeder Fall auf eine Anforderung oder einen Endpunkt zurückverweist.

Vorlagen machen auch die Automatisierung realistisch. Ein strukturierter Fall lässt sich sauber auf einen automatisierten Testschritt abbilden; ein vager Fall muss neu geschrieben werden, bevor eine Maschine ihn ausführen kann.

Der Aufbau eines robusten API-Testfalls

Eine vollständige API-Testfallvorlage enthält diese Felder. Sie benötigen nicht alle für jeden Fall, aber der Kernsatz ist nicht verhandelbar.

Die Felder, die Teams am häufigsten überspringen, sind die erwartete Antwortzeit und der erwartete Antwortkörper. Diese zu überspringen führt dazu, dass ein Test „bestanden“ wird, obwohl er eine 200 mit einem leeren Payload oder einen korrekten Payload drei Sekunden zu spät zurückgibt.

Wie man API-Testfälle Schritt für Schritt schreibt

Zuerst die API-Dokumentation lesen. Notieren Sie die erforderlichen Parameter, die Authentifizierungsmethode, die dokumentierten Statuscodes und das Antwortschema. Jeder Testfall ist eine Aussage über dokumentiertes Verhalten, daher sind die Dokumente Ihre Wahrheitsquelle. Tools, die eine OpenAPI-Spezifikation lesen, um Testsammlungen zu generieren, können Ihnen ein Ausgangsskelett liefern.

Die zu testenden Bedingungen auflisten. Für einen einzelnen Endpunkt bedeutet das normalerweise: gültige Eingabe, jedes fehlende Pflichtfeld, jedes fehlerhafte Feld, eine nicht autorisierte Anfrage, ein abgelaufenes Token und ein überdimensionierter Payload. Jede Bedingung wird zu einem Fall.

Eindeutige Testdaten vorbereiten. Negative Fälle benötigen Daten, die genau auf eine Weise falsch sind. Die Wiederverwendung desselben Payloads über Fälle hinweg versteckt Fehler, weil Sie immer nur einen Pfad ausführen.

Das erwartete Ergebnis präzise formulieren. „Gibt Erfolg zurück“ ist keine Behauptung. „Gibt 200 zurück, Body enthält einen nicht-leeren `token`-String, `expires_in` ist gleich 3600“ ist es. Diese Präzision macht den Fall lohnenswert.

Den Fall zu einer ausführbaren Suite hinzufügen. Ein Fall in einer Tabellenkalkulation dokumentiert die Absicht. Ein Fall in einem Testtool führt zu einem Pass oder Fail. Gruppieren Sie zugehörige Fälle, damit der gesamte Endpunkt mit einem Klick ausgeführt wird; Testsuiten existieren genau dafür.

Fälle aktuell halten. Wenn die API sich ändert, ändern sich die Fälle mit. Ein veralteter Fall, der ein altes Schema überprüft, ist schlimmer als kein Fall, weil er aus dem falschen Grund fehlschlägt und das Team dazu trainiert, rote Builds zu ignorieren.

Ein durchgespieltes Beispiel: Testen eines Login-Endpunkts

Nehmen Sie einen Standard-Authentifizierungsendpunkt: POST /auth/login, der eine E-Mail und ein Passwort entgegennimmt und ein JWT zurückgibt. Hier sind vier Fälle, die ihn ordnungsgemäß abdecken.

AUTH-LOGIN-001: gültige Anmeldeinformationen (funktional, kritisch)

• Endpunkt: POST /auth/login
• Voraussetzungen: Ein Benutzer mit E-Mail dana@example.com existiert
• Body: {"email": "dana@example.com", "password": "Correct-Horse-9"}
• Erwarteter Status: 200
• Erwartete Antwort: Body enthält einen nicht-leeren token (String), token_type ist gleich Bearer, expires_in ist gleich 3600
• Erwartete Antwortzeit: unter 800 ms

AUTH-LOGIN-002: falsches Passwort (negativ, kritisch)

• Body: {"email": "dana@example.com", "password": "wrong"}
• Erwarteter Status: 401
• Erwartete Antwort: error ist gleich invalid_credentials; kein token-Feld vorhanden
• Hinweis: Die Nachricht darf nicht verraten, ob die E-Mail existiert

AUTH-LOGIN-003: fehlendes Passwortfeld (negativ, hoch)

• Body: {"email": "dana@example.com"}
• Erwarteter Status: 400
• Erwartete Antwort: error ist gleich validation_error; details benennt das Feld password

AUTH-LOGIN-004: fehlerhafte E-Mail (negativ, mittel)

• Body: {"email": "not-an-email", "password": "Correct-Horse-9"}
• Erwarteter Status: 400
• Erwartete Antwort: error ist gleich validation_error

Vier Fälle, ein Endpunkt, und schon überprüfen Sie den Vertrag, die Fehlerstruktur, die Statuscodes und ein Latenzbudget. Fügen Sie einen Sicherheitsfall für eine SQL-Injection-Zeichenkette im E-Mail-Feld hinzu, und Sie haben eine Suite, die es wert ist, bei jedem Commit ausgeführt zu werden.

Denselben Testfall in Apidog schreiben

Sie können alle vier oben genannten Fälle ausführen, ohne eine Zeile Code zu schreiben. In Apidog wird ein API-Testfall visuell erstellt.

1. Den Endpunkt importieren oder definieren. POST /auth/login aus einer OpenAPI-Datei, einer Postman-Sammlung importieren oder direkt definieren. Das Request-Schema wird zur Grundlage für jede Überprüfung.
2. Die Request-Daten hinzufügen. Geben Sie den Body für Fall AUTH-LOGIN-001 ein. Für datengesteuerte Abdeckung hängen Sie eine CSV- oder JSON-Datei an, damit ein Fall gegen jede Zeile mit Anmeldeinformationen ausgeführt wird; so ersetzt datengesteuertes API-Testing vier nahezu identische Fälle durch einen.
3. Überprüfungen visuell einstellen. Klicken Sie, um zu überprüfen, dass der Status 200 ist, dass token existiert und ein nicht-leerer String ist, dass expires_in gleich 3600 ist und dass die Antwortzeit unter 800 ms bleibt. Keine Skripterstellung erforderlich.
4. Fälle zu einem Testszenario gruppieren. Fügen Sie alle vier Login-Fälle zu einem Szenario hinzu, damit der Endpunkt in einem einzigen Durchlauf vollständig getestet wird.
5. Den Bericht ausführen und lesen. Apidog führt das Szenario aus, generiert einen Pass/Fail-Bericht pro Fall und zeigt die genaue Überprüfung an, die fehlschlug. Sie können das Szenario lokal, nach Zeitplan oder innerhalb von CI ausführen.

Es geht nicht darum, dass Skripterstellung falsch ist; es geht darum, dass ein strukturierter visueller Fall schneller zu schreiben, leichter zu überprüfen und subtile Fehler schwieriger zu machen sind. Wenn Sie Code benötigen, können Sie in Apidog immer noch zu benutzerdefinierten Skripten wechseln. Für einen vollständig skriptfreien Workflow behandelt API-Testing ohne Postman den breiteren Ansatz.

Häufige Fehler, die vermieden werden sollten

Nur den Statuscode überprüfen. Eine 200 bedeutet, dass die Anfrage bearbeitet wurde, nicht dass die Antwort korrekt war. Überprüfen Sie immer Body-Felder.

Ein riesiger Fall pro Endpunkt. Wenn er fehlschlägt, lernen Sie nichts. Teilen Sie ihn nach Bedingungen auf.

Wiederverwendete Testdaten. Wenn jeder negative Fall denselben Payload sendet, testen Sie nur einen Fehlermodus.

Keine Latenzüberprüfung. Performance-Regressionen schleichen sich still und leise ein, wenn nichts die Antwortzeit misst.

Fälle, die nie automatisiert werden. Ein dokumentierter Fall, den kein Runner ausführt, ist ein Kommentar, kein Test. Verschieben Sie Fälle in eine Suite, die bei jedem Build ausgeführt wird; das Generieren von Testskripten aus einer OpenAPI-Spezifikation ist eine schnelle Möglichkeit, diese Suite zu initialisieren.

Laden Sie Apidog herunter, wenn Sie dem Beispiel folgen und die vier Anmeldefälle selbst erstellen möchten.

Häufig gestellte Fragen

Wie viele Testfälle benötigt ein Endpunkt? Genug, um den Happy Path, jeden Pflichtfeldfehler, einen Authentifizierungsfehler und eine Sicherheitsprüfung abzudecken. Für einen einfachen Endpunkt sind das vier bis sechs Fälle; für einen komplexen kann es mehr sein.

Sollte ich Testfälle schreiben, bevor die API erstellt wird? Ja. Das Schreiben von Testfällen gegen das Design, also Design-First, deckt Vertragslücken frühzeitig auf. Kombinieren Sie dies mit KI-gestützter Testfallgenerierung, um schnell einen ersten Satz zu entwerfen und diesen dann manuell zu verfeinern.

Tabellenkalkulation oder Testtool zur Speicherung von Fällen? Eine Tabellenkalkulation dokumentiert die Absicht, kann aber nicht ausgeführt werden. Bewahren Sie Fälle in einem Tool auf, das sie ausführt und Ergebnisse meldet, damit ein Fall immer entweder grün oder rot ist.

Was ist der Unterschied zwischen einem Testfall und einem Testszenario? Ein Szenario ist das übergeordnete Ziel („Login überprüfen“); ein Fall ist eine konkrete, ausführbare Überprüfung innerhalb dessen. Siehe Testszenario vs. Testfall.