Afficher les rapports de couverture de code (avec l'agent sur l'appareil)

Le plug-in Android Gradle (AGP) peut créer des rapports de couverture de code pour vos tests d'instrumentation avec un agent de couverture sur l'appareil. Par défaut, AGP instrumente les classes de votre application avec JaCoCo lorsqu'il la compile. Cela signifie qu'il ajoute du code qui enregistre les parties de votre application exécutées par vos tests. Avec l'agent de couverture sur l'appareil, AGP compile votre application sans ce code supplémentaire, et l'agent instrumente les classes de votre application sur l'appareil de test pendant l'exécution de vos tests. Cette page explique comment activer la couverture de code sur l'appareil et générer des rapports.

Par rapport à la couverture de code au moment de la compilation, la couverture de code sur l'appareil offre les avantages suivants :

  • Compilations plus rapides : AGP n'exécute pas l'étape d'instrumentation JaCoCo sur les classes de votre application et leurs dépendances, ce qui peut réduire les temps de compilation de 10 à 20%.
  • APK de débogage plus petits : AGP n'ajoute pas de code de suivi de la couverture aux classes de votre application, ce qui peut réduire la taille de votre APK de débogage de 20 à 25 %.
  • Aucune classe générée inutilisée dans les rapports : les classes générées que vos tests n'utilisent pas ne réduisent pas vos chiffres de couverture.

Les améliorations réelles de la durée de compilation et de la taille de l'APK dépendent de votre projet.

Prérequis

Pour utiliser la couverture de code sur l'appareil, assurez-vous que votre projet et vos appareils de test répondent aux exigences suivantes :

  • AGP 9.6.0-alpha01 ou version ultérieure.
  • Un appareil ou un émulateur exécutant Android 9 (niveau d'API 28) ou version ultérieure.
  • Un type de compilation débogable pour la variante que vous testez, tel que le type de compilation debug par défaut. L'agent ne peut s'associer qu'à des applications débogables.
  • Tests d'instrumentation exécutés avec AndroidJUnitRunner ou un exécuteur de test personnalisé qui l'étend.

Activer la couverture de code sur l'appareil

La couverture de code sur l'appareil utilise la même propriété enableAndroidTestCoverage que la couverture de code au moment de la compilation. Définissez enableAndroidTestCoverage sur true dans les fichiers de compilation au niveau du module pour chaque variante pour laquelle vous souhaitez obtenir des rapports de couverture :

Kotlin

android {
    // ...
    buildTypes {
        debug {
            // Enable coverage for instrumentation tests
            enableAndroidTestCoverage = true
        }
    }
}

Groovy

android {
    // ...
    buildTypes {
        debug {
            // Enable coverage for instrumentation tests
            enableAndroidTestCoverage true
        }
    }
}

Ensuite, activez l'agent de couverture sur l'appareil et l'agrégation de rapports dans le fichier gradle.properties de votre projet :

android.experimental.androidTest.coverage.useOnDeviceAgent=true
android.experimental.reportAggregationSupport=true

La couverture de code sur l'appareil génère son rapport HTML avec le même moteur de rendu que les rapports de couverture de code unifiés. Elle nécessite donc les deux propriétés.

Générer des rapports de couverture de code sur l'appareil

Pour exécuter vos tests d'instrumentation et générer des rapports de couverture, connectez un appareil ou démarrez un émulateur, puis exécutez la tâche suivante :

Champ d'application de la couverture Commande Emplacement du rapport
Une variante ./gradlew :module-name:createVariantNameAndroidTestCoverageReport path-to-your-project/module-name/build/reports/coverage/androidTest/variant/connected/index.html

Différences par rapport à la couverture de code au moment de la compilation

Les rapports de couverture sur l'appareil et au moment de la compilation peuvent afficher des résultats différents pour les mêmes tests. Tenez compte des différences suivantes lorsque vous comparez les deux rapports ou lorsque vous déplacez les seuils de couverture de l'un à l'autre :

Région Couverture de code au moment de la compilation Couverture de code sur l'appareil
Quand les classes sont-elles instrumentées ? Lorsque l'AGP compile votre application, l'utilisation de JaCoCo Sur l'appareil de test pendant l'exécution de vos tests, à l'aide de l'agent de couverture
Classes du rapport Toutes les classes de votre module Uniquement les classes de l'espace de noms de votre module qui se chargent pendant l'exécution de vos tests, de sorte que les pourcentages de couverture peuvent être plus élevés
Nombre d'instructions Instructions de bytecode Java Instructions de bytecode DEX
Nombre de branches Branches dans le bytecode Java Branches dans le bytecode DEX. D8 peut compiler des conditions dans différentes branches, et chaque outil omet différentes branches générées par le compilateur. Les nombres peuvent donc différer.
Compteurs Instructions, branches, lignes, complexité, méthodes et classes Instructions, branches, lignes, méthodes et classes. Les compteurs de complexité ne sont pas encore acceptés.
Appareils de test Tous les niveaux d'API compatibles avec votre application Android 9 (niveau d'API 28) ou version ultérieure
Données de couverture brutes .ec fichiers coverage_metadata.pb et coverage_hits.pb fichiers

Pour revenir à la couverture de code au moment de la compilation, définissez android.experimental.androidTest.coverage.useOnDeviceAgent=false ou supprimez la propriété. Vous n'avez pas besoin de modifier vos fichiers de compilation ni les tâches que vous exécutez.

Problèmes connus

La couverture de code sur l'appareil présente les problèmes connus suivants :

  • Classes qui ne se chargent pas : les classes qui ne se chargent jamais pendant l'exécution de vos tests n'apparaissent pas dans le rapport. Les rapports de couverture de code au moment de la compilation les listent avec une couverture de 0 %.
  • Rapports agrégés : si votre projet collecte également la couverture des tests d'hôte, tels que les tests unitaires, le rapport de couverture agrégé créé par les tâches testAllSuites et testAllSuitesWithDependencies combine le nombre de bytecodes Java de ces tests avec le nombre de bytecodes DEX de l'agent. En raison des différences entre les deux, les nombres d'instructions et de branches agrégés peuvent différer de ceux des rapports de couverture de code au moment de la compilation.

Signalez tout autre problème ou commentaire via l'outil de suivi des problèmes.