Sie haben die API-Tests geschrieben. Sie laufen auf Ihrem Rechner erfolgreich. Und genau dort bleiben sie auch, denn das Ausführen ist etwas, woran sich jemand erinnern muss. Ein Teamkollege liefert am Freitagnachmittag eine Änderung aus, der Authentifizierungs-Endpunkt beginnt still und heimlich, auf einem Codepfad einen 500er-Fehler zurückzugeben, und der Erste, der davon erfährt, ist am Montag ein Benutzer. Die Abdeckung war die ganze Zeit vorhanden. Niemand hat die Tests in dem Moment ausgeführt, in dem sie die Regression abgefangen hätten.
Die Lösung besteht darin, die Tests aus Ihrem Editor in die Pipeline zu verschieben, damit sie bei jedem Push automatisch und ohne menschliches Eingreifen ausgeführt werden. Das bedeutet, Sie benötigen einen Befehl, der Ihre API-Tests ohne grafische Oberfläche ausführt, ein klares Bestehen oder Fehlschlagen zurückgibt und sich in jedes CI-System einfügt, das Sie bereits verwenden. Die Apidog CLI erledigt das. Sie erstellen Ihre Testszenarien visuell in Apidog und führen sie dann mit einem einzigen Terminalbefehl aus, den jeder CI-Runner mit Node.js ausführen kann. Keine grafische Benutzeroberfläche, kein Neuschreiben von Tests als Code, kein zusätzlicher Dienst zum Hosten.
Dies ist eine Copy-Paste-Anleitung. Unten finden Sie gebrauchsfertige Pipeline-Dateien für GitHub Actions, GitLab CI, Jenkins, CircleCI und Azure Pipelines, sowie die wenigen Muster, die einen zuverlässigen Build gewährleisten. Nehmen Sie den Block für Ihre Plattform, setzen Sie Ihre IDs und ein Geheimnis ein, und Sie haben bis zum Ende des Tages API-Tests, die jede Zusammenführung absichern. Wenn Sie stattdessen die umfassende Flag-Referenz wünschen, behandelt das umfassendere Thema wie man API-Tests in CI/CD automatisiert die Strategie; diese Seite handelt davon, eine funktionierende Pipeline einzufügen.
Was Sie verdrahten
Die Apidog CLI ist ein npm-Paket, apidog-cli. Sie führt die Testszenarien aus, die Sie in der Apidog-App erstellen: verkettete Anfragen, Assertions, Werte, die aus einer Antwort in die nächste gezogen werden, datengesteuerte Iteration. Die CLI erfindet kein eigenes Testformat. Sie greift in Ihr Projekt ein, findet das Szenario anhand der ID, führt es auf dieselbe Weise aus wie die App und meldet das Ergebnis mit einem Exit-Code zurück.
Dieser Exit-Code ist der entscheidende Punkt. Wenn alle Assertions bestanden werden, beendet der Lauf mit 0. Wenn etwas fehlschlägt, beendet er mit einem Wert ungleich Null. CI-Systeme lesen diesen Exit-Code, markieren den Schritt als fehlgeschlagen und blockieren das Merging oder die Bereitstellung. Sie konfigurieren kein Gate; das Gate ist der Exit-Code. Solange der apidog run-Schritt in Ihrer Pipeline enthalten ist, stoppt eine fehlerhafte Assertion den Prozess.
Drei Dinge lassen einen Lauf funktionieren, und Sie werden sie in jedem der folgenden Blöcke sehen:
- Ein Access Token, das beweist, dass der Lauf Ihr Szenario ausführen darf. Behandeln Sie es wie ein Passwort. Speichern Sie es als CI-Geheimnis, niemals in einer committeten Datei.
- Eine Szenario-ID (oder Ordner-ID oder Testsuite-ID), die angibt, was ausgeführt werden soll.
- Eine Umgebungs-ID, die angibt, wo es ausgeführt werden soll: Dev, Staging oder Produktion.
Sie geben diese IDs nicht manuell ein. Öffnen Sie das Testszenario in Apidog, wechseln Sie zum CI/CD-Tab, wählen Sie die Befehlszeilenoption und generieren Sie ein Access Token. Apidog gibt Ihnen den vollständigen apidog run-Befehl mit bereits ausgefüllter Szenario-ID und Umgebungs-ID. Kopieren Sie es einmal, und verschieben Sie das Token dann in ein Geheimnis. Wenn Sie noch kein Szenario erstellt haben, beginnen Sie mit wie man Testszenarien mit Apidog schreibt und kehren Sie zurück, wenn Sie ein funktionierendes Szenario haben.
Der eine Befehl, auf dem alles aufbaut
Hier ist der kanonische Lauf. Jede Pipeline-Datei ist ein Wrapper um diese Zeile:
apidog run \
--access-token $APIDOG_ACCESS_TOKEN \
-t 605067 \
-e 1629989 \
-n 1 \
-r html,junit \
--out-dir ./apidog-reports
Was jedes Element bewirkt:
--access-tokenauthentifiziert den Lauf. Es liest aus der Umgebungsvariablen$APIDOG_ACCESS_TOKEN, die Sie aus einem Geheimnis befüllen.-t 605067führt das Testszenario mit dieser ID aus. Ersetzen Sie-tdurch-f <folderId>, um einen ganzen Ordner auszuführen, oder--test-suite <id>, um eine kuratierte Suite auszuführen.-e 1629989zielt auf eine Umgebung ab. So trifft dasselbe Szenario Staging bei einem PR-Check und Produktion bei einem Smoke-Test nach der Bereitstellung.-n 1führt das Szenario einmal aus. Erhöhen Sie es für Schleifen, oder kombinieren Sie es mit-d <file>, um Iterationen aus einer CSV- oder JSON-Datendatei zu steuern.-r html,junitwählt die Berichtsformate.juniterzeugt das XML, das Ihr CI-Dashboard in einen Pass/Fail-Baum parst;htmlist ein durchsuchbarer Bericht, den Sie als Build-Artefakt speichern. Fügen Sieclihinzu, wenn Sie auch lesbare Ausgabe im Log wünschen.--out-dir ./apidog-reportsist der Speicherort der Berichte.
Die Reporter sind der Unterschied zwischen „der Build ist rot geworden“ und „hier ist die Assertion, die fehlgeschlagen ist, und die Antwort, die sie kaputt gemacht hat.“ JUnit XML ist das Format, das fast jede Plattform nativ versteht, daher wird es in allen fünf Blöcken unten angezeigt.
GitHub Actions
Fügen Sie dies in .github/workflows/api-tests.yml ein. Es führt Ihr Szenario bei jedem Pull Request gegen main aus, lädt den Bericht als Artefakt hoch und lässt den Check fehlschlagen, wenn eine Assertion fehlschlägt.
name: API tests
on:
pull_request:
branches: [main]
jobs:
api-tests:
runs-on: ubuntu-latest
steps:
- name: Checkout
uses: actions/checkout@v4
- name: Set up Node.js
uses: actions/setup-node@v4
with:
node-version: '20'
- name: Install Apidog CLI
run: npm install -g apidog-cli
- name: Run API test scenario
run: |
apidog run \
--access-token "$APIDOG_ACCESS_TOKEN" \
-t 605067 \
-e 1629989 \
-n 1 \
-r html,junit \
--out-dir ./apidog-reports
env:
APIDOG_ACCESS_TOKEN: ${{ secrets.APIDOG_ACCESS_TOKEN }}
- name: Upload report
if: always()
uses: actions/upload-artifact@v4
with:
name: apidog-report
path: ./apidog-reports
Zwei wichtige Details. Der Token befindet sich unter Einstellungen → Secrets und Variablen → Aktionen als APIDOG_ACCESS_TOKEN und erreicht den Schritt über env:. Und if: always() im Upload-Schritt bedeutet, dass Sie den Bericht auch dann erhalten, wenn die Tests fehlschlagen, was der einzige Zeitpunkt ist, an dem Sie ihn tatsächlich lesen müssen. Wenn ein Szenario fehlschlägt, beendet der apidog run-Schritt mit einem Wert ungleich Null, der Job wird rot, und der PR zeigt einen fehlerhaften Check an. Für eine detailliertere Anleitung speziell zu dieser Plattform, siehe wie man API-Tests in GitHub Actions automatisiert.
GitLab CI
Dasselbe Prinzip in .gitlab-ci.yml. Das node:20-Image enthält bereits die Runtime, sodass die einzige Einrichtung die Installation ist.
stages:
- test
api-tests:
stage: test
image: node:20
script:
- npm install -g apidog-cli
- >
apidog run
--access-token "$APIDOG_ACCESS_TOKEN"
-t 605067
-e 1629989
-r junit,cli
--out-dir ./apidog-reports
artifacts:
when: always
paths:
- apidog-reports/
reports:
junit: apidog-reports/*.xml
Speichern Sie APIDOG_ACCESS_TOKEN unter Einstellungen → CI/CD → Variablen als maskierte, geschützte Variable, damit sie niemals im Log angezeigt wird. Der reports: junit:-Block ist der Teil, den GitLab-Benutzer oft übersehen: Er weist GitLab an, das XML zu parsen und die Ergebnisse direkt im Merge-Request-Widget anzuzeigen. Ein Reviewer sieht, welche Assertions fehlgeschlagen sind, ohne etwas herunterladen zu müssen.
Jenkins
Für eine deklarative Pipeline speichern Sie den Token als Jenkins-Anmeldeinformation und ziehen ihn in die Umgebung, um dann die CLI in einer Stage aufzurufen. Der post-Block speist das JUnit-XML in die Testtrend-Graphen von Jenkins ein und hält den HTML-Bericht am Build.
pipeline {
agent any
environment {
APIDOG_ACCESS_TOKEN = credentials('apidog-access-token')
}
stages {
stage('API tests') {
steps {
sh 'npm install -g apidog-cli'
sh '''
apidog run \
--access-token $APIDOG_ACCESS_TOKEN \
-t 605067 \
-e 1629989 \
-n 1 \
-r html,junit \
--out-dir apidog-reports
'''
}
}
}
post {
always {
junit 'apidog-reports/*.xml'
archiveArtifacts artifacts: 'apidog-reports/**', allowEmptyArchive: true
}
}
}
Wenn Ihre Build-Agents die CLI bereits im Cache haben, entfernen Sie die Zeile npm install und rufen Sie apidog run direkt auf. Apidog liefert auch eine Jenkins-spezifische Integrationsanleitung, wenn Sie den Plugin-Weg statt eines Shell-Schritts bevorzugen: automatisierte Apidog-Tests mit Jenkins für CI/CD integrieren.
CircleCI
Verwenden Sie in .circleci/config.yml das Node-Komfort-Image und speichern Sie den Token als Projekt-Umgebungsvariable unter Projekteinstellungen → Umgebungsvariablen.
version: 2.1
jobs:
api-tests:
docker:
- image: cimg/node:20.11
steps:
- checkout
- run:
name: Install Apidog CLI
command: npm install -g apidog-cli
- run:
name: Run API test scenario
command: |
apidog run \
--access-token "$APIDOG_ACCESS_TOKEN" \
-t 605067
-e 1629989
-r junit,cli \
--out-dir ./apidog-reports
- store_test_results:
path: ./apidog-reports
- store_artifacts:
path: ./apidog-reports
destination: apidog-reports
workflows:
test:
jobs:
- api-tests
store_test_results ist das Äquivalent von GitLabs JUnit-Block in CircleCI; weisen Sie es auf das Berichtsverzeichnis und CircleCI zeigt fehlgeschlagene Assertions im Tab 'Tests' an. store_artifacts hält den HTML-Bericht angehängt, sodass Sie ihn von der Build-Seite aus öffnen können.
Azure Pipelines
In azure-pipelines.yml installieren Sie Node mit der Task, führen die CLI aus und veröffentlichen die JUnit-Ergebnisse. Fügen Sie APIDOG_ACCESS_TOKEN als geheime Variable in der Pipeline hinzu (oder ziehen Sie sie aus einer Azure Key Vault Variablengruppe), und mappen Sie sie dann in das env des Skriptschritts.
trigger:
- main
pool:
vmImage: ubuntu-latest
steps:
- task: NodeTool@0
inputs:
versionSpec: '20.x'
displayName: 'Install Node.js'
- script: npm install -g apidog-cli
displayName: 'Install Apidog CLI'
- script: |
apidog run \
--access-token "$APIDOG_ACCESS_TOKEN" \
-t 605067 \
-e 1629989 \
-r junit,html \
--out-dir ./apidog-reports
displayName: 'Run API test scenario'
env:
APIDOG_ACCESS_TOKEN: $(APIDOG_ACCESS_TOKEN)
- task: PublishTestResults@2
condition: always()
inputs:
testResultsFormat: 'JUnit'
testResultsFiles: 'apidog-reports/*.xml'
testRunTitle: 'Apidog API tests'
Das Makro $(APIDOG_ACCESS_TOKEN) liest die geheime Pipeline-Variable; die Zuordnung über env hält sie aus der sichtbaren Befehlszeile fern. PublishTestResults@2 mit condition: always() sorgt dafür, dass die Ergebnisse im Tab 'Tests' angezeigt werden, unabhängig davon, ob der Lauf bestanden oder fehlgeschlagen ist. Für eine umfassendere Behandlung dieser Plattform bietet Apidog eine spezielle Anleitung zum API-Testen in Azure DevOps-Pipelines.
Muster, die das Gate zuverlässig halten
Eine Pipeline, die Ihre Tests ausführt, ist die Grundlage. Diese Rezepte machen sie im Alltag nützlich.
Smoke-Test direkt nach einem Deploy. Führen Sie ein schnelles Szenario gegen die Produktion aus, sobald eine Veröffentlichung live geht, auf die Produktionsumgebung gerichtet, und stoppen Sie beim ersten Fehler:
apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e <prodEnvId> -r cli --on-error end
Vollständige Regression über Nacht. Führen Sie einen ganzen Ordner von Szenarien nach Zeitplan aus und sammeln Sie alle Fehler in einem Bericht, anstatt beim ersten Halt zu machen:
apidog run --access-token $APIDOG_ACCESS_TOKEN -f <folderId> -r html,junit --on-error continue --out-dir ./nightly-reports
--on-error ist hier der Drehknopf. end schlägt schnell fehl, was Sie für ein Deploy-Gate wünschen. continue führt jeden Schritt aus, sodass ein nächtlicher Bericht alle Fehler auf einmal anzeigt. So oder so beendet der Lauf immer noch mit einem Wert ungleich Null, wenn etwas fehlschlägt, sodass das Gate hält.
Führen Sie ein Szenario mit vielen Eingaben aus. Steuern Sie Iterationen aus einer Datendatei und behandeln Sie jede Zeile als eigenen Durchlauf:
apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -d ./test-data.csv -r junit
Testen Sie einen Feature-Branch, nicht main. Führen Sie die Szenarien genau so aus, wie sie auf einem Branch existieren:
apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 --branch feature-payments -e 1629989 -r cli
Beheben Sie einen nur in CI auftretenden Fehler. Wenn ein Szenario lokal erfolgreich ist, aber in der Pipeline fehlschlägt, fügen Sie --verbose hinzu. Es wird die genaue Anfrage, die der Runner gesendet hat, und die genaue Antwort, die er erhalten hat, ausgegeben, was fast immer der Weg ist, den Umgebungsunterschied zu finden, der die Lücke verursacht.
Wenn der Build trügerisch ist
Einige Fehlermodi treten häufig genug auf, um sie hervorzuheben, da jeder einzelne das Gate stillschweigend außer Kraft setzt.
Der Build bleibt grün, obwohl ein Test fehlschlagen sollte. Dies ist der gefährliche Fall. Es bedeutet fast immer, dass der Exit-Code verschluckt wird. Wenn Sie den Befehl in eine Shell-Pipeline gewickelt oder || true angehängt haben, um „zu verhindern, dass er den Build unterbricht“, haben Sie ihn auch daran gehindert, etwas abzufangen. Entfernen Sie alles, was den Exit-Code ungleich Null maskiert. Der apidog run-Schritt muss das sein, was der CI-Schritt liest.
Authentifizierungsfehler. Der Token ist falsch, abgelaufen oder hat den Befehl nie erreicht. Bestätigen Sie, dass das CI-Geheimnis tatsächlich gefüllt ist (ein maskiertes Echo seiner Länge, niemals der Wert), und generieren Sie es bei Bedarf über den CI/CD-Tab des Szenarios neu.
„Szenario nicht gefunden.“ Die Szenario-ID, Projekt-ID oder der Branch stimmen nicht überein. Kopieren Sie den Befehl erneut vom CI/CD-Tab, um sicherzustellen, dass die IDs aktuell sind, und überprüfen Sie doppelt, ob --branch auf den erwarteten Ort zeigt.
Lokal erfolgreich, in CI fehlerhaft. Fast immer ein Umgebungsunterschied. Der Runner kann auf eine andere -e Umgebung abzielen, sich hinter einer Firewall befinden, die Ihren Host nicht erreichen kann, oder es fehlt eine Variable, die das Szenario benötigt. Führen Sie mit --verbose aus und vergleichen Sie die vom Runner erzeugte Anfrage mit der, die Sie lokal senden.
TLS-Fehler bei internen Hosts. Wenn Ihr Endpunkt eine interne CA verwendet, übergeben Sie das zusätzliche CA-Zertifikat, anstatt die Überprüfung zu deaktivieren. Greifen Sie nur als letztes Mittel zu -k (SSL-Verifizierung überspringen) auf einem vertrauenswürdigen internen Host mit einem selbstsignierten Zertifikat, niemals gegen etwas Öffentliches.
Warum visuell erstellen und ohne GUI ausführen
Es gibt eine echte Designentscheidung, die all dem zugrunde liegt, und sie ist einen Absatz wert. Bei skript-orientierten Runnern sind Test und Ausführung dieselbe Datei, sodass ein anfälliges Skript sowohl Ihr Test als auch Ihr Engpass ist. Mit Apidog ist das Szenario in Ihrem Projekt der Test, und die CLI führt ihn einfach dort aus, wo kein Mensch sein kann. Niemand pflegt zwei Darstellungen desselben Checks. Sie erstellen schnell im visuellen Builder, Sie führen automatisch in der Pipeline aus, und die beiden bleiben synchron, weil sie dasselbe Artefakt sind. Das ist ein großer Grund, warum Teams Apidog als Postman-Alternative für API-Tests betrachten, sobald CI ins Spiel kommt, und warum solide API-Assertions wichtiger sind als der Runner, in den Sie sie einpacken.
Der Ablauf ist einfach, sobald er läuft. Entwerfen und debuggen Sie Anfragen in der App. Verketten Sie sie zu einem Szenario mit Assertions. Pushen Sie Ihren Code, und die CLI führt dieses Szenario bei jeder Änderung in CI aus. Wenn etwas schiefgeht, nennt der Bericht die Assertion und der Exit-Code stoppt das Deploy. Sie beheben es, pushen erneut, und dasselbe Gate bestätigt die Behebung.
Wenn Ihre Tests immer noch im Editor von jemandem liegen, ist das die Lücke, die diese Woche geschlossen werden muss. Laden Sie Apidog herunter, bringen Sie ein Szenario zum Laufen, kopieren Sie den apidog run-Befehl aus seinem CI/CD-Tab und fügen Sie den obigen Block für Ihre Plattform ein. Sie werden noch am selben Nachmittag API-Tests haben, die jedes Merging absichern.
Häufig gestellte Fragen
Ist die Apidog CLI kostenlos in CI nutzbar? Die CLI ist ein kostenloses npm-Paket: npm install -g apidog-cli. Sie führt die Szenarien aus Ihrem Apidog-Projekt aus, daher hängt ab, was Sie ausführen können, von Ihrem Apidog-Plan ab, aber der Befehlszeilen-Runner selbst ist kein separates kostenpflichtiges Produkt.
Muss ich meine Tests als Code neu schreiben? Nein. Sie erstellen Szenarien visuell in Apidog, und die CLI führt sie anhand der ID aus. Das Szenario ist der Test; die CLI ist nur der Executor. Das ist der Hauptunterschied zu skript-orientierten Runnern.
Wie bringt ein fehlerhafter Test meinen Build tatsächlich zum Scheitern? Durch den Exit-Code. Wenn eine Assertion fehlschlägt, beendet apidog run mit einem Wert ungleich Null. Ihr CI-System liest dies, markiert den Schritt als fehlgeschlagen und blockiert das Merging oder Deploy. Sie fügen keine zusätzliche Konfiguration hinzu, damit das Gate funktioniert.
Welches Berichtsformat sollte ich verwenden? Verwenden Sie junit für das maschinenlesbare XML, das Ihr CI-Dashboard in Pass/Fail-Ergebnisse parst, und fügen Sie html hinzu, wenn Sie einen durchsuchbaren Bericht als Build-Artefakt speichern möchten. Eine häufige Kombination ist -r junit,html. Behalten Sie auch cli bei, wenn Sie lesbare Ausgabe im Build-Log wünschen.
Muss ich Apidog auf dem CI-Server installieren? Nein. Der CI-Runner benötigt nur Node.js (v16 oder neuer) und das apidog-cli-Paket. Keine Desktop-App, keine GUI, keine Lizenzdatei auf dem Rechner. Das Paket plus ein Access Token ist ausreichend.
Kann ich es ohne globale Installation ausführen? Ja. Verwenden Sie npx apidog-cli run ..., um es ohne persistente globale Installation auszuführen, was sauberer auf kurzlebigen Runnern ist, die nach jedem Job wieder abgebaut werden.
Wie unterscheidet sich dies von Newman? Newman führt Postman-Sammlungen von der Kommandozeile aus. Die Apidog CLI führt Apidog-Testszenarien aus. Die Rollen sind parallel, aber der Apidog-Runner führt Szenarien aus, die Sie in der App erstellt haben, und wird als einzelnes apidog-cli-Paket ausgeliefert. Siehe Postman CLI vs Newman für die Postman-Seite dieses Vergleichs.
Woher bekomme ich das Access Token und die IDs? Alles über den CI/CD-Tab des Testszenarios in Apidog. Wählen Sie die Befehlszeilenoption, generieren Sie ein Access Token und kopieren Sie den vollständigen apidog run-Befehl, den Apidog mit bereits ausgefüllten Szenario- und Umgebungs-IDs erstellt. Verschieben Sie dann das Token in ein CI-Geheimnis und referenzieren Sie es als $APIDOG_ACCESS_TOKEN.