DEV Community

Cover image for Comment utiliser l'Apidog CLI avec Windsurf
Antoine Laurent
Antoine Laurent

Posted on • Originally published at apidog.com

Comment utiliser l'Apidog CLI avec Windsurf

L’agent Cascade de Windsurf travaille en boucle : il modifie des fichiers, exécute des commandes, lit leur sortie, puis décide de la prochaine action. Pour intégrer vos tests d’API à cette boucle, exposez-les via la CLI Apidog plutôt que de les laisser uniquement dans l’interface graphique. Le package npm apidog-cli permet d’exécuter les scénarios créés dans Apidog depuis le terminal ; Cascade peut alors interpréter le code de sortie comme pour vos tests unitaires.

Essayez Apidog dès aujourd’hui

Avant de continuer, vérifiez que la CLI est installée et authentifiée :

apidog --version
Enter fullscreen mode Exit fullscreen mode

Si nécessaire, suivez le guide d’installation de la CLI Apidog avec un agent de codage IA. Cet article part du principe que apidog --version retourne bien une version et que apidog login a déjà été exécuté.

De quel Windsurf s’agit-il ?

Windsurf est l’IDE agentique de Codeium. Son agent intégré, Cascade, peut lire le dépôt, modifier les fichiers et lancer des commandes shell dans le terminal intégré. Selon votre configuration d’auto-exécution, il peut demander une approbation avant chaque commande.

Si Windsurf n’est pas encore installé, consultez comment télécharger et installer Windsurf.

L’objectif est d’ajouter une règle de projet pour que Cascade connaisse la commande de test Apidog à exécuter après une modification qui affecte votre API.

Étape 1 : ajouter une règle Apidog dans .windsurf/rules

Cascade charge les règles du projet depuis des fichiers Markdown. Créez le répertoire suivant à la racine du dépôt :

.windsurf/rules/
Enter fullscreen mode Exit fullscreen mode

Ajoutez ensuite un fichier apidog.md :

.windsurf/rules/apidog.md
Enter fullscreen mode Exit fullscreen mode

Windsurf prend aussi en charge l’ancien fichier .windsurfrules à la racine et les règles globales dans ~/.codeium/windsurf/memories/global_rules.md. Pour une configuration spécifique au dépôt, préférez toutefois .windsurf/rules/.

La structure est documentée dans la référence des règles et mémoires de Windsurf.

Placez un bloc comme celui-ci dans .windsurf/rules/apidog.md :

# 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` en cas de doute.
- `apidog run` se termine avec 0 si toutes les assertions réussissent,
  et avec un code non nul si l'une d'elles échoue.
  Considérez 0 comme un succès et tout code non nul comme un échec.
  Signalez toujours 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 et n'en commettez jamais un ici.
- Après une modification de code qui affecte l'API, exécutez le scénario
  et agissez selon son résultat.
Enter fullscreen mode Exit fullscreen mode

Cette règle est plus fiable qu’une instruction donnée dans le chat :

  • elle persiste entre les sessions ;
  • elle est partagée avec l’équipe ;
  • elle peut être versionnée dans Git ;
  • Cascade la charge automatiquement au démarrage.

Étape 2 : récupérer la commande exacte depuis Apidog

Ne devinez pas les valeurs de <scenario_id> et <env_id>.

Dans Apidog :

  1. Ouvrez votre scénario de test.
  2. Accédez à l’onglet CI/CD.
  3. Copiez la commande apidog run générée.
  4. Remplacez la commande d’exemple dans .windsurf/rules/apidog.md.

La commande générée contient déjà les identifiants du scénario, de l’environnement et les options de rapport adaptées à votre projet.

Pour connaître tous les paramètres disponibles, consultez la référence de la commande apidog run.

Étape 3 : demander à Cascade d’exécuter le scénario

Une fois la règle en place, ouvrez Cascade dans votre dépôt et demandez-lui :

Exécutez le scénario Apidog et dites-moi le code de sortie.
Enter fullscreen mode Exit fullscreen mode

Cascade doit émettre la commande déclarée dans votre règle, par exemple :

apidog run -t <scenario_id> -e <env_id> -r cli
Enter fullscreen mode Exit fullscreen mode

Le comportement dépend du niveau d’auto-exécution configuré dans Windsurf :

  • Désactivé : chaque commande demande une approbation.
  • Liste blanche uniquement : seules les commandes autorisées s’exécutent automatiquement.
  • Auto : Windsurf décide selon son modèle.
  • Turbo : les commandes s’exécutent automatiquement, sauf celles de la liste noire.

Pour autoriser apidog run sans assouplir toutes les règles, ajoutez apidog à la liste blanche windsurf.cascadeCommandsAllowList.

La liste noire correspondante est windsurf.cascadeCommandsDenyList. Si une commande correspond aux deux listes, la liste noire est prioritaire.

Consultez la documentation du terminal Windsurf pour la configuration complète.

Un scénario en lecture seule contre un environnement de staging est un bon candidat pour une liste blanche.

Étape 4 : lire le rapport dans Windsurf

Le reporter cli affiche le détail de l’exécution directement dans le terminal de Cascade :

  • requêtes exécutées ;
  • assertions évaluées ;
  • valeurs attendues et réelles ;
  • code d’état ou champ ayant échoué ;
  • résumé final et code de sortie.

Une erreur d’assertion donne généralement à Cascade assez de contexte pour localiser la correction dans le code.

Pour générer aussi un rapport HTML, utilisez :

apidog run -t <scenario_id> -e <env_id> -r cli,html
Enter fullscreen mode Exit fullscreen mode

Le reporter html écrit un fichier autonome dans :

./apidog-reports
Enter fullscreen mode Exit fullscreen mode

Conservez cli même si vous ajoutez html : Cascade a besoin de la sortie terminal pour analyser le résultat pendant sa boucle de travail.

Pour les autres reporters, notamment JUnit pour les tableaux de bord CI, consultez :

Intégrer le test à la boucle de Cascade

Une fois la règle ajoutée, le flux devient concret :

  1. Cascade modifie un gestionnaire, un contrôleur ou une route API.
  2. Il exécute le scénario Apidog configuré.
  3. Il lit le code de sortie.
  4. Si le code vaut 0, il continue.
  5. Si le code est non nul, il lit l’assertion en échec.
  6. Il corrige le code, puis relance le scénario.

Par exemple, après une modification d’une réponse de paiement, un scénario peut détecter :

  • un code HTTP incorrect ;
  • un champ manquant ;
  • une valeur de réponse inattendue ;
  • une régression de contrat API.

Le scénario Apidog devient alors une étape de la même boucle édition-test-correction que les tests unitaires.

C’est une application pratique du modèle « déléguer puis vérifier » : l’agent exécute la commande, mais le code de sortie et le rapport restent la source de vérité.

Pour aller plus loin, consultez :

Vérifier que Cascade a réellement exécuté la CLI

Ne vous fiez pas uniquement au résumé de l’agent. Vérifiez ces trois points.

1. Vérifier la commande exécutée

Dans le terminal Cascade, recherchez la commande littérale :

apidog run ...
Enter fullscreen mode Exit fullscreen mode

Vous devez également voir sa sortie.

Si Cascade affirme avoir exécuté les tests sans afficher cette commande, demandez-lui de relancer le scénario et de montrer la sortie brute.

2. Vérifier le code de sortie

Demandez explicitement :

Quel était le code de sortie de cette commande apidog run ?
Enter fullscreen mode Exit fullscreen mode

Règle à retenir :

0       = toutes les assertions ont réussi
non nul = au moins une assertion a échoué
Enter fullscreen mode Exit fullscreen mode

Si le résumé affirme que les tests sont réussis mais que le code de sortie est non nul, considérez l’exécution comme un échec.

3. Vérifier les identifiants du scénario et de l’environnement

Une erreur du type « scénario introuvable » indique souvent un ID incorrect ou inventé.

Comparez les valeurs suivantes avec la commande générée dans l’onglet CI/CD d’Apidog :

-t <scenario_id>
-e <env_id>
Enter fullscreen mode Exit fullscreen mode

Le fichier .windsurf/rules/apidog.md doit contenir la commande de référence de votre projet.

Optionnel : connecter le serveur MCP Apidog

La règle et apidog run couvrent déjà la majorité des cas de test. Pour donner davantage de contexte à Cascade pendant l’implémentation, vous pouvez aussi connecter un serveur MCP.

Windsurf prend en charge le protocole MCP (Model Context Protocol). Sa configuration se trouve dans :

~/.codeium/windsurf/mcp_config.json
Enter fullscreen mode Exit fullscreen mode

Vous pouvez modifier ce fichier directement ou utiliser le panneau MCP de Cascade.

Références utiles :

La répartition des responsabilités reste simple :

CLI Apidog  → exécute les scénarios de test
MCP Apidog  → expose la spécification API à Cascade
Enter fullscreen mode Exit fullscreen mode

Résoudre les problèmes fréquents

Cascade ignore la règle

Vérifiez les points suivants :

✓ Le fichier est dans .windsurf/rules/
✓ Le fichier possède l’extension .md
✓ Le répertoire est à la racine du dépôt
✓ Le fichier ne dépasse pas 12 000 caractères
Enter fullscreen mode Exit fullscreen mode

Redémarrez ensuite Cascade pour forcer le rechargement des règles.

Cascade ajoute un jeton d’accès

La machine est déjà authentifiée avec :

apidog login
Enter fullscreen mode Exit fullscreen mode

Ne placez jamais un vrai jeton dans un fichier de règles commité. Si Cascade tente d’en ajouter un, renforcez l’instruction dans apidog.md et utilisez la commande générée par Apidog sans modifier son mécanisme d’authentification.

Consultez le guide d’authentification de la CLI Apidog.

Cascade invente un drapeau

Si vous obtenez une erreur comme unknown option, demandez à Cascade d’exécuter :

apidog run --help
Enter fullscreen mode Exit fullscreen mode

Utilisez uniquement les options affichées par votre version installée de la CLI.

Cascade signale un succès malgré un échec

Le code de sortie prévaut toujours sur le résumé textuel :

Résumé positif + code non nul = échec
Résumé négatif + code 0       = vérifier la sortie, mais le code est la référence
Enter fullscreen mode Exit fullscreen mode

Passer d’un agent quotidien à une boucle testée

La configuration tient en quelques étapes :

  1. Installez apidog-cli.
  2. Authentifiez la machine avec apidog login.
  3. Copiez la commande CI/CD de votre scénario Apidog.
  4. Ajoutez-la dans .windsurf/rules/apidog.md.
  5. Demandez à Cascade d’exécuter le scénario après les modifications API.
  6. Vérifiez systématiquement le code de sortie.

Vous continuez à construire les scénarios visuellement dans Apidog, tandis que Cascade les exécute depuis son terminal au moment où il modifie le code.

Quand la commande fonctionne localement, vous pouvez réutiliser la même logique dans votre pipeline. Consultez Apidog CLI dans GitHub Actions pour la gestion des secrets, des reporters et des codes de sortie.

Téléchargez Apidog, créez un scénario, ajoutez sa commande apidog run à une règle Windsurf, puis laissez Cascade l’intégrer à sa prochaine boucle de modification.

Top comments (0)