Anleitung: Automatisierte API-Tests in TeamCity ausführen

Ihre API besteht jeden Test auf Ihrem Laptop. Dann führt ein Teamkollege einen Branch zusammen, der ein Feld umbenennt, und niemand bemerkt es, bis ein mobiler Client in der Produktion abstürzt. Manuelle Tests haben dies übersehen, weil niemand die Suite erneut ausgeführt hat. Genau diese Lücke soll Continuous Integration schließen, und TeamCity ist eines der stärksten Tools, um dies zu erreichen.

TeamCity, der CI/CD-Server von JetBrains, führt Ihre Build-Pipeline jedes Mal aus, wenn Code eingecheckt wird. Er kann kompilieren, testen, packen und bereitstellen, ohne dass jemand einen Knopf drücken muss. Was Teams jedoch oft vergessen, ist die Integration echter API-Tests in diese Pipeline. Sie testen Einheiten, sie testen, ob der Build kompiliert, und sie liefern die API auf Vertrauen aus. Ein umbenanntes Feld, ein 500er-Fehler in einem Grenzfall, ein fehlerhafter Authentifizierungsfluss – nichts davon wird sichtbar, bevor ein Mensch den Endpunkt aufruft.

Dieser Leitfaden führt Sie Schritt für Schritt durch die Ausführung automatisierter API-Tests in TeamCity. Sie entwerfen und validieren Ihre Tests in Apidog und führen sie dann über die Apidog CLI als TeamCity-Build-Schritt "headless" aus. Das Ergebnis ist eine Pipeline, die den Build fehlschlagen lässt, sobald Ihre API sich nicht wie erwartet verhält, noch bevor eine fehlerhafte Antwort einen Benutzer erreicht.

Was Sie erstellen werden

Am Ende werden Sie haben:

• Ein TeamCity-Projekt, das mit Ihrem Git-Repository verbunden ist
• Eine Build-Konfiguration mit einem VCS-Trigger, der bei jedem Push ausgelöst wird
• Einen Build-Schritt, der Ihre API-Testsuite über die Apidog CLI ausführt
• Geparsste Testergebnisse, die auf der Registerkarte "Tests" in TeamCity sichtbar sind
• Einen Build, der rot wird und das Mergen blockiert, wenn ein Endpunkt fehlerhaft ist

Das gleiche Muster funktioniert für einen kleinen internen Dienst oder eine öffentliche API mit Hunderten von Endpunkten. Sie skalieren es, indem Sie Testszenarien in Apidog hinzufügen, nicht indem Sie den Pipeline-Code bearbeiten.

Warum API-Tests in TeamCity gehören, nicht nur auf Ihren Rechner

Lokale Tests haben einen fatalen Fehler: Sie hängen davon ab, dass sich jemand daran erinnert, sie auszuführen. CI entfernt den Menschen aus dem Kreislauf. Jeder Commit löst dieselbe Suite in derselben Umgebung mit denselben Zusicherungen aus. Es gibt kein "es funktioniert auf meinem Rechner", weil es keinen Rechner gibt; es gibt einen Build-Agent, der genau die von Ihnen definierten Schritte ausführt.

TeamCity eignet sich aus mehreren konkreten Gründen gut dafür:

• Build-Ketten. Sie können den API-Testschritt von einem Deploy-to-Staging-Schritt abhängig machen, sodass Tests immer gegen einen frisch bereitgestellten Build ausgeführt werden und nie gegen einen veralteten.
• Testhistorie. TeamCity verfolgt, welche Tests über Hunderte von Builds hinweg bestanden und fehlgeschlagen sind. Wenn ein Test zu "flaky" (unzuverlässig) wird, sehen Sie genau, welcher Commit ihn eingeführt hat.
• Untersuchung und Stummschaltung. Ein unzuverlässiger Endpunkt kann stummgeschaltet und einem Besitzer zugewiesen werden, anstatt alle Merges zu blockieren.
• Agent-Pools. Umfangreiche Suiten laufen auf dedizierten Agenten, damit sie Ihre Kompilierungs-Builds nicht verlangsamen.

Der Haken ist, dass TeamCity nicht weiß, wie es Ihre API aufrufen oder die Antwort überprüfen soll. Es führt jeden Befehl aus, den Sie ihm geben. Die eigentliche Aufgabe besteht also darin, einen einzelnen Befehl zu erstellen, der Ihre gesamte API-Suite ausführt und mit einem Code ungleich Null beendet wird, wenn etwas fehlschlägt. Hier kommt das Testdesign ins Spiel.

Schritt 1: Entwerfen und validieren Sie Ihre API-Tests in Apidog

Bevor irgendetwas TeamCity berührt, benötigen Sie Tests, die tatsächlich unbeaufsichtigt ausgeführt werden. Ein Test, bei dem Sie eine JSON-Antwort überprüfen müssen, ist in CI nutzlos. Jede Überprüfung muss eine Assertion sein, die die Maschine auswerten kann: Der Statuscode ist 200, das Feld id ist eine Zahl, die Antwort kam in weniger als 800 ms zurück.

Apidog wurde genau dafür entwickelt. Sie entwerfen die Anfrage und fügen dann API-Assertions hinzu, die die Antwort automatisch validieren: Statuscodes, JSON-Schema-Konformität, spezifische Feldwerte, Antwortzeit. Sie können Anfragen zu einem Szenario verketten, sodass die Ausgabe eines Login-Aufrufs den Token in die nächste Anfrage einspeist. Für die gängigen Fälle ist kein Scripting erforderlich, und bei Bedarf steht ein vollständiges Scripting zur Verfügung.

Ein realistisches Szenario für eine E-Commerce-API könnte so aussehen:

1. POST /auth/login mit Test-Anmeldeinformationen, Assertion 200, Extrahieren des Bearer-Tokens in eine Variable.
2. GET /products?category=books mit diesem Token, Assertion 200, Assertion, dass die Antwort ein Array ist, Assertion, dass jedes Element einen price größer als 0 hat.
3. POST /cart/items mit einer Produkt-ID, Assertion 201, Assertion, dass die zurückgegebene Gesamtsumme des Warenkorbs dem Artikelpreis entspricht.
4. GET /cart, Assertion, dass die Artikelanzahl 1 ist.

Jeder Schritt hat Assertions, die eigenständig bestanden oder fehlschlagen. Führen Sie das Szenario zuerst in Apidog aus und bestätigen Sie, dass es in Ihrer Staging-Umgebung grün ist. Wenn es nicht bestanden werden kann, wenn Sie es manuell ausführen, wird es niemals in CI bestanden. Gruppieren Sie verwandte Szenarien zu einer Testsuite, damit Sie das Ganze mit einem Befehl statt Szenario für Szenario ausführen können.

Der Vorteil dieser Art von Testerstellung ist, dass dieselben Szenarien, die Sie für die manuelle Fehlersuche verwenden, zu Ihrer CI-Suite werden. Sie pflegen nicht zwei parallele Testsätze; einen in einer GUI zur Exploration, einen im Code zur Automatisierung. Es ist eine einzige Quelle der Wahrheit. Wenn Sie von einem Code-First-Framework wie REST Assured kommen, spart dieser Teil die meiste Zeit: Sie hören auf, Boilerplate-Anforderungs-/Assertionscode für jeden Endpunkt zu schreiben und neu zu schreiben.

Laden Sie Apidog herunter, wenn Sie mitmachen möchten. Es ist kostenlos, und die CLI ist Teil derselben Toolchain.

Schritt 2: Die Apidog CLI zuerst lokal zum Laufen bringen

Debuggen Sie einen neuen Befehl niemals zum ersten Mal in CI. Die Feedback-Schleife in einem CI-Server ist brutal; Sie pushen, warten auf einen Agenten, lesen ein Log, korrigieren ein Zeichen, pushen erneut. Beweisen Sie, dass der Befehl auf Ihrem Rechner funktioniert, und kopieren Sie dann die funktionierende Version in TeamCity.

Die Apidog CLI läuft auf Node.js, also installieren Sie sie global mit npm:

npm install -g apidog-cli

Bestätigen Sie die Installation:

apidog --version

Führen Sie nun Ihr Testszenario aus. Die CLI kann ein Szenario oder eine Suite direkt aus Ihrem Apidog-Projekt ausführen, indem sie dessen ID referenziert, mit einem Zugriffstoken authentifiziert oder aus einer lokal exportierten Datei. Der Online-Ansatz hält Ihre Tests als einzige Quelle der Wahrheit; was Ihr Team in Apidog bearbeitet, läuft in CI, ohne dass ein Exportschritt vergessen werden muss.

Erzeugen Sie ein Zugriffstoken in Ihren Apidog-Kontoeinstellungen und führen Sie dann aus:

apidog run \
 --access-token "$APIDOG_ACCESS_TOKEN" \
 -e "$APIDOG_ENV_ID" \
 -r cli,html,junit

Ein paar Dinge, die hier zu beachten sind:

• --access-token authentifiziert den Lauf. Geben Sie es direkt so an, oder melden Sie sich einmal mit apidog login --with-token an.
• -e wählt die Umgebung aus, gegen die getestet werden soll; Staging, schreibgeschützte Produktion, was auch immer Sie in Apidog definiert haben. Sie richten dieselben Tests auf verschiedene Basis-URLs aus, indem Sie diese ID wechseln.
• -r wählt die Reporter. cli gibt menschenlesbare Ausgabe auf der Konsole aus, html erzeugt einen Bericht, den Sie durchsuchen können, und ein JUnit-Format-Bericht ermöglicht TeamCity das Parsen und Anzeigen individueller Testergebnisse.

Wenn der Lauf beendet ist, beendet die CLI mit 0, wenn alles bestanden wurde, und ungleich Null, wenn eine Assertion fehlschlug. Dieser Exit-Code ist das ganze Spiel in CI: Ein Exit-Code ungleich Null weist TeamCity an, den Build als fehlgeschlagen zu markieren.

Für Tests, die über viele Eingaben hinweg ausgeführt werden müssen, unterstützt die CLI datengesteuerte Läufe. Zeigen Sie sie auf eine CSV- oder JSON-Datei, und sie iteriert das Szenario einmal pro Zeile:

apidog run \
 --access-token "$APIDOG_ACCESS_TOKEN" \
 -d test-data/checkout-cases.csv \
 -r cli,junit

So testen Sie hundert Produkt-IDs oder eine Tabelle ungültiger Nutzlasten, ohne hundert Szenarien schreiben zu müssen. Jede Zeile wird zu ihrer eigenen Iteration mit ihrem eigenen Pass/Fail-Ergebnis.

Sobald Sie lokal eine grüne Ausgabe sehen, haben Sie einen Befehl, dem Sie vertrauen. Kopieren Sie ihn. Genau dieser Befehl wird in TeamCity eingefügt.

Schritt 3: TeamCity mit Ihrem Repository verbinden

Wechseln Sie nun zu TeamCity. Ziel dieses Schritts ist es, TeamCity ein Projekt zu geben, es auf Ihren Code zu verweisen und ihm zu ermöglichen, Builds bei jedem Push auszulösen.

Wenn Sie TeamCity zum ersten Mal ausführen, ist der einfachste Weg das offizielle Docker-Image. Damit erhalten Sie in wenigen Minuten einen funktionierenden Server:

docker run -d --name teamcity-server \
 -v ~/teamcity/datadir:/data/teamcity_server/datadir \
 -v ~/teamcity/logs:/opt/teamcity/logs \
 -p 8111:8111 \
 jetbrains/teamcity-server

Öffnen Sie `http://localhost:8111`, schließen Sie die Ersteinrichtung ab (Datenbankauswahl, Admin-Konto) und Sie landen auf dem Dashboard. Produktions-Setups verwenden eine richtige externe Datenbank und dedizierte Build-Agenten, aber für diesen Leitfaden ist der gebündelte Agent ausreichend.

Erstellen Sie das Projekt:

1. Gehen Sie zu "Administration" und wählen Sie "Create project".
2. Wählen Sie "From a repository URL" und fügen Sie Ihre Git-Remote-Adresse ein (HTTPS oder SSH).
3. Fügen Sie Anmeldeinformationen hinzu, falls das Repository privat ist; einen Deploy-Key oder ein persönliches Zugriffstoken.
4. TeamCity scannt das Repository und muss Build-Schritte automatisch erkennen. Sie können es zulassen, aber für API-Tests ist es sauberer, den Schritt im nächsten Abschnitt selbst zu konfigurieren.

TeamCity erstellt einen VCS-Root (seine Verbindung zu Ihrem Repository) und eine Build-Konfiguration (die Menge der auszuführenden Schritte). Sobald der VCS-Root eingerichtet ist, richten Sie den Trigger so ein, dass Builds automatisch ausgelöst werden:

1. Öffnen Sie Ihre Build-Konfiguration und gehen Sie zu "Triggers".
2. Fügen Sie einen "VCS Trigger" hinzu.
3. Belassen Sie die Standardregel, sodass jede Änderung an dem überwachten Branch einen Build in die Warteschlange stellt.

Von nun an wird jeder Push in Ihr Repository einen Build auslösen. Im Moment tut dieser Build nichts Nützliches; der nächste Schritt gibt ihm den API-Testbefehl.

Schritt 4: Die Apidog CLI als Build-Schritt hinzufügen

Dies ist der Kern des Setups. Sie fügen einen Build-Schritt hinzu, der die CLI auf dem Agenten installiert und Ihre Suite ausführt.

In Ihrer Build-Konfiguration öffnen Sie "Build Steps" und fügen einen neuen Schritt vom Typ "Command Line" hinzu. Wählen Sie "Custom script" und fügen Sie ein:

#!/bin/bash
set -e

# Install the Apidog CLI on the build agent
npm install -g apidog-cli

# Run the API test suite and emit a JUnit report for TeamCity
apidog run \
 --access-token "%env.APIDOG_ACCESS_TOKEN%" \
 -e "%env.APIDOG_ENV_ID%" \
 -r cli,junit \
 --out-dir reports

Das ist derselbe Befehl, den Sie lokal bewiesen haben, mit zwei Änderungen für CI. Erstens, `set -e` lässt das Skript bei jedem Fehler abbrechen. Zweitens werden die Geheimnisse als TeamCity-Parameter (`%env.APIDOG_ACCESS_TOKEN%`) referenziert, anstatt fest codiert zu sein; diese werden Sie als Nächstes definieren.

Wenn Ihr Build-Agent noch kein Node.js hat, installieren Sie es früher in der Kette oder verwenden Sie ein Agent-Image, das es enthält. Die offiziellen TeamCity-Agent-Docker-Images und die meisten Cloud-Agent-Pools werden mit verfügbarem Node ausgeliefert. Sie können den gesamten Schritt auch in einem Node-Container ausführen, indem Sie den Schritt so einstellen, dass er in einem Docker-Image wie `node:20` ausgeführt wird.

Ein wichtiges Detail, das beachtet werden sollte: Die CLI muss nachdem Ihre API bereitgestellt und erreichbar ist, ausgeführt werden. Wenn TeamCity einen Dienst testet, der gerade auf Staging bereitgestellt wurde, machen Sie den Test-Build von dem Deploy-Build abhängig, indem Sie eine Snapshot-Abhängigkeit oder eine Build-Kette verwenden. Dies stellt sicher, dass die Tests immer die Version der API treffen, die dieser Commit produziert hat, niemals die vorherige.

Schritt 5: Geheimnisse als TeamCity-Parameter speichern

Ihr Zugriffstoken ist eine Anmeldeinformation. Es gehört nicht in das Build-Skript, in Ihr Repository oder in das Build-Log. TeamCity bietet dafür einen erstklassigen Platz.

1. In Ihrer Build-Konfiguration (oder dem übergeordneten Projekt, um es über Konfigurationen hinweg zu teilen) öffnen Sie "Parameters".
2. Fügen Sie einen neuen Parameter mit dem Namen env.APIDOG_ACCESS_TOKEN hinzu.
3. Stellen Sie dessen Spezifikation auf "Password" ein. Dies maskiert den Wert in der Benutzeroberfläche und entfernt ihn aus den Build-Logs.
4. Fügen Sie Ihr Apidog-Zugriffstoken als Wert ein.
5. Fügen Sie env.APIDOG_ENV_ID auf dieselbe Weise mit Ihrer Umgebungs-ID hinzu (diese ist nicht geheim, aber wenn Sie sie als Parameter speichern, können Sie Umgebungen ändern, ohne das Skript bearbeiten zu müssen).

Wenn Sie diese auf Projektebene und nicht auf Build-Konfigurationsebene definieren, erbt jeder API-Test-Build unter diesem Projekt sie. Rotieren Sie das Token einmal, und jede Pipeline übernimmt den neuen Wert.

Ein Passwort-Parameter macht den Unterschied zwischen einem Token, das sicher in TeamCity lebt, und einem, das in eine Logdatei sickert, die das ganze Team lesen kann. Behandeln Sie es so, wie Sie ein Datenbankpasswort behandeln würden.

Schritt 6: Testergebnisse auf der TeamCity-Registerkarte "Tests" anzeigen

Ein Build, der einfach rot wird, sagt Ihnen, dass etwas kaputt ist. Ein Build, der anzeigt, welcher Test kaputt ist, sagt Ihnen, wo Sie suchen müssen. Das ist es, was der JUnit-Bericht Ihnen gibt.

Der `-r junit`-Reporter schreibt eine XML-Datei im JUnit-Format, dem Standard-CI-Testresultat-Format, das TeamCity nativ lesen kann. Sie weisen TeamCity mit einer "XML Report Processing"-Build-Funktion auf diese Datei hin.

1. Öffnen Sie "Build has" in Ihrer Build-Konfiguration.
2. Fügen Sie "XML report processing" hinzu.
3. Stellen Sie den Berichtstyp auf "Ant JUnit" ein.
4. Stellen Sie den Überwachungspfad so ein, dass er Ihrer Ausgabe entspricht, zum Beispiel `reports/*.xml`.

Führen Sie einen Build aus. Öffnen Sie ihn und klicken Sie auf die Registerkarte "Tests". Sie sehen jedes Szenario und jede Assertion als individuellen Test mit Pass/Fail-Status und Zeitangaben. Wenn ein Test fehlschlägt, zeigt TeamCity die Fehlermeldung inline an, verknüpft sie mit dem Commit, der sie eingeführt hat, und verfolgt sie über zukünftige Builds hinweg. Wenn derselbe Test zweimal hintereinander fehlschlägt, kann TeamCity ihn als neuen Fehler statt als unzuverlässigen Fehler kennzeichnen.

Dies ist der Lohn für die frühere Wahl der JUnit-Ausgabe. Ohne sie ist ein Fehler ein roter Build und eine Wand aus Konsolentext. Damit erhalten Sie eine strukturierte, durchsuchbare Testhistorie, die "der API-Build ist kaputt" in "die Warenkorb-Gesamt-Assertion ist im Commit `a3f9c2` fehlgeschlagen" verwandelt.

Schritt 7: Den Build fehlschlagen lassen und den Merge blockieren

Der Sinn und Zweck all dessen ist es, das Mergen von fehlerhaftem Code zu verhindern. Zwei Dinge bewirken das.

Zuerst der Exit-Code. Da die Apidog CLI bei jeder fehlgeschlagenen Assertion einen Wert ungleich Null zurückgibt und Ihr Skript `set -e` verwendet, lässt ein fehlerhafter Test den Build-Schritt fehlschlagen, was wiederum den Build fehlschlagen lässt. Sie müssen nichts extra konfigurieren; ein roter API-Test ist standardmäßig ein roter Build.

Zweitens, die Merge-Sperre. Wenn Ihr Team mit Pull- oder Merge-Requests arbeitet, konfigurieren Sie Ihren Git-Host (GitHub, GitLab, Bitbucket) so, dass die TeamCity-Prüfung vor dem Mergen bestanden werden muss. TeamCity meldet seinen Build-Status über eine "Commit Status Publisher"-Build-Funktion an den Commit zurück:

1. Fügen Sie die Build-Funktion Commit Status Publisher hinzu.
2. Wählen Sie Ihren VCS-Hosting-Anbieter aus.
3. Fügen Sie ein Zugriffstoken hinzu, damit TeamCity Statusmeldungen posten kann.

Nun öffnet ein Mitwirkender einen PR, TeamCity führt die API-Suite gegen seinen Branch aus, und der Merge-Button bleibt deaktiviert, bis die Suite grün ist. Das Szenario des umbenannten Feldes vom Anfang dieses Leitfadens wird hier, im Branch, abgefangen, bevor es jemals den Main-Branch erreicht.

Eine realistische vollständige Pipeline

Zusammenfassend sieht eine funktionierende Build-Konfiguration für eine API-Test-Pipeline so aus:

• VCS-Root, der auf Ihr Repository verweist, mit einem VCS-Trigger auf dem Hauptbranch und PR-Branches.
• Build-Schritt 1: Bereitstellung des Dienstes in einer Staging-Umgebung (oder Start in einem Docker-Container auf dem Agenten).
• Build-Schritt 2: Der Apidog CLI-Befehl aus Schritt 4, der Ihre Suite gegen diese Staging-Umgebung ausführt.
• Build-Funktionen: XML-Berichtsverarbeitung, die `reports/*.xml` liest.
• Build-Funktionen: Commit Status Publisher, der Status an Ihren Git-Host zurückmeldet.
• Parameter: `env.APIDOG_ACCESS_TOKEN` (Passwort) und `env.APIDOG_ENV_ID`.

Für Teams, die ihre gesamte CI-Konfiguration in der Versionskontrolle verwalten, unterstützt TeamCity die Definition all dessen in einer Kotlin DSL (.teamcity/settings.kts), die im Repository committet wird, anstatt durch die Benutzeroberfläche zu klicken. Der Build-Schritt ist so oder so derselbe apidog run-Befehl; die DSL beschreibt die Konfiguration lediglich als Code, sodass sie zusammen mit allem anderen überprüft und versioniert wird.

Sie können die Suite nicht nur bei jedem Push ausführen. Fügen Sie einen "Schedule Trigger" hinzu, um die vollständige Regression Suite jede Nacht gegen die Staging-Umgebung auszuführen. So fangen Sie Abweichungen ab, die zwischen Commits auftreten; eine geänderte Drittanbieter-Abhängigkeit, eine Datenbank, die in einen seltsamen Zustand geraten ist. Nächtliche API-Läufe sind eine günstige Absicherung und verhindern, dass der erste Commit des Morgens die kaputte Umgebung des Vortags erbt.

Wie dies im Vergleich zu anderen CI-Plattformen abschneidet

Das hier beschriebene Muster ist übertragbar. Der Befehl, der Ihre Tests ausführt (apidog run mit einem Zugriffstoken und einem JUnit-Reporter), ist identisch, egal welcher CI-Server ihn aufruft. Nur der "Wrapper" ändert sich:

• In GitHub Actions würden Sie denselben Befehl in einen Workflow-YAML-Schritt einfügen. Wir behandeln dies in So automatisieren Sie API-Tests in GitHub Actions.
• In Jenkins geht es in eine Jenkinsfile-Stage. Siehe So integrieren Sie automatisierte Apidog-Tests mit Jenkins für CI/CD.
• Die übergeordnete Strategie über jede Plattform hinweg finden Sie unter So automatisieren Sie API-Tests in CI/CD.

Wenn Sie noch einen CI-Server auswählen, zeigt unser Vergleich der besten CI/CD-Tools auf, wo TeamCity im Vergleich zu den Alternativen steht. Die Stärken von TeamCity sind seine Build-Ketten, die detaillierte Testhistorie und die Kotlin DSL; es ist eine gute Wahl für Teams, die bereits im JetBrains-Ökosystem sind oder komplexe mehrstufige Pipelines betreiben.

Häufige Probleme und wie man sie behebt

Der Build findet den Befehl apidog nicht. Node.js ist nicht auf dem Agenten installiert, oder das globale npm-Bin-Verzeichnis ist nicht im PATH des Agenten. Fügen Sie einen Node-Installationsschritt früher in der Kette hinzu oder führen Sie den Schritt in einem node:20 Docker-Image aus.

Tests bestehen lokal, schlagen aber in CI mit Verbindungsfehlern fehl. Der Build-Agent kann Ihre API nicht erreichen. Eine Staging-URL, die sich auf dem VPN Ihres Laptops auflösen lässt, ist möglicherweise von einem Cloud-Agenten aus nicht erreichbar. Bestätigen Sie, dass die von Ihnen mit -e ausgewählte Umgebung auf einen Host verweist, den der Agent tatsächlich erreichen kann, und dass alle erforderlichen Netzwerkzugriffs- oder Firewall-Regeln den Agenten abdecken.

Authentifizierung schlägt nur in CI fehl. Überprüfen Sie, ob der Passwort-Parameter genau so geschrieben ist, wie das Skript ihn referenziert, und ob das Token nicht abgelaufen ist. Ein häufiger Fehler ist das Definieren von APIDOG_ACCESS_TOKEN, während das Skript %env.APIDOG_ACCESS_TOKEN% liest; das Präfix env. ist wichtig.

Tests sind unzuverlässig (flaky); sie bestehen und schlagen bei demselben Code fehl. Dies ist normalerweise ein Problem mit dem Timing oder der Datenreihenfolge. Verwenden Sie die Antwortzeit-Assertions von Apidog, um langsame Endpunkte aufzudecken, und stellen Sie sicher, dass jedes Szenario seine eigenen Daten einrichtet und wieder entfernt, damit die Läufe nicht von den Überresten anderer abhängen. Die Stummschaltungs- und Untersuchungsfunktion von TeamCity ermöglicht es Ihnen, einen unzuverlässigen Test zu isolieren, damit er nicht alle blockiert, während Sie die Ursache beheben.

Die Registerkarte "Tests" ist leer, obwohl der Build ausgeführt wurde. Der Pfad zur Verarbeitung der XML-Berichte stimmt nicht mit dem Ort überein, an dem die CLI den Bericht geschrieben hat. Bestätigen Sie, dass `--out-dir` im Befehl und der Überwachungspfad in der Build-Funktion auf denselben Ort zeigen.

FAQ

Muss ich Code schreiben, um API-Tests in TeamCity auszuführen? Nein. Sie entwerfen die Tests visuell in Apidog mit Assertions, und der einzige „Code“ in TeamCity ist der einzeilige apidog run-Befehl in einem Command Line-Build-Schritt. Das ist der Hauptunterschied zu einem Code-First-Ansatz wie REST Assured, bei dem jeder Endpunkt handgeschriebenen Anforderungs- und Assertionscode benötigt.

Kann ich die Tests in verschiedenen Umgebungen ausführen? Ja. Definieren Sie jede Umgebung (Staging, Pre-Prod, schreibgeschützte Produktion) in Apidog und wechseln Sie dann die Umgebung, die in CI ausgeführt wird, indem Sie den Parameter `-e` (Umgebungs-ID) ändern. Dieselben Tests laufen gegen jede Umgebung, indem sie auf eine andere Basis-URL zeigen.

Wie bewahre ich mein Zugriffstoken in TeamCity sicher auf? Speichern Sie es als TeamCity-Parameter mit der Spezifikation "Password". Dadurch wird es in der Benutzeroberfläche maskiert und aus den Build-Logs entfernt. Hardcodieren Sie es niemals in das Build-Skript oder committen Sie es in Ihr Repository. Definieren Sie es auf Projektebene, damit Sie es einmal für alle Pipelines rotieren können.

Wird ein fehlgeschlagener API-Test tatsächlich ein Mergen blockieren? Ja, mit zwei Komponenten. Die Apidog CLI beendet mit einem Code ungleich Null bei jeder fehlgeschlagenen Assertion, was den TeamCity-Build fehlschlagen lässt. Fügen Sie die Build-Funktion „Commit Status Publisher“ hinzu und fordern Sie die Überprüfung in den Branch-Schutzregeln Ihres Git-Hosts an, und der Merge-Button bleibt deaktiviert, bis die Suite bestanden wurde.

Was ist der Unterschied zwischen dem Online-Ausführen von Tests und dem Ausführen aus einer exportierten Datei? Das Online-Ausführen über Projekt-ID und Zugriffstoken bedeutet, dass Ihre Tests in Apidog die einzige Quelle der Wahrheit sind; was das Team bearbeitet, wird in CI ausgeführt. Das Ausführen aus einer exportierten Datei bindet die Tests an eine im Repository committete Version. Online ist einfacher synchron zu halten; exportiert bietet Tests, die mit dem Code reisen. Die meisten Teams beginnen online.

Kann ich die vollständige Regression Suite nach einem Zeitplan statt bei jedem Push ausführen? Ja. Fügen Sie einen Zeitplan-Trigger zur Build-Konfiguration hinzu, um sie nächtlich (oder stündlich) gegen die Staging-Umgebung auszuführen. Viele Teams führen bei jedem Push eine schnelle Smoke-Suite aus und die vollständige Regression Suite nach einem nächtlichen Zeitplan, sodass schnelles Feedback und umfassende Abdeckung nicht um dieselben Minuten konkurrieren.

Zusammenfassung

Eine TeamCity-Pipeline, die Ihre API-Tests bei jedem Commit ausführt, verändert die Wirtschaftlichkeit eines fehlerhaften Endpunkts. Anstatt dass ein Kunde den Fehler findet, findet ihn der Build; im Branch, vor dem Merge, mit der exakten fehlgeschlagenen Assertion und dem Commit, der sie verursacht hat, übersichtlich auf der Registerkarte "Tests" dargestellt.

Das Setup läuft auf drei bewegliche Teile hinaus: Tests mit echten Assertions, die Sie in Apidog erstellen, ein einziger apidog run-Befehl, der sie headless ausführt und bei Fehler einen Wert ungleich Null zurückgibt, und eine TeamCity-Build-Konfiguration, die diesen Befehl ausführt, die JUnit-Ergebnisse parst und den Status an Ihren Git-Host zurückmeldet. Sobald dies eingerichtet ist, pflegen Sie die Abdeckung, indem Sie Szenarien in Apidog hinzufügen, nicht indem Sie den Pipeline-Code anfassen.

Laden Sie Apidog herunter, um Ihre erste Testsuite zu entwerfen, den CLI-Befehl lokal zu testen und ihn dann in TeamCity einzubinden. Von diesem Zeitpunkt an wird Ihre API bei jedem einzelnen Commit auf dieselbe Weise getestet, egal ob sich jemand daran erinnert, sie auszuführen oder nicht.