Der Cascade-Agent von Windsurf durchläuft eine Schleife: Er bearbeitet Dateien, führt Terminalbefehle aus, liest die Ausgabe und entscheidet, was als Nächstes zu tun ist. Warum sind Ihre API-Tests also nicht in dieser Schleife? Sie sitzen in Apidog hinter einer GUI und werden ausgeführt, wenn jemand daran denkt, zu klicken. Cascade berührt sie nie.
Die Lösung ist ein einziger Konfigurationsblock. Die Apidog CLI ist ein npm-Paket, `apidog-cli`, das die Test-Szenarien, die Sie in Apidog erstellt haben, direkt von einem Terminal aus ausführt. Sobald die CLI installiert ist und Cascade weiß, dass sie existiert, führt Windsurf ein Apidog-Szenario auf die gleiche Weise aus, wie es Ihre Unit-Tests ausführt: Befehl auslösen, Exit-Code lesen, den Code korrigieren, wenn er rot zurückkommt.
Wenn Sie die CLI noch nicht installiert haben, tun Sie dies zuerst. So installieren Sie die Apidog CLI mit einem KI-Code-Agenten beschreibt die npm-Installation, die Authentifizierung und den ersten Lauf, wobei ein Agent die Eingaben vornimmt. Dieser Artikel geht davon aus, dass `apidog --version` eine Zahl ausgibt und Ihr Apidog-Konto authentifiziert ist.
Worum es bei diesem Windsurf geht
Windsurf ist die agentenbasierte IDE von Codeium, und sein integrierter Agent heißt Cascade. Cascade läuft lokal, liest Ihr Repository, bearbeitet Dateien und führt Shell-Befehle in Ihrem integrierten Terminal aus, wobei es je nach Ihrer Einstellung zur automatischen Ausführung um Genehmigung bittet. Dies ist der Editor und sein Agent, keine Browser-Erweiterung oder ein Autocomplete-Plugin.
Wenn Sie es noch nicht eingerichtet haben, beginnen Sie mit dem Herunterladen und Installieren von Windsurf. Sobald Cascade in Ihrem Projekt geöffnet ist, können Sie es über seinen eigenen Regelmechanismus über die Apidog CLI informieren, wodurch ein einmaliges „Führe meine Tests aus“ zu etwas wird, das Cascade selbstständig aufruft.
Schritt 1: Eine Apidog-Regel zu .windsurf/rules hinzufügen
Cascade liest Projektregeln aus Markdown-Dateien, bevor es seine Arbeit aufnimmt. Legen Sie diese in einem `.windsurf/rules/`-Verzeichnis im Stammverzeichnis Ihres Repositorys ab, eine Regel pro Datei. Windsurf liest immer noch eine veraltete Einzeldatei `.windsurfrules` im Workspace-Stammverzeichnis und eine globale `~/.codeium/windsurf/memories/global_rules.md`, die für jedes Projekt gilt, aber für eine projektspezifische Anweisung ist das `.windsurf/rules/`-Verzeichnis der richtige Ort. Dies ist in der Windsurf-Regel- und Speicherreferenz dokumentiert.
Erstellen Sie `.windsurf/rules/apidog.md` mit einem Block wie diesem:
# 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 anstelle einer Chat-Nachricht? Eine in den Chat eingegebene Szenario-ID ist nach Beendigung der Sitzung verschwunden. Eine in `.windsurf/rules/apidog.md` ist von nun an für jeden Teamkollegen und jede Cascade-Sitzung vorhanden. Sie bleibt bestehen, wird in Git versioniert und Cascade lädt sie beim Start automatisch in den Kontext.
Schritt 2: Den Befehl von Apidog abrufen
Die `<scenario_id>` und `<env_id>` in diesem Block sind keine Platzhalter, die Sie erraten. Apidog generiert den genauen Befehl für Sie.
Öffnen Sie das Testszenario in Apidog, wechseln Sie zum CI/CD-Tab und kopieren Sie den vorgefertigten `apidog run`-Befehl. Er enthält bereits die korrekte Szenario-ID, Umgebungs-ID und Reporter-Flags. Fügen Sie diesen Befehl anstelle der Beispielzeile in Ihre `.windsurf/rules/apidog.md` ein. Nun enthält die Regel einen Befehl, der tatsächlich in Ihrem Projekt funktioniert, und kein Template.
Für die vollständige Anatomie dieses Befehls und aller akzeptierten Flags siehe die apidog run-Befehlsreferenz.
Schritt 3: Cascade den Test ausführen lassen
Nachdem die Regel eingerichtet ist, öffnen Sie Cascade in Ihrem Repo. Es lädt `.windsurf/rules/apidog.md` beim Start, sodass es bereits weiß, dass die CLI vorhanden ist. Nehmen Sie eine Änderung vor, die Ihre API betrifft, oder bitten Sie es einfach, die Überprüfung auszuführen:
Run the Apidog scenario and tell me the exit code.
Cascade gibt den `apidog run`-Befehl aus Ihrer Regel aus. Ob er ohne Aufforderung ausgeführt wird, hängt von Ihrer Einstellung zur automatischen Ausführung ab. Windsurf bietet vier Stufen: Deaktiviert (jeder Befehl benötigt Genehmigung), Nur Positivliste (nur Befehle, die Ihrer Positivliste entsprechen, werden automatisch ausgeführt), Auto (eine Premium-Modell-Einschätzung) und Turbo (alles wird automatisch ausgeführt, außer Befehle auf der Sperrliste). Im Turbo-Modus wird ein einfacher `apidog run` von selbst ausgeführt; in den strengeren Modi pausiert Cascade und fragt zuerst.
Wenn Sie möchten, dass `apidog run` automatisch ausgeführt wird, ohne alles zu lockern, fügen Sie es Ihrer Positivliste hinzu. Die Einstellung ist `windsurf.cascadeCommandsAllowList`, erreichbar über die Befehlspalette unter „Einstellungen öffnen“; fügen Sie `apidog` hinzu, und Cascade führt den Befehl ohne Nachfrage aus. Die entsprechende Sperrlisten-Einstellung ist `windsurf.cascadeCommandsDenyList`, und die Sperrliste gewinnt, wenn ein Befehl beidem entspricht. Beide sind in der Windsurf-Terminal-Dokumentation beschrieben. Ein schreibgeschütztes Szenario gegen Staging ist genau die Art von sicherem, In-Workspace-Befehl, für den ein Eintrag in der Positivliste gedacht ist.
Schritt 4: Den Bericht in Windsurf lesen
Wenn ein Lauf fehlschlägt (rot wird), enthält der Bericht die Antwort. Der `-r cli`-Reporter druckt ein Schritt-für-Schritt-Ergebnis und eine Zusammenfassung direkt im Terminal von Cascade: jede Anfrage, jede Assertion und welche davon mit erwartetem versus tatsächlichem Wert fehlgeschlagen ist. Die fehlerhafte Assertion benennt das genaue Feld oder den Statuscode, was normalerweise ausreicht, damit Cascade beim nächsten Durchlauf die Korrektur findet.
Für einen Bericht, den Sie in einem Browser öffnen oder einem Teamkollegen übergeben können, fügen Sie den HTML-Reporter hinzu:
apidog run -t <scenario_id> -e <env_id> -r cli,html
Der `html`-Reporter schreibt eine eigenständige Datei nach `./apidog-reports`. Behalten Sie `cli` in der Liste, damit Cascade weiterhin die Inline-Ausgabe erhält, die es liest, um seinen nächsten Schritt zu entscheiden. Für jeden Reporter, einschließlich des JUnit-Formats, das CI-Dashboards parsen, siehe den vollständigen Apidog CLI-Leitfaden und wie man Apidog CLI-Testberichte liest.
Windsurf-Tests in der eigenen Schleife
Der Punkt ist, was passiert, wenn Sie aufhören zu fragen und Cascade das Szenario von selbst ausführt, weil die Regel es so angewiesen hat.
Stellen Sie sich vor, Cascade bearbeitet einen Handler, der eine Checkout-Antwort erstellt. Seine Schleife ändert sich. Es bearbeitet den Code, dann, anstatt den Sieg zu erklären, führt es Ihr Apidog-Szenario gegen Staging aus, liest den Exit-Code und handelt danach. Grün, es geht weiter. Rot, es öffnet den Bericht, liest, welche Assertion fehlgeschlagen ist (der Statuscode, das fehlende Feld, der falsche Wert), versucht eine Korrektur und führt es erneut aus. Der API-Test wird Teil derselben Bearbeiten-Testen-Beheben-Schleife, die Cascade bereits für Ihre Unit-Tests durchläuft. Sie haben eine Regel geschrieben und Cascade hat den Befehl in seine bestehende Arbeitsweise integriert.
Dies ist das Delegieren-dann-Verifizieren-Modell, das jeden Agenten-Workflow sicher macht. Cascade führt den Befehl aus und liest das Ergebnis; Sie erstellen weiterhin Szenarien visuell in Apidog und überprüfen stichprobenartig, ob der Agent die Exit-Codes ehrlich liest. Für das breitere Muster siehe wie man KI-Agenten für API-Tests verwendet und das Apidog AI-Testharness.
Überprüfen Sie, ob Cascade die CLI tatsächlich ausführt
Agenten melden Erfolge, die sie nicht verdient haben, und Cascade ist keine Ausnahme. Drei Prüfungen, in der Reihenfolge ihrer Häufigkeit, Probleme zu erkennen.
Bestätigen Sie zuerst, dass der Befehl überhaupt ausgeführt wurde. Cascade zeigt die von ihm ausgeführten Befehle und deren Ausgabe direkt im Terminal an. Suchen Sie nach der wörtlichen Zeile `apidog run ...` und einem Ergebnis darunter. Wenn Cascade sagt, es habe die Tests ausgeführt, Sie aber den Befehl nicht sehen, hat es etwas zusammengefasst, was es nie getan hat. Bitten Sie es, es erneut auszuführen und die Rohausgabe anzuzeigen.
Zweitens, bestätigen Sie den Exit-Code, den, der zählt. Fragen Sie direkt:
What was the exit code of that apidog run command?
`apidog run` beendet mit 0, wenn jede Assertion erfolgreich ist, und mit einem Wert ungleich 0, wenn etwas fehlschlägt. Dieses einzige Verhalten ermöglicht es Cascade oder einer Pipeline, den Lauf als sauberes Gate zu behandeln. Wenn Cascades Prosa besagt „Tests bestanden“, der Exit-Code aber ungleich 0 ist, hat der Exit-Code Recht.
Drittens, bestätigen Sie, dass es das echte Szenario verwendet hat. Wenn ein Lauf mit „Szenario nicht gefunden“ fehlschlägt, hat Cascade möglicherweise eine ID erfunden oder falsch in Erinnerung behalten. Überprüfen Sie die Werte von `-t` und `-e` erneut mit Ihrer Regeldatei und dem von Apidog im CI/CD-Tab generierten Befehl. Die IDs in `.windsurf/rules/apidog.md` sind die Wahrheit.
Optional: Den Apidog MCP-Server verbinden
Das Ausführen von `apidog run` aus einer Regel deckt das meiste ab, was Sie benötigen. Um noch einen Schritt weiter zu gehen, verbinden Sie einen MCP-Server.
Cascade unterstützt das Model Context Protocol. Windsurf liest seine Serverliste aus `~/.codeium/windsurf/mcp_config.json`, die Sie direkt bearbeiten oder über das Cascade MCP-Panel verwalten können; das Format ist in Windsurfs MCP-Referenz dokumentiert, und wie man MCP-Server in Windsurf einrichtet führt durch das Panel. Der Apidog MCP-Server stellt Ihre API-Spezifikationen über MCP bereit, sodass Cascade Ihr Schema lesen kann, während es Code schreibt, und nicht erst nachträglich. Die Arbeitsteilung ist sauber: Die CLI führt die Tests aus, und MCP speist den Agenten mit der Spezifikation.
Wenn Windsurf es falsch macht
Einige Fehler treten während der Einrichtung häufig auf.
Es ignoriert die Regel. Wenn Cascade einen generischen Befehl oder gar keinen ausführt, lädt die Regel möglicherweise nicht. Vergewissern Sie sich, dass die Datei in `.windsurf/rules/` im Stammverzeichnis Ihres Repositorys liegt und die Erweiterung `.md` hat. Jede Regeldatei ist auf 12.000 Zeichen begrenzt, halten Sie den Apidog-Block also kurz. Ein Neustart von Cascade erzwingt ein erneutes Einlesen.
Es übergibt trotzdem ein Zugriffstoken. Wenn Cascade versucht, dem Befehl ein Zugriffstoken hinzuzufügen, rät es aus öffentlichen Beispielen. Ihre Regel sagt ihm bereits, dies nicht zu tun, da die Maschine über `apidog login` authentifiziert ist. Verstärken Sie die Zeile und legen Sie niemals ein echtes Token in eine Regeldatei, die committet wird. Wie die Authentifizierung tatsächlich funktioniert, siehe den Apidog CLI-Authentifizierungsleitfaden.
Es erfindet ein Flag. Ein „unbekannte Option“-Fehler bedeutet, dass Cascade ein Flag erraten hat, das Ihre Version nicht besitzt. Sagen Sie ihm, es soll `apidog run --help` ausführen und kopieren Sie das genaue Flag von dort, das immer korrekt für Ihre installierte Version ist.
Es meldet einen Erfolg bei einem fehlgeschlagenen Lauf. Dies ist der kostspieligste Fehler und der Grund, warum die Exit-Code-Regel sowohl in Ihrer Regeldatei als auch in Ihrem Überprüfungsschritt enthalten ist. Wenn die Zusammenfassung und der Exit-Code nicht übereinstimmen, gewinnt der Exit-Code.
Vom täglichen Agenten zur getesteten Schleife
Das ist die Einrichtung. Installieren Sie `apidog-cli` einmal gemäß dem Installationsleitfaden, fügen Sie eine kurze Apidog-Regel zum `.windsurf/rules/`-Verzeichnis Ihres Repos hinzu, und Cascade weiß, wie es Ihre API-Tests ausführt und das Ergebnis in derselben Schleife liest, die es bereits zum Bearbeiten von Code verwendet. Ein fehlerhafter Endpunkt wird erkannt, während Cascade noch an der Änderung arbeitet, nicht erst, nachdem sie ausgeliefert wurde.
Ein Test hinter einer GUI läuft, wenn ein Mensch klickt; ein Ein-Zeilen-Befehl läuft, wann immer Cascade es entscheidet. Sie erstellen weiterhin Szenarien visuell in Apidog, und Ihr Agent führt sie aus, wo Sie nicht zusehen. Um denselben Befehl in einer Pipeline auszuführen, sobald er lokal funktioniert, deckt Apidog CLI in GitHub Actions die Geheimnisse, Reporter und die Exit-Code-Absicherung ab. Laden Sie Apidog herunter, erstellen Sie ein Szenario, fügen Sie den `apidog run`-Befehl in eine Windsurf-Regel ein und beobachten Sie, wie Cascade ihn bei der nächsten Änderung aufgreift.