| name | tdd-workflow |
| description | Use when: any code modification, feature implementation, bug fix, refactoring. Enforces TDD Red-Green-Refactor cycle. Mandatory for all coding agents. |
Skill : tdd-workflow — Test-Driven Development Workflow
BLOCKING SKILL — Doit être chargé par tout agent qui modifie du code dans ce dépôt.
Ce skill impose le cycle TDD Red → Green → Refactor avant toute modification de code.
Il complète xunit-unit-testing (qui définit COMMENT écrire les tests) en imposant QUAND les écrire.
1. Principe fondamental
Aucune ligne de code de production ne doit être écrite ou modifiée AVANT que les tests associés n'existent.
Le cycle obligatoire est :
1. RED — Écrire les tests qui décrivent le comportement attendu. Ils doivent échouer (ou ne pas compiler).
2. GREEN — Implémenter/modifier le code de production pour que tous les tests passent.
3. REFACTOR — Nettoyer le code en gardant les tests verts.
4. VERIFY — `dotnet test` sur le projet de tests puis sur la solution complète.
2. Protocole TDD obligatoire — Étapes détaillées
Étape 0 — Identifier la zone de test
Avant de modifier du code :
- Identifier l'assembly cible (ex:
InfraFlowSculptor.Domain, InfraFlowSculptor.Application, etc.)
- Vérifier si le projet
tests/<Assembly>.Tests/ existe.
- Si le projet n'existe pas → le créer en suivant le skill
xunit-unit-testing section 2 (template de projet).
- Vérifier si une classe de test
<SutName>Tests.cs existe pour le SUT (System Under Test).
- Si la classe de test n'existe pas → la créer avec le constructeur et le setup du SUT.
Étape 1 — RED : Écrire les tests en premier
- Identifier les comportements à tester pour le changement prévu.
- Écrire les tests unitaires qui capturent ces comportements :
- Pour un nouveau feature : tests des cas nominaux + cas d'erreur.
- Pour un bug fix : écrire le test qui reproduit le bug (test rouge).
- Pour un refactoring : vérifier que les tests existants couvrent le comportement, en ajouter si lacunaire.
- Les tests doivent suivre le naming
Given_{Preconditions}_When_{StateUnderTest}_Then_{ExpectedBehavior}.
- Les tests DOIVENT compiler mais PEUVENT échouer (c'est normal — c'est le RED).
Exception compilabilité : Si le SUT n'existe pas encore (nouveau handler, nouveau service),
le test peut ne pas compiler. C'est acceptable. Créer d'abord la structure minimale du SUT
(classe vide, méthode vide avec throw new NotImplementedException()) pour que les tests compilent,
puis passer à l'étape GREEN.
Étape 2 — GREEN : Implémenter le code de production
- Écrire le code de production minimal pour faire passer les tests.
- Ne pas anticiper des besoins futurs — écrire uniquement ce que les tests demandent.
- Exécuter
dotnet test .\tests\<Assembly>.Tests\<Assembly>.Tests.csproj — tous les tests doivent passer.
Étape 3 — REFACTOR : Nettoyer
- Nettoyer le code de production et les tests (duplication, nommage, structure).
- Ré-exécuter les tests — ils doivent toujours passer.
Étape 4 — VERIFY : Validation complète
- Exécuter
dotnet test .\InfraFlowSculptor.slnx — aucune régression sur l'ensemble de la solution.
- Exécuter
dotnet build .\InfraFlowSculptor.slnx — zero warnings si possible.
3. Quand le TDD s'applique
| Situation | TDD obligatoire ? | Détail |
|---|
| Nouveau handler / service / validator | ✅ OUI | RED: tests du handler → GREEN: implémenter → VERIFY |
| Bug fix sur du code existant | ✅ OUI | RED: test qui reproduit le bug → GREEN: corriger → VERIFY |
| Refactoring de code existant | ✅ OUI | Vérifier couverture existante, ajouter si lacunaire, puis refactorer |
| Nouveau domain aggregate / entity | ✅ OUI | RED: tests des invariants → GREEN: implémenter → VERIFY |
| Modification d'un Bicep generator | ✅ OUI | RED: tests du spec produit → GREEN: modifier → VERIFY |
| Ajout d'un endpoint API | ⚠️ PARTIEL | Tests du handler et validator obligatoires, endpoint wiring en intégration |
| Migration EF Core | ❌ NON | Pas de test unitaire sur les migrations |
| Configuration DI / startup | ❌ NON | Pas de test unitaire sur le câblage DI |
Fichier .md, .json, config | ❌ NON | Pas de code exécutable |
| Code Angular frontend | ⚠️ QUAND APPLICABLE | Si des tests Jasmine/Jest existent pour la zone, les maintenir |
4. Détection et enregistrement de la dette de tests
Quand un agent touche une zone de code et constate qu'il n'y a aucun test existant pour cette zone :
- Écrire les tests pour le changement en cours (TDD obligatoire).
- Enregistrer la dette pour le reste de la zone non couverte dans
.github/test-debt.md :
- Ajouter une ligne avec l'assembly, la classe/zone, la description du manque, la priorité, et la date.
- Ne pas essayer de couvrir toute la zone d'un coup — juste signaler.
- Ne jamais ignorer la dette détectée — l'enregistrement est obligatoire.
Priorités de dette
| Priorité | Critère |
|---|
| P1 — Critique | Code métier non testé : aggregates, handlers, validators, domain services |
| P2 — Important | Code infrastructure : repositories, mappers, transformers, clients |
| P3 — Souhaitable | Code utilitaire : extensions, options, helpers, configuration |
5. Initialisation d'un nouveau projet de tests
Si le projet de tests n'existe pas, le créer avant d'écrire les tests :
- Créer le dossier
tests/<Assembly>.Tests/
- Créer le
.csproj selon le template du skill xunit-unit-testing section 2
- Ajouter le projet à
InfraFlowSculptor.slnx via dotnet sln .\InfraFlowSculptor.slnx add .\tests\<Assembly>.Tests\<Assembly>.Tests.csproj
- Vérifier le build :
dotnet build .\tests\<Assembly>.Tests\<Assembly>.Tests.csproj
- Puis commencer le cycle RED
6. Intégration avec les autres skills et agents
| Skill / Agent | Interaction |
|---|
xunit-unit-testing | Définit le HOW (conventions, toolbox, AAA, nommage). Toujours charger en complément. |
dotnet-patterns | Définit les conventions du code de production. Les tests ne suivent pas les XML docs mais suivent le nommage. |
cqrs-feature | Pour une feature CQRS complète, les tests de chaque couche sont écrits AVANT l'implémentation de cette couche. |
dotnet-dev | Agent exécutant : charge ce skill + xunit-unit-testing avant toute modification de code. |
dev | Orchestrateur : s'assure que ce skill est mentionné dans les prompts de délégation. |
7. Checklist TDD — À vérifier avant de clore toute tâche de code
[ ] Projet de tests existe pour l'assembly modifié
[ ] Tests écrits AVANT le code de production (cycle RED → GREEN)
[ ] Tous les tests du projet passent : dotnet test .\tests\<Assembly>.Tests\
[ ] Aucune régression solution : dotnet test .\InfraFlowSculptor.slnx
[ ] Dette de tests enregistrée dans .github/test-debt.md si zone non couverte détectée
[ ] Pas de test dans InfraFlowSculptor.GenerationParity.Tests
8. Exceptions au TDD strict
Le cycle RED peut être assoupli dans ces cas précis (mais les tests restent obligatoires) :
- Scaffolding initial massif (ex:
cqrs-feature génère 15+ fichiers) : écrire les tests par couche après la génération de cette couche, mais AVANT de passer à la couche suivante.
- Correction d'urgence en production : le fix peut être écrit en premier, mais le test de non-régression DOIT suivre immédiatement dans la même tâche.
- Code purement déclaratif (Mapster configs, DI registrations, EF configurations) : pas de test unitaire requis, mais un test d'intégration futur est souhaitable (noter en dette P3).
