Ajouter des arguments d'instrumentation

Configurez le comportement de la bibliothèque avec les arguments d'instrumentation suivants. Vous pouvez les ajouter à votre configuration Gradle ou les appliquer directement lorsque vous exécutez une instrumentation à partir de la ligne de commande. Pour définir ces arguments pour toutes les exécutions de test Android Studio et de ligne de commande, ajoutez-les à testInstrumentationRunnerArguments :

android {
    defaultConfig {
        // ...
        testInstrumentationRunnerArguments["androidx.benchmark.dryRunMode.enable"] = "true"
    }
}

Vous pouvez également configurer des arguments d'instrumentation lorsque vous exécutez les analyses comparatives à partir d'Android Studio. Pour modifier les arguments, procédez comme suit :

  1. Modifiez la configuration d'exécution en cliquant sur Edit (Modifier), puis sur la configuration.
    modifier la configuration d'exécution
    Figure 1 : Modifier la configuration d'exécution.
  2. Modifiez les arguments d'instrumentation en cliquant sur More (Plus) avec la section Arguments d'instrumentation.
    modifier les arguments d'instrumentation
    Figure 2 : Modifier les arguments d'instrumentation.
  3. Ajoutez l'argument d'instrumentation requis en cliquant sur Add (Ajouter) sous Instrumentation Extra Params (Paramètres supplémentaires d'instrumentation).
    ajouter l'argument d'instrumentation requis
    Figure 3 : Ajouter l'argument d'instrumentation requis.

Si vous effectuez un appel direct à partir de la ligne de commande, utilisez -P android.testInstrumentationRunnerArguments.[name of the argument].

./gradlew :benchmark:connectedAndroidTest -P android.testInstrumentationRunnerArguments.androidx.benchmark.enabledRules=BaselineProfile

androidx.benchmark.compilation.enabled

Permet de désactiver la compilation entre chaque itération du benchmark. Par défaut, l'application cible est réinstallée et recompilée entre chaque benchmark, afin de respecter le CompilationMode transmis dans measureRepeated. La désactivation de cette option vous permet d'ignorer la réinstallation et la compilation si vous souhaitez compiler entièrement l'application cible avant d'exécuter la suite de tests, par exemple. Vous pouvez également exécuter toutes les analyses comparatives sur cette cible entièrement compilée.

  • Type d'argument : booléen
  • Valeur par défaut : true

androidx.benchmark.dryRunMode.enable

Vous permet d'exécuter des benchmarks dans une seule boucle afin de vérifier qu'elles fonctionnent correctement. Vous pouvez l'utiliser avec des tests réguliers lors de la vérification.

  • Type d'argument : booléen
  • Valeur par défaut : false

androidx.benchmark.enabledRules

Permet le filtrage des exécutions sur un seul type de test : la génération de profils de référence ou le test Macrobenchmark. Les listes d'éléments séparés par une virgule sont également compatibles.

  • Type d'argument : chaîne
  • Options disponibles :
    • Macrobenchmark
    • BaselineProfile
  • Valeur par défaut : non spécifié

androidx.benchmark.junit4.SideEffectRunListener

Vous pouvez obtenir des résultats de benchmark incohérents si des tâches non liées en arrière-plan sont exécutées en même temps que le benchmark.

Pour désactiver les tâches en arrière-plan lors du benchmark, définissez le type d'argument d'instrumentation listener sur androidx.benchmark.junit4.SideEffectRunListener.

  • Type d'argument : chaîne
  • Options disponibles :
    • androidx.benchmark.junit4.SideEffectRunListener
  • Valeur par défaut : non spécifié

androidx.benchmark.fullTracing.enable

Active les tracepoints androidx.tracing.perfetto tels que le traçage de composition Jetpack Compose.

Vous devez configurer votre projet pour pouvoir capturer le traçage de composition à partir des benchmarks. Pour en savoir plus, consultez Capturer une trace avec Jetpack. Macrobenchmark.

  • Type d'argument : booléen
  • Valeur par défaut : false

androidx.benchmark.profiling.mode

Permet de capturer des fichiers de suivi lors de l'exécution des benchmarks. Les options disponibles sont les mêmes que celles de la bibliothèque Microbenchmark. Pour en savoir plus, consultez les descriptions dans la section Profiler un Microbenchmark.

  • Type d'argument : chaîne
  • Options disponibles :
    • MethodTracing
    • StackSampling
    • None
  • Valeur par défaut : None

androidx.benchmark.startupProfiles.enable

Permet de désactiver la génération de profils de démarrage pendant l'analyse comparative.

  • Type d'argument : booléen
  • Valeur par défaut : true

androidx.benchmark.suppressErrors

Accepte les listes d'erreurs séparées par une virgule qui deviennent des avertissements.

  • Type d'argument : liste de chaînes
  • Options disponibles :

    • DEBUGGABLE

      L'erreur DEBUGGABLE indique que le package cible s'exécute avec debuggable=true dans son fichier manifeste, ce qui réduit considérablement les performances d'exécution pour prendre en charge les fonctionnalités de débogage. Pour éviter cette erreur, exécutez des benchmarks avec debuggable=false. L'argument débogable affecte la vitesse d'exécution de sorte que les améliorations du benchmark peuvent ne pas s'appliquer à l'expérience utilisateur réelle ou diminuer les performances des versions.

    • LOW-BATTERY

      Lorsque le niveau de la batterie est faible, les appareils réduisent souvent les performances pour économiser la batterie restante, par exemple en désactivant les cœurs importants. Cela se produit même lorsque les appareils sont branchés. Ne supprimez cette erreur que si vous profilez délibérément l'application avec des performances réduites.

    • EMULATOR

      L'erreur EMULATOR vous indique que le benchmark s'exécute sur un émulateur, ce qui n'est pas représentatif des appareils réels des utilisateurs. Les améliorations constatées sur l'émulateur peuvent ne pas se refléter dans l'expérience utilisateur réelle ou diminuer les performances réelles de l'appareil. Vous devez utiliser un appareil physique pour effectuer des benchmarks. Faites preuve d'une grande précaution quand vous supprimez cette erreur.

    • NOT-PROFILEABLE

      Le package cible $packageName s'exécute sans <profileable shell=true>. Un profilable est nécessaire sur Android 10 et 11 pour permettre à Macrobenchmark de capturer des informations de trace détaillées depuis le processus cible, comme les sections de traçage système définies dans l'application ou les bibliothèques. Faites preuve d'une grande précaution quand vous supprimez cette erreur.

    • METHOD-TRACING-ENABLED

      Le traçage de méthode est activé pour l'exécution de l'application analysée dans Macrobenchmark. Cela ralentit l'exécution de la VM. Par conséquent, ne prenez en compte que les métriques des fichiers de suivi de manière relative (par exemple, en comparant la rapidité de la première exécution à celle de la seconde). La suppression de cette erreur peut entraîner des résultats inexacts si vous comparez des builds utilisant différentes options de traçage des méthodes.

  • Valeur par défaut : liste vide

additionalTestOutputDir

Configure l'emplacement sur l'appareil où sont enregistrés les rapports de benchmark JSON et les résultats de profilage.

  • Type d'argument : chaîne du chemin d'accès
  • Valeur par défaut : tester le répertoire externe de l'APK