DEV Community

Cover image for Schemathesis: Eigenschaftsbasierte API-Tests für OpenAPI-Spezifikationen
Emre Demir
Emre Demir

Posted on • Originally published at apidog.com

Schemathesis: Eigenschaftsbasierte API-Tests für OpenAPI-Spezifikationen

Wenn Sie ein OpenAPI- oder GraphQL-Schema haben, kann Schemathesis daraus Tausende von API-Testfällen generieren, ohne dass Sie einzelne Assertions schreiben. Es liest Ihre Spezifikation, erzeugt gültige und unerwartete Eingaben, sendet sie an Ihre API und meldet Abweichungen vom Vertrag. In diesem Leitfaden richten Sie Schemathesis ein, führen erste Tests aus und kombinieren es sinnvoll mit funktionalen Tests und Vertragstests in Apidog.

Apidog noch heute ausprobieren

Was ist Schemathesis?

Schemathesis ist ein Open-Source-Python-Tool, das automatisch API-Tests aus OpenAPI- oder GraphQL-Schemas generiert. Es nutzt die in Ihrer Spezifikation definierten Typen, Formate, Parameter, Statuscodes und Einschränkungen, um Requests zu erzeugen und die tatsächlichen Responses Ihrer laufenden API zu prüfen.

Schemathesis basiert auf Hypothesis, einer Bibliothek für eigenschaftsbasiertes Testen in Python, und steht unter der MIT-Lizenz.

Schemathesis Demo

Die Idee ist einfach:

  1. Ihre Spezifikation beschreibt, wie Requests und Responses aussehen sollen.
  2. Schemathesis generiert daraus viele Testfälle.
  3. Die Tests werden gegen Ihre echte API ausgeführt.
  4. Abweichungen werden mit reproduzierbaren Requests gemeldet.

Typische Fehler, die Schemathesis findet:

  • 500er-Fehler bei unerwarteten Eingaben
  • Responses, die nicht zum deklarierten Schema passen
  • undokumentierte Statuscodes
  • falsche Content-Type-Header
  • Probleme in zustandsbehafteten API-Workflows

Sie können Schemathesis über die CLI mit schemathesis run oder kurz st run ausführen. Alternativ lässt es sich über Python und pytest integrieren. Für den Einstieg ist die CLI meist der schnellste Weg.

Was eigenschaftsbasiertes Testen bedeutet

Klassische API-Tests sind meistens beispielbasiert:

GET /users/123
Enter fullscreen mode Exit fullscreen mode

Dann prüfen Sie eine konkrete Response:

{
  "id": 123,
  "name": "Ada"
}
Enter fullscreen mode Exit fullscreen mode

Das ist wichtig, deckt aber nur die Fälle ab, die Sie explizit geschrieben haben.

Eigenschaftsbasiertes Testen dreht den Ansatz um. Statt einzelne Beispiele zu definieren, beschreiben Sie Eigenschaften, die immer gelten sollen. Das Tool generiert anschließend viele Eingaben, um diese Eigenschaften zu brechen.

Für Schemathesis lautet die zentrale Eigenschaft ungefähr:

Eine gültige Anfrage darf den Server nicht zum Absturz bringen und die Antwort muss zur Spezifikation passen.

Beispiel: Ihre OpenAPI-Spezifikation definiert ein Feld als Integer mit minimum: 1.

parameters:
  - name: limit
    in: query
    schema:
      type: integer
      minimum: 1
Enter fullscreen mode Exit fullscreen mode

Schemathesis testet dann nicht nur limit=10, sondern auch Grenzwerte und problematische Varianten wie:

limit=1
limit=0
limit=-1
limit=999999999
Enter fullscreen mode Exit fullscreen mode

Wenn ein Test fehlschlägt, reduziert Hypothesis den Fehlerfall auf eine möglichst kleine Reproduktion. Statt einer großen zufälligen Payload erhalten Sie einen minimalen Request, den Sie debuggen können.

Das unterscheidet sich von Monkey-Testing. Monkey-Testing sendet zufällige Eingaben, um Abstürze zu finden. Schemathesis arbeitet strukturierter: Es nutzt Ihr Schema, generiert gezielte Eingaben und prüft die Antworten gegen die Spezifikation.

Schemathesis installieren

Schemathesis ist ein Python-Paket. Sie benötigen Python 3 und pip.

pip install schemathesis
Enter fullscreen mode Exit fullscreen mode

Prüfen Sie danach die Installation:

st --version
Enter fullscreen mode Exit fullscreen mode

Alternativ können Sie Schemathesis ohne dauerhafte Installation mit uvx ausführen, wenn Sie uv verwenden:

uvx schemathesis run http://127.0.0.1:8000/openapi.json
Enter fullscreen mode Exit fullscreen mode

Ersten Schemathesis-Test ausführen

Wenn Ihre API lokal läuft und das OpenAPI-Schema unter /openapi.json bereitstellt, starten Sie den Test so:

st run http://127.0.0.1:8000/openapi.json
Enter fullscreen mode Exit fullscreen mode

Schemathesis liest das Schema, entdeckt die Operationen und führt generierte Requests gegen die API aus.

Wenn Ihr Schema lokal als Datei vorliegt, geben Sie zusätzlich die Basis-URL Ihrer API an:

st run ./openapi.yaml --url http://127.0.0.1:8000
Enter fullscreen mode Exit fullscreen mode

Für eine JSON-Spezifikation funktioniert es genauso:

st run ./openapi.json --url http://127.0.0.1:8000
Enter fullscreen mode Exit fullscreen mode

Authentifizierung hinzufügen

Für APIs mit Bearer Token übergeben Sie den Header direkt über die CLI:

st run http://127.0.0.1:8000/openapi.json \
  --header 'Authorization: Bearer your-token'
Enter fullscreen mode Exit fullscreen mode

Für mehrere Header:

st run ./openapi.yaml \
  --url http://127.0.0.1:8000 \
  --header 'Authorization: Bearer your-token' \
  --header 'X-Client-Version: dev'
Enter fullscreen mode Exit fullscreen mode

Wenn Ihre API Cookies verwendet:

st run ./openapi.yaml \
  --url http://127.0.0.1:8000 \
  --header 'Cookie: session=your-session-id'
Enter fullscreen mode Exit fullscreen mode

Flag-Namen und Standardwerte können sich zwischen Versionen ändern. Prüfen Sie deshalb immer die installierte Version:

st run --help
Enter fullscreen mode Exit fullscreen mode

Fehler reproduzieren

Wenn Schemathesis einen Fehler findet, gibt es die konkrete Anfrage aus. Diese können Sie meist direkt mit curl oder einem API-Client nachstellen.

Ein typischer Debug-Workflow:

  1. Schemathesis-Output lesen
  2. fehlgeschlagenen Request kopieren
  3. Request lokal reproduzieren
  4. Server-Logs prüfen
  5. Spezifikation oder Implementierung korrigieren
  6. Schemathesis erneut ausführen

Beispiel für eine manuelle Reproduktion:

curl -i \
  -H 'Authorization: Bearer your-token' \
  'http://127.0.0.1:8000/users?limit=0'
Enter fullscreen mode Exit fullscreen mode

Wenn limit laut Schema mindestens 1 sein muss, sollte Ihre API den Fehler kontrolliert behandeln, zum Beispiel mit 400 Bad Request, statt mit 500 Internal Server Error.

Was Schemathesis erkennt

Die Standardprüfungen zielen auf die Lücke zwischen Spezifikation und Implementierung.

Problem Wie es aussieht
Serverfehler Eine Anfrage löst einen 500-Fehler aus, obwohl ein behandelter 4xx-Fehler oder eine gültige Antwort erwartet wird
Schemaverletzungen Der Response-Body entspricht nicht dem Schema für den jeweiligen Statuscode
Statuscode-Abweichungen Die API gibt einen Statuscode zurück, der in der Spezifikation nicht dokumentiert ist
Content-Type-Abweichungen Der Content-Type der Antwort passt nicht zur Spezifikation
Zustandsabhängige Fehler Eine Operation funktioniert einzeln, schlägt aber in einem mehrstufigen Workflow fehl

Zustandsbehaftete Tests verwenden

Einzelne Requests finden viele Fehler, aber nicht alle. Manche Bugs entstehen erst in Sequenzen:

  1. Ressource erstellen
  2. Ressource abrufen
  3. Ressource aktualisieren
  4. Ressource erneut abrufen
  5. Ressource löschen

Schemathesis kann zustandsbehaftete Tests ausführen, wenn die Spezifikation passende Verknüpfungen beschreibt. Dabei werden Operationen als Zustandsmaschine kombiniert.

Das ist nützlich für Fehler wie:

  • Eine erstellte Ressource ist direkt danach nicht abrufbar
  • Ein Update speichert falsche Werte
  • Ein DELETE meldet Erfolg, entfernt die Ressource aber nicht korrekt
  • Ein Folge-Request gibt einen Zustand zurück, der nicht zum Schema passt

Schemathesis mit Hooks erweitern

Wenn Ihre API Regeln hat, die nicht vollständig in OpenAPI oder GraphQL abbildbar sind, können Sie Schemathesis mit Hooks anpassen.

Typische Anwendungsfälle:

  • Testdaten filtern
  • generierte Werte anpassen
  • eigene Checks hinzufügen
  • bestimmte Operationen überspringen
  • Authentifizierungsabläufe ergänzen

Beispielhaftes Muster:

import schemathesis

schema = schemathesis.from_uri("http://127.0.0.1:8000/openapi.json")

@schema.parametrize()
def test_api(case):
    response = case.call()
    case.validate_response(response)
Enter fullscreen mode Exit fullscreen mode

Damit können Sie Schemathesis über pytest ausführen und bei Bedarf eigene Logik ergänzen.

pytest test_api.py
Enter fullscreen mode Exit fullscreen mode

Schemathesis in CI ausführen

Schemathesis eignet sich gut als zusätzliche CI-Schicht. Ein einfacher CI-Schritt sieht so aus:

pip install schemathesis

st run ./openapi.yaml \
  --url "$API_BASE_URL" \
  --header "Authorization: Bearer $API_TOKEN"
Enter fullscreen mode Exit fullscreen mode

Praktische Empfehlungen:

  • Führen Sie Schemathesis gegen eine Test- oder Staging-Umgebung aus.
  • Verwenden Sie isolierte Testdaten.
  • Begrenzen Sie destructive Operations, wenn Ihre API produktionsnahe Daten nutzt.
  • Starten Sie mit einem kleinen Umfang und erweitern Sie später.
  • Speichern Sie reproduzierbare Fehlerfälle als Regressionstests.

Wann Sie Schemathesis verwenden sollten

Schemathesis ist besonders sinnvoll, wenn Sie eine brauchbare OpenAPI- oder GraphQL-Spezifikation haben und Randfälle automatisiert prüfen möchten.

Es passt gut, wenn:

  • Sie eine OpenAPI-Spezifikation pflegen und gegen den echten Server validieren möchten.
  • Sie unbehandelte 500-Fehler finden wollen.
  • Sie Fuzzing in Ihre CI integrieren möchten.
  • Ihre API zustandsbehaftete Workflows enthält.
  • Ihr Team bereits Python, pip oder pytest verwendet.

Es passt weniger gut, wenn:

  • Ihre Spezifikation veraltet ist.
  • wichtige Constraints nicht im Schema stehen.
  • Sie Geschäftslogik validieren möchten.
  • Sie ausschließlich visuelle API-Tests benötigen.

Schemathesis ersetzt keine funktionalen Tests. Es prüft, ob Ihre API stabil bleibt und dem Vertrag folgt. Es prüft nicht, ob Ihre Preisberechnung, Rabattlogik oder Berechtigungslogik fachlich korrekt ist.

Schemathesis und Apidog: Wo jedes Tool passt

Apidog und Schemathesis lösen unterschiedliche Aufgaben.

Apidog ist eine All-in-One-Plattform für API-Design, Debugging, Tests, Mocking und Dokumentation. Schemathesis ist ein spezialisiertes Tool für eigenschaftsbasiertes Fuzzing aus einer Spezifikation.

Wichtig: Apidog führt kein eigenschaftsbasiertes Fuzzing wie Schemathesis aus. Die nächstgelegene Funktion ist Monkey-Testing, das zufällige Eingaben sendet, um Abstürze aufzudecken. Das ist hilfreich, aber nicht identisch mit schemabasiertem Property-Based Testing.

Workflow-Phase Schemathesis Apidog
Eigenschaftsbasiertes Fuzzing aus einer Spezifikation Ja, Kernfunktion Nein
Visuelles API-Design und Spezifikationsbearbeitung Nein Ja
Beispielbasierte Funktionstests Begrenzt Ja, visueller Test-Builder
Vertragstesting gegen eine Spezifikation Teilweise, über Schema-Prüfungen Ja, dedizierter Workflow
Mock-Server aus einem Schema Nein Ja, Smart Mock
CI-Test-Runner Ja, st run Ja, apidog run
Automatisch generierte Dokumentation Nein Ja

Ein praktischer Workflow:

  1. API-Spezifikation in Apidog entwerfen und pflegen.
  2. Funktionale Testfälle in Apidog erstellen.
  3. Mock-Server für Frontend- oder Integrationsteams bereitstellen.
  4. Funktionale Tests in CI mit apidog run ausführen.
  5. Zusätzlich Schemathesis gegen dieselbe Spezifikation laufen lassen.
  6. Gefundene Fehler als Regressionstests übernehmen.

So decken Sie zwei Fehlerklassen ab:

  • Apidog prüft bekannte, fachlich relevante Beispiele.
  • Schemathesis sucht unbekannte Randfälle und Vertragsverletzungen.

Wenn Sie aus einer Spezifikation eine funktionale Testsuite erzeugen möchten, kann Apidog API-Testsammlungen direkt aus OpenAPI-Spezifikationen generieren. Sie können Apidog herunterladen, um diesen Workflow auszuprobieren.

Häufig gestellte Fragen

Ist Schemathesis kostenlos?

Ja. Schemathesis ist Open Source unter der MIT-Lizenz. Sie können es kostenlos installieren und lokal oder in CI ausführen:

pip install schemathesis
Enter fullscreen mode Exit fullscreen mode

Es gibt zusätzlich ein gehostetes kommerzielles Angebot für Teams, die eine verwaltete Erfahrung benötigen. Das lokale CLI-Tool bleibt kostenlos nutzbar.

Was ist der Unterschied zwischen schemathesis run und st run?

Es ist derselbe Befehl. st ist der kurze Alias für schemathesis.

Diese beiden Befehle sind äquivalent:

schemathesis run ./openapi.yaml --url http://127.0.0.1:8000
Enter fullscreen mode Exit fullscreen mode 
st run ./openapi.yaml --url http://127.0.0.1:8000
Enter fullscreen mode Exit fullscreen mode

Kann Schemathesis meine funktionalen API-Tests ersetzen?

Nein. Schemathesis prüft Stabilität und Schema-Konformität. Es validiert keine fachliche Geschäftslogik.

Beispiel: Schemathesis kann erkennen, dass ein Rabatt-Endpunkt eine ungültige Response-Struktur zurückgibt. Es weiß aber nicht automatisch, ob ein Rabatt von 17.5 % fachlich korrekt berechnet wurde.

Dafür brauchen Sie weiterhin beispielbasierte funktionale Tests und Vertragstests, die Sie in Apidog erstellen und ausführen können.

Funktioniert Schemathesis mit GraphQL?

Ja. Schemathesis unterstützt OpenAPI- und GraphQL-Schemas. Für GraphQL generiert es Abfragen aus den Typdefinitionen und prüft die Antworten ähnlich wie bei REST-APIs mit OpenAPI.

Fazit

Schemathesis ist ein fokussiertes Werkzeug für eigenschaftsbasiertes API-Fuzzing. Es nimmt Ihre OpenAPI- oder GraphQL-Spezifikation, generiert viele Testfälle und prüft Ihre Live-API auf Abstürze und Vertragsverletzungen.

Verwenden Sie es als zusätzliche Schicht neben Ihren funktionalen Tests:

st run ./openapi.yaml --url "$API_BASE_URL"
Enter fullscreen mode Exit fullscreen mode

Apidog ergänzt diesen Workflow auf der Design- und Funktionstest-Seite: Spezifikation erstellen, Tests definieren, Mocks bereitstellen, Dokumentation generieren und CI-Läufe mit apidog run ausführen. Danach kann Schemathesis dieselbe Spezifikation nutzen, um Randfälle zu finden.

Laden Sie Apidog herunter, um den Design- und Funktionstest-Teil des Workflows aufzubauen, und lassen Sie Schemathesis die Randfälle jagen.

Top comments (0)