Comment utiliser l'Apidog CLI dans Antigravity

Antigravity fonctionne en boucle : l’agent modifie des fichiers, exécute des commandes, lit leur sortie et choisit l’étape suivante. Vos tests d’API doivent faire partie de cette boucle, plutôt que de rester dans Apidog derrière une interface graphique qui ne s’exécute que lorsqu’une personne clique.

Essayez Apidog dès aujourd’hui

La solution tient dans une configuration de projet. La CLI Apidog, distribuée via le package npm apidog-cli, exécute les scénarios créés dans Apidog depuis le terminal. Une fois la CLI installée et déclarée dans les règles d’Antigravity, l’agent peut lancer vos tests d’API comme vos tests unitaires : exécuter la commande, lire le code de sortie et corriger le code si le test échoue.

Si vous n’avez pas encore installé la CLI, commencez par le guide d’installation de la CLI Apidog avec un agent de codage IA. Il couvre l’installation npm, l’authentification et la première exécution. La suite suppose que apidog --version renvoie une version et que votre machine est authentifiée.

De quel Antigravity s’agit-il ?

Antigravity est la plateforme de développement agentique de Google, basée sur Gemini 3 et lancée fin 2025. Son Gestionnaire d’Agents planifie le travail, modifie les fichiers du dépôt et exécute des commandes shell dans son terminal et son navigateur.

L’agent travaille directement sur votre machine locale. Si vous avez déjà lancé une tâche dans Antigravity et vu l’agent exécuter des commandes puis rapporter le résultat, ce guide s’applique à votre flux de travail. Pour le contexte général, consultez ce qu’est Google Antigravity et comment l’utiliser.

Le point clé : Antigravity apprend les conventions de votre projet à partir de fichiers de règles. C’est ce mécanisme qui permet de transformer « exécute mes tests » en comportement récurrent de l’agent.

Étape 1 : Ajouter une règle de projet pour Apidog

Antigravity reconnaît le répertoire .agents/ à la racine de l’espace de travail. Le codelab Google sur la création de pipelines de développement autonomes dans Antigravity indique que les règles de l’espace de travail peuvent être placées dans .agents/rules/.

Créez par exemple le fichier suivant :

.agents/rules/apidog.md

Antigravity peut aussi lire un fichier AGENTS.md à la racine du projet. C’est le même format utilisé par Codex pour la CLI Apidog. Si votre dépôt contient déjà un AGENTS.md, ajoutez-y cette règle plutôt que de maintenir deux fichiers.

Ajoutez un bloc comme celui-ci :

## Tests d’API avec la CLI Apidog

- Pour tester l’API, exécutez le scénario Apidog ; n’utilisez pas l’interface graphique.
- Commande : apidog run -t <scenario_id> -e <env_id> -r cli
- Un code de sortie 0 signifie que toutes les assertions sont validées.
- Un code de sortie non nul indique un échec : ouvrez le rapport et corrigez le code.
- La machine est déjà authentifiée avec `apidog login`.
- N’ajoutez jamais `--access-token` et ne stockez jamais de jeton dans ce fichier.

Cette règle est préférable à une instruction donnée uniquement dans le chat. Antigravity ne conserve pas nécessairement le contexte d’une session à l’autre. En revanche, une commande et des identifiants écrits dans les règles du dépôt sont disponibles pour chaque coéquipier et chaque nouvelle tâche.

Étape 2 : Copier la commande générée par Apidog

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

1. Ouvrez le scénario de test dans Apidog.
2. Accédez à l’onglet CI/CD.
3. Copiez la commande générée.

Elle ressemble à ceci :

apidog run -t 123456 -e 789012 -r cli

Les options principales sont :

• -t : identifiant du scénario de test ;
• -e : identifiant de l’environnement ;
• -r cli : rapporteur qui affiche les résultats directement dans le terminal.

Collez les identifiants réels dans .agents/rules/apidog.md ou AGENTS.md. L’agent exécutera alors exactement la commande fournie par Apidog.

Pour le détail des options, consultez la référence de la commande apidog run.

Étape 3 : Demander à l’agent d’exécuter le scénario

Une fois la règle enregistrée, démarrez une tâche Antigravity. L’agent charge les règles au début de la tâche et sait donc que la CLI est disponible.

Après une modification qui affecte votre API, envoyez une instruction simple :

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

L’agent exécute alors la commande apidog run déclarée dans le fichier de règles.

L’exécution automatique dépend de vos paramètres d’autorisation. Le préréglage de sécurité d’Antigravity contrôle notamment la validation des commandes de terminal et des accès aux fichiers, comme l’explique le codelab Google pour démarrer avec Antigravity.

Si Antigravity demande une validation, approuvez la commande apidog run lorsque vous la reconnaissez. Un scénario de test en lecture seule contre un environnement de staging est typiquement une commande sûre dans le contexte du projet. Si l’agent est configuré pour agir de manière autonome, il exécutera la commande et rapportera le résultat sans interruption.

Demandez toujours le résumé et le code de sortie, pas seulement une paraphrase du résultat.

Étape 4 : Lire le rapport dans Antigravity

Avec -r cli, le terminal affiche les informations nécessaires au diagnostic :

• chaque requête exécutée ;
• chaque assertion ;
• l’assertion en échec ;
• la valeur attendue et la valeur réelle.

Cette sortie permet généralement à l’agent d’identifier le code de statut incorrect, le champ manquant ou la valeur inattendue, puis de tenter une correction.

Pour générer aussi un rapport partageable dans un navigateur, ajoutez le rapporteur HTML :

apidog run -t 123456 -e 789012 -r cli,html

Le rapporteur html génère un fichier autonome dans :

./apidog-reports

Conservez cli dans la liste des rapporteurs : l’agent a besoin de la sortie en ligne pour décider de sa prochaine action.

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

Intégrer le test à la boucle de l’agent

L’objectif n’est pas de demander manuellement l’exécution du scénario à chaque tâche. Le fichier de règles doit indiquer à l’agent d’exécuter le test lorsqu’il modifie une partie pertinente de l’API.

Par exemple, si l’agent modifie un gestionnaire qui construit une réponse de commande, sa boucle peut devenir :

1. modifier le code ;
2. exécuter le scénario Apidog contre le staging ;
3. lire le code de sortie ;
4. si le code est 0, poursuivre ;
5. si le code est non nul, lire le rapport ;
6. corriger l’assertion en cause ;
7. réexécuter le scénario.

Le test d’API rejoint ainsi la même boucle édition-test-correction que les tests unitaires.

Ce fonctionnement suit le modèle « déléguer puis vérifier » : Antigravity exécute et interprète la commande, tandis que vous continuez à concevoir visuellement les scénarios dans Apidog et vérifiez ponctuellement que l’agent rapporte bien les résultats. Pour aller plus loin, consultez comment utiliser les agents IA pour les tests d’API et le harnais de test IA Apidog.

Vérifier qu’Antigravity exécute réellement la CLI

Un agent peut annoncer un succès sans avoir exécuté le test. Vérifiez systématiquement ces trois points.

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

Antigravity affiche les commandes et leur sortie dans son terminal. Recherchez la ligne exacte :

apidog run ...

Vous devez également voir sa sortie juste en dessous. Si l’agent affirme avoir exécuté les tests mais qu’aucune commande n’apparaît, demandez-lui de relancer le scénario et d’afficher la sortie brute.

2. Vérifier le code de sortie

Demandez explicitement :

Quel a été le code de sortie de cette commande apidog run ?

apidog run retourne :

• 0 lorsque toutes les assertions sont validées ;
• un code non nul lorsqu’au moins une assertion échoue.

C’est ce code qui doit servir de porte de décision pour l’agent ou un pipeline CI. Si le résumé indique « tests réussis » mais que le code est non nul, fiez-vous au code de sortie.

3. Vérifier les identifiants utilisés

Une erreur telle que « scénario introuvable » peut indiquer que l’agent a utilisé un identifiant incorrect.

Comparez les valeurs -t et -e avec :

• la commande générée dans l’onglet CI/CD d’Apidog ;
• les valeurs enregistrées dans votre fichier de règles.

Les identifiants déclarés dans les règles du projet doivent correspondre à la commande générée par Apidog.

Facultatif : connecter le serveur MCP Apidog

La commande apidog run depuis votre fichier de règles couvre la plupart des cas. Pour donner davantage de contexte à l’agent pendant l’implémentation, vous pouvez aussi connecter un serveur MCP.

Antigravity prend en charge le Model Context Protocol (MCP). D’après le codelab Google pour démarrer, les serveurs MCP sont configurés dans :

$HOME/.gemini/config/mcp_config.json

Ajoutez votre serveur dans l’objet mcpServers avec ses propriétés command, args et env, puis actualisez le MCP depuis les paramètres d’Antigravity.

Le serveur MCP Apidog expose vos spécifications d’API via MCP. L’agent peut alors consulter le schéma pendant qu’il écrit le code.

En résumé :

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

Corriger les problèmes fréquents

L’agent ignore le fichier de règles

Si l’agent exécute une commande générique, ou n’exécute aucun test :

1. vérifiez le nom du fichier ;
2. vérifiez son emplacement dans .agents/rules/ ou à la racine pour AGENTS.md ;
3. démarrez une nouvelle tâche afin qu’Antigravity recharge les règles.

L’agent ajoute un jeton d’accès

Si l’agent ajoute --access-token, il s’appuie probablement sur un exemple générique. Renforcez la règle indiquant que la machine utilise déjà :

apidog login

Ne placez jamais de jeton réel dans le fichier de règles. Pour comprendre le fonctionnement de cette étape, consultez l’authentification de la CLI Apidog.

L’agent invente une option

Une erreur « option inconnue » signifie que l’agent a proposé un indicateur absent de votre version installée.

Demandez-lui d’exécuter :

apidog run --help

Il doit utiliser les options affichées par cette commande, qui correspondent à votre version locale de la CLI.

L’agent annonce un succès malgré un échec

C’est le cas le plus coûteux. La règle est simple : lorsque le résumé de l’agent et le code de sortie ne correspondent pas, le code de sortie l’emporte.

D’un agent quotidien à une boucle testée

La mise en place est courte :

1. installez apidog-cli avec le guide d’installation ;
2. ajoutez une règle Apidog dans .agents/rules/apidog.md ou AGENTS.md ;
3. copiez la commande apidog run depuis l’onglet CI/CD de votre scénario ;
4. faites exécuter le scénario par Antigravity après les modifications API ;
5. utilisez le code de sortie comme résultat de référence.

Un endpoint défectueux peut alors être détecté pendant que l’agent travaille encore sur la modification, avant le déploiement.

Un test laissé derrière une interface graphique ne s’exécute que lorsqu’une personne clique. Une commande d’une ligne peut être exécutée à chaque fois qu’Antigravity en a besoin. Continuez à créer vos scénarios visuellement dans Apidog, puis laissez l’agent les lancer depuis le terminal.

Téléchargez Apidog, créez un scénario, ajoutez sa commande apidog run aux règles du projet et vérifiez son exécution lors de la prochaine modification. Pour exécuter ensuite la même commande dans un pipeline sans agent, consultez Apidog CLI dans GitHub Actions, qui couvre les secrets, les rapporteurs et le filtrage par code de sortie.