Die meisten API-Tests beginnen ihr Leben in einer GUI. Man klickt sich durch, fügt ein paar Assertions hinzu und führt sie manuell aus. Das funktioniert so lange, bis dieselben Tests bei jedem Push, jede Nacht oder in einer Pipeline, wo niemand zuschaut, ausgeführt werden müssen. An diesem Punkt möchte man einen Befehl haben, den man eingeben, skripten und in die CI einbinden kann.
Dieser Befehl ist die Apidog CLI. Dieses Tutorial führt Sie durch das End-to-End-Testen einer echten REST-API von Ihrem Terminal aus: Installieren Sie das Tool, importieren Sie eine API, richten Sie eine Umgebung ein, erstellen Sie ein Testszenario, führen Sie es mit Assertions aus, speisen Sie Daten ein und sammeln Sie Berichte. Jeder Befehl und jede Ausgabe unten stammt von einem echten Lauf der Apidog CLI Version 2.2.2 gegen eine Live-Public-API, sodass Sie mitmachen und die gleichen Ergebnisse erzielen können.
Wenn Sie die visuelle Seite derselben Plattform nutzen möchten, können Sie Apidog herunterladen und die Tests zuerst in der App entwerfen. Aber alles hier bleibt auf der Kommandozeile.
Was Sie erstellen werden
Sie testen restful-api.dev, eine kostenlose öffentliche REST-API mit echtem CRUD über eine /objects-Ressource. Am Ende werden Sie Folgendes haben:
- Ein Apidog-Projekt, das aus einer OpenAPI-Datei erstellt wurde
- Ein dreistufiges Testszenario, das ein Objekt erstellt, es zurückliest und löscht, wobei jeder Schritt bestätigt wird
- Ein datengesteuerter Lauf, der eine Anfrage einmal pro Zeile Testdaten wiederholt
- CLI-, HTML-, JSON- und JUnit-Berichte sowie einen teilbaren Cloud-Bericht
Derselbe Ablauf lässt sich auf Ihre eigene API skalieren und ist die Grundlage für das Ausführen von API-Tests in CI/CD.
Bevor Sie beginnen
Sie benötigen Node.js 16 oder neuer und ein Apidog-Konto. Wenn Sie zuerst Runner vergleichen, ist die Kurzversion, dass die Apidog CLI vollständige Testszenarien ausführt und API-Ressourcen als Code verwaltet, was sie von Newman und der Postman CLI unterscheidet.
Schritt 1: Installieren und anmelden
Installieren Sie die CLI global von npm:
npm install -g apidog-cli@latest
Bestätigen Sie die Installation:
apidog --version
# 2.2.2
Authentifizieren Sie sich jetzt. Holen Sie sich ein Token aus der Apidog-App unter Ihrem Avatar, Kontoeinstellungen, API-Zugriffstoken und führen Sie dann aus:
apidog login --with-token <YOUR_TOKEN>
Das Token wird in ~/.apidog/config.toml gespeichert, sodass Sie dies nur einmal pro Maschine tun müssen. Überprüfen Sie, wer Sie sind:
Jeder Befehl gibt strukturiertes JSON mit einem success-Flag und hilfreichen agentHints zurück, was die Ausgabe leicht skriptfähig oder in jq umleitbar macht.
Schritt 2: Ein Projekt erstellen
Wählen Sie das Team aus, unter dem Sie das Projekt erstellen möchten, und erstellen Sie es dann:
apidog team list
apidog project create --team 329562 --name "CLI Field Test"
Sie erhalten die neue Projekt-ID zurück.
Speichern Sie sie in einer Shell-Variable, damit der Rest dieses Tutorials per Copy-Paste übernommen werden kann:
PID=1314366 # replace with your project id
apidog project get $PID
Schritt 3: Ihre REST-API importieren
Sie könnten Endpunkte manuell erstellen, aber das Importieren einer OpenAPI-Datei ist schneller und spiegelt wider, wie echte Projekte beginnen. Hier ist eine kleine Spezifikation, die die /objects CRUD-Endpunkte beschreibt (speichern Sie sie als objects-api.openapi.json):
{
"openapi": "3.0.3",
"info": { "title": "Objects API", "version": "1.0.0" },
"servers": [{ "url": "https://api.restful-api.dev" }],
"paths": {
"/objects": {
"get": { "summary": "List objects" },
"post": { "summary": "Create object" }
},
"/objects/{id}": {
"get": { "summary": "Get object by id" },
"put": { "summary": "Update object" },
"delete": { "summary": "Delete object" }
}
}
}
Importieren Sie sie:
apidog import --project $PID --format openapi --file ./objects-api.openapi.json
# "createCount": 5 (5 endpoints created, 0 errors)
Der Importer liest auch openapi, postman, har, insomnia, jmeter und mehr. Listen Sie auf, was geladen wurde:
apidog endpoint list --project $PID
# 37921721 get /objects
# 37921722 post /objects
# 37921723 get /objects/{id}
# 37921724 put /objects/{id}
# 37921725 delete /objects/{id}
Schritt 4: Eine Umgebung einrichten
Eine Umgebung enthält die Basis-URL und alle Variablen, die Ihre Tests wiederverwenden. Erstellen Sie eine und speichern Sie deren ID:
apidog environment create "Production" --project $PID --base-url "https://api.restful-api.dev"
apidog environment list --project $PID
# { "id": 6334917, "name": "Production", "baseUrls": { "default": "https://api.restful-api.dev" } }
ENV=6334917 # replace with your environment id
Sie werden später -e $ENV an den Run-Befehl übergeben, damit der Test weiß, wohin Anfragen gesendet werden sollen.
Schritt 5: Die Automatisierungs-Schreibsperre überwinden
Hier ist das erste, was Leute stolpern lässt. Testszenarien und Testdaten sind Automatisierungsressourcen, und das Schreiben dieser in Ihren Hauptzweig von einem externen Tool ist standardmäßig blockiert:
apidog test-scenario create --project $PID --name "x" --description "" --folder-id 0 --priority 1
# "error": { "code": "403075", "message": "Automation caller branch required" }
Dies ist eine Leitplanke, kein Fehler. Sie haben zwei Wege, dies zu umgehen:
- Aktivieren Sie die direkte Bearbeitungsberechtigung in der Apidog-Desktop-App unter Projekteinstellungen, Funktionsseinstellungen, AI-Funktionseinstellungen, Externe AI-Bearbeitungsberechtigungen.
- Arbeiten Sie an einem AI-Zweig, der Automatisierungsänderungen isoliert hält, bis Sie sich zum Mergen entscheiden. Dieser Pfad bleibt vollständig auf der Kommandozeile, also werden wir diesen verwenden.
Erstellen Sie den Zweig von main:
apidog branch create --project $PID --type ai \
--name "ai/20260616-from-main-cli-field-test" --from main
BR="ai/20260616-from-main-cli-field-test"
Das Namensmuster ai/JJJJMMTT-von-<Quelle>-<Funktion> ist die Konvention, die die CLI erwartet. Beachten Sie, dass import, environment create und Endpunktbearbeitungen nicht gesperrt sind; nur die Automatisierungsressourcen sind betroffen.
Schritt 6: Ein Testszenario erstellen
Ein Szenario ist ein geordneter Ablauf von Anfragen mit Assertions dazwischen. Sie erstellen zuerst die Hülle und fügen dann Schritte hinzu. Erstellen Sie es auf Ihrem AI-Zweig:
apidog test-scenario create --project $PID --branch "$BR" \
--name "Object CRUD lifecycle" \
--description "Create, read, then delete an object and assert each step" \
--folder-id 0 --priority 1
SID=1836498 # the returned scenario id
Schritte werden über update mit einer JSON-Datei hinzugefügt. Die goldene Regel bei jeder JSON-Schreiboperation ist, vor dem Senden zu validieren, damit Sie niemals eine fehlerhafte Nutzlast übertragen:
apidog cli-schema get test-scenario-update # see the exact shape
apidog cli-schema validate test-scenario-update --file ./steps-crud.json
# "data file is valid"
Jeder Schritt ist eine Anfrage plus ein kleines Skript, das die Antwort bestätigt und Daten an den nächsten Schritt übergibt. Hier ist die Struktur des Erstellungsschritts, der ein neues Objekt postet und dessen id für spätere Schritte speichert:
{
"type": "customHttp",
"name": "Create object",
"customHttpRequest": {
"path": "https://api.restful-api.dev/objects",
"method": "post",
"requestBody": { "type": "json", "data": "{\"name\":\"Apidog CLI Field Test\",\"data\":{\"price\":42}}" },
"postProcessors": [{
"type": "customScript",
"data": "pm.test('create returns 200', function () { pm.response.to.have.status(200); });\nvar body = pm.response.json();\npm.globals.set('objId', body.id);",
"enable": true
}],
"projectId": 1314366
}
}
Die nächsten Schritte verwenden {{objId}} in der URL, um dasselbe Objekt abzurufen und dann zu löschen. Wenden Sie die vollständige dreistufige Datei an:
apidog test-scenario update $SID --project $PID --branch "$BR" --file ./steps-crud.json
# "success": true
Sie müssen Szenarien nicht als JSON erstellen. Sie visuell in Apidog zu erstellen und von der CLI aus auszuführen, ist genauso gültig. Der JSON-Pfad ist wichtig, wenn Sie Ihre Tests wie jeden anderen Code versionskontrollieren und überprüfen möchten.
Schritt 7: Ausführen über die Kommandozeile
Das ist die Belohnung. Führen Sie das Szenario mit dem CLI-Reporter aus:
apidog run -t $SID --project $PID --branch "$BR" -e $ENV -r cli
❏ Object CRUD lifecycle
↳ Create object POST .../objects [200 OK]
✓ create returns 200 ✓ response has an id ✓ name was echoed back
↳ Get the created object GET .../objects/ff80...3de [200 OK]
✓ get returns 200 ✓ id matches the created object ✓ price persisted in data
↳ Delete the object DELETE .../objects/ff80...3de [200 OK]
✓ delete returns 200
Http Requests 3 / 0 failed
Assertions 7 / 0 failed
Drei Anfragen, sieben Assertions, null Fehler, und die erstellte id floss vom ersten Schritt in die nächsten beiden. Das ist ein vollständiger API-Test, der ohne einen einzigen Klick ausgeführt wird.
Möchten Sie Dateien statt Konsolenausgabe? Fordern Sie mehrere Reporter gleichzeitig an und verweisen Sie sie auf einen Ordner:
apidog run -t $SID --project $PID --branch "$BR" -e $ENV \
-r cli,html,json,junit --out-dir ./reports --out-file "crud-report"
ls ./reports
# crud-report.html crud-report.json crud-report.xml
Die JUnit-XML-Datei ist das, was Ihr CI-Server liest, um Pass/Fail pro Build anzuzeigen. Der HTML-Bericht ist der, den Sie mit Teamkollegen teilen.
Schritt 8: Denselben Test mit vielen Eingaben ausführen
Echte Testsuiten decken mehr als einen Fall ab. Datengesteuerte Läufe wiederholen ein Szenario einmal pro Datenzeile, sodass Sie zehn Eingaben testen, ohne zehn Szenarien zu schreiben. Dies ist die gleiche Idee wie parametrisierte Tests aus CSV und JSON.
Legen Sie Ihre Zeilen in einer Datei ab:
[
{ "name": "Pixel 8 Pro", "price": 999 },
{ "name": "iPhone 15", "price": 899 },
{ "name": "Galaxy S24", "price": 799 }
]
Referenzieren Sie die Daten mit -d, und lassen Sie das Szenario {{name}} und {{price}} aus jeder Zeile lesen:
apidog run -t $DID --project $PID --branch "$BR" -e $ENV -d ./objects-data.json -r cli
Iteration 1/3 … ✓ row created (200) ✓ name matches the data row
Iteration 2/3 … ✓ row created (200) ✓ name matches the data row
Iteration 3/3 … ✓ row created (200) ✓ name matches the data row
Iterations 3 / 0 failed Assertions 6 / 0 failed
Drei Zeilen hinein, drei Iterationen heraus. Tauschen Sie die Datei gegen eine CSV-Datei aus und nichts ändert sich.
Schritt 9: Berichte sammeln
Lokale Läufe schreiben Dateien. Um einen Bericht zu erhalten, den Ihr gesamtes Team im Browser öffnen kann, fügen Sie --upload-report hinzu:
apidog run -t $SID --project $PID --branch "$BR" -e $ENV -r cli --upload-report
# Apidog CLI runs data uploaded to the cloud successfully.
# https://app.apidog.com/link/project/1314366/api-test/test-report/2605398
Eine wichtige Besonderheit: Ein Cloud-Bericht wird mit dem Zweig markiert, auf dem er ausgeführt wurde. Da dieser Lauf auf Ihrem AI-Zweig stattfand, wird ein einfaches apidog test-report list --project $PID (das auf main abzielt) ihn nicht anzeigen. Rufen Sie ihn stattdessen über die ID aus dem Upload-Link ab:
apidog test-report get 2605398 --project $PID
apidog test-report download 2605398 --project $PID --format json --output ./cloud-report.json
Schritt 10: Ihre API als Dokumentation oder Spezifikation exportieren
Die CLI gibt auch Daten aus. Exportieren Sie das Projekt als OpenAPI-Datei, Markdown oder HTML-Dokumentation:
apidog export --project $PID --format openapi --oas-version 3.0 --output ./openapi-export.json
apidog export --project $PID --format markdown --output ./api-docs.md
apidog export --project $PID --format html --output ./api-docs.html
Dies ist praktisch, um bei jeder Änderung eine neue Spezifikation zu committen oder statische Dokumente aus einer Pipeline zu veröffentlichen.
Schritt 11: In CI/CD integrieren
Alles, was Sie manuell ausgeführt haben, wird zu drei Zeilen in einer Pipeline. Der Kern ist die Installation, dann die Ausführung mit dem JUnit-Reporter, damit der CI-Server die Ergebnisse lesen kann:
- run: npm install -g apidog-cli@latest
- run: apidog login --with-token $APIDOG_TOKEN
- run: apidog run -t $SID --project $PID -e $ENV -r junit --out-dir ./reports
Speichern Sie das Token als Geheimnis und lassen Sie den Build fehlschlagen, wenn ein Test fehlschlägt (die CLI gibt bei Fehlern einen Exit-Code ungleich Null zurück). Für einen vollständigen Copy-Paste-Workflow siehe die Anleitung zum Ausführen von Apidog CLI-Tests in GitHub Actions oder durchsuchen Sie API-Testautomatisierungstools, die in eine Pipeline passen.
Zusammenfassung
Sie haben von einem leeren Terminal aus einen erfolgreichen, datengesteuerten API-Test mit teilbaren Berichten durchgeführt und dabei nie die Kommandozeile verlassen. Das Muster ist immer dasselbe: Importieren oder entwerfen Sie Ihre API, erstellen Sie eine Umgebung, bauen Sie ein Szenario mit Assertions und führen Sie es dann mit apidog run aus. Sobald dieser Befehl lokal funktioniert, ist das Einfügen in CI eine Änderung von drei Zeilen.
Richten Sie dieselben Schritte auf Ihre eigene API aus, committen Sie die Szenariodateien zusammen mit Ihrem Code, und Ihre Tests laufen überall dort, wo eine Shell vorhanden ist. Laden Sie Apidog herunter, um loszulegen, und halten Sie die curl-Alternativen für REST-API-Tests griffbereit für schnelle Einzelprüfungen, für die die CLI überdimensioniert wäre.