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 會執行六個階段的工作流程,包括建立工作階段、執行測試和完成測試:
- 讀取歷來時間資料,並比對裝置情境。在排定 shard 前,Device Run 服務代理會從 Cloud Storage 讀取智慧型 sharding YAML 檔案。它會在
records清單中搜尋與目標工作的deviceModel和osVersion(不區分大小寫) 相符的shardingContext。如果沒有完全比對該裝置和 OS 組合的項目,Developer Device Platform 會改用檔案中第一個可用的records項目。如果 YAML 檔案尚不存在,工作階段會以冷啟動方式進行,且沒有時間記錄。 - 將樣本篩選為 30 天滾動週期,並計算預期持續時間。對於所選情境記錄,Developer Device Platform 只會保留
recordTime落在過去 30 天內的計時樣本,並計算每個測試案例的算術平均時間長度。如果透過--orchestrator-version啟用 Android Test Orchestrator,Developer Device Platform 也會計算ANDROID_TEST_ORCHESTRATOR負載樣本的 30 天平均值,並將該平均負載加入每個測試案例的預期時間長度。 - 找出可執行的測試,並指派備用預估值。在 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 秒。
- 記錄的測試案例:使用 30 天歷來平均時間長度 (加上啟用 Android Test Orchestrator 時的平均 Orchestrator 負擔)。在 Android 上,參數化 JUnit 類別 (例如使用
計算資料分割數量。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)。
使用最長處理時間優先裝箱法指派測試。Developer Device Platform 會按照預期時間長度,由慢到快排序所有可執行的測試單元,並依累積時間長度,初始化空 shard 的 min-heap。這項功能會逐一處理測試單元,將剩餘測試中最慢的測試指派給累積時間最短的資料分割,並更新該資料分割的總時間。先排定緩慢的「長桿」測試,將其隔離到不同的資料分割,再以較短的測試填補剩餘的空隙,保持總資料分割時間長度平衡。
記錄通過時間並更新 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),並計算:
- 總 shard 執行時間:從 shard 中最早的測試
startTime到 shard 中最晚的測試endTime經過的時間。 - 測試案例總時間長度:該資料分割中所有
N測試案例的(endTime - startTime)總和。 每次轉換的平均負擔:由於
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 封裝。在最長處理時間優先的裝箱過程中,指派一個
40sUI 測試的 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 天的時間範圍內平均取樣,可消除一次性高峰,同時保留足夠的歷來資料,讓夜間、每週或衝刺節奏的持續整合管道在執行之間保持暖機時間記錄。
第一週和第二週的預期情況
如果現在為現有測試套件啟用智慧型資料分割功能,執行時間會遵循快速暖機曲線,而不是等待數週才改善:
- 首次執行 (冷啟動)。由於 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 檔案,其中包含通過測試的測量時間長度。
- 如果測試平均時間遠低於 30 秒,執行作業 1 可能會分配過多 shard (最多
- 第二次執行 (執行 1 完成後立即執行)。智慧型資料分割功能已啟用。Developer Device Platform 會讀取執行作業 1 記錄的時間長度,根據套件的實際執行時間重新計算 shard 數量,並先將最慢的測試隔離到個別 shard。通常從第 2 次執行開始,您就會看到實際工作階段持續時間和 shard 數量適當調整,即使在啟用智慧型 sharding 的當天也是如此。
- 第一週剩餘時間和第二週。在接下來的幾次執行中,shard 平衡會在以下三種特定情況下持續收緊:
- 平滑單次執行變異。由於每次執行都會附加另一個
TimingSample,因此執行 1 的暫時波動會平均分配,減少在--smart-sharding-target-duration之後才完成的落後 shard。 - 填入最初失敗執行的測試。為避免快速當機或測試逾時導致歷來平均值不準確,Developer Device Platform 只會記錄通過測試的時間 (在 Android 上,則只記錄整體套件狀態為
PASSED的 shard)。如果測試在第 1 次執行時未記錄時間,則會在第 2 次執行時使用套件的平均時間長度,並在通過測試後切換至實際測得的時間。 - 新增測試或裝置型號。在第一週和第二週提交的任何新測試案例,都會自動使用套件的平均預期時間長度,而不會還原為 30 秒的預設值。如果您使用相同的記錄名稱,在工作階段中新增第二個
--device模型,則該模型首次執行時會使用現有裝置的時間做為初始備用,然後記錄專屬的shardingContext項目,供後續執行使用。
- 平滑單次執行變異。由於每次執行都會附加另一個
常見問題
以下問題涵蓋在 CI/CD 管道中執行智慧型 sharding 時的常見作業情境。
後續步驟
- 瞭解 TestParameterInjector 測試執行器。
- 在「執行 Android 檢測設備測試」中設定智慧型資料分割旗標。
- 如要設定 iOS 測試執行作業,請參閱「執行 iOS XCTest」。
- 請參閱「與 Developer Device Platform 共用 Cloud Storage bucket」,確認服務代理的跨專案 bucket 權限。
- 在「尋找 Developer Device Platform 測試結果」中,檢查每個 shard 的
junit.xml和記錄構件。