Wie man API-Tests in Travis CI mit Apidog CLI automatisiert

Ihre API funktioniert auf Ihrem Rechner. Die Unit-Tests sind grün. Sie mergen, deployen, und eine Stunde später meldet sich ein Teamkollege: Der /checkout-Endpunkt gibt einen 500er-Fehler zurück für jeden mit einem leeren Warenkorb. Der Fehler lag nie in dem Code, den Sie geändert haben; er steckte in einem Vertrag, zwei Dienste entfernt, den niemand neu getestet hatte. Dies ist die Lücke, die Integrations-API-Tests schließen, und genau die Art von Überprüfung, die Sie bei jedem Commit automatisch ausführen lassen möchten, anstatt dass sie jemand manuell im Kopf behält.

Travis CI ist einer der ältesten gehosteten Continuous-Integration-Dienste und beherrscht immer noch eine Sache gut: Es überwacht Ihr Git-Repository, startet eine saubere Umgebung für jeden Push und Pull Request und führt alle Befehle aus, die Sie in eine .travis.yml-Datei legen. Die meisten Teams nutzen es für Kompilierungs- und Unit-Test-Schleifen. Viel weniger Teams nutzen es, um echte HTTP-Tests gegen eine laufende API auszuführen, obwohl sich dort die teuren Bugs verstecken. Der Grund dafür ist die Reibung. Einen API-Test-Runner in eine CI-Box einzubinden, Geheimnisse sicher zu übergeben und ein Erfolgs-/Fehlersignal zurückzubekommen, ist knifflig genug, dass die Leute es überspringen.

Dieser Leitfaden beschreibt, wie Sie diese Lücke mit dem Apidog Befehlszeilen-Runner schließen. Sie entwerfen und debuggen Ihre API-Tests in der Apidog Desktop-App, wo Sie Anfragen und Assertions visuell sehen können, und führen dann genau dieselben Tests headless innerhalb von Travis CI mit einem einzigen Befehl aus. Kein Umschreiben der Testlogik als Code, keine Wartung eines separaten Test-Harness. Der Artikel behandelt den gesamten Pfad: eine minimale .travis.yml, die Installation des Runners, die sichere Übergabe Ihres Zugriffstokens, die Auswahl der auszuführenden Tests, die Generierung von Berichten und das laute Fehlschlagen des Builds, wenn ein Endpunkt defekt ist. Laden Sie Apidog herunter, wenn Sie mitmachen möchten.

Warum API-Tests überhaupt in CI ausführen

Unit-Tests bestätigen, dass eine Funktion den richtigen Wert zurückgibt. API-Tests bestätigen, dass der gesamte Anfrage-Antwort-Zyklus korrekt funktioniert: Die Route existiert, die Authentifizierung wird durchgesetzt, der Statuscode ist korrekt, das JSON-Schema stimmt überein und die Werte im Body sind sinnvoll. Dies sind unterschiedliche Fehlermodi, und die zweite Art ist die, auf die Ihre Benutzer tatsächlich stoßen.

Sie lokal auszuführen ist in Ordnung, bis es das nicht mehr ist. Lokale Ausführungen hängen davon ab, dass Sie daran denken, sie auszuführen, dass Ihr Rechner der Produktionskonfiguration entspricht und dass Sie nicht gerade beim Kaffeetrinken sind, wenn eine Regression durchschlüpft. Continuous Integration eliminiert alle drei Ausreden. Jeder Push löst dieselbe Suite in derselben Umgebung aus, und das Ergebnis wird dem Commit und dem Pull Request für alle sichtbar angehängt.

Speziell für API-Teams gibt es einen tieferen Nutzen. Wenn Ihre Tests neben Ihrem API-Design existieren, taucht eine breaking change als fehlgeschlagene Assertion in dem Moment auf, in dem sie gepusht wird, und nicht als Support-Ticket. Wenn Sie den konzeptionellen Hintergrund wissen möchten, wo dies in eine Lieferpipeline passt, ist der Erklärer „Was ist CI/CD“ eine gute Begleitlektüre; dieser Artikel konzentriert sich auf den praktischen Travis CI Build.

Was Sie benötigen, bevor Sie beginnen

Drei Dinge, und zwei davon haben Sie wahrscheinlich schon.

• Ein Git-Repository, das mit Travis CI verbunden ist. Der kostenlose Tarif auf travis-ci.com funktioniert für öffentliche und private Repos innerhalb der Nutzungslimits.

• Ein Apidog-Projekt mit mindestens einem Testszenario, das Sie bereits in der Desktop-App erfolgreich erstellt und ausgeführt haben. Ein Testszenario in Apidog ist eine geordnete Reihe von API-Anfragen mit Assertions; stellen Sie es sich als einen End-to-End-Flow vor, wie „Anmelden, eine Bestellung erstellen, die Bestellung abrufen, sie löschen“.
• Node.js. Die Apidog CLI läuft auf Node und benötigt Version 16 oder höher. Travis bietet Node standardmäßig in der node_js-Sprachumgebung an, daher ist dies größtenteils eine einzeilige Deklaration.

Wenn Sie noch kein Testszenario erstellt haben, tun Sie dies zuerst in der App. Der Sinn dieses Workflows ist es, dass Sie einmal visuell debuggen und dann für immer automatisieren. Tests blind in einem CI-Log zu erstellen, ist der langsame Weg. Für die Grundlagen des Schreibens guter Überprüfungen behandelt „API-Asserts: Ein praktischer Leitfaden“, wie Statuscodes, Antwortbodies und JSON-Schema validiert werden, bevor Sie überhaupt pushen.

Schritt 1: Ihr Zugriffstoken und Ihre Szenario-ID abrufen

Die Apidog CLI führt Ihre in der Cloud gespeicherten Tests headless aus, daher benötigt sie zwei Identitätsmerkmale:

1. Ein Zugriffstoken, das beweist, dass der Runner berechtigt ist, Ihr Projekt zu lesen. Generieren Sie es in Ihren Apidog-Kontoeinstellungen unter „Zugriffstoken“. Behandeln Sie es wie ein Passwort; es gewährt API-Zugriff auf Ihre Projektdaten.
2. Eine Testszenario-ID. Öffnen Sie das Szenario in der Desktop-App und kopieren Sie dessen ID, oder verwenden Sie die Option „In CI/CD ausführen“, die einen vorgefertigten Befehl mit bereits ausgefüllter ID generiert.

Der einfachste Weg, einen korrekten ersten Befehl zu erhalten, ist, Apidog ihn für Sie schreiben zu lassen. Innerhalb eines Testszenarios erzeugt die CI/CD-Laufoption etwas Ähnliches wie dies:

apidog run --access-token <your-access-token> -t 5564321 -e 4417023 -r cli

Das ist die ganze Formel: authentifizieren, auf ein Szenario zeigen (-t), auf eine Umgebung zeigen (-e) und einen Reporter auswählen (-r). Kopieren Sie das, bestätigen Sie, dass es zuerst auf Ihrem eigenen Laptop läuft, und verschieben Sie es erst dann nach Travis. Lokales Verifizieren erspart Ihnen ein Dutzend fehlgeschlagener Builds, die Sie mit der Fehlersuche eines Tippfehlers in einem Token verbringen würden.

Schritt 2: Das Token als verschlüsselte Travis-Variable speichern

Fügen Sie Ihr Zugriffstoken niemals in .travis.yml ein. Diese Datei wird in Git committet, und ein geleaktes Token gewährt jedem Lesezugriff auf Ihr API-Projekt. Travis bietet zwei sichere Optionen.

Der saubere Weg sind Repository-Umgebungsvariablen, die in der Travis-Web-Benutzeroberfläche festgelegt werden. Gehen Sie zu Ihren Repository-Einstellungen auf Travis, finden Sie die Umgebungsvariablen und fügen Sie hinzu:

• APIDOG_ACCESS_TOKEN mit Ihrem Token-Wert
• APIDOG_ENV_ID mit der Umgebung-ID, gegen die Sie testen möchten

Lassen Sie die Option „Wert im Build-Log anzeigen“ deaktiviert, damit das Token niemals ausgegeben wird. Travis injiziert diese als echte Umgebungsvariablen in jeden Build, und Ihre Konfiguration verweist namentlich auf sie. Dies hält Geheimnisse vollständig aus dem Repository heraus, was das gewünschte Verhalten ist; wenn ein Contributor das Repo forkt, wird Ihr Token nicht mitgegeben.

Wenn Sie alles in der Datei bevorzugen, unterstützt Travis auch verschlüsselte Variablen über seine CLI:

travis encrypt APIDOG_ACCESS_TOKEN="your-token-here" --add env.global

Dies schreibt einen verschlüsselten Blob in .travis.yml, den nur der Build Ihres Repositorys entschlüsseln kann. Beide Ansätze funktionieren. Der UI-Weg ist für die meisten Teams einfacher und leichter zu handhaben, wenn ein Token abläuft.

Schritt 3: Die .travis.yml schreiben

Hier ist eine vollständige, minimale Konfiguration, die die Apidog CLI installiert und ein Szenario bei jedem Push und Pull Request ausführt:

language: node_js
node_js:
  - "18"

cache:
  npm: true

install:
  - npm install -g apidog-cli

script:
  - apidog run --access-token $APIDOG_ACCESS_TOKEN -t 5564321 -e $APIDOG_ENV_ID -r cli

Drei Blöcke erledigen die Arbeit. language: node_js mit einer Version bietet Ihnen eine Node-Laufzeit, die neu genug für die CLI ist. Der install-Schritt installiert apidog-cli global, sodass der apidog-Befehl im Pfad verfügbar ist. Der script-Schritt führt Ihre Tests aus. Der -r cli-Reporter gibt eine lesbare Erfolgs-/Fehlerzusammenfassung direkt in das Travis-Log aus, was Sie ansehen werden, wenn etwas kaputtgeht.

Beachten Sie, dass die Szenario-ID fest codiert ist, aber die Geheimnisse aus Umgebungsvariablen stammen. Das ist die richtige Aufteilung: Die ID ist nicht sensibel, das Token schon. Committen Sie diese Datei, pushen Sie, und Travis führt Ihre API-Tests automatisch aus. Der erste grüne Build ist der Moment, in dem Ihre API ein Sicherheitsnetz erhält.

Wenn Sie mehrere Dienste warten und ein gemeinsames mentales Modell über verschiedene Runner hinweg wünschen, zeigt der Leitfaden „API-Tests in CI/CD automatisieren“ dasselbe Muster, angewendet auf andere Plattformen, und die GitHub Actions-Version ist im Wesentlichen nahezu identisch, falls Sie jemals migrieren.

Schritt 4: Den Build fehlschlagen lassen, wenn ein Test fehlschlägt

Dies ist der Teil, den Teams vergessen, und er macht die gesamte Übung stillschweigend zunichte. Ein CI-Job ist nur dann nützlich, wenn ein fehlerhafter Test den Build rot färbt. Wenn der Runner unabhängig davon mit Null beendet wird, haben Sie einen sehr teuren Log-Drucker gebaut.

Gute Nachrichten: Die Apidog CLI macht bereits das Richtige. Wenn eine Assertion fehlschlägt, beendet sich der apidog run-Prozess mit einem Nicht-Null-Statuscode, und Travis behandelt jeden Nicht-Null-Exit in der script-Phase als Build-Fehler. Die minimale Konfiguration oben schlägt also bereits standardmäßig korrekt fehl. Sie benötigen keine zusätzliche 'Klebstoff'-Logik.

Was Sie anpassen können, ist, wie sich der Lauf mitten im Szenario verhält, wenn eine einzelne Anfrage fehlschlägt. Das Flag --on-error steuert dies:

• --on-error end stoppt das Szenario beim ersten Fehler. Schnellstes Feedback, weniger Ausgabe.
• --on-error continue führt die verbleibenden Schritte aus, damit Sie jeden Fehler in einem Durchlauf sehen.
• --on-error ignore läuft weiter und lässt Fehler den Lauf nicht stoppen.

Für CI ist continue normalerweise der ideale Punkt: Sie möchten das vollständige Bild dessen, was kaputtgegangen ist, ohne dass der Job nach der ersten fehlerhaften Assertion abbricht, und dennoch mit einem Nicht-Null-Exit enden, damit der Build fehlschlägt. Eine vernünftige Skriptzeile sieht so aus:

script:
  - apidog run --access-token $APIDOG_ACCESS_TOKEN -t 5564321 -e $APIDOG_ENV_ID -r cli --on-error continue

Vermeiden Sie die Versuchung, || true an den Befehl anzuhängen, um „den Build passieren zu lassen“. Das schluckt den Exit-Code und führt genau den blinden Fleck wieder ein, den Sie entfernen wollten.

Schritt 5: Einen HTML-Bericht generieren und aufbewahren

Der cli-Reporter ist gut für einen schnellen Überblick, aber wenn ein Build fehlschlägt, möchten Sie oft ein reichhaltigeres Artefakt: welche Anfrage, welche Assertion, wie der tatsächliche Antwort-Body war. Die CLI generiert einen HTML-Bericht mit dem html-Reporter, und Sie können Reporter in einem Lauf stapeln.

script:
  - apidog run --access-token $APIDOG_ACCESS_TOKEN -t 5564321 -e $APIDOG_ENV_ID -r cli,html --out-dir ./apidog-reports

-r cli,html druckt ins Log und schreibt eine eigenständige HTML-Datei. --out-dir legt fest, wohin der Bericht gespeichert wird, standardmäßig ./apidog-reports. Damit dieser Bericht nach Beendigung des Builds erhalten bleibt, stellen Sie ihn an einem Ort bereit, an den Travis veröffentlichen kann, z. B. einem S3-Bucket oder GitHub Pages, in einem deploy-Block. Ein gängiges Muster:

deploy:
  provider: pages
  skip_cleanup: true
  github_token: $GITHUB_TOKEN
  local_dir: apidog-reports
  on:
    branch: main

Wenn Sie die Artefakt-Speicherung überhaupt nicht verwalten möchten, kann die CLI den Bericht mit --upload-report in die Apidog-Cloud pushen, wo Ihr Team ihn über einen Link ohne zusätzliches Hosting öffnen kann. Das ist die wartungsärmste Option für verteilte Teams.

Schritt 6: Umgebungen, Daten und Matrix-Läufe hinzufügen

Ein einzelnes Szenario gegen eine einzelne Umgebung ist ein guter Anfang. Echte Pipelines wachsen in drei Richtungen, und die CLI-Flags lassen sich sauber auf jede abbilden.

• Mehrere Umgebungen. Das Flag -e wählt aus, welche Basis-URLs und Variablen der Umgebung verwendet werden sollen. Führen Sie dasselbe Szenario bei jedem Push gegen Staging und bei einem nächtlichen Cron-Build gegen Produktion aus, indem Sie die Umgebung-ID austauschen. Travis-Cron-Jobs werden pro Repository in der Einstellungen-Benutzeroberfläche konfiguriert.
• Datengesteuerte Läufe. Das Flag -d (Langform --iteration-data) speist eine CSV- oder JSON-Datei in Ihr Szenario ein, sodass es einmal pro Zeile ausgeführt wird. So decken Sie Randfälle ab: gültige Eingaben, fehlende Felder, übergroße Payloads, Sonderzeichen – alles aus einer einzigen Szenariodefinition. Kombinieren Sie es mit -n (--iteration-count), wenn Sie eine feste Anzahl von Wiederholungen anstelle von dateigesteuerten Iterationen wünschen.

apidog run --access-token $APIDOG_ACCESS_TOKEN -t 5564321 -e $APIDOG_ENV_ID -d ./test-data.csv -r cli

• Parallele Szenarien. Travis Build-Matrizen ermöglichen es Ihnen, mehrere Szenarien gleichzeitig über parallele Jobs auszuführen. Definieren Sie eine Umgebungsvariablen-Matrix, bei der jeder Eintrag eine andere Szenario-ID trägt, und jeder Matrix-Job führt eine aus. Der Build wird nur grün, wenn alle bestehen.

env:
  - SCENARIO_ID=5564321   # checkout flow
  - SCENARIO_ID=5564322   # auth flow
  - SCENARIO_ID=5564323   # search flow

script:
  - apidog run --access-token $APIDOG_ACCESS_TOKEN -t $SCENARIO_ID -e $APIDOG_ENV_ID -r cli

Wenn Suiten wachsen, hilft die Organisation von Szenarien in Testsuiten für automatisiertes API-Testing, die Matrix überschaubar zu halten, anstatt zu einer Wand aus IDs zu werden.

Warum dies das manuelle Kodieren von Tests in Ihrem CI-Skript übertrifft

Sie könnten API-Tests direkt in einem Travis-Skript mit curl und jq schreiben oder als Newman-Lauf einer exportierten Sammlung. Beides funktioniert, und beides altert schlecht.

Der curl-plus-Shell-Ansatz verwandelt jede Assertion in einen brüchigen Zeichenkettenvergleich. Das Überprüfen eines verschachtelten JSON-Feldes wird zu einer jq-Beschwörung; das Überprüfen eines Schemas ist praktisch unmöglich; und in dem Moment, in dem Ihre API ein Feld hinzufügt, muss die Hälfte Ihrer Greps neu geschrieben werden. Sie enden damit, eine zweite, schlechtere Kopie Ihres API-Wissens in Bash zu pflegen.

Der Collection-Runner-Ansatz ist besser, koppelt aber Ihr CI an ein Export- und Synchronisierungsritual: Tests in einem Tool bearbeiten, exportieren, das JSON committen, hoffen, dass es nicht von der Realität abweicht. Die Abweichung ist real und die Ursache für die Beschwerden „die Tests bestehen, aber die API ist kaputt“. Wir haben über genau diesen Fehlermodus in „Warum Ihre Postman-Sammlungen keine Quelle der Wahrheit sind“ geschrieben, und wenn Sie heute Sammlungen in CI ausführen, behandelt „Wie man Postman-Sammlungen in CI ohne Newman ausführt“ den Migrationspfad.

Das Apidog-Modell schließt die Schleife. Ihre Tests, Ihr API-Design, Ihre Umgebungen und Ihre Mock-Server leben an einem Ort. Die CLI führt die Live-Version dieser Tests aus; es gibt nichts zu exportieren und nichts, das abweichen könnte. Sie debuggen eine wackelige Assertion visuell in der App, speichern, und der nächste CI-Lauf übernimmt die Änderung. Diese einzige Quelle der Wahrheit ist der gesamte Grund, einen zweckbestimmten Runner gegenüber einem Haufen von Shell-Skripten zu verwenden. Wenn Sie es mit Ihrem aktuellen Setup vergleichen, stellt der Überblick über die besten Postman-Alternativen für API-Tests die Optionen nebeneinander dar.

Ein Hinweis speziell zu Travis CI

Travis war jahrelang die Standard-Open-Source-CI, und viele ältere Repositories laufen immer noch darauf. Wenn Sie 2026 neu anfangen, sollten Sie wissen, dass sich das Feld verschoben hat; GitHub Actions, GitLab CI und CircleCI tragen jetzt die meisten neuen Projekte, und unser Vergleich der besten CI/CD-Tools zeigt, wo jedes davon passt. Die gute Nachricht ist, dass die Apidog CLI von Grund auf plattformunabhängig ist. Der exakt gleiche apidog run-Befehl, der in Ihrer .travis.yml funktioniert, funktioniert auch in einem GitHub Actions-Schritt, einer GitLab .gitlab-ci.yml oder einer Jenkins-Stufe. Wenn Sie jemals von Travis weg wechseln, ziehen Ihre API-Tests unverändert mit um; nur die umgebenden YAML-Schlüssel unterscheiden sich. Diese Portabilität ist ein stiller, aber realer Vorteil, wenn man die Testlogik aus CI-spezifischer Syntax heraushält.

Häufig gestellte Fragen

Muss ich die Apidog Desktop-App auf der CI-Box installieren? Nein. Die Desktop-App dient zum Entwerfen und Debuggen von Tests. Travis benötigt lediglich das apidog-cli npm-Paket und eine Node 16+-Laufzeitumgebung, die die node_js-Sprachumgebung bereits bereitstellt. Die CLI ruft Ihre in der Cloud gespeicherten Szenarien headless ab und führt sie aus.

Wo finde ich mein Zugriffstoken und meine Szenario-ID? Generieren Sie das Zugriffstoken in Ihren Apidog-Kontoeinstellungen unter „Zugriffstoken“. Die Szenario-ID ist in der Desktop-App für jedes Testszenario sichtbar; die integrierte Option „In CI/CD ausführen“ generiert auch einen vollständigen Befehl mit vorausgefüllter ID, was der schnellste Weg ist, eine funktionierende Basislinie zu erhalten.

Wie halte ich das Token aus meinem Repository fern? Legen Sie es als Repository-Umgebungsvariable in der Travis-Web-Benutzeroberfläche fest, wobei die Anzeige im Build-Log deaktiviert ist, und referenzieren Sie es dann als $APIDOG_ACCESS_TOKEN in Ihrer Konfiguration. Alternativ können Sie travis encrypt verwenden, um einen verschlüsselten Wert in .travis.yml zu speichern. Committen Sie niemals das unverschlüsselte Token.

Wird der Build tatsächlich fehlschlagen, wenn ein Test fehlschlägt? Ja. Der Befehl apidog run beendet sich mit einem Nicht-Null-Wert, wenn eine Assertion fehlschlägt, und Travis behandelt jeden Nicht-Null-Exit in der script-Phase als fehlgeschlagenen Build. Unterdrücken Sie den Exit-Code einfach nicht mit || true. Verwenden Sie --on-error continue, wenn Sie jeden Fehler in einem einzigen Lauf gemeldet haben möchten und der Build dennoch fehlschlagen soll.

Kann ich Tests gegen mehrere Umgebungen oder mit mehreren Datensätzen ausführen? Ja. Verwenden Sie -e, um Umgebungen zu wechseln (Staging bei Push, Produktion bei einem nächtlichen Cron), -d, um eine CSV- oder JSON-Datendatei für datengesteuerte Iterationen einzuspeisen, und eine Travis-Build-Matrix, um mehrere Szenarien in parallelen Jobs auszuführen.

Kann ich dies verwenden, wenn ich nicht Travis CI nutze? Ja. Der CLI-Befehl ist plattformübergreifend identisch. Tauschen Sie das umgebende YAML für GitHub Actions, GitLab CI oder Jenkins aus, und die apidog run-Zeile bleibt dieselbe.

Zusammenfassung

API-Tests in Travis CI zu integrieren, läuft auf vier Schritte hinaus: Speichern Sie Ihr Zugriffstoken als verschlüsselte Variable, installieren Sie apidog-cli im Installationsschritt, führen Sie Ihr Szenario mit apidog run im Skriptschritt aus und lassen Sie den Build durch den Nicht-Null-Exit-Code fehlschlagen. Von dort aus fügen Sie HTML-Berichte, mehrere Umgebungen, datengesteuerte Iterationen und eine parallele Matrix hinzu, während Ihre Suite wächst.

Der Grund, dies mit einem dedizierten Runner statt mit einer Wand von curl-Aufrufen zu tun, ist die einzige Quelle der Wahrheit. Sie entwerfen und debuggen visuell und führen dann die Live-Version genau dieser Tests bei jedem Commit aus, ohne einen Exportschritt, der aus dem Takt geraten könnte. Ihre /checkout-Regression wird im Pull Request abgefangen, nicht in der Produktion.

Erstellen Sie Ihr erstes Testszenario, laden Sie dann Apidog herunter und binden Sie es in Ihren nächsten Push ein. Sobald der erste Build grün wird, wird jeder nachfolgende Commit mit einem Netz ausgeliefert.