Was ist Specmatic?

Wenn Sie eine OpenAPI-Datei pflegen, aber Ihr laufender Dienst langsam davon abweicht, ist Specmatic genau für diese Lücke gebaut. Es behandelt Ihre Spezifikation als ausführbaren Vertrag, testet dann einen echten Dienst dagegen und führt dieselbe Spezifikation als smarten Stub aus. Dieser Leitfaden erklärt, was Specmatic tut, wie sich Vertragstests von beispielbasierten Tests unterscheiden und wo das Tool passt, mit einem Hinweis, wie es sich zu einem breiteren Plattformansatz wie Apidogs API-Vertragstests verhält. Für das zugrunde liegende Spezifikationsformat ist die OpenAPI Specification die Quelle der Wahrheit, aus der Specmatic liest.

button

Was Specmatic ist

Specmatic ist ein Open-Source-Tool für die vertragsgesteuerte Entwicklung. Die Kernidee ist einfach: Ihre API-Spezifikation ist der Vertrag, und Specmatic macht diesen Vertrag ausführbar. Weisen Sie es auf eine OpenAPI-Datei und es kann zwei komplementäre Aufgaben erledigen.

Führen Sie die Spezifikation als Tests gegen einen Live-Dienst aus und überprüfen Sie, ob der Dienst jeden Pfad, Statuscode und Schema einhält, den die Spezifikation verspricht.
Führen Sie die Spezifikation als Stub-Server aus, damit Verbraucher gegen einen Mock entwickeln können, der genau wie im Vertrag beschrieben reagiert.

Beide Aufgaben lesen dieselbe Datei. Es gibt keine separate "Testdefinition" und "Spezifikation", die synchron gehalten werden müssten, was der entscheidende Punkt ist. Specmatic geht auch über OpenAPI hinaus. Version 2.0 fügte GraphQL und gRPC hinzu, und es unterstützt AsyncAPI für Kafka-ähnliche Ereignisverträge sowie Formate wie WSDL und Avro. Für die meisten Teams ist der Einstiegspunkt jedoch eine einfache OpenAPI YAML- oder JSON-Datei.

Sie führen es über die Befehlszeile oder ein Docker-Image aus, sodass es ohne großen Aufwand in die CI integriert werden kann. Das dahinterstehende Unternehmen bietet kommerzielle Add-ons an, aber die Vertrags-Engine selbst ist kostenlos und Open Source.

Vertragstests vs. beispielbasierte Tests

Dies ist der Unterschied, der die meisten Menschen verwirrt, daher lohnt es sich, präzise zu sein.

Beispielbasierte Tests sind das, was Sie in den meisten API-Clients tun. Sie schreiben eine Anfrage, überprüfen die erhaltene Antwort, vielleicht prüfen Sie einen Statuscode und ein oder zwei Felder. Jeder Test ist ein handgeschriebenes Beispiel. Wenn Ihre Spezifikation 40 Endpunkte hat, schreiben und pflegen Sie viele Beispiele, und Lücken sind leicht zu übersehen.

Vertragstests kehren das Modell um. Anstatt spezifische Beispiele zu überprüfen, überprüfen Sie, ob der Dienst dem Vertrag entspricht. Specmatic liest das Schema und generiert daraus Tests. Es prüft, ob die Antworten den deklarierten Typen entsprechen, ob erforderliche Felder vorhanden sind, ob die Statuscodes übereinstimmen und ob der Dienst fehlerhafte Anfragen so ablehnt, wie es die Spezifikation impliziert. Sie schreiben die Zusicherungen nicht einzeln. Die Spezifikation ist die Zusicherung.

Aspekt	Beispielbasierte Tests	Vertragstests mit Specmatic
Wahrheitsquelle	Manuell geschriebene Testfälle	Die OpenAPI-Spezifikation selbst
Was Sie pflegen	Jede Anfrage und Zusicherung	Die Spezifikation, die Sie sowieso behalten
Abdeckung	Nur das, was Sie sich gemerkt haben zu schreiben	Jede Operation, die die Spezifikation deklariert
Drift-Erkennung	Manuell	Automatisch bei Änderungen der Spezifikation
Typischer Fehler	Ein spezifisches Beispiel ist fehlerhaft	Der Dienst entspricht nicht mehr dem Vertrag

Es gibt eine zweite Achse, die es wert ist, benannt zu werden. Vertragstests gibt es in verschiedenen Ausprägungen, und Specmatic befindet sich in einer bestimmten. Pact-ähnliche konsumentengesteuerte Vertragstests lassen Konsumenten ihre Erwartungen an einen Broker veröffentlichen, und Anbieter überprüfen diese. Specmatic führt stattdessen vertragsgesteuerte Tests durch: Die Spezifikation ist der einzige Vertrag, dem beide Seiten zustimmen, und Specmatic validiert den Anbieter dagegen und erstellt Stubs für den Anbieter für Konsumenten. Es ist kein Pact-Broker und verwaltet keine von Konsumenten veröffentlichten Pacte. Wenn Sie ein umfassenderes Bild wünschen, lesen Sie diese Übersicht über API-Vertragstests und Mocking-Tools.

Wie Specmatic läuft

Sie können die CLI direkt installieren oder das Docker-Image ziehen. Docker ist die gängige Wahl in der CI, da es die lokale Laufzeitkonfiguration vermeidet.

Vertragstests ausführen

Der Testbefehl weist Specmatic auf eine Spezifikation und einen laufenden Dienst hin. Ein minimaler lokaler Durchlauf sieht so aus.

# Native CLI
specmatic test api.yaml --testBaseURL=http://localhost:8080

# Docker
docker run -v "$(pwd):/usr/src/app" specmatic/specmatic \
  test api.yaml --testBaseURL=http://host.docker.internal:8080

Specmatic liest api.yaml, generiert Anfragen für die beschriebenen Operationen, sendet sie an die Basis-URL und validiert jede Antwort gegen das Schema. Ein fehlerhafter Test bedeutet, dass der Dienst und der Vertrag nicht übereinstimmen. Sie beheben entweder das eine oder das andere. Das ist der Kreislauf.

Die Spezifikation als Stub ausführen

Der Stub-Server ist die andere Hälfte. Starten Sie ihn, und Specmatic liefert Antworten, die dem Vertrag entsprechen, sodass ein Frontend oder ein nachgeschalteter Dienst darauf aufbauen kann, bevor das echte Backend existiert.

specmatic stub api.yaml --port=9000

Standardmäßig generiert es schema-gültige Antworten im laufenden Betrieb. Sie können auch konkrete Beispiele in einem _examples-Verzeichnis neben der Spezifikation speichern, und der Stub gibt diese zurück, wenn eine Anfrage übereinstimmt. Dies liefert Ihnen realistische, kontrollierbare Daten, ohne ein echtes Backend aufsetzen zu müssen. Wenn Sie Stub- und Mock-Optionen verschiedener Tools vergleichen, ordnet die Übersicht über Vertragstests und Mock-Server Specmatic ein.

Specmatic kann Ihnen auch dabei helfen, die Spezifikation überhaupt erst zu erstellen. Es kann als Proxy vor einem bestehenden Dienst sitzen, realen Datenverkehr erfassen und ein OpenAPI-Dokument sowie Beispieldateien aus dem Gesehenen generieren. Das ist praktisch, wenn Sie einen Dienst, aber noch keine Spezifikation haben.

Das Modell der Spezifikation als Vertrag und Stub

Deshalb ist es wichtig, eine Datei sowohl als Test als auch als Stub auszuführen. Wenn die Spezifikation der Vertrag ist, können die Testseite und die Stub-Seite niemals uneinig sein, da sie dasselbe Dokument lesen.

Das Anbieter-Team führt specmatic test in der CI aus. Wenn sie die API ändern, ohne die Spezifikation zu aktualisieren, schlagen die Vertragstests fehl.
Das Konsumenten-Team führt specmatic stub lokal aus. Sie entwickeln gegen Antworten, die garantiert demselben Vertrag entsprechen.

So wird die Spezifikation zu einer lebendigen Vereinbarung, nicht zu einem veralteten Dokument, dem niemand vertraut. Dies ist der Unterschied zwischen einem Stub und einem umfassenderen Mock, und es lohnt sich, die zugrunde liegenden Ideen in API-Stubbing vs. Mocking zu verstehen, bevor Sie einen Workflow darum herum entwerfen.

Specmatic fügt auch eine Prüfung der Abwärtskompatibilität hinzu. Der Befehl backward-compatibility-check startet einen Stub aus der neuen Version einer Spezifikation, generiert Tests aus der vorherigen Version und führt diese gegen den neuen Stub aus. Wenn etwas, das früher funktionierte, nicht mehr funktioniert, finden Sie das heraus, bevor Sie es ausliefern. Das ist eine starke Absicherung für Microservices, die unabhängig voneinander bereitgestellt werden, und es ist eine Variante der breiteren Idee, die in bidirektionalen Vertragstests behandelt wird.

Wo Specmatic passt

Specmatic verdient seinen Platz, wenn folgende Punkte für Ihr Team zutreffen:

Ihre OpenAPI- (oder AsyncAPI-, GraphQL-, gRPC-) Spezifikation ist real und einigermaßen vollständig.
Sie haben separate Anbieter- und Konsumententeams oder -dienste, die synchron bleiben müssen.
Sie möchten, dass Spezifikationsabweichungen automatisch einen Build fehlschlagen lassen, anstatt erst im Review entdeckt zu werden.
Sie sind mit einem CLI- und CI-zentrierten Workflow vertraut.

Es passt weniger gut, wenn Sie keine Spezifikation pflegen, wenn Sie einen visuellen Arbeitsbereich zum Entwerfen und Erkunden von APIs wünschen oder wenn Sie ein einziges Tool für Ad-hoc-Debugging, Dokumentation und Teamzusammenarbeit suchen. Specmatic konzentriert sich auf die Vertrags-Engine, und diese eine Aufgabe erledigt es gut.

Dieser Fokus ist auch der Punkt, an dem eine Plattform wie Apidog eine andere Form annimmt. Apidog ist auf dieselbe Weise schemabasiert: Es liest Ihre OpenAPI-Spezifikation, validiert Antworten gegen das Schema und startet einen Mock-Server aus Ihrem OpenAPI-Schema ohne Code. Der ehrliche Unterschied liegt im Umfang. Specmatic ist ein scharfes, CLI-natives Vertragstool. Apidog vereint Design, Tests, Mocking und Dokumentation in einem Arbeitsbereich mit einem visuellen Editor, sodass die Spezifikation, die Tests und der Mock zusammenleben und während Ihrer Arbeit synchron bleiben. Apidog ist auch kein Pact-ähnlicher, konsumentengesteuerter Vertragsbroker, wenn Ihr Team also speziell einen Pact-Broker benötigt, ist keines der beiden Tools dafür geeignet.

Wenn Sie ausführbare Tests direkt aus einer Spezifikation innerhalb eines solchen Arbeitsbereichs generieren möchten, sehen Sie, wie Apidog die Generierung von API-Testsammlungen aus OpenAPI-Spezifikationen handhabt.

Häufig gestellte Fragen

Ist Specmatic kostenlos?

Ja. Die Kern-Vertrags-Engine ist Open Source und kann kostenlos über die CLI oder Docker verwendet werden. Es gibt kommerzielle Angebote drumherum, aber Sie können Vertragstests und Stub-Server aus OpenAPI-Spezifikationen kostenlos ausführen. Überprüfen Sie die offizielle Website und GitHub für aktuelle Details zu den kostenpflichtigen Stufen.

Funktioniert Specmatic nur mit OpenAPI?

Nein. OpenAPI ist der gängigste Einstiegspunkt, aber Specmatic unterstützt auch AsyncAPI für ereignisgesteuerte Verträge, sowie GraphQL und gRPC seit Version 2.0, zusammen mit Formaten wie WSDL und Avro. Das Modell ist bei allen dasselbe: Die Spezifikation ist der ausführbare Vertrag. Wenn Sie neu in dem Format sind, beginnen Sie mit diesem OpenAPI-Spezifikations-Tutorial.

Ist Specmatic dasselbe wie Pact?

Nicht ganz. Pact ist konsumentengesteuert: Konsumenten veröffentlichen Erwartungen an einen Broker, und Anbieter überprüfen diese. Specmatic ist vertragsgesteuert: Die Spezifikation ist der einzige gemeinsame Vertrag, und Specmatic validiert den Anbieter dagegen, während es den Anbieter für Konsumenten stummiert. Beide reduzieren Integrationsüberraschungen, aber sie organisieren den Vertrag unterschiedlich.

Kann Specmatic eine OpenAPI-Spezifikation für mich generieren?

Ja. Specmatic kann als Proxy vor einem bestehenden Dienst ausgeführt werden, echten Anfrage- und Antwortverkehr erfassen und daraus ein OpenAPI-Dokument sowie Beispieldateien generieren. Das ist nützlich, wenn Sie einen funktionierenden Dienst haben, aber noch keine formale Spezifikation zum Testen.

Fazit

Specmatic löst ein spezifisches, reales Problem: Einen laufenden Dienst ehrlich gegenüber der OpenAPI-Spezifikation zu halten, der er folgen soll. Indem es die Spezifikation ausführbar macht, erhalten Sie Vertragstests und einen passenden Stub aus einer Datei, mit zusätzlichen Abwärtskompatibilitätsprüfungen. Wenn Sie im Terminal und in der CI leben und eine solide Spezifikation pflegen, passt es perfekt.

Wenn Sie lieber den Vertrag, die Tests, den Mock und die Dokumentation in einem visuellen Arbeitsbereich haben möchten, der dieselbe OpenAPI-Datei liest, probieren Sie Apidog aus. Es validiert Antworten gegen Ihr Schema, mickt Endpunkte ohne Code und wandelt Spezifikationen in ausführbare Testsammlungen um. Laden Sie Apidog herunter, um es auf Ihre Spezifikation zu richten und den gesamten Design-zu-Test-Loop an einem Ort zu sehen.