Cet article explique comment combiner Apidog CLI avec les Compétences Claude (Claude Skills) pour créer un flux de travail efficace de tests d'automatisation d'API pilotés par le langage naturel.
Dans ce flux de travail, il vous suffit de prononcer une seule phrase à Claude Code dans votre terminal, par exemple :
"Exécute les tests de flux de commande utilisateur en dev."
Claude Code comprendra automatiquement votre intention, localisera le scénario de test ou la suite de tests correspondante, exécutera les tests, puis résumera et interprétera les résultats pour vous.
Aperçu des outils
Ce flux de travail est composé de trois outils :
1. Apidog CLI
L'interface de ligne de commande fournie par Apidog. Elle est utilisée pour exécuter des tests d'automatisation d'API depuis le terminal et générer des rapports de test.
2. Claude Code
Un assistant IA en ligne de commande développé par Anthropic. Il peut opérer sur des fichiers, exécuter des commandes, lancer des scripts et interagir avec votre environnement de développement local.
3. Compétences Claude (Claude Skills)
Également connues sous le nom d'Agent Skills, un mécanisme d'extension de Claude Code. Une compétence (Skill) définit comment Claude doit accomplir une tâche spécifique, agissant essentiellement comme un ensemble exécutable d'instructions opérationnelles.
Dans ce flux de travail, Claude Code est responsable de la compréhension des instructions en langage naturel. Lorsqu'une requête d'utilisateur correspond à une Compétence Claude prédéfinie, Claude exécute automatiquement les commandes Apidog CLI correspondantes et analyse les résultats.
Ce que ce flux de travail peut faire
Vous trouverez ci-dessous plusieurs scénarios réels pour illustrer comment ce flux de travail peut être utilisé en pratique.
Exécuter un seul test
Si vous souhaitez exécuter un scénario de test spécifique, vous pouvez le nommer explicitement. Par exemple :
"Exécute les tests de connexion en dev."
Une fois le test terminé, Claude analyse les résultats et fournit un résumé.
Lister tous les tests disponibles
Pour voir quels scénarios de test ou suites de tests sont disponibles, vous pouvez dire :
"Montre-moi les tests disponibles."
Claude exécutera le script pertinent et listera tous les tests.
Exécuter tous les tests pour un module métier
Si vous souhaitez exécuter tous les tests pour un domaine métier spécifique – comme les tests liés au paiement – vous pouvez dire :
"Exécute tous les tests de paiement dans l'environnement de test."
Claude localisera automatiquement tous les fichiers de test associés et les exécutera séquentiellement ou en parallèle.
Comparer les résultats des tests entre les environnements
Pour comparer les résultats entre les environnements, vous pouvez dire :
"Exécute les tests de connexion en dev et en test."
Claude exécutera les tests dans les deux environnements et analysera les différences dans les résultats.
Exécuter des tests basés sur des modifications de code
Après des modifications de code, vous pouvez demander à Claude d'exécuter uniquement les tests affectés :
"En fonction des récentes modifications de code, exécute les tests d'API impactés en dev."
Claude analysera les changements Git, déterminera les scénarios de test ou les suites de tests affectés, et exécutera uniquement ces tests – ce qui permet d'économiser du temps et des ressources.
D'autres scénarios vous attendent à explorer.
Ensuite, nous allons vous guider à travers l'installation et la configuration d'Apidog CLI, de Claude Code et des Compétences Claude, et comment les combiner en un flux de travail complet.
Préparation
Exigences d'environnement
Assurez-vous que Node.js est installé sur votre machine. Vérifiez-le dans votre terminal :
node -v
npm -vInstallation d'Apidog CLI : installer via npm :
npm install -g apidog-cli
Vérifiez l'installation :
apidog --versionSi un numéro de version s'affiche, l'installation a réussi.
Vous pouvez copier une commande CLI pour un scénario de test ou une suite de tests depuis Apidog → Tests → CI/CD, ajouter votre jeton d'accès (Access Token) et l'exécuter dans le terminal.
Si une sortie de test apparaît, Apidog CLI fonctionne correctement.
Installation de Claude
Code : installer via npm :
npm install -g @anthropic-ai/claude-codeVérifier :
claude --versionLors de la première exécution, vous devrez vous connecter :
claude
Suivez les étapes d'autorisation. Un compte Claude est requis. Après vous être connecté, vous accéderez à l'interface interactive et pourrez poser des questions de base.
À ce stade, Claude ne sait pas encore comment exécuter les tests Apidog. Ensuite, nous allons lui apprendre à l'aide des Compétences Claude (Claude Skills).
Construction des Compétences Claude (Claude Skills)
Comprendre le fonctionnement des compétences
Lorsque vous utilisez Claude Code, vous ne sélectionnez pas manuellement une Compétence. Vous décrivez simplement ce que vous voulez faire en langage naturel.
Si votre requête correspond à la description d'une Compétence, Claude charge automatiquement cette Compétence et exécute le flux de travail défini.
Étape 1 : Créer le dossier de compétence
Toutes les configurations de Compétences se trouvent sous le dossier .claude/skills/. Chaque Compétence a son propre sous-dossier.
Créez un dossier de Compétence minimal pour les tests d'automatisation Apidog à la racine du projet :
mkdir -p .claude/skills/apidog-tests
Structure résultante :
.claude/skills/apidog-tests/Nous y ajouterons progressivement des fichiers d'entrée et des scripts.
Étape 2 : Créer SKILL.md
Chaque Compétence nécessite un fichier SKILL.md qui définit comment Claude doit exécuter la tâche une fois la Compétence déclenchée.
Le fichier commence par des métadonnées YAML enveloppées dans ---. Les champs name et description sont obligatoires.
La description est particulièrement importante – elle détermine quand Claude doit activer cette Compétence.
Sous le bloc YAML, le contenu Markdown définit la logique d'exécution, les règles de décision, les scripts à invoquer et les contraintes.
Exemple de SKILL.md pour les tests d'automatisation Apidog
---
name: apidog-tests
description: Exécute et interprète les tests d'API automatisés Apidog via Apidog CLI. Déclenchez cette Compétence chaque fois que l'utilisateur demande explicitement d'exécuter des tests, des cas de test, des scénarios de test ou des suites de tests, y compris les requêtes pour exécuter des tests dans un environnement spécifique tel que dev, test ou prod, pour vérifier le comportement de l'API après des modifications de code, pour effectuer des tests de régression ou de pré-version, ou pour exécuter des vérifications d'API avant un commit, un push ou un merge Git. Même si l'utilisateur ne mentionne pas explicitement "Apidog" ou "API", supposez que ces requêtes se réfèrent aux tests automatisés Apidog lorsque l'exécution de tests est implicite. La Compétence doit sélectionner le scénario de test ou la suite de tests appropriée, exécuter les tests et expliquer les résultats sans modifier les définitions de test ou les commandes elles-mêmes.
---
# Tests Apidog
Exécute les tests automatisés Apidog et interprète les résultats.
## Flux de travail
1. **Sélectionner le test**:
- Si l'utilisateur fournit explicitement :
- Chemin du fichier de test
- Nom du fichier de test
- Ou un nom de test clair et correspondant de manière unique
- Utilisez ce test directement sans sélection automatique.
- Si l'information est peu claire, privilégiez l'exécution du script `node ./.claude/skills/apidog-tests/scripts/list-tests.js` pour récupérer rapidement tous les chemins de fichiers de test et leurs descriptions.
- Évitez les recherches globales aveugles dans les grands répertoires de projet ; localisez plutôt le répertoire de fichiers de test `./.claude/skills/apidog-tests/tests/` dédié à cette compétence.
2. **Règles d'exécution de tests multiples**
- Par défaut, n'exécutez qu'un seul test, mais offrez l'option d'exécution par lots.
- Si l'utilisateur déclare explicitement :
- "Exécute ces quelques-uns"
- "Exécute-les tous"
- Entrez en **Mode d'exécution par lots**.
En Mode d'exécution par lots :
- Listez clairement les tests à exécuter.
- **Demandez la méthode d'exécution** : Laissez l'utilisateur choisir entre "Exécution séquentielle" (meilleure lisibilité) ou "Exécution parallèle" (plus rapide).
- **Exécution séquentielle** : Exécutez les tests un par un et analysez immédiatement, adapté au débogage.
- **Exécution parallèle** : Démarrez plusieurs tests simultanément (en utilisant `&` ou des scripts concurrents), adapté à la régression rapide, bien que les journaux puissent s'entrelacer.
- Demandez la confirmation de l'utilisateur pour la méthode d'exécution et la liste des tests (Oui / Non).
- Exécutez les tests selon la méthode choisie.
- Enfin, résumez ou expliquez individuellement les résultats de chaque test.
3. **Confirmer l'environnement**:
- Les environnements pris en charge incluent :
- `dev`
- `test`
- `prod`
- Si l'utilisateur n'a pas spécifié d'environnement :
- Listez les noms d'environnement ci-dessus.
- Demandez à l'utilisateur de confirmer lequel utiliser.
4. **Exécuter le test**:
- Exécutez le test une fois que les informations suivantes sont claires :
- Chemin du fichier de test
- Nom de l'environnement (dev / test / prod)
```bash
node ./.claude/skills/apidog-tests/scripts/run-cli.js <test_file_path> <env_name>
```
5. **Interpréter les résultats** : Analysez la sortie d'Apidog CLI et expliquez les causes de l'échec.
## Gestion des échecs
- Ne modifiez pas les fichiers de test.
- Ne modifiez pas les commandes d'exécution.
- Expliquez les raisons de l'échec en vous basant sur les noms de test, la sémantique de l'API et la sortie CLI.
Étape 3 : Fichiers de support
Lors des étapes précédentes, nous avons créé le fichier SKILL.md, qui définit les conditions de déclenchement et le flux de travail général pour cette Compétence.
Sur cette base, tous les fichiers restants servent uniquement de composants de support pour SKILL.md. Des fichiers supplémentaires sont introduits à la demande, uniquement lorsque le flux de travail nécessite des informations supplémentaires – telles que les environnements d'exécution, les commandes d'exécution ou les définitions de test.
Structure finale des dossiers :
.claude/skills/apidog-tests/
├── SKILL.md
├── env/
│ ├── dev.env
│ ├── test.env
│ └── prod.env
├── scripts/
│ ├── list-tests.js
│ └── run-cli.js
└── tests/
├── payment-flow.md
└── refund-flow.md
Ci-dessous, nous examinons chaque fichier de support, en expliquant son objectif et en fournissant des exemples.
Configuration de l'environnement (env)
Le dossier env/ est utilisé pour stocker les configurations de variables d'environnement, telles que le jeton d'accès Apidog et l'ID d'environnement.
En extrayant l'ID d'environnement dans une variable, nous pouvons rapidement changer l'environnement d'exécution des tests (par exemple, développement, test, production) sans modifier les commandes ou les scripts.
Par exemple, créez un fichier dev.env sous le dossier env/ :
APIDOG_ACCESS_TOKEN=APS-votre-jeton-d-acces
APIDOG_ENV_ID=votre-id-d-environnementSi plusieurs environnements sont nécessaires, vous pouvez créer des fichiers supplémentaires de la même manière :
test.envprod.env- …
Chaque fichier n'a besoin de maintenir que les variables de son environnement correspondant.
L'ID d'environnement correspond à la valeur numérique passée au paramètre -e dans la commande Apidog CLI. Chaque environnement d'exécution (tel que le développement, le test ou la production) possède un ID d'environnement unique dans Apidog.
.env sous le dossier env/ contiennent des jetons d'accès, qui sont des informations sensibles et ne doivent pas être commis dans Git.Scripts d'exécution (scripts)
Le dossier scripts/ contient des scripts exécutables responsables de la conversion des définitions de test en commandes Apidog CLI réellement exécutables, de l'injection des variables d'environnement et de l'exécution des tests.
Dans cette Compétence, Node.js est choisi pour deux raisons principales :
- Apidog CLI lui-même dépend de Node.jsLa réutilisation du même runtime évite la nécessité d'installer des runtimes supplémentaires tels que Python.
- Réduction des frais généraux de contexte et de la consommation de jetonsEn gérant l'analyse des commandes, l'injection de variables et la logique d'exécution à l'intérieur des scripts, Claude n'a pas besoin de construire à plusieurs reprises des commandes CLI complètes pendant la conversation, ce qui réduit considérablement l'utilisation du contexte.
Si vous n'êtes pas familier avec les scripts, vous pouvez choisir de ne pas utiliser de scripts du tout. Au lieu de cela, vous pouvez laisser Claude assembler et exécuter les commandes CLI directement dans SKILL.md.
Cependant, cette approche entraîne des coûts de contexte et de jetons plus élevés.
Créez run-cli.js sous le dossier scripts/. Ses responsabilités principales sont :
- Extraire la commande Apidog CLI d'un fichier de test Markdown spécifié
- Charger le fichier
.envcorrespondant en fonction de l'environnement sélectionné (par exemple,dev/test) - Injecter les variables d'environnement et exécuter le test
Un exemple de script prêt à l'emploi est présenté ci-dessous :
import fs from "fs";
import path from "path";
import { execSync } from "child_process";
import dotenv from "dotenv";
import { fileURLToPath } from "url";
const __filename = fileURLToPath(import.meta.url);
const __dirname = path.dirname(__filename);
// args
const mdPath = process.argv[2];
const envName = process.argv[3] || "local";
if (!mdPath) {
console.error("❌ Chemin du fichier .md de test manquant");
process.exit(1);
}
// chemin de l'environnement : toujours relatif au dossier de la compétence
const envPath = path.join(__dirname, "..", "env", `${envName}.env`);
if (!fs.existsSync(envPath)) {
console.error(`❌ Configuration d'environnement introuvable : ${envPath}`);
process.exit(1);
}
dotenv.config({ path: envPath });
// Lire le fichier markdown
const content = fs.readFileSync(mdPath, "utf-8");
const match = content.match(/```bash([\s\S]*?)```/);
if (!match) {
console.error("❌ Bloc de commande Bash introuvable");
process.exit(1);
}
let command = match[1].trim();
// Remplacement des variables
command = command
.replaceAll("$APIDOG_ACCESS_TOKEN", process.env.APIDOG_ACCESS_TOKEN)
.replaceAll("$APIDOG_ENV_ID", process.env.APIDOG_ENV_ID);
console.log(`▶ Exécution (${envName})`);
console.log(command);
// Exécuter
try {
execSync(command, { stdio: "inherit" });
} catch (e) {
// Apidog CLI renvoie le code de sortie 1 lorsque les tests échouent
process.exit(1);
}
Créez également list-tests.js sous le dossier scripts/. Il est utilisé pour :
- Analyser récursivement le dossier
tests/ - Localiser tous les fichiers de test Markdown
- Extraire la description de la première ligne
- Afficher une liste de tous les tests automatisés Apidog disponibles
Un exemple de script prêt à l'emploi est présenté ci-dessous :
import fs from "fs";
import path from "path";
import { fileURLToPath } from "url";
const __filename = fileURLToPath(import.meta.url);
const __dirname = path.dirname(__filename);
const testsDir = path.join(__dirname, "..", "tests");
function scan(dir, relativePath = "") {
const items = fs.readdirSync(dir, { withFileTypes: true });
for (const item of items) {
const fullPath = path.join(dir, item.name);
const relPath = path.join(relativePath, item.name);
if (item.isDirectory()) { // Correction : isDirectory() au lieu de isfolder()
scan(fullPath, relPath);
} else if (item.name.endsWith(".md")) {
try {
const content = fs.readFileSync(fullPath, "utf-8");
const firstLine = content.split("\n")[0].trim();
const description = firstLine.startsWith(">")
? firstLine.replace(/^>\s*/, "").trim()
: "Aucune description"; // Correction : "No description"
const displayPath = path.join(
"./.claude/skills/apidog-tests/tests",
relPath
);
console.log(`[${displayPath}] - ${description}`);
} catch (err) {
console.log(`[${relPath}] - (Impossible de lire le fichier)`); // Correction : "Unable to read file"
}
}
}
}
console.log("🔍 Tests automatisés Apidog disponibles :"); // Correction : "Available Apidog automated tests"
if (fs.existsSync(testsDir)) {
scan(testsDir);
} else {
console.log("❌ Dossier de tests introuvable"); // Correction : "tests folder not found"
}Définitions de tests (tests)
Le dossier tests/ stocke les définitions de tests écrites en Markdown.
Principe de conception : Chaque fichier Markdown correspond à un scénario de test ou une suite de tests Apidog. Vous pouvez réutiliser directement les structures de dossiers existantes, les noms de scénarios de test, les noms de suites de tests et les descriptions des tests d'automatisation Apidog.
Chaque fichier Markdown ne doit contenir que deux parties :
- Une courte description du test
- Une seule commande Apidog CLI qui peut être exécutée directement
Dans la commande Apidog CLI :
- Le jeton d'accès est remplacé par
$APIDOG_ACCESS_TOKEN - L'ID d'environnement passé à
-eest remplacé par$APIDOG_ENV_ID
Ces deux variables sont configurées de manière centralisée dans les fichiers .env. Cette approche prévient les fuites de jetons et permet un changement d'environnement flexible.
Exemple : login-auth-flow.md
> Vérifie les API principales telles que la connexion, le rafraîchissement de jeton et la déconnexion.
```bash
apidog run --access-token $APIDOG_ACCESS_TOKEN -t 5564xxx -e $APIDOG_ENV_ID -n 1 -r html,cli
```
À ce stade, la Compétence est entièrement construite. Vous pouvez revoir la structure des dossiers et la comparer avec votre propre implémentation pour identifier toute différence.
Utilisation du flux de travail dans Claude Code
Exécutez claude dans le dossier du projet. Claude scanne automatiquement .claude/skills/ et charge la Compétence apidog-tests.
Vous pouvez lister les Compétences chargées en utilisant /skills.
Essayez ensuite une commande en langage naturel :
"Exécute les tests de connexion en dev."
Claude localisera le test, l'exécutera via Apidog CLI, analysera la sortie et résumera les résultats.
Résumé
Cet article a montré comment construire un flux de travail de tests d'API automatisés en utilisant Claude Code, Apidog CLI et les Compétences Claude (Claude Skills).
L'idée principale est de faire de Claude le pont entre les humains et les outils :
- Vous décrivez votre intention en langage naturel
- Claude comprend et invoque les scripts
- Les scripts exécutent Apidog CLI
- Claude analyse et présente les résultats de manière lisible par l'homme
Pour rendre ce flux de travail vraiment efficace, vous devez l'adapter à votre projet – l'organisation des tests, la stratégie d'environnement et la logique d'analyse des résultats peuvent toutes être personnalisées.
Si votre équipe exécute fréquemment des tests d'API et souhaite une expérience plus automatisée et intelligente, cette approche vaut la peine d'être essayée. Cela nécessite une certaine configuration initiale, mais une fois établie, elle peut améliorer considérablement l'efficacité – et continue de s'améliorer à mesure que vous l'affinez.