Developer Device Platform Device Run 中的智能分片

Developer Device Platform Device Run 中的智能分片功能会使用存储在 Cloud Storage 中的历史测试作业时间,将 Android 插桩测试和 iOS XCTest 分配到并行分片中。统一分片会按数量划分测试用例,而不考虑每个测试的运行时间;智能分片则不同,它会按预期时长平衡分片,使并行分片在目标时间前后完成。

本文档介绍了智能分片算法如何计算分片数量和分配测试,说明了存储在 Cloud Storage 存储桶中的 YAML 计时记录的架构,并解答了有关 Android Test Orchestrator 开销和 30 天滚动数据窗口的常见问题。如需了解使用 Google Cloud CLI 的命令行说明,请参阅 Android 插桩和 iOS XCTest 说明。

智能分片算法的工作原理

分片不等于可以并发运行的测试数量。在请求时,可用设备数量可能少于分片限制。可分配给用户的实际并发设备数量可能低于他们指定的分片数量。

当您在 gcloud CLI 中使用 --sharding-option=smart 提交会话或在 REST API 中配置 smartSharding 时,Developer Device Platform 会在会话创建、测试执行和完成过程中运行一个包含六个阶段的工作流:

  1. 读取历史时间数据并匹配设备情境。在安排分片之前,Device Run 服务代理会从 Cloud Storage 中读取您的智能分片 YAML 文件。它会在 records 列表中搜索与目标作业的 deviceModel 和 osVersion(不区分大小写)匹配的 shardingContext。如果该设备和操作系统组合没有完全匹配项,Developer Device Platform 会回退到文件中的第一个可用 records 条目。如果 YAML 文件尚不存在,则会话将作为冷启动继续,并且计时历史记录为空。
  2. 将样本过滤到 30 天滚动窗口,并计算预期时长。对于所选上下文记录,Developer Device Platform 仅保留 recordTime 属于过去 30 天内的计时样本,并计算每个测试用例的算术平均时长。如果通过 --orchestrator-version 启用了 Android Test Orchestrator,Developer Device Platform 还会计算 ANDROID_TEST_ORCHESTRATOR 开销样本的 30 天平均值,并将该平均开销添加到每个测试用例的预期时长中。
  3. 发现可运行的测试并分配后备估算值。在工作器主机上,Developer Device Platform 会静态检查测试软件包,即读取 Android 测试 APK 中的 DEX 文件,或 iOS 上已编译的 .xctest 符号和 .xctestrun 过滤条件,应用所有 --test-targets 过滤条件,并排除已忽略或已抑制的测试(例如 @Ignore 或 @Suppress)。每个可运行的测试单元都会根据以下三个层级获得预期时长:
    • 录制的测试用例:使用其 30 天历史平均时长(如果启用了 Android Test Orchestrator,则加上平均 Orchestrator 开销)。在 Android 上,参数化 JUnit 类(例如使用 @RunWith(Parameterized.class)、JUnitParamsRunner 或 TestParameterInjector 的类)会安排为单个类级单元,其预期时长是该类的所有记录方法时长的总和。
    • 现有套件中未记录的测试用例:使用匹配记录中所有记录的非零测试用例的平均预期时长。
    • 冷启动(无记录的历史记录):使用默认估算值,即每个测试单元 30 秒。
  4. 计算分片数。Developer Device Platform 会将所有可运行测试单元的预期时长相加,然后除以您配置的 --smart-sharding-target-duration(有效范围为 2m 到 1h),并向上舍入到最接近的整数分片:

    optimal_shards = max(1, ceil(total_expected_duration / target_duration))
    

    接下来,Developer Device Platform 会将最终分片数量设置为 1 与以下限制中的最低值之间的值:

    • 可运行的测试单元总数(防止出现空分片)。
    • 您的 --smart-sharding-max-shard-count 值(如果设置的值大于 0)。
    • 平台限制(实体设备为 20 个分片,Android 虚拟设备为 200 个分片)。
  5. 使用最长处理时间优先装箱算法分配测试。 Developer Device Platform 会按预期时长降序(从最慢到最快)对所有可运行的测试单元进行排序,并初始化一个按累计时长排序的空分片最小堆。它每次处理一个测试单元,将剩余的最慢测试分配给累计时长最短的分片,并更新该分片的总时长。优先安排耗时较长的“长杆”测试,将其隔离到单独的分片中,而较短的测试则填补剩余的空隙,以保持总分片时长均衡。

  6. 记录通过时间并更新 Cloud Storage。所有分片完成后,Developer Device Platform 会收集通过测试用例的测量 startTime 到 endTime 持续时间,在 YAML 文件中修剪所有设备上下文中超过 30 天的所有样本,移除所有没有剩余有效样本的上下文记录,并使用代系匹配的乐观并发重试将更新后的 YAML 文件写回 Cloud Storage。

智能分片 YAML 文件结构

使用 gcloud CLI 运行会话时,--smart-sharding-record-name 会指定存储在 Google Cloud 项目的 Cloud Storage 存储桶中的计时记录的基本文件名(不包括 YAML 扩展名):

gs://BUCKET_NAME/automation/smart-sharding/RECORD_NAME.yaml

替换以下占位符:

  • BUCKET_NAME:使用 --bucket-name 指定的 Cloud Storage 存储桶名称,或默认情况下为 <var>PROJECT_ID</var>-devicerun(其中 PROJECT_ID 是您的 Google Cloud项目 ID)。
  • RECORD_NAME:传递给 --smart-sharding-record-name 的记录标识符,不带 YAML 文件扩展名(例如,checkout-suite 映射到 automation/smart-sharding/checkout-suite.yaml)。

YAML 计时记录示例

以下示例展示了一个智能分片 YAML 文件 (checkout-suite.yaml),其中包含两个设备上下文(一个运行 Android Test Orchestrator 的 Android 设备和一个 iOS 设备)的时间记录:

records:
- shardingContext:
    deviceModel: shiba
    osVersion: '34'
  testCaseTimingRecords:
  - testCaseName: com.example.shop.CheckoutTest#testCompletePurchase
    timingSamples:
    - duration: 42.180s
      recordTime: '2026-11-08T14:20:11Z'
    - duration: 44.050s
      recordTime: '2026-11-09T16:45:03Z'
  - testCaseName: com.example.shop.CartTest#testApplyPromoCode
    timingSamples:
    - duration: 8.600s
      recordTime: '2026-11-08T14:20:11Z'
    - duration: 9.120s
      recordTime: '2026-11-09T16:45:03Z'
  conditionalOverheads:
  - condition: ANDROID_TEST_ORCHESTRATOR
    timingSamples:
    - duration: 2.850s
      recordTime: '2026-11-08T14:20:11Z'
    - duration: 3.150s
      recordTime: '2026-11-09T16:45:03Z'
- shardingContext:
    deviceModel: iphonese3
    osVersion: '18.4'
  testCaseTimingRecords:
  - testCaseName: ShopTests.CheckoutTests#testApplePaySheet
    timingSamples:
    - duration: 19.340s
      recordTime: '2026-11-09T17:10:29Z'

YAML 字段参考

智能分片 YAML 文件使用 camelCase 字段名称对 SuiteTiming 架构进行序列化。下表介绍了文件中的每个字段:

字段 类型 说明
metadata 地图(string到string) 在聚合更新期间保留的可选套件级键值对元数据。
records 对象列表 每个设备的时间条目 (SuiteTimingWithContext),按硬件型号和操作系统版本进行分区。
records[].shardingContext 对象 用于限定一组时间测量结果范围的硬件和操作系统维度。
records[].shardingContext.deviceModel string 记录耗时的设备的型号标识符(例如,Android 上的 shiba 或 iOS 上的 iphonese3)。
records[].shardingContext.osVersion string 设备的操作系统或 SDK 版本(例如 Android API 级别 '34' 或 iOS 版本 '18.4')。
records[].testCaseTimingRecords 对象列表 此上下文中各个通过测试用例的历史执行时长。
records[].testCaseTimingRecords[].testCaseName string 采用 package.ClassName#methodName 格式(如果缺少方法元数据,则采用 package.ClassName 格式)的完全限定测试标识符。
records[].testCaseTimingRecords[].timingSamples 对象列表 测试用例的测量时长列表(滚动 30 天),在通过运行后附加。
timingSamples[].duration 时长字符串 测量的时长,格式为秒,可选择小数精度(例如 10s 或 42.180s)。
timingSamples[].recordTime 时间戳字符串 RFC 3339 UTC 时间戳,表示 Developer Device Platform 记录样本的时间(例如 '2026-11-09T16:45:03Z')。
records[].conditionalOverheads 对象列表 在特定运行程序模式下测量的可选执行开销,范围限定为 shardingContext。如果没有适用的条件性开销,则省略。
records[].conditionalOverheads[].condition string 执行条件的标识符。支持的值:ANDROID_TEST_ORCHESTRATOR。
records[].conditionalOverheads[].timingSamples 对象列表 从符合条件的分片中记录的每次转换开销样本的滚动 30 天列表。

了解 ANDROID_TEST_ORCHESTRATOR 开销时间

使用 --orchestrator-version 运行 Android 插桩测试时,智能分片 YAML 文件会包含一个值为 condition: ANDROID_TEST_ORCHESTRATOR 的 conditionalOverheads 条目。与 testCaseTimingRecords 不同,这些开销样本不会附加到单个测试方法或编号的分片。

一个开销时长样本代表的内容

启用 Android Test Orchestrator 后,它会在其自己的隔离 Instrumentation 进程中运行每个测试方法。单个测试 startTime 和 endTime 时间戳仅捕获在每个测试方法内花费的时间,不包括在测试之间花费的时间,即停止上一个应用进程、选择性清除软件包数据 (clearPackageData) 以及为下一个测试启动全新 Instrumentation 进程所花费的时间。

为了衡量测试间转换费用,Developer Device Platform 会检查每个运行两个或更多测试用例的通过分片 (N > 1),并计算:

  1. 总分片执行时间跨度:从分片中最早的测试 startTime 到分片中最新的测试 endTime 经过的实际用时。
  2. 测试用例总时长:该分片中所有 N 个测试用例的 (endTime - startTime) 之和。
  3. 平均每次转换开销:由于 N 个依序测试在测试之间有 N - 1 次转换,因此 Developer Device Platform 会从分片跨度中减去总测试时长,然后除以 N - 1:

    overhead_sample = max(0, total_span - total_test_duration) / (N - 1)
    

作业中每个通过的多测试分片都会为 ANDROID_TEST_ORCHESTRATOR 贡献一个 TimingSample。例如,如果一个会话在三个分片上运行,并且每个分片至少通过两个测试用例,则该会话会附加三个开销样本,并带有该会话的 recordTime。仅运行单个测试用例 (N = 1) 的分片具有零个测试间转换,并且不会发出开销样本。

为什么开销未与测试用例或分片关联

Developer Device Platform 会在 shardingContext(deviceModel 和 osVersion)级别(而非每个测试或每个分片级别)存储 ANDROID_TEST_ORCHESTRATOR 样本,原因有两点:

  • 开销取决于设备和操作系统,而不是测试逻辑。无论接下来运行哪个 JUnit 方法,进程启动、binder 初始化和软件包数据清除所花费的时间大致相同,而每当测试时间或分片数量发生变化时,分片分组都会动态变化。
  • 分离开销可保留干净的基准测试时间。将进程隔离开销排除在 testCaseTimingRecords 之外,意味着您可以在共享同一 YAML 记录的运行之间启用或关闭 --orchestrator-version,而不会影响底层每次测试作业的执行时长。

Developer Device Platform 如何在分片分配期间使用开销

在新会话中设置 --orchestrator-version 后,Developer Device Platform 会计算有效 ANDROID_TEST_ORCHESTRATOR 样本的 30 天平均值 (avg_overhead),并将其添加到每个测试用例的 30 天平均时长中,然后再计算分片数量或打包分片:

expected_test_duration = avg_test_duration + avg_overhead

如果未在会话中设置 --orchestrator-version,则 avg_overhead 为 0s,并且在运行期间会忽略 YAML 文件中的任何现有 ANDROID_TEST_ORCHESTRATOR 条目。

向每个测试用例添加 avg_overhead 会通过以下三种方式影响分片:

  • 针对包含许多快速测试的套件,提供准确的分片数量。假设有一个包含 60 个单元式插桩测试的套件,每个测试运行 1s,平均 Orchestrator 转换开销为 3s,目标分片时长为 2m (120s)。如果不考虑开销,总预期时长看起来像 60s,因此所有 60 项测试都会打包到 1 个分片中,而该分片实际上需要近 4 分钟才能完成(60s 的测试作业时间加上 59 * 3s = 177s 的 Orchestrator 转换时间)。通过将 3s 开销添加到每个测试(每个测试的预期时长为 4s,总时长为 240s),Developer Device Platform 会分配 2 个分片 (ceil(240s / 120s)),以便每个分片在接近两分钟的目标时间内完成。
  • 测试数量不同时,平衡分片打包。在最长处理时间优先装箱期间,分配了一个 40s 界面测试的分片会产生 43s 的预期费用 (40s + 3s),而分配了 10 个 4s 测试的分片会产生 70s 的预期费用 (10 * (4s + 3s))。包含每次测试的开销可防止具有许多简短测试的分片在不经意间累积数分钟未计入的进程重启延迟时间。
  • 针对新添加的测试提供切合实际的估算值。由于现有套件中未记录的测试会沿用已知测试的平均预期时长(其中已包含 avg_overhead),因此新测试在首次运行时会自动考虑 Orchestrator 开销。

了解 30 天数据窗口和初始运行行为

智能分片不需要 30 天的历史数据即可开始优化测试运行。即使只记录了一个样本,也会在下一次会话中激活基于时长的分片计算和装箱。 30 天是 Developer Device Platform 在读取和更新 YAML 时间记录时使用的滚动保留和回溯期。

为什么智能分片使用 30 天滚动窗口

每次 Developer Device Platform 读取或更新智能分片 YAML 文件时,都会滤除 recordTime 超过 30 天的所有 TimingSample。这个 30 天的时间窗口平衡了两个工程目标:

  • 适应代码库变化并限制文件大小。应用功能、界面流程和测试实现会随着时间的推移而不断演变。自动逐出超过 30 天的样本可防止过时的计时(例如,屏幕重新设计或网络层重构之前的计时)影响当前的分片分配。逐出过期条目(并丢弃不再具有有效样本的设备上下文)还可以使 YAML 文件保持紧凑,并远低于 32 MB 的限制。
  • 在支持每周套件的同时,平滑运行间差异。单次测试运行可能会受到垃圾回收、后台系统服务或模拟器调度产生的瞬时噪声的影响。对 30 天时间范围内的样本进行平均处理,可以消除一次性峰值,同时保留足够的历史记录,以便夜间、每周或冲刺节奏的持续集成流水线在运行之间保留热启动时间记录。

第 1 周和第 2 周的预期效果

如果您现在对现有测试套件启用智能分片,执行时间会遵循快速预热曲线,而无需等待数周才能缩短:

  1. 首次运行(冷启动)。由于 YAML 文件尚不存在于 Cloud Storage 中,Developer Device Platform 会为每个可运行的测试单元分配 30 秒的默认预估时间。它会将分片数量计算为 ceil(num_tests * 30s / target_duration)(受最大分片数量和平台限制),并将测试分布到各个分片,类似于均匀分片。在首次运行时:
    • 如果测试的平均运行时间远低于 30 秒,则运行 1 分配的分片数量可能会超出所需数量(最多 --smart-sharding-max-shard-count 个)。
    • 如果您的套件包含多个耗时数分钟的界面测试,则两个慢速测试可能会偶然落在同一分片中,从而使该分片成为实际完成时间的瓶颈。
    • 运行 1 完成后,Developer Device Platform 会在 Cloud Storage 中创建 YAML 文件,其中包含通过测试的测量时长。
  2. 第二次运行(在第 1 次运行完成后立即执行)。智能分片已启用。Developer Device Platform 会读取运行 1 记录的时长,根据套件的实际执行时间重新计算分片数量,并首先将最慢的测试隔离到单独的分片中。通常,您会在第 2 次运行(即使在启用智能分片的当天)时看到实际会话时长和分片数量适当调整的主要缩减。
  3. 第 1 周的剩余时间和第 2 周。在接下来的几次运行中,分片平衡在以下三种特定情况下会继续收紧:
    • 平滑单次运行方差。由于每次通过运行都会附加另一个 TimingSample,因此运行 1 的瞬时波动会平均化,从而减少在 --smart-sharding-target-duration 之后完成的落后分片。
    • 从最初失败的运行中填充测试。为防止快速崩溃或测试超时破坏历史平均值,Developer Device Platform 仅记录通过测试的时间(在 Android 上,仅记录整体套件状态为 PASSED 的分片的时间)。任何在第 1 次运行中未记录时间的测试都会在第 2 次运行中使用套件的平均时长,然后在通过后切换到其自己的测量时间。
    • 添加新的测试或设备型号。在第 1 周和第 2 周期间提交的所有新测试用例都会自动使用套件的平均预期时长,而不是还原为 30 秒的默认值。如果您使用相同的记录名称向会话添加第二个 --device 模型,则其首次运行会使用现有设备的时间作为初始回退,然后为后续运行记录专用的 shardingContext 条目。

常见问题解答

以下问题涵盖了在 CI/CD 流水线中运行智能分片时的常见操作场景。

后续步骤