Couverture de Test Dart

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

Quand utiliser cette compétence

• Quand on vous demande de « vérifier la couverture de test » ou « améliorer la couverture ».
• Quand vous avez besoin d'identifier les parties d'une bibliothèque qui ne sont pas testées.

Découverte

Pour trouver les zones manquant de couverture de test :

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 comme décrit dans la section Interprétation des résultats pour identifier les fichiers spécifiques et les lignes manquées.

Comment utiliser cette compétence (Le Workflow)

1. Assurez-vous que les tests réussissent 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 standards.
4. Ajoutez des tests pour couvrir les lignes manquées.

Exécution de 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étation des résultats

Option 1 : Utiliser le script d'interpréteur 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 à partir de 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 depuis 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 « pretty print » 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 visites à gauche (p. ex., 0| pour les lignes manquées).

Bonnes pratiques pour présenter 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 les fichiers spécifiques et les lignes manquées clairement.
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 correctifs concrets : 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 Fichier, Couverture %, et Lignes manquées pour que le résumé soit facile à parcourir.

Contraintes

• TOUJOURS vérifier que les tests réussissent avant de collecter la couverture.
• NE PAS valider 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.