Couverture de Tests Dart

Directives pour exécuter et interpréter la couverture de tests dans les packages Dart.

Quand utiliser cette compétence

• Quand on vous demande de « vérifier la couverture de tests » ou « améliorer la couverture ».
• Quand vous devez identifier quelles parties d'une librairie ne sont pas testées.

Découverte

Pour trouver les zones manquant de couverture de tests :

Exécuter l'Analyse de Couverture

Suivez le workflow pour générer et interpréter les données de couverture :

1. Exécuter les Tests avec Couverture : dart test --coverage=.dart_tool/coverage
2. Interpréter les Résultats : Utilisez le script ou format_coverage tel que décrit dans la section Interpreting Results pour identifier les fichiers spécifiques et les lignes manquantes.

Comment utiliser cette compétence (Le Workflow)

1. Assurez-vous que les tests passent en exécutant dart test.
2. Collectez la couverture en exécutant dart test --coverage=.dart_tool/coverage.
3. Interprétez les résultats en utilisant le script fourni ou des outils standard.
4. Ajoutez des tests pour couvrir les lignes manquées.

Exécuter la Couverture

Exécutez la commande suivante pour collecter la couverture au format JSON :

dart test --coverage=.dart_tool/coverage

[!NOTE] Nous utilisons .dart_tool/coverage comme répertoire de sortie car .dart_tool est généralement déjà ignoré dans les fichiers .gitignore.

[!TIP] Pour les projets avec une logique conditionnelle complexe, vous pouvez passer le flag --branch-coverage à dart test pour collecter la couverture au niveau des branches.

Interpréter les Résultats

Option 1 : Utiliser le script d'interprétation personnalisé

Ce repository inclut un script sans dépendances qui analyse la sortie JSON brute et fournit un résumé du pourcentage couvert et des lignes manquées.

Exécutez-le depuis la racine du projet (ajustez le chemin du script si nécessaire) :

dart run .agent/skills/dart-test-coverage/scripts/interpret_coverage.dart .dart_tool/coverage <package_name>

Remplacez <package_name> par le nom du fichier pubspec.yaml.

Exemple de Sortie :

package:my_pkg/src/file.dart: 50.0% (2/4 lines)
  Missed lines: 3, 4

Option 2 : Utiliser package:coverage

Si package:test est installé, package:coverage est probablement disponible comme dépendance transitive. Vous pouvez utiliser son outil format_coverage.

Pour obtenir un affichage lisible de la couverture :

dart run coverage:format_coverage --in=.dart_tool/coverage --out=stdout --pretty-print --report-on=lib

Cela affichera le contenu du fichier avec les compteurs de couverture à gauche (p. ex., 0| pour les lignes manquées).

Bonnes Pratiques pour Rapporter les Résultats

Quand vous présentez les résultats de couverture à l'utilisateur, suivez ces directives :

1. Énoncez d'abord le pourcentage de haut niveau pour donner un contexte immédiat.
2. Identifiez clairement les fichiers spécifiques et les lignes manquées.
3. Traduisez les numéros de ligne en code : Ne dites pas simplement « les lignes 3-6 sont manquées ». Regardez le fichier source et dites à l'utilisateur quelles fonctions ou blocs ne sont pas testés (p. ex., « La fonction divide manque de couverture »).
4. Proposez des corrections concrètes : Fournissez un exemple de code de test que l'utilisateur peut immédiatement appliquer pour couvrir les lignes manquées.
5. Utilisez des tableaux pour les résumés multi-fichiers : Quand vous rapportez sur plusieurs fichiers, utilisez un tableau markdown avec des colonnes pour File, Coverage %, et Missed Lines pour que le résumé soit facile à scanner.

Contraintes

• VÉRIFIEZ TOUJOURS que les tests passent avant de collecter la couverture.
• NE COMMITEZ PAS le répertoire .dart_tool/coverage.
• Concentrez les améliorations de couverture sur les fichiers lib/, pas sur test/ ou les fichiers générés.