Sie möchten API-Tests, die sich wie einfaches Englisch lesen, in Git neben Ihrem Code leben und in jeder CI-Pipeline ausgeführt werden. Karate wurde genau dafür entwickelt. Es verwendet eine domänenspezifische Sprache (DSL), sodass Sie Tests als Given / When / Then-Schritte anstelle von Java-Methoden schreiben. Dieser Leitfaden erläutert, was Karate ist, wie seine Feature-Dateien funktionieren und enthält ein ausführbares Beispiel.
Was Karate ist
Karate ist ein Open-Source-, Java-basiertes Testautomatisierungs-Framework für APIs. Sie beschreiben jeden Test als Szenario in einer .feature-Datei mit Gherkin, der gleichen Given/When/Then-Struktur, die aus dem Behavior-Driven Development stammt. Der Unterschied zu Tools wie Cucumber besteht darin, dass Sie keinen Step-Definition-Glue-Code schreiben. Karate liefert die HTTP-Schritte, Assertions und JSON-Verarbeitung integriert, sodass ein funktionierender API-Test überhaupt kein Java benötigt.
Das Projekt bündelt mehr als nur API-Tests. Das Repository umfasst Module für Mocks, Performance-Tests (über Gatling) und UI-Automatisierung. Für diesen Leitfaden liegt der Fokus auf dem API-Testkern, den die meisten Teams zuerst nutzen.
Da Tests einfache Textdateien sind, lassen sie sich gut versionieren. Ein Pull-Request-Diff zeigt genau, welche Assertion sich geändert hat. Das passt gut zu Code Reviews und einem Git-nativen, codebasierten Workflow.
Wenn Sie neu im Given/When/Then-Stil sind, erklärt unser Leitfaden zum Behavior-Driven Development, woher er kommt und warum Teams ihn verwenden.
So funktioniert's: Feature-Dateien und karate-config.js
Ein Karate-Test beginnt mit einer Feature-Datei. Jede Datei hat einen Feature:-Block und einen oder mehrere Scenario:-Blöcke. Innerhalb eines Szenarios richten Sie die Anfrage mit Given ein, senden sie mit When und überprüfen sie mit Then.
Hier ist die Struktur, die Karates eigener Quick Start zeigt:
Feature: User API
Scenario: List all users
Given url 'https://jsonplaceholder.typicode.com'
And path 'users'
When method get
Then status 200
And match response == '#[10]'
Lesen Sie es von oben nach unten. url legt die Basisadresse fest. path hängt die Ressource an. method get sendet die Anfrage. status 200 überprüft den HTTP-Code. Die letzte Zeile bestätigt, dass die Antwort ein JSON-Array mit genau 10 Elementen ist. Das #[10] ist ein Karate-Marker, kein JavaScript. Mehr zu diesen Markern im Abschnitt über Assertions.
Das Gherkin hier ist standardmäßiges Given/When/Then. Wenn Sie einen tieferen Einblick in diese Syntax wünschen, lesen Sie unseren Leitfaden zu Gherkin für BDD- und API-Tests.
Die meisten Projekte benötigen umgebungsspezifische Werte: eine Entwicklungs-Basis-URL, ein Staging-Token, einen Produktions-Endpunkt. Karate handhabt dies mit einer einzigen Datei namens karate-config.js. Diese wird einmal vor Ihren Tests ausgeführt und gibt ein Konfigurationsobjekt zurück, das jedes Szenario lesen kann.
function fn() {
var env = karate.env || 'dev';
var config = {
baseUrl: 'https://jsonplaceholder.typicode.com'
};
if (env === 'qa') {
config.baseUrl = 'https://qa.example.com';
}
return config;
}
karate.env stammt von einer System-Property, die Sie zur Laufzeit übergeben. Wechseln Sie Umgebungen, ohne eine einzige Feature-Datei zu berühren. In einem Szenario würden Sie dann Given url baseUrl schreiben, anstatt die Adresse fest zu codieren.
Ein Beispielszenario
Schreiben wir etwas mit einem Request Body. Dieses Szenario erstellt einen Benutzer, überprüft den Status und validiert die Form der Antwort.
Feature: Create user
Background:
* url baseUrl
Scenario: Create a new user returns 201
Given path 'users'
And request { name: 'Ada', job: 'engineer' }
When method post
Then status 201
And match response.name == 'Ada'
And match response.id == '#string'
Ein paar Dinge, die auffallen. Der Background:-Block wird vor jedem Szenario in der Datei ausgeführt, sodass Sie die Basis-URL einmal festlegen. Das * ist ein Wildcard-Schritt; Karate behandelt * genauso wie Given, When oder Then, was Ihnen erlaubt, Setup-Schritte ohne grammatikalische Bedenken zu schreiben. Das Schlüsselwort request nimmt eine JSON-Payload direkt entgegen. Kein Serializer, kein POJO. Und #string ist ein Fuzzy-Matcher, der bestätigt, dass das Feld id existiert und ein String ist, ohne es an einen bestimmten Wert zu binden.
Assertions und JSON-Matching
Assertions sind das, womit Karate glänzt. Das Kernschlüsselwort ist match. Es vergleicht einen tatsächlichen Wert mit einem erwarteten Wert und lässt den Test bei jeder Abweichung fehlschlagen.
Genaue Übereinstimmung prüft die Gleichheit:
And match response == { id: '#number', name: 'Ada', job: 'engineer' }
Die Tokens #number, #string, #boolean und #uuid sind Fuzzy-Matcher. Sie bestätigen Typ und Vorhandensein, ohne einen literalischen Wert zu verlangen, was Tests stabil hält, wenn der Server generierte IDs oder Zeitstempel zurückgibt.
Wenn Sie sich nur um eine Untermenge von Feldern kümmern, verwenden Sie contains:
And match response contains { name: 'Ada' }
Das ist erfolgreich, solange name gleich Ada ist, selbst wenn die Antwort zehn andere Felder hat. Karate unterstützt auch !contains, contains only, contains any und contains deep für eine feinere Kontrolle über partielles Matching.
Sie können auch Arrays validieren. match response == '#[10]' bestätigt ein Array der Länge 10. Sie können ein Schema auf jedes Element mit each anwenden:
And match each response == { id: '#number', name: '#string' }
Diese einzige Zeile überprüft, ob jedes Objekt im Array eine numerische id und einen String-name hat. Eine solche Formvalidierung würde in einem Allzweck-Testframework eine Schleife und mehrere Assertions erfordern. Wenn Sie ein umfassenderes Bild der Validierung von Antworten wünschen, behandelt unser praktischer Leitfaden zu API-Assertions die Muster über verschiedene Tools hinweg.
Datengesteuertes Testen und CI
Echte Testsuiten führen dieselbe Logik mit vielen Eingaben aus. Karate handhabt dies mit Scenario Outline und einer Examples-Tabelle. Platzhalter in spitzen Klammern werden aus jeder Zeile gefüllt.
Scenario Outline: Create users from a table
Given url baseUrl
And path 'users'
And request { name: '<name>', job: '<job>' }
When method post
Then status 201
And match response.name == '<name>'
Examples:
| name | job |
| Ada | engineer |
| Grace | scientist |
| Alan | analyst |
Das führt das Szenario dreimal aus, einmal pro Zeile. Sie können Zeilen auch aus einer externen Datei anstelle einer Inline-Tabelle lesen, wodurch große Datensätze aus Ihren Feature-Dateien ferngehalten werden:
Examples:
| read('classpath:test-data/users.json') |
Karate liest JSON- und CSV-Dateien auf diese Weise, sodass Ihre Testdaten dort gespeichert werden können, wo Ihr Team sie am liebsten verwaltet.
Für die kontinuierliche Integration gibt es zwei Wege. In einem Maven- oder Gradle-Projekt läuft Karate über JUnit 5. Sie fügen die Abhängigkeit karate-junit5 hinzu und verweisen einen Runner auf Ihre Feature-Dateien, sodass mvn test diese wie jeden anderen Unit-Test ausführt. Das bedeutet, dass Ihr vorhandener CI-Schritt keine speziellen Tools benötigt.
Der zweite Weg ist die eigenständige Jar-Datei, die kein Build-Tool benötigt. Laden Sie karate.jar aus den Releases des Projekts herunter und führen Sie Feature-Dateien direkt aus. Beachten Sie, dass die Jar-Datei eine aktuelle Java-Version erfordert, prüfen Sie daher die Release Notes auf das Minimum.
java -jar karate.jar src/test/java/features
Sie können nach Tags filtern, parallel ausführen und ein Ausgabeverzeichnis wählen:
java -jar karate.jar --tags @smoke --threads 4 --output reports src/test/java/features
Übergeben Sie eine Umgebung mit einer System-Property, die in karate.env innerhalb von karate-config.js einfließt:
java -jar karate.jar -Dkarate.env=qa src/test/java/features
Karate schreibt nach jedem Lauf einen HTML-Bericht in das Ausgabeverzeichnis, sodass Fehler in einem Pipeline-Artefakt leicht zu überprüfen sind. Für ein umfassenderes CI-Bild erfahren Sie, wie Sie API-Tests in CI/CD automatisieren können.
Stärken und Kompromisse
Karate hat klare Stärken. Tests lesen sich fast wie einfaches Englisch, was die Einstiegshürde für Personen senkt, die Java nicht fließend beherrschen. Das integrierte JSON-Matching, einschließlich Fuzzy-Matcher und each, eliminiert viel Assertion-Boilerplate. Alles befindet sich in Textdateien unter Git, sodass Tests wie Quellcode überprüft und verglichen werden können. Und es deckt mehr als nur HTTP ab, sodass ein Team später Mocks oder Performance-Tests hinzufügen kann, ohne die Tools wechseln zu müssen.
Die Kompromisse sind ebenfalls real. Karate läuft auf der JVM, daher benötigen Sie Java und ein gewisses Vertrautheit mit dem JVM-Ökosystem für alles, was über die Grundlagen hinausgeht. Die DSL ist etwas Eigenes, das man lernen muss; die Syntax liest sich leicht, aber das Schreiben korrekter Matcher und Wiederverwendungsmuster erfordert Übung. Wiederverwendbare Logik, benutzerdefinierte Helfer und komplexe Setups ziehen Sie oft zurück zu JavaScript-Funktionen oder Java-Interoperabilität. Und da Tests Code sind, können Nicht-Entwickler im Team sie normalerweise nicht ohne Hilfe erstellen oder bearbeiten.
Nichts davon ist ein Manko. Es ist das Profil eines Code-First-Frameworks. Die Frage ist, ob dieses Profil zu der Arbeitsweise Ihres Teams passt.
Karate vs. ein Code-freier Ansatz (Apidog)
Karate ist codebasiert und Git-nativ. Sie schreiben Feature-Dateien, committen sie und führen sie mit einem Build-Tool oder der Jar-Datei aus. Das passt Ingenieuren, die Tests in der Versionskontrolle neben der Anwendung haben möchten und mit der JVM vertraut sind.
Apidog verfolgt einen visuellen, codefreien Ansatz für dasselbe Ziel. Sie erstellen Testszenarien in einer Benutzeroberfläche, verketten Anfragen und fügen Assertions durch Klicken statt durch Schreiben von DSL hinzu. Da der gesamte API-Lebenszyklus (Design, Debugging, Mocking, Dokumentation) an einem Ort gebündelt ist, können die Tests die bereits definierten Endpunkte und Schemata wiederverwenden. Das senkt die Einstiegshürde für QA-Ingenieure und Produktverantwortliche, die kein Java-Projekt verwalten möchten.
Die visuellen Suiten sind nicht in der Benutzeroberfläche gefangen. Apidog führt sie headless in CI über die Apidog CLI aus, sodass eine codefreie Suite immer noch in eine automatisierte Pipeline passt. Sie installieren sie mit Node:
npm install -g apidog-cli
Anschließend lösen Sie ein gespeichertes Szenario oder eine Suite per ID aus, verweisen auf eine Umgebung und wählen Berichtsformate:
apidog run --access-token "$APIDOG_ACCESS_TOKEN" -t <scenarioOrSuiteId> -e <environmentId> -r cli,html,junit
Das Flag -t zielt auf ein Szenario, einen Ordner oder eine Suite ab; -e wählt die Umgebung; -r wählt einen oder mehrere Reporter (cli, html, json, junit). Für datengesteuerte Läufe nimmt -d (oder --iteration-data) einen Datenpfad oder eine Testdaten-ID entgegen. Die CLI ist headless und läuft auf jedem CI-Schritt, der Node ausführen kann. Sie führt Ihre gespeicherten Apidog-Szenarien aus; sie ist kein interaktiver Request-Sender oder Lastgenerator. Eine vollständige Anleitung finden Sie unter Apidog CLI für CI/CD und einen Vergleich mit einem anderen Runner unter Apidog CLI vs. Newman.
Beide Ansätze erzeugen automatisierte API-Tests, die headless in CI ausgeführt werden. Der Unterschied liegt im Erstellungsstil: Karate möchte, dass Sie DSL in Git schreiben; Apidog möchte, dass Sie in einer Benutzeroberfläche klicken, die auch in die Pipeline exportiert wird.
Wie man wählt
Wählen Sie Karate, wenn Ihr Team entwicklerlastig ist, mit der JVM vertraut ist und Tests als Code direkt neben der Anwendung versionieren möchte. Die Klartext-Feature-Dateien und das integrierte JSON-Matching zahlen sich aus, wenn Ingenieure die Testsuite von Anfang bis Ende verantworten.
Wählen Sie ein codefreies Tool wie Apidog, wenn Autoren QA- und Produktmitarbeiter umfassen, wenn Sie Tests an einen bestehenden Design- und Dokumentations-Workflow binden möchten oder wenn Sie lieber keinen Java-Build pflegen möchten, um API-Prüfungen auszuführen. Sie erhalten dennoch CI-Abdeckung über die CLI.
Einige Teams nutzen beides: Karate für tiefgehende, codebasierte Regressionstests und ein visuelles Tool für eine breite, schnelle Abdeckung, die von Nicht-Entwicklern erweitert werden kann. Wenn Sie noch Optionen abwägen, legt unser Überblick zur Wahl eines API-Automatisierungs-Testframeworks die Entscheidungskriterien dar.
FAQ
Muss ich Java können, um Karate zu verwenden? Nein, nicht für das Schreiben grundlegender API-Tests. Feature-Dateien verwenden die Gherkin-DSL, und Karate liefert die HTTP- und Assertions-Schritte integriert. Sie benötigen Java, um die Tests auszuführen, und etwas Java- oder JavaScript-Kenntnisse helfen, sobald Sie benutzerdefinierte Helfer oder komplexe Wiederverwendung benötigen.
Wie unterscheidet sich Karate von Cucumber? Beide verwenden die Given/When/Then-Syntax von Gherkin. Mit Cucumber schreiben Sie Step-Definition-Code, um jeden Schritt zu unterstützen. Karate stellt die API-Testschritte für Sie bereit, sodass für Standard-HTTP-Tests kein Glue-Code gepflegt werden muss.
Kann Karate ohne Maven oder Gradle laufen? Ja. Laden Sie die eigenständige karate.jar aus den Releases des Projekts herunter und führen Sie Feature-Dateien mit java -jar karate.jar <path> aus. Es unterstützt Tags, parallele Threads und ein benutzerdefiniertes Ausgabeverzeichnis ohne ein Build-Tool.
Was bedeuten die Syntax #string oder #[10]? Das sind Karates Fuzzy-Matcher. #string bestätigt, dass ein Feld ein String beliebigen Werts ist, #number eine Zahl und #[10] bestätigt ein JSON-Array der Länge 10. Sie ermöglichen es Ihnen, die Form der Antwort zu validieren, ohne generierte Werte fest zu codieren.
Können codefreie API-Tests immer noch in CI laufen? Ja. Ein visuelles Tool wie Apidog exportiert gespeicherte Szenarien an die Apidog CLI, die headless ist und auf jedem CI-Schritt mit Node läuft. So erstellen Sie Tests in einer Benutzeroberfläche und erhalten dennoch automatisierte Pipeline-Läufe.