Wie man die Apidog CLI in Windsurf verwendet

Der Cascade-Agent von Windsurf arbeitet in einer Schleife: Dateien bearbeiten, Terminalbefehle ausführen, Ausgabe lesen und den nächsten Schritt bestimmen. Wenn Ihre API-Tests nur hinter der Apidog-GUI liegen, fehlen sie in dieser Schleife – sie werden nur ausgeführt, wenn jemand manuell klickt.

Teste Apidog noch heute

Die Lösung ist ein Konfigurationsblock im Repository. Die Apidog CLI (apidog-cli) führt Test-Szenarien, die Sie in Apidog erstellt haben, direkt im Terminal aus. Sobald die CLI installiert ist und Cascade die Regel kennt, behandelt Windsurf API-Tests wie Unit-Tests: Befehl starten, Exit-Code prüfen und bei einem Fehler den Code korrigieren.

Installieren Sie die CLI zuerst, falls sie noch nicht verfügbar ist. So installieren Sie die Apidog CLI mit einem KI-Code-Agenten beschreibt npm-Installation, Authentifizierung und den ersten Lauf. Dieses Tutorial setzt voraus, dass der folgende Befehl eine Versionsnummer ausgibt und Ihr Konto bereits authentifiziert ist:

apidog --version

Worum es bei diesem Windsurf-Setup geht

Windsurf ist die agentenbasierte IDE von Codeium. Der integrierte Agent heißt Cascade und kann lokal im Repository Dateien lesen und ändern sowie Shell-Befehle im integrierten Terminal ausführen.

Wenn Windsurf noch nicht eingerichtet ist, starten Sie mit dem Herunterladen und Installieren von Windsurf. Anschließend geben Sie Cascade über Projektregeln eine dauerhafte Anweisung, Ihre Apidog-Szenarien auszuführen.

Schritt 1: Apidog-Regel in .windsurf/rules anlegen

Cascade lädt Projektregeln aus Markdown-Dateien. Legen Sie diese im Repository-Stamm unter .windsurf/rules/ ab, idealerweise eine Regel pro Datei.

Windsurf unterstützt außerdem die ältere Datei .windsurfrules im Workspace-Stamm sowie globale Regeln in ~/.codeium/windsurf/memories/global_rules.md. Für eine versionskontrollierte, projektspezifische Integration ist .windsurf/rules/ der passende Ort. Details finden Sie in der Windsurf-Referenz für Regeln und Memories.

Erstellen Sie die Datei .windsurf/rules/apidog.md:

# Apidog API tests

This project has Apidog test scenarios. Run them with the Apidog CLI:

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

Rules:
- Use the exact command above; do not invent flags. Run `apidog run --help` if unsure.
- `apidog run` exits 0 when every assertion passes, non-zero when any fails.
  Treat exit 0 as pass and non-zero as fail. Report the real exit code.
- The machine is already authenticated via `apidog login`. Never add an
  access token to the command or commit one to this file.
- After you change code that touches the API, run the scenario and act on the result.

Warum eine Regeldatei statt einer Chat-Anweisung?

• Sie bleibt über Cascade-Sitzungen hinweg erhalten.
• Das Team kann sie gemeinsam in Git versionieren.
• Cascade lädt sie beim Start automatisch in seinen Kontext.
• Szenario-ID, Umgebung und erwartetes Verhalten stehen direkt beim Code.

Schritt 2: Den echten apidog run-Befehl übernehmen

Ersetzen Sie <scenario_id> und <env_id> nicht durch geschätzte Werte. Apidog generiert den vollständigen Befehl für das konkrete Szenario.

1. Öffnen Sie das Testszenario in Apidog.
2. Wechseln Sie zum Tab CI/CD.
3. Kopieren Sie den erzeugten apidog run-Befehl.
4. Ersetzen Sie die Beispielzeile in .windsurf/rules/apidog.md durch diesen Befehl.

Der kopierte Befehl enthält bereits die richtige Szenario-ID, Umgebungs-ID und Reporter-Konfiguration. Damit verwendet Cascade keinen generischen Platzhalter, sondern einen reproduzierbaren Befehl für Ihr Projekt.

Eine Übersicht zu Syntax und Flags finden Sie in der Referenz für den Befehl apidog run.

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

Öffnen Sie Cascade im Repository, nachdem die Regeldatei erstellt wurde. Ändern Sie dann einen API-relevanten Teil des Codes oder fordern Sie den Test explizit an:

Run the Apidog scenario and tell me the exit code.

Cascade sollte den in der Regel definierten apidog run-Befehl verwenden.

Ob der Befehl sofort oder erst nach Bestätigung läuft, hängt von den Einstellungen für die automatische Befehlsausführung ab:

• Deaktiviert: Jeder Befehl benötigt eine Genehmigung.
• Nur Positivliste: Nur erlaubte Befehle werden automatisch ausgeführt.
• Auto: Windsurf entscheidet anhand einer Modellbewertung.
• Turbo: Befehle werden automatisch ausgeführt, sofern sie nicht gesperrt sind.

Wenn apidog run ohne Rückfrage laufen soll, ohne die globale Sicherheit zu lockern, fügen Sie apidog zur Positivliste hinzu:

{
  "windsurf.cascadeCommandsAllowList": [
    "apidog"
  ]
}

Die Einstellung ist über die Befehlspalette unter Einstellungen öffnen erreichbar. Beachten Sie: windsurf.cascadeCommandsDenyList hat Vorrang, wenn ein Befehl gleichzeitig auf beiden Listen steht.

Weitere Details stehen in der Windsurf-Terminal-Dokumentation. Für ein schreibgeschütztes Szenario gegen Staging ist eine gezielte Positivlisten-Regel ein sinnvoller Anwendungsfall.

Schritt 4: Terminalbericht und Exit-Code auswerten

Der CLI-Reporter gibt das Ergebnis direkt im Terminal aus:

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

Bei einem Fehlschlag zeigt die Ausgabe unter anderem:

• ausgeführte Requests,
• Assertions,
• erwartete und tatsächliche Werte,
• fehlerhafte Statuscodes oder Felder,
• den resultierenden Exit-Code.

Cascade kann diese Ausgabe als Grundlage für den nächsten Korrekturschritt verwenden. Entscheidend ist dabei der Exit-Code:

• 0: Alle Assertions waren erfolgreich.
• Ungleich 0: Mindestens eine Assertion ist fehlgeschlagen.

Für einen teilbaren HTML-Bericht ergänzen Sie den Reporter:

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

Der html-Reporter schreibt einen eigenständigen Bericht nach ./apidog-reports. Lassen Sie cli aktiviert, damit Cascade die Terminalausgabe weiterhin lesen kann.

Informationen zu weiteren Reportern, einschließlich JUnit für CI-Dashboards, finden Sie im vollständigen Apidog CLI-Leitfaden und in der Anleitung zum Lesen von Apidog CLI-Testberichten.

API-Tests in Cascades Arbeitsablauf integrieren

Der Nutzen entsteht, wenn Cascade den Test nicht nur auf Anfrage, sondern nach API-relevanten Änderungen selbst ausführt.

Ein typischer Ablauf sieht so aus:

1. Cascade ändert beispielsweise einen Checkout-Handler.
2. Cascade startet das konfigurierte Apidog-Szenario gegen die Zielumgebung.
3. Der Agent liest Exit-Code und Testausgabe.
4. Bei Exit-Code 0 fährt er mit der Aufgabe fort.
5. Bei einem Fehler prüft er die fehlgeschlagene Assertion.
6. Er passt den Code an und führt das Szenario erneut aus.

Damit wird der API-Test Teil derselben Bearbeiten-Testen-Korrigieren-Schleife wie lokale Unit-Tests.

Das bleibt ein Delegieren-und-Verifizieren-Workflow: Cascade führt den Befehl aus und interpretiert die Ausgabe, während Sie Szenarien weiterhin visuell in Apidog erstellen und die Ergebnisse stichprobenartig kontrollieren. Mehr zum übergeordneten Ansatz finden Sie unter KI-Agenten für API-Tests verwenden und im Artikel zum Apidog AI-Testharness.

Prüfen, ob Cascade die CLI wirklich ausgeführt hat

Agenten können einen Erfolg zusammenfassen, ohne dass der zugrunde liegende Befehl tatsächlich ausgeführt wurde. Prüfen Sie deshalb diese drei Punkte.

1. Wurde der Befehl ausgeführt?

Suchen Sie im Terminal nach der vollständigen Befehlszeile:

apidog run ...

Darunter sollte die tatsächliche CLI-Ausgabe stehen. Wenn Cascade behauptet, der Test sei gelaufen, aber kein Befehl sichtbar ist, fordern Sie eine erneute Ausführung mit Rohausgabe an.

2. Welchen Exit-Code hatte der Lauf?

Fragen Sie Cascade direkt:

What was the exit code of that apidog run command?

Verlassen Sie sich bei einem Widerspruch immer auf den Exit-Code, nicht auf die Zusammenfassung des Agenten:

Exit code 0      → Test bestanden
Exit code != 0   → Test fehlgeschlagen

3. Wurde das richtige Szenario verwendet?

Ein Fehler wie „Szenario nicht gefunden“ deutet oft darauf hin, dass eine ID falsch oder erfunden ist. Vergleichen Sie die Werte von -t und -e mit:

• Ihrer Datei .windsurf/rules/apidog.md
• dem von Apidog im CI/CD-Tab generierten Befehl

Die Regeldatei sollte immer den verifizierten Befehl enthalten.

Optional: Apidog MCP-Server verbinden

Die CLI deckt das Ausführen und Bewerten der Tests ab. Mit einem MCP-Server kann Cascade zusätzlich API-Spezifikationen beim Schreiben von Code lesen.

Windsurf unterstützt das Model Context Protocol und lädt die Serverkonfiguration aus:

~/.codeium/windsurf/mcp_config.json

Sie können die Datei direkt bearbeiten oder das Cascade-MCP-Panel verwenden. Die Konfiguration ist in der Windsurf-MCP-Referenz beschrieben. Eine praktische Anleitung für das Panel finden Sie unter MCP-Server in Windsurf einrichten.

Der Apidog MCP-Server stellt API-Spezifikationen über MCP bereit. Die Aufgabenteilung ist klar:

• Apidog CLI: Führt Test-Szenarien aus und liefert Exit-Code sowie Reports.
• Apidog MCP-Server: Gibt Cascade Zugriff auf das API-Schema während der Implementierung.

Häufige Fehler und schnelle Korrekturen

Cascade ignoriert die Regel

Prüfen Sie diese Punkte:

• Die Datei liegt unter .windsurf/rules/ im Repository-Stamm.
• Die Datei endet auf .md.
• Die Apidog-Regel bleibt kurz; einzelne Regeldateien sind auf 12.000 Zeichen begrenzt.
• Starten Sie Cascade neu, damit die Regeln erneut geladen werden.

Cascade fügt ein Zugriffstoken hinzu

Wenn Cascade ein Token an apidog run anhängt, übernimmt es vermutlich ein öffentliches Beispiel. Die Regeldatei sollte explizit festlegen:

The machine is already authenticated via `apidog login`.
Never add an access token to the command or commit one to this file.

Speichern Sie niemals echte Tokens in einer versionierten Regeldatei. Details zur Anmeldung finden Sie im Apidog CLI-Authentifizierungsleitfaden.

Cascade erfindet ein CLI-Flag

Ein Fehler wie „unbekannte Option“ bedeutet, dass ein Flag nicht zur installierten CLI-Version passt. Lassen Sie Cascade zuerst die lokale Hilfe ausführen:

apidog run --help

Verwenden Sie anschließend nur die dort dokumentierten Flags.

Cascade meldet Erfolg bei einem fehlgeschlagenen Lauf

Das ist der kritischste Fehler. Erzwingen Sie daher in der Regeldatei und bei manuellen Prüfungen dieselbe Logik:

Exit code 0      → bestanden
Exit code != 0   → fehlgeschlagen

Wenn Zusammenfassung und Exit-Code nicht übereinstimmen, gilt immer der Exit-Code.

Vom täglichen Agenten zur getesteten API-Schleife

Die Einrichtung besteht aus wenigen Schritten:

1. Installieren Sie apidog-cli gemäß dem Installationsleitfaden.
2. Authentifizieren Sie die lokale Umgebung mit apidog login.
3. Erstellen Sie .windsurf/rules/apidog.md.
4. Fügen Sie den von Apidog erzeugten apidog run-Befehl ein.
5. Lassen Sie Cascade nach API-Änderungen den Test ausführen und den Exit-Code prüfen.

So wird ein fehlerhafter Endpoint erkannt, während Cascade noch an der Änderung arbeitet – nicht erst nach dem Deployment.

Sie erstellen Test-Szenarien weiterhin visuell in Apidog; Cascade führt sie automatisiert im Repository aus. Sobald der lokale Befehl zuverlässig funktioniert, können Sie ihn auch in CI übernehmen. Apidog CLI in GitHub Actions behandelt dafür Secrets, Reporter und Exit-Code-Absicherung.

Apidog herunterladen, ein Szenario erstellen, den generierten apidog run-Befehl in die Windsurf-Regel einfügen und Cascade beim nächsten API-Change testen lassen.