Wenn Sie ein OpenAPI- oder GraphQL-Schema haben, kann Schemathesis es in Tausende von Testfällen umwandeln, ohne dass Sie eine einzige Assertion schreiben müssen. Es liest die Spezifikation, generiert unvorhergesehene und gültige Eingaben, sendet diese an Ihre API und meldet, wo die Antworten den Vertrag verletzen. Dieser Leitfaden erklärt, was Schemathesis ist, wie man es installiert und ausführt, was eigenschaftsbasiertes Testen tatsächlich bedeutet und wie es neben einem funktionalen und Vertragstesting-Workflow in Apidog passt.
Was ist Schemathesis?
Schemathesis ist ein Open-Source-Python-Tool, das automatisch API-Tests aus einem Schema generiert. Sie verweisen es auf eine OpenAPI- oder GraphQL-Definition, und es erstellt Testfälle aus den bereits deklarierten Typen, Formaten und Einschränkungen. Es basiert auf Hypothesis, der Bibliothek für eigenschaftsbasiertes Testen für Python, und wird unter der MIT-Lizenz vertrieben.
Die Kernidee ist einfach. Ihre Spezifikation beschreibt bereits, wie eine gültige Anfrage und Antwort aussehen. Schemathesis behandelt diese Beschreibung als Quelle der Wahrheit und prüft, ob Ihre laufende API sie tatsächlich einhält. Wenn die API einen 500er-Fehler zurückgibt, eine Antwort sendet, die das deklarierte Schema verletzt, oder Eingaben akzeptiert, die sie hätte ablehnen sollen, markiert Schemathesis dies.
Sie führen es über die Befehlszeile mit schemathesis run (oder dem kürzeren Alias st run) aus. Es gibt auch eine Python-Integration, wenn Sie es anstelle der CLI über pytest steuern möchten. Die meisten Teams beginnen mit der CLI, da sie kaum Einrichtung erfordert.
Was eigenschaftsbasiertes Testen bedeutet
Die meisten API-Tests sind beispielbasiert. Sie schreiben eine Anfrage, Sie überprüfen eine bestimmte Antwort, und der Test besteht oder schlägt in diesem einen Fall fehl. Das ist nützlich, aber Sie finden nur die Fehler, für die Sie einen Test geschrieben haben.
Eigenschaftsbasiertes Testen kehrt diesen Ansatz um. Anstatt eines festen Beispiels beschreiben Sie eine Eigenschaft, die immer gelten sollte, und lassen das Tool dann Hunderte von Eingaben generieren, um diese zu brechen. Für Schemathesis lautet die Eigenschaft grob: „Keine gültige Anfrage sollte jemals den Server zum Absturz bringen oder eine Antwort erzeugen, die das Schema verletzt.“
Schemathesis generiert Eingaben aus den Einschränkungen Ihrer Spezifikation. Wenn ein Feld eine Ganzzahl mit einem Minimum von 1 ist, wird es 1, große Zahlen, Grenzwerte und die Arten von Eingaben ausprobieren, die eine naive Validierung stolpern lassen. Wenn ein Test fehlschlägt, verkleinert Hypothesis die Eingabe auf den kleinsten Fall, der den Fehler immer noch reproduziert, sodass Sie eine minimale, lesbare Reproduktion anstelle einer zufälligen 4 KB großen Nutzlast erhalten.
Dies unterscheidet sich vom Monkey-Testing, das zufällige Eingaben an eine Schnittstelle sendet, um zu sehen, was abstürzt. Eigenschaftsbasiertes Testen ist strukturiert. Es verwendet das Schema, um plausible und gezielte Eingaben zu generieren, und es weiß, wie ein korrektes Ergebnis aussieht, weil die Spezifikation es ihm gesagt hat.
Schemathesis installieren und ausführen
Schemathesis ist ein Python-Paket, daher benötigen Sie Python 3 und pip. Installieren Sie es auf die übliche Weise:
pip install schemathesis
Sie können es auch ohne dauerhafte Installation mit uvx schemathesis ausführen, wenn Sie uv eingerichtet haben. Nach der Installation zeigt der grundlegende Befehl auf ein Schema und eine Basis-URL:
st run http://127.0.0.1:8000/openapi.json
Wenn Ihr Schema auf der Festplatte und nicht hinter einer URL liegt, geben Sie den Dateipfad an und teilen Sie Schemathesis mit, wo sich die Live-API befindet:
st run ./openapi.yaml --url http://127.0.0.1:8000
Für eine authentifizierte API fügen Sie einen Header hinzu:
st run http://127.0.0.1:8000/openapi.json \
--header 'Authorization: Bearer your-token'
Schemathesis entdeckt jede Operation in der Spezifikation, generiert Fälle für jede und druckt eine Zusammenfassung, welche Überprüfungen bestanden und welche fehlgeschlagen sind. Fehler werden mit der exakten gesendeten Anfrage geliefert, sodass Sie sie mit curl oder in jedem API-Client wiederholen können. Flag-Namen und Standardwerte ändern sich zwischen Hauptversionen, überprüfen Sie daher st run --help mit Ihrer installierten Version, anstatt einem Blog-Snippet, einschließlich diesem hier, zu vertrauen.
Was Schemathesis erkennt
Die Standardprüfungen zielen auf die Lücke zwischen dem, was Ihre Spezifikation verspricht, und dem, was Ihr Server leistet. Hier ist, was typischerweise auftritt.
| Problem | Wie es aussieht |
|---|---|
| Serverfehler | Eine Anfrage löst einen 500er-Fehler aus anstelle eines behandelten 4xx-Fehlers oder einer gültigen Antwort |
| Schemaverletzungen | Der Antwortkörper stimmt nicht mit dem Schema überein, das Sie für diesen Statuscode deklariert haben |
| Statuscode-Fehlanpassungen | Die API gibt einen Statuscode zurück, der in der Spezifikation nie dokumentiert wurde |
| Content-Type-Abweichung | Der Content-Type der Antwort stimmt nicht mit dem überein, was die Spezifikation angibt |
| Zustandsabhängige Fehler | Eine Operation funktioniert allein, schlägt aber innerhalb eines realistischen mehrstufigen Workflows fehl |
Der letzte Punkt ist einen genaueren Blick wert. Schemathesis kann zustandsbehaftete Tests ausführen, bei denen Operationen basierend auf Links in Ihrer Spezifikation miteinander verkettet werden, z. B. eine Ressource erstellen, sie dann abrufen und dann löschen. Fehler, die nur in Sequenzen auftreten, wie z. B. eine Ressource, die nach einer Aktualisierung einen falschen Zustand meldet, sind mit Einzelanfrage-Tests schwer zu finden. Die zustandsbehaftete Phase steuert diese Sequenzen als Zustandsmaschine.
Sie können das Standardverhalten mit Hooks erweitern. Hooks sind Python-Funktionen, mit denen Sie die Datengenerierung anpassen, eigene Prüfungen hinzufügen oder filtern können, welche Operationen getestet werden. So passen Teams Schemathesis an APIs mit Authentifizierungs-Flows oder nicht offensichtlichen Einschränkungen an, die die Spezifikation nicht ausdrücken kann.
Wann Schemathesis verwenden
Schemathesis hat seinen Platz verdient, wenn Sie eine einigermaßen genaue OpenAPI- oder GraphQL-Spezifikation haben und eine breite, kostengünstige Abdeckung von Randfällen wünschen. Es ist stark darin, die Fehler zu finden, für die Sie niemals einen manuellen Test schreiben würden: unbehandelte Eingaben, undokumentierte Fehlerformen und Vertragsabweichungen zwischen Spezifikation und Implementierung.
Es passt gut, wenn:
- Sie eine OpenAPI-Spezifikation pflegen und deren Einhaltung gegenüber dem echten Server erzwingen möchten.
- Sie sich Sorgen um unbehandelte 500er-Fehler machen und eine Fuzzing-Schicht in Ihrer CI wünschen.
- Ihre API zustandsbehaftete Workflows hat, bei denen die Reihenfolge wichtig ist.
- Ihr Team bereits mit Python arbeitet und mit
pipundpytestvertraut ist.
Es passt weniger gut, wenn Ihre Spezifikation dünn oder veraltet ist, da Schemathesis nur das testen kann, was das Schema beschreibt. „Garbage in, garbage out.“ Es wird auch Ihre beispielbasierten Funktionstests nicht ersetzen. Zu wissen, dass ein Endpunkt niemals abstürzt, ist nicht dasselbe wie zu wissen, dass er für eine bekannte Eingabe den richtigen Wert zurückgibt. Sie möchten beides.
Schemathesis und Apidog: Wo jedes seinen Platz hat
Apidog und Schemathesis lösen unterschiedliche Probleme und arbeiten gut nebeneinander. Apidog ist eine All-in-One-Plattform für Design, Debugging, Testen, Mocking und Dokumentation von APIs. Schemathesis ist ein spezialisierter eigenschaftsbasierter Fuzzer. Ehrlichkeit bezüglich der Abgrenzung ist hier wichtig.
Apidog führt kein eigenschaftsbasiertes Fuzzing durch. Die nächstgelegene Funktion ist das Monkey-Testing, das zufällige Eingaben sendet, um Abstürze aufzudecken. Das ist nützlich, aber nicht dasselbe wie schemabasiertes, eigenschaftsbasiertes Testen. Schemathesis generiert Eingaben aus den Einschränkungen Ihrer Spezifikation und überprüft die Antworten anhand des Schemas. Wenn Sie also eigenschaftsbasiertes Fuzzing benötigen, greifen Sie zu Schemathesis, nicht zu Apidog.
Wo Apidog passt, ist der Rest des Lebenszyklus um diesen Fuzzing-Durchlauf herum.
| 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 |
Eine praktische Kombination sieht so aus: Sie entwerfen und pflegen die Spezifikation in Apidog, generieren daraus funktionale Testfälle und einen Mock-Server und führen diese in der CI mit apidog run aus. Dann fügen Sie einen Schemathesis-Durchlauf hinzu, der dieselbe Spezifikation auf Randfall-Abstürze und Vertragsverletzungen fuzzt. Die beiden Schichten fangen unterschiedliche Fehlerklassen ab. Apidog bestätigt, dass die API bei bekannten Fällen das Richtige tut; Schemathesis sucht nach den unbekannten Fällen, die sie zum Absturz bringen.
Wenn Ihr Ziel darin besteht, eine Spezifikation in eine lauffähige funktionale Suite umzuwandeln, anstatt einen Fuzzing-Lauf durchzuführen, kann Apidog API-Testsammlungen direkt aus Ihren OpenAPI-Spezifikationen generieren, und 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, und die CLI kann kostenlos über pip install schemathesis installiert und ausgeführt werden. Es gibt auch ein gehostetes kommerzielles Angebot für Teams, die eine verwaltete Erfahrung wünschen, aber das Kernwerkzeug, das Sie lokal und in der CI ausführen, kostet nichts.
Was ist der Unterschied zwischen schemathesis run und st run?
Es ist derselbe Befehl. st ist ein kurzer Alias für schemathesis, daher tun st run und schemathesis run genau dasselbe. Verwenden Sie, was Sie bevorzugen. Beide akzeptieren einen Schema-Pfad oder eine URL sowie Optionen wie --url und --header.
Kann Schemathesis meine funktionalen API-Tests ersetzen?
Nein, und das ist auch nicht beabsichtigt. Schemathesis prüft, ob Ihre API nicht abstürzt und ob die Antworten dem Schema entsprechen. Es überprüft keine Geschäftslogik, wie z. B. ob eine Rabattberechnung korrekt ist. Dafür benötigen Sie weiterhin beispielbasierte funktionale Tests und Vertragstests, die Sie in Apidog erstellen und ausführen können. Betrachten Sie Schemathesis als eine zusätzliche Fuzzing-Schicht, nicht als Ersatz.
Funktioniert Schemathesis mit GraphQL?
Ja. Schemathesis unterstützt sowohl OpenAPI- als auch GraphQL-Schemas. Für GraphQL generiert es Abfragen aus den Typdefinitionen des Schemas und überprüft die Antworten auf dieselbe Weise wie bei REST-APIs, die in OpenAPI definiert sind.
Fazit
Schemathesis ist ein scharfes Werkzeug für eine Aufgabe: Ihre OpenAPI- oder GraphQL-Spezifikation zu nehmen und Ihre Live-API mit eigenschaftsbasierter Generierung darauf zu testen. Es findet Abstürze und Vertragsverletzungen, die beispielbasierte Tests übersehen, und es kostet Sie fast nichts, es zur CI hinzuzufügen. Was es nicht tut, ist das Entwerfen, Mocken, Dokumentieren oder Überprüfen der Geschäftslogik.
Hier ergänzt Apidog Schemathesis. Entwerfen Sie die Spezifikation, generieren Sie funktionale Tests und Mocks, führen Sie diese in der CI mit apidog run aus und dokumentieren Sie das Ergebnis, alles an einem Ort. Legen Sie dann Schemathesis für das Fuzzing darüber. Laden Sie Apidog herunter, um die Design- und funktionale Seite dieses Workflows zu erstellen, und lassen Sie Schemathesis die Jagd nach Randfällen übernehmen.