Arguments d'instrumentation Macrobenchmark

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 :

Si vous exécutez le macrobenchmark à partir de la ligne de commande, utilisez -P android.testInstrumentationRunnerArguments.[name of the argument]:

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

Si vous appelez directement la commande am instrument (ce qui peut être le cas dans les environnements de test CI), transmettez l'argument à am instrument avec -e:

adb shell am instrument -e androidx.benchmark.enabledRules BaselineProfile -w com.example.macrobenchmark/androidx.test.runner.AndroidJUnitRunner

Pour en savoir plus sur la configuration des analyses comparatives dans l'intégration continue, consultez la section Analyse comparative dans l'intégration continue.

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 de 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