tdd-guide

Présentation du skill tdd-guide

À quoi sert tdd-guide

tdd-guide est un skill de Test Driven Development conçu pour générer des tests unitaires, repérer les manques de couverture, créer des fixtures et des mocks, et guider le cycle red-green-refactor sur les stacks les plus courantes. Il est particulièrement utile lorsque vous voulez qu’un assistant IA fasse plus que « écrire quelques tests » : le skill oriente l’échange vers le code source, les exigences, le framework cible, les rapports de couverture et les critères de validation.

Utilisateurs et projets les mieux adaptés

Le skill tdd-guide convient aux équipes d’ingénierie, aux développeurs solo et aux contributeurs orientés QA qui travaillent en TypeScript, JavaScript, Python ou Java. Il est surtout pertinent pour des workflows de type Jest, Pytest, JUnit, Vitest et Mocha. Utilisez-le lorsque vous ajoutez des tests à du code existant, démarrez une nouvelle fonctionnalité en commençant par les tests, cherchez à améliorer la couverture jusqu’à un seuil donné ou voulez harmoniser la production de tests au sein d’une équipe.

Ce qui le distingue d’un prompt de test générique

Un prompt générique peut produire des tests plausibles, mais il passe souvent à côté des conventions du framework, des cas limites, des priorités de couverture ou du cycle TDD lui-même. tdd-guide apporte une structure de workflow, des exemples d’entrées, des formats de sortie attendus, des outils d’analyse de couverture, de la génération de fixtures, une adaptation aux frameworks et des références pour l’intégration CI. Il est donc mieux adapté à un travail d’ingénierie répétable qu’à une expérimentation ponctuelle avec un prompt.

Quand tdd-guide peut ne pas suffire

tdd-guide for Test Driven Development ne remplace pas la compréhension du comportement métier. Si vous ne pouvez pas fournir les résultats attendus, les dépendances, les règles d’erreur ou les détails du framework, les tests générés risquent de rester superficiels. Il ne garantit pas non plus automatiquement que les tests compileront dans votre dépôt : vous devez toujours exécuter votre commande de test locale et ajuster les imports, les fichiers de setup, les mocks et la configuration propre à votre environnement.

Comment utiliser le skill tdd-guide

Installation de tdd-guide et aperçu du dépôt

Installez le skill dans un environnement compatible avec Claude Skills avec :

npx skills add alirezarezvani/claude-skills --skill tdd-guide

Ensuite, consultez le dossier amont du skill dans engineering-team/skills/tdd-guide. Commencez par SKILL.md pour les règles d’activation et les workflows, puis lisez HOW_TO_USE.md pour les exemples d’invocation. Si vous avez besoin d’une configuration propre à un framework, examinez references/framework-guide.md ; si votre objectif est de faire respecter les tests dans la build, lisez references/ci-integration.md ; si vous voulez améliorer vos habitudes TDD, consultez references/tdd-best-practices.md.

Entrées qui rendent l’utilisation de tdd-guide plus efficace

Le skill donne ses meilleurs résultats lorsque vous fournissez quatre éléments : le code ou l’exigence fonctionnelle, le langage, le framework de test et le comportement attendu. Les bonnes entrées incluent les chemins nominaux, les cas d’erreur, les valeurs limites, les dépendances externes et les objectifs de couverture.

Un prompt faible serait : « Write tests for my auth service. »

Un prompt plus solide serait : « Use tdd-guide to generate Jest tests for src/auth/password-validator.ts. Cover valid password, too short password, missing uppercase, missing number, missing special character, and null or empty input. Target 90% branch coverage. Use existing project style: describe, beforeEach, and expect(...).toBe(...). »

Workflow tdd-guide en pratique

Pour du code existant, suivez cette séquence :

1. Collez ou référencez le fichier source.
2. Précisez language, framework et la convention de nommage des fichiers de test.
3. Demandez des tests regroupés par priorité : comportement P0, cas limites P1, régressions P2.
4. Exécutez les tests générés localement.
5. Collez les erreurs de compilation, les assertions en échec ou la sortie de couverture dans l’assistant.
6. Demandez au skill d’affiner les imports, les mocks, les fixtures et les branches manquantes.

Pour une nouvelle fonctionnalité, appliquez red-green-refactor : demandez d’abord des tests en échec à partir des critères d’acceptation, implémentez le plus petit code qui les fait passer, puis demandez des améliorations sûres pour le refactoring tout en gardant les tests au vert.

Fichiers et scripts utiles à examiner en premier

Le dépôt contient des fichiers de support pratiques qu’il vaut la peine de lire avant un usage sérieux :

• assets/sample_input_python.json et assets/sample_input_typescript.json montrent le niveau d’entrée structurée qui améliore la qualité des sorties.
• assets/expected_output.json montre le type de synthèse sur les tests, la couverture et la qualité que le skill est conçu pour produire.
• scripts/test_generator.py prend en charge des modèles de génération de tests.
• scripts/coverage_analyzer.py est utile lorsque vous disposez de données de couverture LCOV, JSON ou XML.
• scripts/fixture_generator.py, framework_adapter.py et tdd_workflow.py indiquent comment le skill raisonne sur les mocks, les conventions de framework et les phases TDD.

FAQ du skill tdd-guide

tdd-guide est-il adapté aux débutants ?

Oui, si le débutant dispose d’une fonctionnalité ou d’une fonction concrète à tester. Le skill tdd-guide peut enseigner le rythme red, green, refactor tout en produisant des exemples exploitables. Cela dit, les débutants doivent quand même exécuter chaque test généré et lire les échecs. L’intérêt pédagogique vient de la comparaison entre le comportement attendu, les assertions générées et l’implémentation réelle.

Quels frameworks tdd-guide prend-il le mieux en charge ?

Les cas les plus adaptés sont Jest, Pytest, JUnit et Vitest, avec Mocha également mentionné dans la description du skill. La référence de framework incluse couvre des patterns TypeScript/JavaScript, Python et Java. Si vous utilisez un framework moins courant, fournissez un exemple de fichier de test issu de votre dépôt afin que le skill puisse reproduire les imports, le nommage, les hooks de setup et le style d’assertion.

Peut-il analyser des rapports de couverture ?

Oui. tdd-guide est conçu pour travailler avec des rapports de couverture comme LCOV, JSON et XML. Pour de meilleurs résultats, collez les fichiers et branches non couverts pertinents plutôt qu’un simple pourcentage. Un prompt comme « coverage is 65% » est moins utile que le partage de coverage/lcov.info, des plages de lignes non couvertes et des fichiers source liés à ces écarts.

Quand faut-il éviter d’utiliser tdd-guide ?

Ne l’utilisez pas comme seul garde-fou qualité pour des comportements critiques en matière de sécurité, de finance, de santé ou de conformité. Il peut aider à rédiger des tests et à faire apparaître des lacunes, mais il ne peut pas confirmer la justesse métier sans règles faisant autorité. Il est également peu adapté lorsque la base de code ne peut pas être partagée, qu’aucun comportement public n’est défini ou que le projet dépend fortement d’environnements d’intégration cachés.

Comment améliorer le skill tdd-guide

Améliorer les résultats de tdd-guide avec de meilleurs prompts

Le moyen le plus rapide d’améliorer les sorties de tdd-guide est de fournir le comportement attendu, pas seulement le code. Ajoutez des exemples d’entrées valides, d’entrées invalides, d’exceptions attendues, de valeurs limites et de conventions de test existantes. Si des mocks sont nécessaires, nommez la dépendance et indiquez ce qui doit être stubbed plutôt qu’exécuté réellement.

Ajouts utiles dans un prompt :

• “Do not mock the pure calculation function.”
• “Mock the payment gateway and assert it is called once.”
• “Use parameterized Pytest cases for boundary values.”
• “Prefer behavior-focused test names over implementation names.”

Corriger les échecs fréquents après la première sortie

Les problèmes courants sont les mauvais imports, le sur-mocking, les assertions fragiles liées à l’implémentation, l’absence de gestion de l’asynchrone et les tests qui améliorent la couverture de lignes sans renforcer la confiance. Après le premier résultat, collez l’échec de test ou l’erreur de compilation et demandez une correction ciblée. Par exemple : « These Jest tests fail because the service constructor requires a repository dependency. Revise using a typed mock and keep the same behavioral coverage. »

Utiliser les données de couverture pour prioriser le travail

Si votre objectif est d’améliorer la couverture, demandez au skill de classer les écarts par risque plutôt que de générer des tests pour chaque ligne non couverte. Priorisez les conditions non testées, les branches d’erreur, les méthodes publiques et les règles métier avant les getters triviaux ou les branches défensives. Le workflow de couverture du dépôt prend en charge la priorisation P0/P1/P2, plus utile que la seule poursuite d’un pourcentage brut.

Avancer par itérations vers une pratique TDD maintenable

La meilleure façon d’utiliser tdd-guide est de procéder par itérations. Demandez d’abord des tests en échec à partir des exigences, puis la forme minimale d’implémentation, puis des suggestions de refactoring qui gardent les tests stables. Gardez l’assistant concentré sur le comportement observable : entrées, sorties, effets de bord, exceptions et frontières d’intégration. Vous obtenez ainsi des tests qui restent utiles après les changements d’implémentation.