Apidog CLI in Trae nutzen – Leitfaden

Trae arbeitet in einer Schleife: Der Builder-Agent liest Ihr Repository, bearbeitet Dateien, führt Terminalbefehle aus und wertet deren Ausgabe aus, um den nächsten Schritt zu bestimmen. API-Tests sollten Teil genau dieser Schleife sein — statt nur in einer grafischen Oberfläche in Apidog zu liegen und manuell gestartet zu werden.

Apidog noch heute ausprobieren

Die Umsetzung benötigt einen Konfigurationsblock: Die Apidog CLI (apidog-cli) führt Testszenarien aus Apidog direkt im Terminal aus. Sobald die CLI installiert ist und Trae die Projektregel kennt, kann der Builder API-Tests wie Unit-Tests behandeln: Befehl ausführen, Exit-Code prüfen und bei Fehlern nachbessern.

Falls die CLI noch nicht installiert ist, folgen Sie zuerst der Anleitung zur Installation der Apidog CLI mit einem KI-Coding-Agenten. Dieser Artikel setzt voraus, dass apidog --version eine Versionsnummer ausgibt und Ihr Apidog-Konto bereits authentifiziert ist.

Worum es bei diesem Trae geht

Trae ist die VS-Code-basierte KI-IDE von ByteDance. Ihr Agentenmodus Builder kann Dateien bearbeiten und Terminalbefehle ausführen. Details finden Sie auf der offiziellen Trae-Website. Dieser Artikel bezieht sich auf die Desktop-IDE, nicht auf das eigenständige GitHub-Projekt trae-agent.

Wenn Sie in Trae ein Chat-Panel neben dem Editor sehen und den Agenten auf Builder umstellen können, verwenden Sie die richtige Umgebung.

Der entscheidende Mechanismus sind Projektregeln. Sie machen aus einer einmaligen Chat-Anweisung wie „Führe meine Tests aus“ eine wiederverwendbare Vorgabe für jeden Builder-Lauf. Einen werkzeugunabhängigen Überblick bietet der vollständige Apidog-CLI-Leitfaden.

Schritt 1: Projektregeldatei anlegen

Trae lädt Regeldateien vor dem Start des Builder-Agenten. Laut Traes Dokumentation für Regeln gehört die projektweite Datei in Ihr Repository:

.trae/rules/project_rules.md

Erstellen Sie die Datei und hinterlegen Sie den Apidog-Befehl inklusive Regeln für die Auswertung:

## API testing with the Apidog CLI

When you change code that touches an API endpoint, verify it by running the
Apidog test scenario, not just the unit tests.

Command:
  apidog run -t <scenario_id> -e <env_id> -r cli

Rules:
- `apidog run` exits 0 when every assertion passes and non-zero on any failure.
  Treat a non-zero exit code as a failing test, even if the summary looks fine.
- This machine is already authenticated via `apidog login`. Never add an
  --access-token flag and never put a token in this file.
- If a flag is unknown, run `apidog run --help` and use the exact flag from there.

Ersetzen Sie später <scenario_id> und <env_id> durch Ihre tatsächlichen Werte.

Warum gehört diese Konfiguration in die Regeldatei statt in den Chat? Chat-Kontext verschwindet nach einer Sitzung. Die Datei .trae/rules/project_rules.md bleibt im Repository, gilt für Teammitglieder und wird bei künftigen Builder-Läufen erneut geladen.

In Monorepos können Sie zusätzlich .trae/rules/-Ordner in Unterverzeichnissen verwenden, um dienstspezifische API-Testregeln direkt neben dem jeweiligen Service zu speichern.

Schritt 2: Den korrekten Apidog-Befehl kopieren

Raten Sie Szenario- und Umgebungs-IDs nicht.

1. Öffnen Sie das gewünschte Testszenario in Apidog.
2. Wechseln Sie zum Tab CI/CD.
3. Kopieren Sie die generierte apidog run-Zeile.
4. Ersetzen Sie damit den Platzhalter-Befehl in .trae/rules/project_rules.md.

Der Befehl enthält bereits:

• -t für die Szenario-ID
• -e für die Umgebungs-ID
• die für das Szenario passende CLI-Syntax

Beispiel:

apidog run -t <scenario_id> -e <env_id> -r cli

Eine vollständige Übersicht der verfügbaren Optionen finden Sie in der Referenz für apidog run.

Schritt 3: Builder den API-Test ausführen lassen

Starten Sie den Builder in Ihrem Repository, nachdem die Regeldatei vorhanden ist. Bei der Initialisierung lädt Trae project_rules.md; der Agent kennt damit den vorgesehenen Testbefehl.

Sie können eine API-relevante Änderung vornehmen oder den Test explizit anfordern:

Run the Apidog test scenario and tell me the exit code.

Der Builder sollte den in der Regeldatei definierten apidog run-Befehl vorschlagen.

Traes Genehmigungsmodell bleibt dabei erhalten: Bevor der Agent einen Shell-Befehl ausführt, zeigt Trae den vorgeschlagenen Befehl mit einer Ausführen-Option an. Erst nach Ihrer Genehmigung läuft der Befehl im Terminal. Anschließend kann Builder die Ausgabe und den Exit-Code analysieren.

Der Reporter -r cli ist dafür wichtig: Er schreibt einzelne Schritte und die Zusammenfassung direkt ins Terminal. So kann Builder Requests, Assertions und Fehler unmittelbar auswerten.

Schritt 4: Fehlerberichte auswerten

Bei einem fehlgeschlagenen Lauf liefert -r cli die Details direkt in Traes Terminal:

• ausgeführte Requests
• erfolgreiche und fehlgeschlagene Assertions
• erwartete und tatsächliche Werte
• fehlerhafte Statuscodes oder Response-Felder

Diese Informationen reichen meist aus, damit Builder die betroffene Implementierung findet und gezielt korrigiert.

Wenn Sie zusätzlich einen im Browser teilbaren Bericht benötigen, ergänzen Sie den HTML-Reporter:

apidog run -t <scenario_id> -e <env_id> -r cli,html

Der html-Reporter erstellt eine eigenständige Datei unter:

./apidog-reports

Behalten Sie cli in der Reporter-Liste. Nur so steht die lesbare Inline-Ausgabe weiterhin im Terminal zur Verfügung, das Builder für seine Entscheidungen auswertet.

Weitere Reporter — einschließlich JSON und JUnit für CI-Dashboards — beschreibt der Leitfaden zu Apidog-CLI-Testberichten.

API-Tests in Builders Bearbeiten-Testen-Beheben-Schleife

Sobald die Regeldatei vorhanden ist, wird der Test Teil von Builders normalem Ablauf:

1. Builder ändert beispielsweise einen Checkout-Handler.
2. Builder führt das Apidog-Szenario gegen die konfigurierte Umgebung aus.
3. Builder prüft den Exit-Code.
4. Bei Exit-Code 0 arbeitet Builder weiter.
5. Bei einem Exit-Code ungleich 0 liest Builder die fehlgeschlagene Assertion.
6. Builder korrigiert den Code und führt den Test erneut aus.

Damit wird ein API-Test nicht erst nach dem Coding oder nach einem Deployment relevant. Er wird zum direkten Qualitäts-Gate innerhalb der Agentenschleife.

Dieses Vorgehen folgt dem Delegieren-und-Verifizieren-Modell: Builder führt Befehle aus und verarbeitet deren Ergebnisse; Sie erstellen und pflegen die Testszenarien weiterhin visuell in Apidog und prüfen stichprobenartig, ob Exit-Codes korrekt interpretiert werden.

Mehr zum übergeordneten Muster finden Sie unter KI-Agenten für API-Tests verwenden und im Artikel zum Apidog AI Test Harness.

Verifizieren, dass Trae die CLI wirklich ausführt

Verlassen Sie sich nicht nur auf eine textuelle Erfolgsmeldung des Agenten. Prüfen Sie drei Dinge.

1. Den ausgeführten Befehl im Terminal prüfen

Trae zeigt ausgeführte Befehle und ihre Ausgabe im Terminal an. Suchen Sie nach der tatsächlichen Zeile:

apidog run ...

Darunter sollte die CLI-Ausgabe stehen. Wenn Builder behauptet, Tests ausgeführt zu haben, aber kein entsprechender Terminalbefehl sichtbar ist, lassen Sie den Lauf wiederholen und fordern Sie die Rohausgabe an.

2. Exit-Code bestätigen

Fragen Sie Builder direkt:

What was the exit code of that apidog run command?

Die Regel ist eindeutig:

• Exit-Code 0: Alle Assertions waren erfolgreich.
• Exit-Code ungleich 0: Mindestens eine Assertion ist fehlgeschlagen.

Wenn eine textuelle Zusammenfassung „Tests bestanden“ sagt, der Exit-Code aber ungleich 0 ist, ist der Exit-Code maßgeblich.

3. Szenario- und Umgebungs-ID kontrollieren

Ein Fehler wie scenario not found deutet häufig darauf hin, dass Builder eine ID falsch erinnert oder erfunden hat.

Vergleichen Sie in diesem Fall die Werte für -t und -e mit:

• .trae/rules/project_rules.md
• dem von Apidog im CI/CD-Tab generierten Befehl

Die IDs in Ihrer Regeldatei sollten die verbindliche Quelle sein.

Optional: Apidog MCP-Server verbinden

Die Regeldatei mit apidog run deckt das Ausführen von Tests ab. Ein MCP-Server ergänzt dies um Zugriff auf API-Spezifikationen während der Implementierung.

Trae-Agenten können als MCP-Clients arbeiten. Um einen Server hinzuzufügen:

1. Öffnen Sie die Trae-Einstellungen.
2. Wechseln Sie zum Tab MCP.
3. Wählen Sie einen Server aus dem Marketplace oder Manuell hinzufügen.
4. Hinterlegen Sie die vom Server benötigten Felder command, args und env.

Die genaue Konfiguration beschreibt Traes Anleitung zum Hinzufügen von MCP-Servern.

Der Apidog MCP-Server stellt API-Spezifikationen über MCP bereit. Dadurch kann Builder Schema-Informationen bereits beim Schreiben des Codes nutzen.

Die Aufgabentrennung bleibt klar:

• Apidog CLI: führt Testszenarien aus
• MCP: stellt API-Spezifikationen für den Agenten bereit

Häufige Probleme und Korrekturen

Builder ignoriert die Regeldatei

Prüfen Sie den exakten Pfad:

.trae/rules/project_rules.md

Achten Sie darauf, dass der Ordner rules und nicht rule heißt und dass sich die Datei im Repository-Stammverzeichnis befindet. Starten Sie die Builder-Sitzung anschließend neu, damit die Regeln erneut geladen werden.

Builder fügt ein Access Token hinzu

Wenn Builder --access-token ergänzt, orientiert er sich vermutlich an öffentlichen Beispielen. Ihre Regeldatei sollte klar festlegen, dass die Maschine bereits mit folgendem Befehl authentifiziert ist:

apidog login

Speichern Sie kein echtes Token in project_rules.md. Informationen zur Authentifizierung für lokale Nutzung und CI finden Sie im Artikel zur Apidog-CLI-Authentifizierung.

Builder erfindet ein CLI-Flag

Bei unknown option verwendet Builder möglicherweise eine Option, die Ihre installierte CLI-Version nicht unterstützt.

Lassen Sie den Agenten zuerst die lokale Hilfe aufrufen:

apidog run --help

Verwenden Sie anschließend nur die dort dokumentierten Flags.

Builder meldet Erfolg trotz fehlgeschlagenem Lauf

Das ist der kritischste Fehler. Halten Sie deshalb die Exit-Code-Regel in project_rules.md fest und prüfen Sie den tatsächlichen Terminalstatus.

Bei einem Widerspruch gilt immer:

Exit-Code vor Textzusammenfassung.

Vom täglichen Agenten zur getesteten Schleife

Die Einrichtung besteht aus wenigen konkreten Schritten:

1. Installieren Sie apidog-cli gemäß der Installationsanleitung.
2. Erstellen Sie .trae/rules/project_rules.md.
3. Kopieren Sie den echten apidog run-Befehl aus dem CI/CD-Tab Ihres Apidog-Szenarios.
4. Definieren Sie Exit-Code und Authentifizierungsregeln.
5. Lassen Sie Builder den Test nach API-relevanten Änderungen ausführen.

Damit erkennt Builder defekte Endpunkte, während er noch an der Änderung arbeitet — nicht erst nach dem Deployment.

Sie erstellen Testszenarien weiterhin visuell in Apidog, während Builder sie über die CLI automatisiert ausführt. Laden Sie Apidog herunter, erstellen Sie ein Szenario, hinterlegen Sie den Befehl in .trae/rules/project_rules.md und prüfen Sie, ob Builder ihn bei der nächsten API-Änderung verwendet.

Für denselben Ablauf ohne Agenten behandelt Apidog CLI in GitHub Actions Geheimnisse, Reporter und Exit-Code-Gating in CI.