Argumentos de instrumentação da biblioteca Macrobenchmark

Configure o comportamento da biblioteca com os argumentos de instrumentação apresentados a seguir. Os argumentos podem ser adicionados à configuração do Gradle ou aplicados diretamente ao executar a instrumentação na linha de comando. Para definir esses argumentos para todas as execuções de teste de linha de comando e do Android Studio, adicione-os a testInstrumentationRunnerArguments:

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

Também é possível configurar argumentos de instrumentação ao executar as comparações no Android Studio. Para mudar os argumentos, siga estas etapas:

Se você estiver executando o macrobenchmark na linha de comando, use -P android.testInstrumentationRunnerArguments.[name of the argument]:

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

Se você estiver invocando o comando am instrument diretamente (o que pode acontecer em ambientes de teste de CI), transmita o argumento para am instrument com -e:

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

Para mais informações sobre como configurar comparativos de mercado na CI, consulte Comparativo de mercado na CI.

androidx.benchmark.compilation.enabled

Permite desativar a compilação entre cada iteração da comparação. Por padrão, o aplicativo de destino é reinstalado e recompilado entre cada comparação, para respeitar o CompilationMode transmitido para measureRepeated. Desativar essa opção permite pular a reinstalação e a compilação se, por exemplo, você quiser compilar totalmente o app de destino uma vez antes de executar o pacote de testes e executar todas as comparações nesse destino totalmente compilado.

• Tipo de argumento: booleano
• Padrão: true

androidx.benchmark.dryRunMode.enable

Permite executar comparações em um único loop para conferir se elas funcionam corretamente. Pode ser usado com testes regulares como parte da verificação.

• Tipo de argumento: booleano
• Padrão: false

androidx.benchmark.enabledRules

Permite filtrar execuções para apenas um tipo de teste: geração de perfil de referência ou teste de Macrobenchmark. Além disso, oferece suporte a listas separadas por vírgulas.

• Tipo de argumento: string
• Opções disponíveis:
  • Macrobenchmark
  • BaselineProfile
• Padrão: não especificado

androidx.benchmark.junit4.SideEffectRunListener

Você poderá receber resultados inconsistentes de comparativos de mercado, se um trabalho em segundo plano não relacionado for executado enquanto o comparativo estiver em execução.

Para desativar o trabalho em segundo plano durante a execução do comparativo de mercado, defina o tipo de argumento de instrumentação listener como androidx.benchmark.junit4.SideEffectRunListener.

• Tipo de argumento: string
• Opções disponíveis:
  • androidx.benchmark.junit4.SideEffectRunListener
• Padrão: não especificado

androidx.benchmark.fullTracing.enable

Ativa os tracepoints androidx.tracing.perfetto, por exemplo, o rastreamento de composição do Jetpack Compose.

É necessário configurar o projeto para poder capturar o rastreamento de composição de comparativos de mercado. Para saber mais, consulte Capturar um rastro com a Macrobenchmark do Jetpack.

• Tipo de argumento: booleano
• Padrão: false

androidx.benchmark.profiling.mode

Permite capturar arquivos de rastreamento durante comparações. As opções disponíveis são as mesmas da biblioteca Microbenchmark. Para saber mais, consulte as descrições em Criar um perfil de Microbenchmark.

• Tipo de argumento: string
• Opções disponíveis:
  • MethodTracing
  • StackSampling
  • None
• Padrão: None

androidx.benchmark.startupProfiles.enable

Permite desativar a geração de perfis de inicialização durante a comparação.

• Tipo de argumento: booleano
• Padrão: true

androidx.benchmark.suppressErrors

Aceita uma lista de erros separada por vírgulas para transformar em avisos.

• Tipo de argumento: lista de strings

• Opções disponíveis:

  • DEBUGGABLE

    O erro DEBUGGABLE indica que o pacote de destino está sendo executado com debuggable=true no manifesto, o que reduz drasticamente o desempenho na execução para oferecer suporte a recursos de depuração. Para evitar esse erro, execute comparações com debuggable=false. O argumento depurável afeta a velocidade de execução de maneiras que fazem com que as melhorias na comparação possam não se repetir na experiência de um usuário real ou regredir o desempenho da versão.

  • LOW-BATTERY

    Quando a bateria está fraca, os dispositivos geralmente reduzem o desempenho para economizar a bateria restante, como ao desativar os núcleos grandes. Isso ocorre mesmo quando os dispositivos estão conectados. Suprima esse erro apenas se você estiver deliberadamente criando um perfil de desempenho reduzido para o app.

  • EMULATOR

    O erro EMULATOR informa que a comparação está sendo executada em um emulador, que não representa dispositivos de um usuário real. As melhorias de comparação no emulador podem não se repetir na experiência de um usuário real ou regredir o desempenho de um dispositivo real. Para fazer comparações, use um dispositivo físico. Tome cuidado ao suprimir esse erro.

  • NOT-PROFILEABLE

    O pacote de destino $packageName está sendo executado sem <profileable shell=true>. A criação de perfis é necessária no Android 10 e 11 para permitir que a Macrobenchmark capture informações detalhadas de rastreamento do processo de destino, como seções de rastreamento do sistema definidas no app ou bibliotecas. Tome cuidado ao suprimir esse erro.

  • METHOD-TRACING-ENABLED

    A execução da Macrobenchmark para o app que está sendo comparado tem o rastreamento de método ativado. Como isso torna a VM mais lenta que o normal, considere apenas as métricas dos arquivos de rastreamento em termos relativos. Por exemplo, comparando a velocidade da primeira execução com a segunda. A supressão desse erro poderá causar resultados imprecisos se você comparar versões com diferentes opções de rastreamento de método.

• Padrão: uma lista vazia

additionalTestOutputDir

Configura o local onde os relatórios de comparação JSON e os resultados de criação de perfil são salvos no dispositivo.

• Tipo de argumento: string do caminho
• Padrão: testar o diretório externo do APK