Developer Device Platform Device Run 的智慧型 sharding 功能

Developer Device Platform Device Run 的智慧型 sharding 功能,會使用儲存在 Cloud Storage 的歷來測試執行時間,將 Android 檢測設備測試和 iOS XCTest 分配到平行 shard。統一資料分割會依數量劃分測試案例,不考慮各項測試的執行時間;智慧型資料分割則會依預期時間長度平衡資料分割,讓平行資料分割在相近的目標時間內完成。

本文說明智慧型 shard 演算法如何計算 shard 數量及指派測試、儲存在 Cloud Storage bucket 的 YAML 時間記錄結構定義,並回答有關 Android Test Orchestrator 負擔和 30 天滾動資料時間範圍的常見問題。如需使用 Google Cloud CLI 的指令列操作說明,請參閱 Android 檢測和 iOS XCTest 操作說明。

智慧型 sharding 演算法的運作方式

資料分割不等於可同時執行的測試數量。在要求時,可用裝置數量可能少於資料分割限制。使用者可分配到的實際並行裝置數量,可能低於指定的 shard 數量。

在 gcloud CLI 中使用 --sharding-option=smart 提交工作階段,或在 REST API 中設定 smartSharding 時,Developer Device Platform 會執行六個階段的工作流程,包括建立工作階段、執行測試和完成測試:

  1. 讀取歷來時間資料,並比對裝置情境。在排定 shard 前,Device Run 服務代理會從 Cloud Storage 讀取智慧型 sharding YAML 檔案。它會在 records 清單中搜尋與目標工作的 deviceModel 和 osVersion (不區分大小寫) 相符的 shardingContext。如果沒有完全比對該裝置和 OS 組合的項目,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. 找出可執行的測試,並指派備用預估值。在 worker 主機上,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),然後無條件進位至最接近的整數 shard:

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

    接著,Developer Device Platform 會將最終 shard 數量設為 1 和下列最低限制之間的值:

    • 可執行的測試單元總數 (避免空白 shard)。
    • --smart-sharding-max-shard-count 值 (如果設為大於 0)。
    • 平台限制 (實體裝置為 20 個 shard,Android 虛擬裝置為 200 個 shard)。
  5. 使用最長處理時間優先裝箱法指派測試。Developer Device Platform 會按照預期時間長度,由慢到快排序所有可執行的測試單元,並依累積時間長度,初始化空 shard 的 min-heap。這項功能會逐一處理測試單元,將剩餘測試中最慢的測試指派給累積時間最短的資料分割,並更新該資料分割的總時間。先排定緩慢的「長桿」測試,將其隔離到不同的資料分割,再以較短的測試填補剩餘的空隙,保持總資料分割時間長度平衡。

  6. 記錄通過時間並更新 Cloud Storage。所有 shard 完成後,Developer Device Platform 會收集通過測試案例的 startTime 到 endTime 測量時間長度,並在 YAML 檔案中,刪除所有裝置情境中超過 30 天的樣本,移除沒有剩餘有效樣本的情境記錄,然後使用世代比對樂觀並行重試,將更新後的 YAML 檔案寫回 Cloud Storage。

智慧型資料分割 YAML 檔案結構

使用 gcloud CLI 執行工作階段時,--smart-sharding-record-name 會指定儲存在 Google Cloud 專案 Cloud Storage bucket 中的計時記錄基本檔案名稱 (不含 YAML 副檔名):

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

替換下列預留位置:

  • BUCKET_NAME:使用 --bucket-name 指定的 Cloud Storage bucket 名稱,或預設為 <var>PROJECT_ID</var>-devicerun (其中 PROJECT_ID 是您的 Google Cloud專案 ID)。
  • RECORD_NAME:傳遞至 --smart-sharding-record-name 的記錄 ID,不含 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 欄位參考資料

智慧型 sharding YAML 檔案會使用 camelCase 欄位名稱,將 SuiteTiming 結構定義序列化。下表說明檔案中的各個欄位:

欄位 類型 說明
metadata 地圖 (string到string) 選用的套件層級鍵/值中繼資料,會在匯總更新時保留。
records 物件清單 每部裝置的時間項目 (SuiteTimingWithContext),依硬體型號和 OS 版本分區。
records[].shardingContext 物件 硬體和 OS 維度,可界定一組時間測量結果。
records[].shardingContext.deviceModel string 記錄時間的裝置型號 ID (例如 Android 上的 shiba 或 iOS 上的 iphonese3)。
records[].shardingContext.osVersion string 裝置的 OS 或 SDK 版本 (例如 Android API 級別 '34' 或 iOS 版本 '18.4')。
records[].testCaseTimingRecords 物件清單 在這個情境中,個別通過測試案例的歷來執行時間長度。
records[].testCaseTimingRecords[].testCaseName string 採用 package.ClassName#methodName 格式的完整測試 ID (如果沒有方法中繼資料,則為 package.ClassName)。
records[].testCaseTimingRecords[].timingSamples 物件清單 測試案例的 30 天滾動式測量時間長度清單,會在執行通過後附加。
timingSamples[].duration 時間長度字串 以秒為單位的測量時間長度,可選擇小數精確度 (例如 10s 或 42.180s)。
timingSamples[].recordTime 時間戳記字串 RFC 3339 世界標準時間時間戳記,指出 Developer Device Platform 記錄樣本的時間 (例如 '2026-11-09T16:45:03Z')。
records[].conditionalOverheads 物件清單 在特定執行器模式下測得的選用執行負擔,範圍限於 shardingContext。如果沒有適用的條件式間接費用,則會省略。
records[].conditionalOverheads[].condition string 執行條件的 ID。支援的值:ANDROID_TEST_ORCHESTRATOR。
records[].conditionalOverheads[].timingSamples 物件清單 從符合資格的分區記錄的每轉換負擔樣本,滾動 30 天清單。

瞭解 ANDROID_TEST_ORCHESTRATOR 負擔時間

使用 --orchestrator-version 執行 Android 檢測設備測試時,智慧型資料分割 YAML 檔案會包含 conditionalOverheads 項目和 condition: ANDROID_TEST_ORCHESTRATOR。與 testCaseTimingRecords 不同,這些負載樣本不會附加至個別測試方法或編號 shard。

一個負載時間長度樣本代表的意義

啟用 Android Test Orchestrator 後,系統會在各自獨立的 Instrumentation 程序中執行每個測試方法。個別測試 startTime 和 endTime 時間戳記只會擷取「在」各測試方法中花費的時間,不包括測試之間的間隔時間,例如停止前一個應用程式程序、視需要清除套件資料 (clearPackageData),以及為下一個測試啟動新的 Instrumentation 程序。

為評估測試間轉換成本,Developer Device Platform 會檢查執行兩個以上測試案例的每個通過 shard (N > 1),並計算:

  1. 總 shard 執行時間:從 shard 中最早的測試 startTime 到 shard 中最晚的測試 endTime 經過的時間。
  2. 測試案例總時間長度:該資料分割中所有 N 測試案例的 (endTime - startTime) 總和。
  3. 每次轉換的平均負擔:由於 N 個依序測試在測試之間有 N - 1 個轉換,Developer Device Platform 會從 shard 跨度中減去測試時間總和,然後除以 N - 1:

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

工作中每個通過的多重測試 shard 都會為 ANDROID_TEST_ORCHESTRATOR 貢獻一個 TimingSample。舉例來說,如果工作階段在三個 shard 上執行,且每個 shard 至少通過兩個測試案例,則該工作階段會附加三個負載樣本,並附上工作階段的 recordTime。只執行單一測試案例 (N = 1) 的 shard 沒有測試間轉換,也不會發出負載樣本。

為什麼負擔未連結至測試案例或 shard

Developer Device Platform 會在 shardingContext (deviceModel 和 osVersion) 層級儲存 ANDROID_TEST_ORCHESTRATOR 樣本,而不是依測試或依 shard 儲存,原因有兩個:

  • 負擔取決於裝置和 OS,而非測試邏輯。無論接下來執行哪種 JUnit 方法,程序啟動、繫結器初始化和套件資料清除所需的時間大致相同,而每當測試時間或 shard 數量變更時,shard 分組就會動態變更。
  • 區隔負擔可保留乾淨的基準測試時間。將程序隔離負擔排除在 testCaseTimingRecords 之外,代表您可以在共用相同 YAML 記錄的執行作業中啟用或關閉 --orchestrator-version,而不會扭曲基礎的每次測試執行時間。

Developer Device Platform 如何在指派 shard 時使用額外資源

在新工作階段設定 --orchestrator-version 時,Developer Device Platform 會計算有效 ANDROID_TEST_ORCHESTRATOR 樣本 (avg_overhead) 的 30 天平均值,並將其加入「每個」測試案例的 30 天平均時間長度,然後計算 shard 數量或封裝 shard:

expected_test_duration = avg_test_duration + avg_overhead

如果未在工作階段設定 --orchestrator-version,avg_overhead 會是 0s,且系統會忽略 YAML 檔案中任何現有的 ANDROID_TEST_ORCHESTRATOR 項目。

在每個測試案例中加入 avg_overhead,會對資料分割造成三種影響:

  • 針對包含許多快速測試的套件,提供準確的 shard 數量。假設有一組 60 項單元式檢測設備測試,每項測試在 1s 執行,平均 Orchestrator 轉換負擔為 3s,目標 shard 時間長度為 2m (120s)。如果不計入額外負擔,預期總時間長度看起來像 60s,因此所有 60 項測試都會封裝到 1 個 shard 中,實際需要將近四分鐘才能完成 (60s 的測試執行時間加上 59 * 3s = 177s 的 Orchestrator 轉換時間)。將 3s 負擔加到每項測試 (每項測試預期時間長度為 4s,或總計 240s),Developer Device Platform 會分配 2 個 shard (ceil(240s / 120s)),讓每個 shard 都能在接近兩分鐘的目標時間內完成。
  • 測試數量不同時,平衡 shard 封裝。在最長處理時間優先的裝箱過程中,指派一個 40s UI 測試的 shard 會產生 43s 的預期費用 (40s + 3s),而指派 10 個 4s 測試的 shard 則會產生 70s 的預期費用 (10 * (4s + 3s))。納入每項測試的負擔,可避免含有許多短測試的 shard 默默累積未計入的程序重新啟動延遲時間。
  • 新加入測試的實際預估值。由於現有套件中未記錄的測試會沿用已知測試的平均預期時間長度 (已包含 avg_overhead),因此新測試在首次執行時會自動計入自動化調度管理工具負擔。

瞭解 30 天資料時間範圍和初始執行行為

智慧型資料分割不需要 30 天的歷來資料,即可開始最佳化測試執行。即使只記錄一個樣本,系統也會在下一個工作階段中,啟用以時間長度為依據的 shard 計算和分箱封裝。30 天是 Developer Device Platform 讀取及更新 YAML 時間記錄時,使用的滾動式保留和回溯期。

為什麼智慧型資料分割採用 30 天滾動週期

每當 Developer Device Platform 讀取或更新智慧型 sharding YAML 檔案時,都會篩除 recordTime 超過 30 天的 TimingSample。這個 30 天的時間範圍可平衡兩項工程目標:

  • 因應程式碼集變更並限制檔案大小。應用程式功能、UI 流程和測試實作會隨著時間演變。自動剔除超過 30 天的樣本,可避免過時的時間資料 (例如螢幕重新設計或網路層重構前的時間資料) 影響目前的分區指派。此外,系統也會移除過期的項目 (並捨棄不再有有效樣本的裝置情境),讓 YAML 檔案保持精簡,且遠低於 32 MB 的限制。
  • 在支援每週套件的同時,減少每次執行之間的差異。單次測試執行可能會受到垃圾收集、背景系統服務或模擬器排程的暫時性雜訊影響。在 30 天的時間範圍內平均取樣,可消除一次性高峰,同時保留足夠的歷來資料,讓夜間、每週或衝刺節奏的持續整合管道在執行之間保持暖機時間記錄。

第一週和第二週的預期情況

如果現在為現有測試套件啟用智慧型資料分割功能,執行時間會遵循快速暖機曲線,而不是等待數週才改善:

  1. 首次執行 (冷啟動)。由於 Cloud Storage 中尚無 YAML 檔案,Developer Device Platform 會為每個可執行的測試單元指派 30 秒的預設預估時間。這項功能會將資料分割數量計算為 ceil(num_tests * 30s / target_duration) (上限為資料分割數量上限和平台限制),並在各個資料分割中發布測試,類似於統一資料分割。首次執行時:
    • 如果測試平均時間遠低於 30 秒,執行作業 1 可能會分配過多 shard (最多 --smart-sharding-max-shard-count 個)。
    • 如果套件包含多個耗時數分鐘的 UI 測試,兩個緩慢的測試可能會偶然落在同一個資料分割中,導致該資料分割成為實際完成時間的瓶頸。
    • 執行作業 1 完成後,Developer Device Platform 會在 Cloud Storage 中建立 YAML 檔案,其中包含通過測試的測量時間長度。
  2. 第二次執行 (執行 1 完成後立即執行)。智慧型資料分割功能已啟用。Developer Device Platform 會讀取執行作業 1 記錄的時間長度,根據套件的實際執行時間重新計算 shard 數量,並先將最慢的測試隔離到個別 shard。通常從第 2 次執行開始,您就會看到實際工作階段持續時間和 shard 數量適當調整,即使在啟用智慧型 sharding 的當天也是如此。
  3. 第一週剩餘時間和第二週。在接下來的幾次執行中,shard 平衡會在以下三種特定情況下持續收緊:
    • 平滑單次執行變異。由於每次執行都會附加另一個 TimingSample,因此執行 1 的暫時波動會平均分配,減少在 --smart-sharding-target-duration 之後才完成的落後 shard。
    • 填入最初失敗執行的測試。為避免快速當機或測試逾時導致歷來平均值不準確,Developer Device Platform 只會記錄通過測試的時間 (在 Android 上,則只記錄整體套件狀態為 PASSED 的 shard)。如果測試在第 1 次執行時未記錄時間,則會在第 2 次執行時使用套件的平均時間長度,並在通過測試後切換至實際測得的時間。
    • 新增測試或裝置型號。在第一週和第二週提交的任何新測試案例,都會自動使用套件的平均預期時間長度,而不會還原為 30 秒的預設值。如果您使用相同的記錄名稱,在工作階段中新增第二個 --device 模型,則該模型首次執行時會使用現有裝置的時間做為初始備用,然後記錄專屬的 shardingContext 項目,供後續執行使用。

常見問題

以下問題涵蓋在 CI/CD 管道中執行智慧型 sharding 時的常見作業情境。

後續步驟