Comment utiliser la CLI Apidog dans Trae

Trae fonctionne en boucle : son agent Builder lit votre référentiel, modifie des fichiers, exécute des commandes dans le terminal et analyse leur sortie pour décider de l’étape suivante. Pourquoi vos tests API restent-ils en dehors de cette boucle ? S’ils sont uniquement dans l’interface graphique d’Apidog, ils ne s’exécutent que lorsqu’une personne pense à cliquer. Votre agent ne les exécute jamais.

Essayez Apidog dès aujourd’hui

La solution tient dans un fichier de configuration. La CLI d’Apidog, distribuée via le package npm apidog-cli, exécute les scénarios de test créés dans Apidog depuis un terminal. Une fois la CLI installée et déclarée dans les règles de Trae, Builder peut lancer un scénario Apidog comme vos tests unitaires : il exécute la commande, lit le code de sortie et corrige le code si le test échoue.

Si vous n’avez pas encore installé la CLI, commencez par là. Ce guide d’installation de la CLI Apidog avec un agent de codage IA couvre l’installation npm, l’authentification et la première exécution. Cet article suppose que apidog --version retourne une version et que votre compte Apidog est déjà authentifié.

De quel Trae parle-t-on ?

Trae est l’IDE IA de ByteDance, basé sur VS Code. Son mode agent, Builder, peut modifier des fichiers et exécuter des commandes de terminal de manière autonome. Consultez les détails sur le site officiel de Trae.

Cet article concerne l’IDE de bureau Trae, pas le projet de recherche autonome trae-agent sur GitHub. Si vous avez un panneau de discussion près de votre éditeur et pouvez activer le mode Builder, vous utilisez le bon produit.

Cette distinction est importante : Trae dispose de son propre mécanisme pour charger les règles d’un projet. C’est ce qui transforme une demande ponctuelle — « exécute mes tests » — en comportement réutilisable par Builder.

Pour une approche indépendante de Trae, consultez également le guide complet de la CLI Apidog.

Étape 1 : ajouter les règles du projet

Trae lit les fichiers de règles avant que Builder commence à travailler. Le fichier de règles au niveau du projet se trouve ici :

.trae/rules/project_rules.md

Placez-le à la racine du référentiel, conformément à la documentation des règles de Trae.

Builder charge ces règles à l’initialisation et s’y réfère lorsqu’il génère ou modifie du code. Trae prend aussi en charge un fichier global user_rules.md, mais un fichier de projet est préférable pour stocker les commandes et identifiants propres à un dépôt.

Créez .trae/rules/project_rules.md, puis ajoutez un bloc explicite :

## Tests API avec la CLI Apidog

Lorsque vous modifiez du code qui touche un point de terminaison API, vérifiez-le
en exécutant le scénario de test Apidog, et pas seulement les tests unitaires.

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

Règles :
- `apidog run` sort avec le code 0 lorsque toutes les assertions passent et non-zéro en cas d'échec.
  Traitez un code de sortie non-zéro comme un test échoué, même si le résumé semble correct.
- Cette machine est déjà authentifiée via `apidog login`. N'ajoutez jamais de
  flag --access-token et ne mettez jamais de jeton dans ce fichier.
- Si un flag est inconnu, exécutez `apidog run --help` et utilisez le flag exact à partir de là.

Ajoutez la commande au fichier de règles, pas seulement au chat :

• un ID de scénario écrit dans une conversation disparaît à la fin de la session ;
• .trae/rules/project_rules.md reste disponible pour chaque membre de l’équipe ;
• Builder peut réutiliser la règle à chaque nouvelle session.

Dans un monorepo, Trae peut aussi lire des dossiers .trae/rules/ dans les sous-répertoires. Vous pouvez donc placer des règles spécifiques à côté de chaque service.

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

Ne devinez pas les identifiants de scénario ou d’environnement.

1. Ouvrez votre scénario de test dans Apidog.
2. Accédez à l’onglet CI/CD.
3. Copiez la commande apidog run générée.
4. Remplacez <scenario_id> et <env_id> dans project_rules.md par les valeurs copiées.

La commande générée contient déjà :

• l’ID réel du scénario après -t ;
• l’ID de l’environnement après -e.

Vous évitez ainsi de saisir ou d’inventer des IDs manuellement.

Pour connaître les options disponibles, consultez la référence de la commande apidog run.

Étape 3 : demander à Builder d’exécuter le test

Une fois le fichier de règles en place :

1. Ouvrez le dépôt dans Trae.
2. Activez le mode Builder.
3. Modifiez un endpoint, ou demandez directement une exécution.

Exemple de demande :

Exécutez le scénario de test Apidog et indiquez-moi le code de sortie.

Builder utilise alors la commande déclarée dans project_rules.md.

Le modèle d’approbation de Trae reste important : lorsqu’un agent veut exécuter une commande shell, il propose la commande avec un bouton Exécuter. La commande ne démarre dans le terminal de Trae qu’après votre validation.

Après l’exécution, Builder peut lire la sortie et continuer son raisonnement à partir du résultat.

Le rapporteur -r cli affiche chaque étape et un résumé dans le terminal. Builder peut donc lire les requêtes, les assertions et le résultat final directement dans sa boucle de travail.

Étape 4 : lire le rapport dans Trae

Quand une exécution échoue, le rapport contient les éléments nécessaires au diagnostic.

Avec -r cli, le terminal de Trae affiche notamment :

• les requêtes exécutées ;
• les assertions vérifiées ;
• les assertions en échec ;
• la valeur attendue et la valeur reçue ;
• le code de sortie de la commande.

L’assertion en échec indique généralement le champ, la valeur ou le code d’état à corriger.

Pour générer aussi un rapport partageable dans un navigateur, 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 des rapporteurs : Builder a besoin de la sortie terminal pour décider de l’étape suivante.

Pour les autres formats, notamment JSON et JUnit pour les tableaux de bord CI, consultez le guide des rapports de test de la CLI Apidog.

Trae teste dans sa propre boucle

L’objectif n’est pas de demander manuellement un test à chaque modification. L’objectif est que Builder exécute le scénario parce que les règles du projet l’y obligent.

Prenons un gestionnaire qui construit une réponse de paiement :

1. Builder modifie le code.
2. Il exécute le scénario Apidog sur l’environnement configuré.
3. Il lit le code de sortie.
4. Si le résultat est vert, il passe à la suite.
5. Si le résultat est rouge, il lit l’assertion en échec.
6. Il applique une correction et relance le scénario.

Le test API rejoint alors la même boucle modifier → tester → corriger que les tests unitaires.

Vous déléguez l’exécution à l’agent, mais vous vérifiez toujours le résultat : le code de sortie est la source de vérité.

Pour aller plus loin, consultez comment utiliser les agents IA pour les tests d’API et le harnais de test Apidog AI.

Vérifier que Trae exécute réellement la CLI

Un agent peut annoncer une réussite sans avoir exécuté la commande attendue. Vérifiez systématiquement les trois points suivants.

1. Confirmer que la commande a été exécutée

Dans le terminal de Trae, recherchez la ligne exacte :

apidog run

Vous devez voir la commande et sa sortie. Si Builder affirme avoir exécuté les tests sans qu’aucune commande n’apparaisse, demandez-lui de relancer le scénario et d’afficher la sortie brute.

2. Confirmer le code de sortie

Demandez explicitement :

Quel était le code de sortie de cette commande apidog run ?

Règle à appliquer :

• code 0 : toutes les assertions passent ;
• code non nul : l’exécution a échoué.

Si Builder écrit « les tests ont réussi » alors que le code de sortie est non nul, considérez le test comme échoué.

3. Confirmer le scénario et l’environnement utilisés

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

Vérifiez que les valeurs suivantes correspondent exactement :

• -t dans la commande exécutée ;
• -e dans la commande exécutée ;
• les IDs de .trae/rules/project_rules.md ;
• la commande générée dans l’onglet CI/CD d’Apidog.

Le fichier de règles doit rester votre référence.

Facultatif : connecter le serveur Apidog MCP

L’exécution de apidog run depuis project_rules.md couvre la plupart des besoins de validation. Un serveur MCP ajoute l’accès aux spécifications API pour l’agent.

Les agents Trae agissent comme des clients MCP : Builder peut appeler les outils exposés par un serveur MCP.

Pour en ajouter un dans Trae :

1. Ouvrez les paramètres.
2. Accédez à l’onglet MCP.
3. Choisissez un serveur depuis le marketplace ou sélectionnez Ajouter manuellement.
4. Collez la configuration JSON contenant command, args et env.

Suivez le guide Trae pour l’ajout de serveurs MCP.

Le serveur Apidog MCP expose les spécifications API via MCP. Builder peut ainsi consulter le schéma pendant qu’il écrit du code.

La séparation des responsabilités reste simple :

• la CLI exécute les tests ;
• MCP fournit la spécification API à l’agent.

Quand Trae se trompe

Voici les problèmes les plus fréquents lors de la configuration.

Builder ignore le fichier de règles

Si Builder exécute une commande générique — ou aucune commande — le fichier n’est peut-être pas chargé.

Vérifiez :

.trae/rules/project_rules.md

Assurez-vous que :

• le fichier est à la racine du dépôt ;
• le dossier se nomme rules, et non rule ;
• vous redémarrez la session Builder après avoir modifié les règles.

Builder ajoute un jeton d’accès

Si Builder tente d’ajouter --access-token, il a probablement extrapolé depuis des exemples publics.

Votre règle doit être explicite :

Cette machine est déjà authentifiée via `apidog login`.
N'ajoutez jamais `--access-token`.

Ne stockez jamais un véritable jeton dans project_rules.md.

Pour comprendre la gestion des identifiants en interactif et en CI, consultez l’authentification de la CLI Apidog.

Builder invente un flag

Une erreur « option inconnue » signifie que Builder a utilisé une option non disponible dans votre version de la CLI.

Demandez-lui d’exécuter :

apidog run --help

Puis utilisez exactement les options affichées par votre installation.

Builder annonce une réussite après un échec

C’est le problème le plus coûteux. La règle doit rester simple : le code de sortie prévaut sur le résumé textuel.

Si le résumé semble positif mais que la commande retourne un code non nul, le test a échoué.

D’un agent quotidien à une boucle testée

La configuration est courte :

1. Installez apidog-cli en suivant le guide d’installation.
2. Ajoutez la commande Apidog à .trae/rules/project_rules.md.
3. Ajoutez une règle exigeant l’exécution des tests API après les modifications d’endpoint.
4. Faites respecter le code de sortie.

Builder sait alors exécuter vos tests API et interpréter leur résultat dans la même boucle que celle utilisée pour modifier le code.

Un endpoint défectueux peut être détecté pendant que Builder travaille encore sur le changement, plutôt qu’après le déploiement.

Un test enfermé dans une interface graphique dépend d’un clic humain. Une commande d’une ligne peut être exécutée chaque fois que Builder doit vérifier une modification. Continuez à créer vos scénarios visuellement dans Apidog, puis ajoutez leur commande apidog run à .trae/rules/project_rules.md.

Téléchargez Apidog, créez un scénario, copiez sa commande dans vos règles Trae et vérifiez son exécution lors de votre prochain changement d’API.

Pour exécuter le même scénario sans agent, consultez Apidog CLI dans GitHub Actions, qui couvre les secrets, les rapporteurs et le contrôle du code de sortie en CI.