L'agent Cascade de Windsurf exécute une boucle : il édite des fichiers, exécute des commandes de terminal, lit la sortie et décide quoi faire ensuite. Alors pourquoi vos tests d'API ne sont-ils pas dans cette boucle ? Ils sont stockés dans Apidog derrière une interface graphique et ne sont exécutés que lorsque quelqu'un pense à cliquer. Cascade ne les touche jamais.
La solution est un seul bloc de configuration. L'interface de ligne de commande (CLI) d'Apidog est un package npm, apidog-cli, qui exécute les scénarios de test que vous avez créés dans Apidog directement depuis un terminal. Une fois la CLI installée et que Cascade sait qu'elle existe, Windsurf exécute un scénario Apidog de la même manière qu'il exécute vos tests unitaires : il lance la commande, lit le code de sortie, corrige le code s'il revient rouge.
Si vous n'avez pas encore installé la CLI, faites-le d'abord. Comment installer la CLI Apidog avec un agent de codage IA vous guide à travers l'installation npm, l'authentification et le premier lancement, avec un agent effectuant la saisie. Cet article suppose que apidog --version affiche un numéro et que votre compte Apidog est authentifié.
De quel Windsurf s'agit-il ?
Windsurf est l'IDE agentique de Codeium, et son agent intégré s'appelle Cascade. Cascade s'exécute localement, lit votre dépôt, modifie les fichiers et exécute des commandes shell dans votre terminal intégré, demandant une approbation en fonction de votre paramètre d'auto-exécution. Il s'agit de l'éditeur et de son agent, et non d'une extension de navigateur ou d'un plugin d'autocomplétion.
Si vous ne l'avez pas encore configuré, commencez par comment télécharger et installer Windsurf. Une fois que Cascade est ouvert dans votre projet, vous pouvez lui enseigner la CLI Apidog grâce à son propre mécanisme de règles, qui transforme un "exécuter mes tests" ponctuel en quelque chose que Cascade utilise de lui-même.
Étape 1 : Ajouter une règle Apidog à .windsurf/rules
Cascade lit les règles du projet à partir de fichiers Markdown avant de commencer à travailler. Placez-les dans un répertoire .windsurf/rules/ à la racine de votre dépôt, une règle par fichier. Windsurf lit toujours un ancien fichier unique .windsurfrules à la racine de l'espace de travail, et un fichier global ~/.codeium/windsurf/memories/global_rules.md qui s'applique à chaque projet, mais pour une instruction par projet, le répertoire .windsurf/rules/ est le bon emplacement. Ceci est documenté dans la référence des règles et mémoires de Windsurf.
Créez .windsurf/rules/apidog.md avec un bloc comme ceci :
# Tests API Apidog
Ce projet contient des scénarios de test Apidog. Exécutez-les avec la CLI Apidog :
apidog run -t <scenario_id> -e <env_id> -r cli
Règles :
- Utilisez la commande exacte ci-dessus ; n'inventez pas de drapeaux. Exécutez `apidog run --help` si vous n'êtes pas sûr.
- `apidog run` se termine avec 0 si toutes les assertions réussissent, et non-zéro si l'une d'elles échoue.
Considérez 0 comme succès et non-zéro comme échec. Signalez le code de sortie réel.
- La machine est déjà authentifiée via `apidog login`. N'ajoutez jamais de
jeton d'accès à la commande ni n'en commettez un dans ce fichier.
- Après avoir modifié du code qui affecte l'API, exécutez le scénario et agissez en fonction du résultat.
Pourquoi un fichier de règles plutôt qu'un message de chat ? Un ID de scénario tapé dans le chat disparaît à la fin de la session. Un ID dans .windsurf/rules/apidog.md est là pour chaque membre de l'équipe et chaque session Cascade à partir de maintenant. Il persiste, il est versionné dans Git, et Cascade le charge automatiquement dans le contexte au démarrage.
Étape 2 : Obtenir la commande depuis Apidog
Les <scenario_id> et <env_id> dans ce bloc ne sont pas des espaces réservés à deviner. Apidog génère la commande exacte pour vous.
Ouvrez le scénario de test dans Apidog, allez dans son onglet CI/CD, et copiez la commande apidog run prête à l'emploi. Elle contient déjà les ID de scénario, ID d'environnement et drapeaux de rapport corrects. Collez cette commande dans votre fichier .windsurf/rules/apidog.md à la place de la ligne d'exemple. Désormais, la règle contient une commande qui fonctionne réellement pour votre projet, et non un modèle.
Pour l'anatomie complète de cette commande et tous les drapeaux qu'elle accepte, consultez la référence de la commande apidog run.
Étape 3 : Demander à Cascade d'exécuter le test
Avec la règle en place, ouvrez Cascade dans votre dépôt. Il charge .windsurf/rules/apidog.md au démarrage, il sait donc déjà que la CLI est présente. Effectuez une modification qui affecte votre API, ou demandez-lui simplement d'exécuter la vérification :
Exécutez le scénario Apidog et dites-moi le code de sortie.
Cascade émet la commande apidog run de votre règle. L'exécution sans invite dépend de votre paramètre d'auto-exécution. Windsurf propose quatre niveaux : Désactivé (chaque commande nécessite une approbation), Liste Blanche Uniquement (seules les commandes correspondant à votre liste blanche s'exécutent automatiquement), Auto (un jugement de modèle premium), et Turbo (tout s'exécute automatiquement sauf les commandes en liste noire). En mode Turbo, un simple apidog run s'exécute seul ; dans les modes plus stricts, Cascade met en pause et demande d'abord.
Si vous souhaitez que apidog run s'exécute automatiquement sans tout assouplir, ajoutez-le à votre liste blanche. Le paramètre est windsurf.cascadeCommandsAllowList, accessible depuis la palette de commandes sous Ouvrir les paramètres ; ajoutez apidog et Cascade exécutera la commande sans demander. Le paramètre de liste noire correspondant est windsurf.cascadeCommandsDenyList, et la liste noire l'emporte lorsqu'une commande correspond aux deux. Les deux sont couverts dans la documentation du terminal de Windsurf. Un scénario en lecture seule contre l'environnement de staging est exactement le type de commande sûre, dans l'espace de travail, pour laquelle une entrée de liste blanche est conçue.
Étape 4 : Lire le rapport dans Windsurf
Quand une exécution échoue (devient rouge), le rapport contient la réponse. Le rapporteur -r cli affiche un résultat étape par étape et un résumé directement dans le terminal de Cascade : chaque requête, chaque assertion, et laquelle a échoué avec la valeur attendue par rapport à la valeur réelle. L'assertion échouée nomme le champ exact ou le code d'état, ce qui est généralement suffisant pour que Cascade trouve la correction lors de son prochain passage.
Pour un rapport que vous pouvez ouvrir dans un navigateur ou transmettre à un coéquipier, ajoutez le rapporteur HTML :
apidog run -t <scenario_id> -e <env_id> -r cli,html
Le rapporteur html écrit un fichier autonome dans ./apidog-reports. Conservez cli dans la liste afin que Cascade obtienne toujours la sortie en ligne qu'il lit pour décider de sa prochaine étape. Pour tous les rapporteurs, y compris le format JUnit que les tableaux de bord CI analysent, consultez le guide complet de la CLI Apidog et comment lire les rapports de test de la CLI Apidog.
Le test Windsurf dans sa propre boucle
L'intérêt est ce qui se passe lorsque vous arrêtez de demander et que Cascade exécute le scénario de lui-même parce que la règle le lui a dit.
Imaginez Cascade éditant un gestionnaire qui construit une réponse de paiement. Sa boucle change. Il édite le code, puis, au lieu de déclarer victoire, exécute votre scénario Apidog contre l'environnement de staging, lit le code de sortie et agit en conséquence. Vert, il passe à autre chose. Rouge, il ouvre le rapport, lit quelle assertion a échoué (le code d'état, le champ manquant, la mauvaise valeur), essaie une correction et relance. Le test d'API devient partie intégrante de la même boucle d'édition-test-correction que Cascade utilise déjà pour vos tests unitaires. Vous avez écrit une seule règle et Cascade a intégré la commande à son fonctionnement.
C'est le modèle "déléguer puis vérifier" qui sécurise tout flux de travail d'agent. Cascade exécute la commande et lit le résultat ; vous continuez à créer visuellement des scénarios dans Apidog et vérifiez que l'agent lit honnêtement les codes de sortie. Pour le modèle plus large, consultez comment utiliser les agents IA pour les tests d'API et le harnais de test IA Apidog.
Vérifier que Cascade exécute réellement la CLI
Les agents signalent des succès qu'ils n'ont pas mérités, et Cascade ne fait pas exception. Trois vérifications, classées par fréquence de détection des problèmes.
Premièrement, confirmez que la commande a bien été exécutée. Cascade affiche les commandes qu'il exécute et leur sortie directement dans le terminal. Recherchez la ligne littérale apidog run ... et un résultat en dessous. Si Cascade dit qu'il a exécuté les tests mais que vous ne voyez pas la commande, il a résumé quelque chose qu'il n'a jamais fait. Demandez-lui de l'exécuter à nouveau et de montrer la sortie brute.
Deuxièmement, confirmez le code de sortie, celui qui compte. Demandez-lui directement :
Quel était le code de sortie de cette commande apidog run ?
apidog run se termine avec 0 lorsque toutes les assertions réussissent et non-zéro lorsque quelque chose échoue. Ce comportement unique permet à Cascade, ou à un pipeline, de considérer l'exécution comme une porte claire. Lorsque le texte de Cascade dit "tests réussis" mais que le code de sortie est non-zéro, c'est le code de sortie qui est correct.
Troisièmement, confirmez qu'il a utilisé le scénario réel. Si une exécution échoue avec "scénario introuvable", Cascade a peut-être inventé ou mal mémorisé un ID. Revérifiez les valeurs -t et -e par rapport à votre fichier de règles et à la commande Apidog générée dans l'onglet CI/CD. Les ID dans .windsurf/rules/apidog.md sont la vérité.
Optionnel : connecter le serveur Apidog MCP
Exécuter apidog run depuis une règle couvre la plupart de vos besoins. Pour aller plus loin, connectez un serveur MCP.
Cascade prend en charge le protocole de contexte de modèle (MCP). Windsurf lit sa liste de serveurs depuis ~/.codeium/windsurf/mcp_config.json, que vous pouvez éditer directement ou gérer via le panneau MCP de Cascade ; le format est documenté dans la référence MCP de Windsurf, et comment configurer des serveurs MCP dans Windsurf explique le panneau. Le serveur MCP Apidog expose vos spécifications API via MCP, afin que Cascade puisse lire votre schéma pendant qu'il écrit du code, et pas seulement après coup. La répartition des tâches est claire : la CLI exécute les tests, et MCP fournit la spécification à l'agent.
Quand Windsurf se trompe
Quelques échecs apparaissent souvent lors de la configuration.
Il ignore la règle. Si Cascade exécute une commande générique ou aucune, la règle pourrait ne pas être chargée. Confirmez que le fichier se trouve dans .windsurf/rules/ à la racine de votre dépôt et qu'il a une extension .md. Chaque fichier de règles est limité à 12 000 caractères, alors gardez le bloc Apidog court. Le redémarrage de Cascade force une nouvelle lecture.
Il transmet un jeton d'accès quand même. Si Cascade essaie d'ajouter un jeton d'accès à la commande, il devine à partir d'exemples publics. Votre règle lui dit déjà de ne pas le faire, puisque la machine est authentifiée via apidog login. Renforcez la ligne, et ne mettez jamais un vrai jeton dans un fichier de règles qui est commité. Pour savoir comment l'authentification fonctionne réellement, consultez le guide d'authentification de la CLI Apidog.
Il invente un drapeau. Une erreur "option inconnue" signifie que Cascade a deviné un drapeau que votre version ne possède pas. Dites-lui d'exécuter apidog run --help et copiez le drapeau exact à partir de là, ce qui est toujours correct pour votre version installée.
Il signale un succès sur une exécution échouée. C'est le plus coûteux, et la raison pour laquelle la règle du code de sortie se trouve à la fois dans votre fichier de règles et dans votre étape de vérification. Lorsque le résumé et le code de sortie ne concordent pas, le code de sortie l'emporte.
D'un agent quotidien à une boucle testée
Voilà la configuration. Installez apidog-cli une fois en suivant le guide d'installation, ajoutez une courte règle Apidog au répertoire .windsurf/rules/ de votre dépôt, et Cascade saura comment exécuter vos tests API et lire le résultat à l'intérieur de la même boucle qu'il utilise déjà pour éditer le code. Un point de terminaison cassé est détecté pendant que Cascade travaille encore sur la modification, et non après son déploiement.
Un test derrière une interface graphique s'exécute quand un humain clique ; une commande d'une ligne s'exécute chaque fois que Cascade le décide. Vous continuez à construire des scénarios visuellement dans Apidog, et votre agent les exécute là où vous ne regardez pas. Pour exécuter la même commande dans un pipeline une fois qu'elle fonctionne localement, Apidog CLI dans GitHub Actions couvre les secrets, les rapporteurs et la gestion des codes de sortie. Téléchargez Apidog, construisez un scénario, insérez sa commande apidog run dans une règle Windsurf, et regardez Cascade la prendre en compte lors de la prochaine modification.