Comment utiliser l'Apidog CLI dans Cursor

L'Agent de Cursor modifie déjà des fichiers, exécute votre terminal, lit la sortie et corrige ce qu'il a cassé. La prochaine étape consiste à intégrer vos tests d'API dans cette boucle : laissez Cursor exécuter vos scénarios Apidog réels, lire le succès ou l'échec, et continuer. L'élément qui rend cela possible est un exécuteur en ligne de commande que Cursor peut appeler.

Cet exécuteur est l'Apidog CLI, un paquet npm nommé apidog-cli. Il exécute les scénarios de test que vous avez construits visuellement dans Apidog depuis un terminal et se termine avec un code d'état sur lequel Cursor peut agir. Ce guide couvre la partie spécifique à Cursor : le fichier de règles qui enseigne à Cursor votre flux de travail, l'invite qui exécute un test, comment l'exécution s'intègre dans sa boucle d'édition-test-correction, et le serveur MCP facultatif qui fournit à Cursor votre spécification d'API pendant qu'il code.

Si l'outil CLI n'est pas encore installé, commencez par comment installer l'Apidog CLI avec un agent de codage IA, qui guide Cursor à travers l'installation et l'authentification. Revenez une fois que apidog --version affiche un numéro. Vous avez également besoin d'un compte Apidog avec au moins un scénario de test enregistré. Téléchargez Apidog si vous n'en avez pas.

Ce que signifie « utiliser le CLI dans Cursor »

Il n'y a pas de plugin Apidog pour Cursor, et vous n'en avez pas besoin. L'Agent de Cursor exécute déjà des commandes shell dans le terminal de votre projet. Ainsi, utiliser l'Apidog CLI dans Cursor signifie trois choses :

1. Enseigner le flux de travail à Cursor une seule fois avec une règle de projet, afin qu'il connaisse la commande, les drapeaux et que le code de sortie soit la source de vérité.
2. Faire exécuter apidog run par l'Agent comme une étape normale de sa boucle, de la même manière qu'il exécute vos tests unitaires.
3. Connecter facultativement le serveur Apidog MCP, afin que Cursor puisse lire votre spécification d'API pendant qu'il écrit le code que ces tests vérifient.

La règle est ce qui rend cela spécifique à Cursor plutôt qu'un guide générique « ouvrir un terminal et taper ».

Étape 1 : Ajouter une règle de projet

Cursor lit les règles de projet depuis un répertoire .cursor/rules à la racine de votre dépôt. Chaque règle est un fichier .mdc avec un petit bloc d'en-tête, versionné aux côtés de votre code afin que toute l'équipe bénéficie du même comportement.

Créez-en une de deux manières : tapez /create-rule dans le chat et décrivez ce que vous voulez, ou ouvrez Cursor Settings > Rules, Commands, cliquez sur + Add Rule. Dans les deux cas, vous obtiendrez un fichier sous .cursor/rules.

Enregistrez ceci sous le nom .cursor/rules/apidog-cli.mdc :

---
description: Comment exécuter des tests d'API Apidog depuis le terminal
alwaysApply: false
---

# Exécution des tests d'API Apidog

Ce projet contient des scénarios de test d'API dans Apidog. Exécutez-les avec l'
apidog-cli, qui est installé globalement et déjà authentifié.

- La commande est `apidog run`. Le binaire est `apidog`.
- Exécutez un scénario unique par ID : `apidog run -t <scenarioId> -e <environmentId> -n 1 -r cli`
  - `-t` est l'ID du scénario de test, `-e` est l'ID de l'environnement.
  - `-n 1` l'exécute une fois. `-r cli` imprime un rapport lisible dans le terminal.
- Ne pas passer `--access-token`. L'authentification est gérée par une précédente `apidog login`.
- Le code de sortie est la source de vérité : `0` signifie que toutes les assertions sont passées,
  non nul signifie un échec. Signalez le code de sortie, pas seulement un résumé.
- Si un drapeau est inconnu, exécutez `apidog run --help` et utilisez le drapeau exact à partir de là.
  Ne jamais deviner les noms des drapeaux.
- Après avoir modifié du code qui touche un endpoint, exécutez le scénario pertinent
  et lisez le résultat avant de prétendre que la modification fonctionne.

L'en-tête (frontmatter) est important. description et alwaysApply: false en font une règle d'application intelligente : Cursor l'inclut lorsque la conversation concerne l'exécution de tests, au lieu de consommer du contexte à chaque conversation. Définissez alwaysApply: true pour qu'elle soit toujours dans le champ d'application. Pour la limiter à un type de fichier, supprimez la description et ajoutez une ligne globs, et Cursor l'attachera automatiquement lorsqu'un fichier correspondant est ouvert.

Le contenu fait le vrai travail. Il fixe la forme de la commande, indique d'où vient l'authentification, et établit la règle qui garantit l'honnêteté d'un agent : le code de sortie l'emporte sur la prose. Les agents lisent parfois un rapport d'échec et disent que « ça a l'air bon ». Écrire cette règle une fois signifie que vous n'avez pas à le vérifier manuellement.

Étape 2 : Obtenir la commande d'Apidog

Avant de demander à l'Agent d'exécuter quoi que ce soit, obtenez une commande validée. Ne laissez pas Cursor deviner les ID.

Ouvrez votre scénario de test dans Apidog, passez à son onglet CI/CD et choisissez l'option de ligne de commande. Apidog construit la commande complète apidog run avec l'ID du scénario, l'ID de l'environnement et un jeton d'accès déjà renseignés :

apidog run --access-token YOUR_ACCESS_TOKEN -t 605067 -e 1629989 -n 1 -r cli

605067 est l'ID du scénario de test et 1629989 est l'ID de l'environnement ; les vôtres seront différents. Puisque vous avez authentifié le CLI lors de l'installation, supprimez la partie --access-token et conservez les ID. C'est la commande que votre règle a dit à Cursor d'utiliser.

Étape 3 : Faire exécuter le test par l'Agent

Ouvrez l'Agent de Cursor (le mode chat qui exécute des commandes terminales, et non l'édition en ligne). Avec la règle en place, l'invite est courte :

Exécutez mon scénario de test Apidog et montrez-moi la sortie complète et le code de sortie.

Cursor propose la commande et, après votre approbation, l'exécute dans le terminal intégré :

apidog run -t 605067 -e 1629989 -n 1 -r cli

Par défaut, Cursor demande avant d'exécuter une commande de terminal, afin que vous voyiez exactement ce qu'il est sur le point d'exécuter. Approuvez-la, et l'Agent exécute le scénario, puis lit l'exécution et un résumé.

Votre vérification : examinez le code de sortie, pas le résumé. apidog run se termine par 0 lorsque toutes les assertions réussissent et par un nombre non nul lorsqu'une échoue. Ce comportement est la raison principale pour laquelle cela fonctionne comme une passerelle, pour le CI et pour l'Agent. Si Cursor dit « tests réussis » mais que le code de sortie était non nul, c'est faux ; faites confiance au code. C'est précisément cette erreur que la règle de l'Étape 1 empêche.

Pour un format de rapport différent ou plus d'itérations, demandez à l'Agent d'exécuter apidog run --help afin qu'il lise la liste réelle des drapeaux pour votre version installée. Le guide complet d'Apidog CLI documente chaque drapeau, y compris les rapporteurs html, json et junit, et l'itération basée sur les données.

Étape 4 : Lire le rapport dans Cursor

Le rapporteur -r cli affiche les résultats dans le terminal que Cursor lit déjà, ce qui le rend adapté au travail de l'Agent. L'Agent voit les mêmes lignes que vous : quel scénario a été exécuté, chaque requête, chaque assertion, et le nombre final de succès ou d'échecs.

Lorsqu'une exécution échoue (devient rouge), le rapport indique l'assertion défaillante, la valeur attendue et ce que le point de terminaison a renvoyé. Puisque ce texte est dans le contexte de l'Agent, poursuivez dans le même chat :

Le scénario a échoué. Lisez l'assertion défaillante dans le rapport, trouvez le gestionnaire qui produit ce champ et proposez une correction. Ensuite, exécutez le scénario à nouveau et montrez-moi le nouveau code de sortie.

Maintenant, le test fait partie de la boucle. Cursor modifie le gestionnaire, réexécute apidog run, lit le nouveau code de sortie et soit passe à autre chose, soit réessaye. Vos vérifications d'API vivent dans le même cycle d'édition-test-correction que Cursor utilise pour les tests unitaires, à l'exception que ceux-ci s'exécutent sur de vrais points de terminaison. Pour le schéma plus large, comment utiliser les agents IA pour les tests d'API couvre où cela s'applique et où cela ne s'applique pas.

Facultatif : Connecter le serveur Apidog MCP

L'outil CLI permet à Cursor d'exécuter vos tests. Le serveur Apidog MCP permet à Cursor de lire votre spécification d'API pendant qu'il écrit du code. Les deux s'empilent : le serveur MCP fournit à Cursor votre schéma afin qu'il génère du code correspondant au contrat, et le CLI vérifie ce code par rapport à des scénarios réels.

Cursor prend en charge les serveurs MCP via une configuration JSON. Placez les serveurs spécifiques au projet dans .cursor/mcp.json à la racine de votre dépôt, ou les serveurs globaux dans ~/.cursor/mcp.json. La structure est un objet mcpServers indexé par un nom, chacun avec une command, un tableau args, et des valeurs env facultatives :

{
  "mcpServers": {
    "apidog": {
      "command": "npx",
      "args": ["-y", "apidog-mcp-server@latest", "--project=YOUR_PROJECT_ID"],
      "env": {
        "APIDOG_ACCESS_TOKEN": "YOUR_ACCESS_TOKEN"
      }
    }
  }
}

Deux remarques. Le MCP est bloqué derrière un interrupteur dans certaines installations, alors ouvrez les Paramètres de Cursor, trouvez la section Protocole de Contexte de Modèle, et confirmez que le serveur Apidog est activé. Et si vous commitez .cursor/mcp.json, ne codez pas en dur le jeton ; référencez une variable d'environnement. Pour la configuration complète, y compris où obtenir l'ID de projet et le jeton, consultez le guide du serveur Apidog MCP. Pour un flux de travail packagé et réutilisable au lieu de le câbler manuellement, le guide Apidog CLI avec les compétences Claude montre la version basée sur les compétences.

De la boucle locale à la CI

Une fois que Cursor a exécuté le scénario localement et agi sur le code de sortie, vous avez validé la commande exacte que votre pipeline utilisera. Le passage à l'intégration continue (CI) est minime : même apidog run, avec le jeton transmis comme un secret masqué au lieu d'une connexion stockée. Vous pouvez même demander à Cursor d'écrire l'étape, car il connaît la commande grâce à votre règle :

Les mécanismes de cette étape (secrets, rapporteurs, contrôle par code de sortie) se trouvent dans Apidog CLI dans GitHub Actions. La même commande s'exécute désormais à trois endroits : votre terminal, la boucle de l'Agent de Cursor et la CI, tous faisant confiance au même code de sortie.

Problèmes courants

La règle ne s'applique pas. Avec description et alwaysApply: false, Cursor ne charge la règle que lorsqu'il juge le chat pertinent. Si une session de test ne la prend pas en compte, mentionnez-la avec @apidog-cli dans le chat, ou passez à alwaysApply: true.

L'Agent ne peut pas exécuter la commande. S'il ne fait que suggérer des commandes au lieu de les exécuter, vous êtes probablement en mode édition plutôt qu'en mode Agent, ou vous avez manqué l'invite d'approbation. Confirmez que vous êtes dans le chat de l'Agent et approuvez lorsque Cursor le demande. Si les exécutions de terminal échouent complètement, c'est généralement le problème de PATH « apidog: command not found » que le guide d'installation couvre.

apidog whoami indique que vous n'êtes pas authentifié. La connexion est stockée sur votre machine, pas dans Cursor. Exécutez apidog login --with-token vous-même avec un nouveau jeton d'Apidog, puis demandez à l'Agent de confirmer avec apidog whoami. Gardez le jeton hors du chat.

Il invente un drapeau. Si une exécution échoue avec une erreur « option inconnue », l'Agent a deviné un drapeau qui n'existe pas dans votre version. Demandez-lui d'exécuter apidog run --help et copiez le drapeau exact.

Conclusion

La configuration de Cursor se résume à un fichier et une habitude : une règle .cursor/rules/apidog-cli.mdc qui fixe la commande, la source d'authentification et la règle du code de sortie, ainsi que l'habitude de laisser l'Agent exécuter apidog run et de vérifier vous-même le code de sortie. Ajoutez le serveur Apidog MCP et Cursor pourra également lire votre spécification pendant qu'il code.

Vous continuez à créer des scénarios visuellement dans Apidog ; Cursor ne fait que les exécuter. À partir de là, pointez la même commande vers votre pipeline avec Apidog CLI dans GitHub Actions, ou lisez la référence complète des drapeaux dans le guide complet d'Apidog CLI.