API Tests in CI mit apidog run ausführen

Sie haben einen Befehl aus einem CI/CD-Tab kopiert, in eine Pipeline eingefügt, und er hat funktioniert. Dann fragt ein Teamkollege, warum der Build immer noch grün ist, obwohl ein Test eindeutig fehlgeschlagen ist, oder ob Sie denselben Lauf statt auf die Produktion auf Staging verweisen können, oder wie Sie einen Bericht erhalten, den Ihr CI-Dashboard tatsächlich parsen kann. Plötzlich reicht der Einzeiler nicht mehr aus. Sie müssen wissen, was jeder Teil davon bewirkt.

apidog run ist der einzelne Befehl im Herzen des Apidog-Kommandozeilen-Runners. Er führt die in Apidog erstellten API-Testszenarien headless, von einem Terminal aus, ohne GUI und ohne dass ein Mensch einen Button anklickt, aus. Alles, was der Runner tun kann, geschieht über Flags bei diesem einen Befehl: welches Szenario ausgeführt werden soll, welche Umgebung angesprochen werden soll, wie oft eine Schleife durchlaufen werden soll, welche Berichte ausgegeben werden sollen und was als Fehler zählt. Lernen Sie die Flag-Oberfläche einmal kennen, und Sie hören auf, blind zu kopieren und einzufügen.

Was apidog run ist

Die Apidog CLI wird als npm-Paket namens apidog-cli ausgeliefert. Sie installieren es einmal und erhalten eine einzelne ausführbare Datei, apidog, deren primärer Unterbefehl run ist. Dieser Unterbefehl nimmt eines Ihrer Apidog-Testszenarien und führt es so aus, wie es die Desktop-App tun würde, meldet dann einen Exit-Code und alle von Ihnen angeforderten Berichtsdateien zurück.

Global installieren:

npm install -g apidog-cli

Bestätigen Sie die Auflösung:

apidog -v

Bevor wir uns den Flags widmen, ist es wichtig zu verstehen, worauf apidog run operiert. Es definiert kein eigenes Testformat. Der Test ist das Szenario, das Sie in der Apidog-App erstellt haben: verkettete Anfragen, Assertions, Werte, die aus einer Antwort in die nächste übernommen werden, optionale datengesteuerte Iteration. Die CLI greift in Ihr Projekt ein, findet das Szenario anhand der ID und führt es aus. Die meisten Flags dienen also dazu, dem Runner mitzuteilen, was abgerufen werden soll und wie er sich während der Ausführung verhalten soll, und nicht dazu, Tests direkt zu schreiben.

Ein minimaler echter Befehl sieht so aus:

apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e 1629989 -n 1 -r html,cli

Das bedeutet: Authentifizieren Sie sich mit diesem Token, führen Sie das Testszenario 605067 einmal gegen die Umgebung 1629989 aus und erstellen Sie einen HTML-Bericht sowie eine lesbare Terminalausgabe. Jedes Flag in dieser Zeile wird unten erklärt, zusammen mit denen, die der Befehl weglässt.

Die gesamte Optionsfläche auf einen Blick

Hier ist die vollständige Liste der Optionen, gruppiert nach Aufgabe. Verwenden Sie sie als Nachschlagetabelle; die nachfolgenden Abschnitte erklären diejenigen, die mehr als einen Satz benötigen.

Flag-Namen und Standardwerte können sich zwischen CLI-Versionen ändern. Im Zweifelsfall ist der Runner seine eigene Quelle der Wahrheit: Führen Sie apidog run --help mit der von Ihnen installierten Version aus und vertrauen Sie dieser über jedem Artikel, einschließlich diesem.

Auswählen, was ausgeführt werden soll

Drei Flags bestimmen den Umfang eines Laufs, und Sie wählen genau eines davon pro Befehl.

-t, --test-scenario <id> führt ein einzelnes Szenario aus. Dies ist der alltägliche Fall: ein fokussierter Smoke-Test, ein Regressionsszenario, eine Sache, die Sie bei einem Pull Request absichern möchten.

-f, --test-scenario-folder <id> führt jedes Szenario in einem Ordner aus. Greifen Sie hierzu, wenn Sie einen Funktionsbereich in einem Ordner organisiert haben und die gesamte Gruppe als einen Job ausführen möchten, z. B. einen nächtlichen Regressionstestlauf.

--test-suite <id> führt eine kuratierte Testsuite aus, die eine Reihe von Szenarien ist, die Sie zusammengestellt haben, um sie als eine logische Einheit auszuführen. Eine Suite ist das richtige Werkzeug, wenn die gewünschten Szenarien nicht alle in einem Ordner sind, aber dennoch zum selben Testdurchlauf gehören.

Zwei weitere Selektoren verfeinern, wo der Runner sucht. --project <id> benennt das Projekt, in dem ein Szenario lebt, nützlich, wenn Ihr Token Zugriff auf mehr als eines hat. --branch <name> führt das Szenario so aus, wie es auf einem bestimmten Branch existiert, anstatt auf main, wodurch Sie Teständerungen auf einem Feature-Branch vor dem Mergen validieren können.

# ein Szenario
apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e 1629989 -r cli

# ein ganzer Ordner
apidog run --access-token $APIDOG_ACCESS_TOKEN -f 88012 -r html,junit

# eine kuratierte Suite
apidog run --access-token $APIDOG_ACCESS_TOKEN --test-suite 40231 -r junit

Authentifizierung des Laufs

--access-token <token> ist das einzige Flag, das jeder Online-Lauf benötigt. Es beweist, dass der Lauf Ihr Szenario abrufen und ausführen darf. Sie generieren das Token im CI/CD-Tab eines Testszenarios in Apidog, wo die App auch den vollständigen apidog run-Befehl für Sie erstellt, wobei die Szenario-ID und die Umgebungs-ID bereits ausgefüllt sind.

Behandeln Sie das Token wie ein Passwort. Fügen Sie es nicht in eine committete Pipeline-Datei oder ein geteiltes Skript ein. Speichern Sie es als Geheimnis in Ihrem CI-System und übergeben Sie es über eine Umgebungsvariable, weshalb jedes Beispiel hier auf $APIDOG_ACCESS_TOKEN verweist und nicht auf einen Literalstring. Wenn ein Token durchsickert, generieren Sie es aus demselben CI/CD-Tab neu, und das alte funktioniert nicht mehr.

Eine Umgebung ansteuern und iterieren

Das Umgebungs-Flag ermöglicht es, dass ein Szenario viele Zwecke erfüllen kann. -e, --environment <id> richtet den Lauf auf eine bestimmte Umgebung aus, sodass dasselbe Szenario Staging in einem Pull-Request-Gate und die Produktion in einem Smoke-Test nach der Bereitstellung überprüfen kann, ohne dass Sie etwas duplizieren müssen. Wenn Sie Werte über verschiedene Umgebungen hinweg verwalten, erklärt der Leitfaden zum Umgebungs- und Geheimnismanagement für API-Clients, wie diese Werte fließen.

-n, --iteration-count <n> führt das Szenario n-mal hintereinander aus. Nützlich für einen schnellen Stabilitätstest oder zum Wiederholen eines Flows, der idempotent sein sollte.

-d, --iteration-data <path> ist das datengesteuerte Flag. Zeigen Sie es auf eine JSON- oder CSV-Datei, und der Runner führt das Szenario einmal pro Zeile aus, wobei jede Zeile als eigener Durchlauf mit eigenen Eingabewerten behandelt wird. So führen Sie ein Login-Szenario für fünfzig Konten oder einen Bestellvorgang für eine Tabelle von Payloads aus. Das tiefergehende Muster finden Sie unter datengesteuertes API-Testing mit CSV und JSON.

Drei Flags injizieren Werte, ohne das Szenario zu bearbeiten. --variables <path> lädt Variablen aus einer lokalen Datei. --global-var key=value setzt eine globale Variable direkt. --env-var key=value überschreibt eine einzelne Umgebungsvariable nur für diesen Lauf. Diese sind nützlich in CI, wenn ein Wert (eine Basis-URL, ein Feature-Flag) pro Pipeline unterschiedlich ist und Sie keine separate Umgebung für jede möchten. Wenn Variablen in Apidog neu für Sie sind, erklärt Variablen in Apidog meistern die Bereiche.

# ein Szenario 50-mal über eine CSV-Datei von Eingaben ausführen
apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -d ./accounts.csv -r junit

# eine Umgebungsvariable nur für diesen Lauf überschreiben
apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e 1629989 --env-var baseUrl=https://staging.internal -r cli

Reporter: jedes Ausgabeformat, das apidog run erzeugen kann

Dies ist die Gruppe, nach der die meisten Leute suchen. Hier ist jeder Reporter und wofür er gedacht ist. Sie wählen sie mit -r, --reporters aus und können mehrere gleichzeitig, durch Komma getrennt, übergeben. Der Standardwert ist cli.

cli druckt eine lesbare Zusammenfassung ins Terminal. Dies ist das, was ein Mensch in den Build-Logs überfliegt, um Erfolgs-/Fehlerzählungen und welche Assertions fehlgeschlagen sind zu sehen. Behalten Sie es auch neben maschinenlesbaren Formaten bei, damit das Log nützlich bleibt.

html schreibt einen eigenständigen HTML-Bericht. Archivieren Sie ihn als Build-Artefakt und öffnen Sie ihn in einem Browser, um den vollständigen Lauf mit Anfrage- und Antwortdetails zu sehen. Dies ist das Format, das Sie jemandem geben, der die Pipeline nicht beobachtet hat.

junit gibt XML im Standard-JUnit-Format aus. Nahezu jedes CI-Dashboard kann JUnit-XML in einen Pass-/Fail-Baum parsen, Fehler in einem Merge-Request-Widget anzeigen und Ergebnisse über die Zeit verfolgen. Wenn Sie nur ein maschinenlesbares Format für CI auswählen, wählen Sie dieses.

json erzeugt das rohe, strukturierte Ergebnis. Greifen Sie darauf zurück, wenn Sie das Ergebnis selbst nachbearbeiten möchten: Führen Sie es einem Skript zu, pushen Sie Metriken irgendwohin oder erstellen Sie eine benutzerdefinierte Zusammenfassung.

Eine gängige CI-Kombination ist HTML für Menschen und JUnit für das Dashboard:

apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -r html,junit --out-dir ./apidog-reports

Die restlichen Berichts-Flags steuern, wohin die Ausgabe geschrieben wird und welche zusätzlichen Informationen sie enthält:

• --out-dir <dir> legt das Verzeichnis fest, in das Berichte geschrieben werden. Der Standardwert ist ./apidog-reports.
• --out-file <name> legt den Berichtsdateinamen fest und akzeptiert die Platzhalter {FOLDER_NAME}, {SCENARIO_NAME} und {GENERATE_TIME}, sodass Sie Dateien mit dem Szenario-Namen und einem Zeitstempel versehen können, anstatt eine Datei bei jedem Lauf zu überschreiben.
• --out-json-failures-separated <value> teilt Fehler in eine eigene JSON-Datei auf, was einen Nur-Fehler-Diff leicht lesbar macht.
• --upload-report [value] lädt eine Berichtsübersicht in die Apidog Cloud hoch, sodass der Lauf in der Historie Ihres Projekts neben den lokalen Dateien angezeigt wird.

Fehlerkontrolle: Fehlerbehandlung und Exit-Codes

Ein Runner ist in einer Pipeline nur dann nützlich, wenn er der Pipeline mitteilt, ob die Tests bestanden wurden. apidog run tut dies auf die Art und Weise, wie sich gut verhaltende Kommandozeilentools verhalten: Es beendet mit 0, wenn jede Assertion bestanden wird, und mit einem ungleich Null-Code, wenn etwas fehlschlägt. Dieses einzelne Verhalten ist das gesamte Qualitäts-Gate. CI liest den Exit-Code, markiert den Schritt als fehlgeschlagen und blockiert den Merge oder die Bereitstellung. Sie konfigurieren kein Gate; der Exit-Code ist das Gate.

--on-error <behavior> bestimmt, was passiert, wenn ein Schritt mitten im Szenario fehlschlägt, und hat drei Werte:

• end stoppt den Lauf beim ersten fehlgeschlagenen Schritt. Verwenden Sie es für einen schnell fehlschlagenden Smoke-Test, bei dem Sie sofort Feedback wünschen, wenn etwas kaputtgeht.
• continue führt jeden verbleibenden Schritt aus, sodass Sie alle Fehler in einem Bericht sammeln. Verwenden Sie es für einen Regressionstest, bei dem das gleichzeitige Sehen aller Fehler eine Runde spart.
• ignore lässt den Lauf einen bekanntermaßen wackeligen Schritt passieren, ohne ihn als fatal zu behandeln. Verwenden Sie es sparsam; ein ignorierter Schritt sollte keine echte Regression verbergen.

In jedem Fall, wenn eine Assertion fehlschlägt, endet der Lauf immer noch mit einem ungleich Null-Code, sodass das Gate unabhängig von Ihrem gewählten Verhalten hält. Eine Sache, die das Gate stillschweigend bricht: das Umschließen des Befehls in etwas, das seinen Exit-Code verschluckt, wie das Anhängen von || true in einer Shell. Tun Sie das nicht. Der ungleich Null-Exit ist der ganze Punkt.

Vier Flags stimmen das Anforderungsverhalten während des Laufs ab:

• --ignore-redirects verhindert, dass der Runner HTTP-Weiterleitungen automatisch verfolgt, sodass Sie auf die Weiterleitungsantwort selbst prüfen können.
• --delay-request [n] wartet n Millisekunden zwischen Anfragen, was bei Ratenbegrenzungen oder lastsensitiven Endpunkten hilfreich ist.
• --timeout-request [n] begrenzt, wie lange eine einzelne Anfrage dauern darf, in Millisekunden.
• --timeout-script [n] begrenzt, wie lange ein Pre- oder Post-Request-Skript ausgeführt werden darf, in Millisekunden.

# Smoke-Test: beim ersten Fehler stoppen
apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e 1629989 -r cli --on-error end

# Regression: alles ausführen, alle Fehler in einem HTML- und JUnit-Bericht sammeln
apidog run --access-token $APIDOG_ACCESS_TOKEN -f 88012 -r html,junit --on-error continue --out-dir ./nightly-reports

TLS und Zertifikate

Wenn Sie Endpunkte hinter gegenseitigem TLS oder einer internen Zertifizierungsstelle testen, ist diese Gruppe dafür da, die Verbindung herzustellen.

-k, --insecure deaktiviert die SSL-Zertifikatsprüfung vollständig. Greifen Sie nur darauf zurück bei einem vertrauenswürdigen internen Host mit einem selbstsignierten Zertifikat; richten Sie es niemals auf etwas Öffentliches, da es die Prüfung deaktiviert, die die Verbindung schützt.

Für ein ordnungsgemäßes gegenseitiges TLS geben Sie stattdessen die Client-Anmeldeinformationen an: --ssl-client-cert <path> für das PEM-Zertifikat, --ssl-client-key <path> für dessen privaten Schlüssel und --ssl-client-passphrase <passphrase>, falls der Schlüssel verschlüsselt ist. Wenn verschiedene Hosts unterschiedliche Zertifikate benötigen, verweist --ssl-client-cert-list <path> auf eine Konfigurationsdatei, die diese zuordnet. Und --ssl-extra-ca-certs <path> fügt vertrauenswürdige CA-Zertifikate hinzu, was die saubere Lösung für eine interne CA-Kette ist, die der Runner sonst nicht erkennen würde, besser als zu -k zu greifen.

Ausgabe und Diagnostik

Die letzte Gruppe steuert, was der Runner ausgibt, sowie eine Handvoll Ausführungsdetails.

--verbose druckt die vollständige Anfrage und Antwort für jeden Schritt. Dies ist Ihr erster Schritt, wenn ein Szenario lokal besteht, aber in CI fehlschlägt: Es zeigt die genauen Bytes, die der Runner gesendet und empfangen hat, sodass Sie sie mit dem vergleichen können, was Sie manuell senden. --silent macht das Gegenteil und unterdrückt die Konsolenausgabe für laute geplante Jobs, bei denen Sie sich nur um den Exit-Code und den gespeicherten Bericht kümmern. --color <value> erzwingt farbige Ausgabe ein oder aus, nützlich, wenn ein CI-Log-Viewer ANSI-Codes verstümmelt.

Der Rest ist für spezifische Szenario-Funktionen:

• --external-program-path <path> verweist auf eine Datei mit externen Programmen für benutzerdefinierte Logik, die ein Szenario aufruft.
• --database-connection <path> liefert eine Datenbankkonfiguration für Szenarien mit Schritten, die eine Datenbank direkt abfragen.
• --preferred-http-version <version> legt die bevorzugte HTTP-Protokollversion des Runners fest.
• -b, --bigint aktiviert die BigInt-Verarbeitung, damit große numerische Werte keine Präzision verlieren.
• --lang <language> legt die Anzeigesprache der CLI fest.
• -h, --help druckt den Hilfetext, der die maßgebliche Liste für Ihre installierte Version ist.

Zusammensetzen: Befehle, die Sie tatsächlich ausführen werden

Smoke-Test gegen die Produktion direkt nach einem Deployment, der schnell fehlschlägt:

apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e $PROD_ENV_ID -r cli --on-error end

Vollständige nächtliche Regression über einen Ordner, alle Fehler in einem HTML- und JUnit-Bericht:

apidog run --access-token $APIDOG_ACCESS_TOKEN -f 88012 -r html,junit --on-error continue --out-dir ./nightly-reports

Datengesteuerter Lauf über eine CSV-Datei, maschinenlesbare Ausgabe für CI:

apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -d ./test-cases.csv -r junit

Teständerungen an einem Feature-Branch validieren, bevor sie gemergt werden:

apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 --branch feature-payments -e 1629989 -r cli

Einen nur in CI auftretenden Fehler debuggen, indem die Wire-Details ausgegeben werden:

apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e 1629989 -r cli --verbose

Wenn Sie die CLI auf einem ephemeren CI-Runner ausführen und nicht global installieren möchten, tauschen Sie die Installation gegen npx aus:

npx apidog-cli run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e 1629989 -r junit

Das deckt dieselbe Oberfläche ab. Die Wahl zwischen einer globalen Installation und npx betrifft die Runner-Hygiene, nicht die Funktionalität. Um das Szenario einzurichten, das die CLI ausführt, laden Sie Apidog herunter, erstellen Sie ein Szenario in der App und kopieren Sie dann den generierten Befehl aus dem CI/CD-Tab und parametrieren Sie das Token.\