宏基准测试插桩参数

使用以下插桩参数配置库的行为。您可以将其添加到 Gradle 配置中,也可以在从命令行运行插桩时直接应用它们。要为所有 Android Studio 和命令行测试运行设置这些参数,请将其添加到 testInstrumentationRunnerArguments

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

您还可以在从 Android Studio 运行基准测试时设置插桩参数。如需更改参数,请执行以下操作

  1. 点击修改,然后点击配置,以修改运行配置。
    edit run configuration
    图 1. 修改运行配置。
  2. 点击 更多(位于插桩参数旁),以修改插桩参数。
    edit the instrumentation arguments
    图 2. 修改插桩参数。
  3. 插桩额外参数下点击 添加,以添加所需的插桩参数。
    add required instrumentation argument
    图 3. 添加所需的插桩参数。

如果您从命令行运行宏基准测试,请使用 -P android.testInstrumentationRunnerArguments.[name of the argument]

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

如果您直接调用 am instrument 命令(在 CI 测试环境中可能会出现这种情况),请使用 -e 将参数传递给 am instrument

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

有关在 CI 中配置基准测试的更多信息,请参阅在 CI 中进行基准测试

androidx.benchmark.compilation.enabled

允许您在基准测试的每次迭代之间停用编译。默认情况下,目标应用会在每次基准测试之间重新安装和重新编译,以遵循传递给 CompilationModemeasureRepeated。如果您想在运行测试套件之前完整编译目标应用一次,然后针对该完整编译的目标运行所有基准测试,则可以停用此功能以跳过重新安装和编译。

  • 参数类型:布尔值
  • 默认值: true

androidx.benchmark.dryRunMode.enable

允许您在单个循环中运行基准测试,以验证其是否正常工作。您可以将其与常规测试一起用作验证的一部分。

  • 参数类型:布尔值
  • 默认值: false

androidx.benchmark.enabledRules

允许过滤运行,仅针对一种测试类型:基准配置文件生成或宏基准测试。也支持逗号分隔列表。

  • 参数类型:字符串
  • 可用选项
    • 宏基准测试
    • BaselineProfile
  • 默认值:未指定

androidx.benchmark.junit4.SideEffectRunListener

如果在基准测试运行时执行了不相关的后台工作,您可能会得到不一致的基准测试结果。

要在基准测试期间停用后台工作,请将 listener 插桩参数类型设置为 androidx.benchmark.junit4.SideEffectRunListener

  • 参数类型:字符串
  • 可用选项
    • androidx.benchmark.junit4.SideEffectRunListener
  • 默认值:未指定

androidx.benchmark.fullTracing.enable

启用 androidx.tracing.perfetto 跟踪点,例如 Jetpack Compose 组合跟踪。

您需要设置项目才能从基准测试中捕获组合跟踪。如需了解更多信息,请参阅使用 Jetpack Macrobenchmark 捕获跟踪

  • 参数类型:布尔值
  • 默认值false

androidx.benchmark.profiling.mode

允许在运行基准测试时捕获跟踪文件。可用选项与 Microbenchmark 库的选项相同,有关更多信息,请参阅分析微基准测试中的说明。

  • 参数类型:字符串
  • 可用选项
    • MethodTracing
    • StackSampling
    • None
  • 默认值: None

androidx.benchmark.startupProfiles.enable

允许您在基准测试期间停用启动配置文件的生成。

  • 参数类型:布尔值
  • 默认值: true

androidx.benchmark.suppressErrors

接受逗号分隔的错误列表,将其转换为警告。

  • 参数类型:字符串列表
  • 可用选项

    • DEBUGGABLE

      DEBUGGABLE 错误表示目标软件包在其清单中以 debuggable=true 运行,这会大大降低运行时性能以支持调试功能。为了避免此错误,请在 debuggable=false 的情况下运行基准测试。可调试参数会以影响执行速度的方式,这可能意味着基准测试的改进无法转化为真实用户的体验,或者可能导致发布性能下降。

    • LOW-BATTERY

      当电池电量低时,设备通常会降低性能以节省剩余电量,例如通过禁用大核。即使设备已插入电源也会发生这种情况。仅当您有意以降低的性能分析应用时,才抑制此错误。

    • EMULATOR

      EMULATOR 错误表示基准测试正在模拟器上运行,这不代表真实用户设备。模拟器基准测试的改进可能无法转化为真实用户的体验,或者可能导致真实设备性能下降。您应该改用物理设备进行基准测试。请务必谨慎抑制此错误。

    • NOT-PROFILEABLE

      目标软件包 $packageName 正在运行,但没有 <profileable shell=true>。在 Android 10 和 11 上,需要 Profileable 才能让 Macrobenchmark 从目标进程捕获详细的跟踪信息,例如应用或库中定义的系统跟踪部分。请务必谨慎抑制此错误。

    • METHOD-TRACING-ENABLED

      正在进行基准测试的应用的宏基准测试运行已启用方法跟踪。这会导致虚拟机运行速度慢于平时,因此仅从相对角度考虑跟踪文件中的指标,例如,比较第一次运行与第二次运行的速度。如果您比较使用不同方法跟踪选项的构建的基准测试结果,抑制此错误可能会导致不准确的结果。

  • 默认值:空列表

additionalTestOutputDir

配置 JSON 基准测试报告和性能分析结果在设备上的保存位置。

  • 参数类型:路径字符串
  • 默认值:测试 APK 的外部目录