Developer Device Platform のデバイスランでのスマート シャーディング

Developer Device Platform のデバイスランのスマート シャーディングは、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 は、セッションの作成、テストの実行、完了にわたる 6 段階のワークフローを実行します。

  1. 過去のタイミング データを読み取り、デバイスのコンテキストを一致させます。シャードをスケジュールする前に、デバイスラン サービス エージェントは Cloud Storage からスマート シャーディング YAML ファイルを読み取ります。records リストで、ターゲット ジョブの deviceModel と osVersion(大文字と小文字を区別しない)に一致する shardingContext を検索します。そのデバイスと OS の組み合わせに完全一致するものがない場合、Developer Device Platform はファイル内の最初に使用可能な records エントリにフォールバックします。YAML ファイルがまだ存在しない場合、セッションは空のタイミング履歴でコールド スタートとして続行されます。
  2. サンプルを 30 日間のローリング ウィンドウにフィルタし、予想される期間を計算します。選択したコンテキスト レコードについて、Developer Device Platform は recordTime が過去 30 日以内にあるタイミング サンプルのみを保持し、各テストケースの算術平均時間を計算します。Android Test Orchestrator が --orchestrator-version で有効になっている場合、Developer Device Platform は ANDROID_TEST_ORCHESTRATOR オーバーヘッド サンプルの 30 日間の平均も計算し、その平均オーバーヘッドをすべてのテストケースの想定所要時間に追加します。
  3. 実行可能なテストを検出し、フォールバックの見積もりを割り当てます。ワーカーホストでは、Developer Device Platform がテスト パッケージを静的に検査します。Android ではテスト APK の DEX ファイルを読み取り、iOS ではコンパイル済みの .xctest シンボルと .xctestrun フィルタを読み取ります。--test-targets フィルタを適用し、無視または抑制されたテスト(@Ignore や @Suppress など)を除外します。実行可能な各テストユニットは、次の 3 つの階層に基づいて想定される実行時間を受け取ります。
    • 記録されたテストケース: 30 日間の平均所要時間(Android Test 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 は、実行可能なすべてのテスト単位を予想される実行時間の降順(遅い順)に並べ替え、累積実行時間で並べ替えられた空のシャードの最小ヒープを初期化します。一度に 1 つのテスト単位を取得し、最も遅い残りのテストを、累積時間が最も短いシャードに割り当て、そのシャードの合計を更新します。遅い「ロングポール」テストを最初にスケジュールすると、それらのテストが個別のシャードに分離されます。一方、短いテストは残りのギャップを埋めるため、シャードの合計時間がバランスよく保たれます。

  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: YAML ファイル拡張子なしで --smart-sharding-record-name に渡されるレコード ID(例: checkout-suite は automation/smart-sharding/checkout-suite.yaml にマッピングされます)。

YAML タイミング レコードの例

次の例は、2 つのデバイス コンテキスト(Android Test Orchestrator で実行されている Android デバイスと iOS デバイス)のタイミング レコードを含むスマート シャーディング YAML ファイル(checkout-suite.yaml)を示しています。

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) 集計の更新全体で保持される、オプションのスイートレベルの Key-Value メタデータ。
records オブジェクトのリスト デバイスごとのタイミング エントリ(SuiteTimingWithContext)。ハードウェア モデルと OS バージョンでパーティション分割されます。
records[].shardingContext オブジェクト 一連のタイミング測定のスコープとなるハードウェアと OS のディメンション。
records[].shardingContext.deviceModel string タイミングが記録されたデバイスのモデル識別子(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 タイムスタンプ文字列 Developer Device Platform がサンプルを記録した日時を示す RFC 3339 UTC タイムスタンプ(例: '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 とは異なり、これらのオーバーヘッド サンプルは個々のテストメソッドや番号付きシャードにアタッチされません。

1 つのオーバーヘッド期間サンプルが表すもの

Android Test Orchestrator が有効になっている場合、各テストメソッドは個別の Instrumentation プロセスで実行されます。個々のテストの startTime タイムスタンプと endTime タイムスタンプは、各テストメソッドの内部で費やされた時間のみをキャプチャします。前のアプリプロセスの停止、パッケージ データの消去(clearPackageData)(オプション)、次のテストのための新しい Instrumentation プロセスの開始に費やされたテスト間のギャップは含まれません。

このテスト間の移行コストを測定するために、Developer Device Platform は、2 つ以上のテストケースを実行する合格シャード(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 に 1 つの TimingSample が追加されます。たとえば、セッションが 3 つのシャードで実行され、各シャードが少なくとも 2 つのテストケースに合格した場合、そのセッションはセッションの recordTime を含む 3 つのオーバーヘッド サンプルを追加します。1 つのテストケース(N = 1)のみを実行するシャードでは、テスト間の遷移がゼロになり、オーバーヘッド サンプルは出力されません。

オーバーヘッドがテストケースまたはシャードにリンクされていない理由

Developer Device Platform が ANDROID_TEST_ORCHESTRATOR サンプルをテストごとやシャードごとではなく、shardingContext(deviceModel と osVersion)レベルで保存する理由は 2 つあります。

  • オーバーヘッドは、テストロジックではなく、デバイスと OS に依存します。プロセスの起動、バインダの初期化、パッケージ データの消去は、次に実行される JUnit メソッドに関係なく、ほぼ同じ時間がかかります。一方、シャードのグループ化は、テストのタイミングやシャード数が変わるたびに動的に変化します。
  • オーバーヘッドを分離することで、ベースライン テストのタイミングをクリーンに保つことができます。プロセス分離のオーバーヘッドを 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 を追加すると、次の 3 つの方法でシャーディングに影響します。

  • 高速テストが多数あるスイートの正確なシャード数。それぞれ 1s で実行される 60 個のユニットスタイルのインストルメンテーション テストのスイートを考えてみましょう。オーケストレーターの移行オーバーヘッドの平均は 3s、ターゲット シャードの持続時間は 2m(120s)です。オーバーヘッドがない場合、予想される合計時間は 60s のようになります。そのため、60 個のテストすべてが 1 シャードにパックされ、実際には完了までに 4 分近くかかります(テスト実行の 60s とオーケストレーターの移行の 59 * 3s = 177s)。各テストに 3s のオーバーヘッドを追加すると(テストあたりの予想時間は 4s、合計は 240s)、Developer Device Platform は 2 個のシャード(ceil(240s / 120s))を割り当て、各シャードが 2 分の目標時間近くで完了するようにします。
  • テスト数が異なる場合のバランスの取れたシャード パッキング。最長処理時間優先のビンパッキングでは、1 つの 40s UI テストが割り当てられたシャードの予想コストは 43s(40s + 3s)ですが、10 個の 4s テストが割り当てられたシャードの予想コストは 70s(10 * (4s + 3s))です。テストごとのオーバーヘッドを含めることで、短いテストが多数あるシャードで、カウントされないプロセス再起動のレイテンシが数分間も蓄積されるのを防ぐことができます。
  • 新しく追加されたテストの現実的な見積もり。既存のスイート内の未記録のテストは、既知のテストの平均予想時間を継承します。この時間にはすでに avg_overhead が含まれているため、新しいテストは最初の実行時にオーケストレーターのオーバーヘッドを自動的に考慮します。

30 日間のデータ ウィンドウと初回実行の動作について

スマート シャーディングでは、テスト実行の最適化を開始する前に 30 日間の過去のデータは必要ありません。1 つのサンプルが記録されただけでも、次のセッションで期間ベースのシャード計算とビンパッキングが有効になります。代わりに、30 日は、Developer Device Platform が YAML タイミング レコードの読み取りと更新を行う際に使用するローリング保持期間とルックバック ウィンドウです。

スマート シャーディングで 30 日間のローリング ウィンドウが使用される理由

Developer Device Platform は、スマート シャーディング YAML ファイルを読み取りまたは更新するたびに、recordTime が 30 日以上経過している TimingSample を除外します。この 30 日間の期間は、次の 2 つのエンジニアリング目標のバランスを取ります。

  • コードベースの変更に適応し、ファイルサイズを制限する。アプリの機能、UI フロー、テストの実装は、時間の経過とともに進化します。30 日以上経過したサンプルを自動的に削除することで、古いタイミング(画面の再設計やネットワーク レイヤのリファクタリング前のタイミングなど)が現在のシャード割り当てに影響を与えないようにします。期限切れのエントリを削除する(有効なサンプルがなくなったデバイス コンテキストを削除する)ことで、YAML ファイルをコンパクトに保ち、32 MB の上限を大幅に下回るようにします。
  • 週単位のスイートをサポートしながら、実行間の差異を平滑化する。1 回のテスト実行で、ガベージ コレクション、バックグラウンド システム サービス、エミュレータのスケジューリングによる一時的なノイズが発生することがあります。30 日間のウィンドウでサンプルを平均化すると、1 回限りのスパイクが平滑化されます。また、夜間、毎週、またはスプリントの継続的インテグレーション パイプラインが実行間でウォーム タイミング レコードを保持するのに十分な履歴が保持されます。

1 ~ 2 週目の予定

既存のテストスイートでスマート シャーディングを有効にすると、実行時間は数週間待つことなく、急速なウォームアップ曲線に沿って改善されます。

  1. 初回実行(コールド スタート)。YAML ファイルがまだ Cloud Storage に存在しないため、Developer Device Platform は、実行可能なすべてのテスト単位に 30 秒のデフォルトの見積もりを割り当てます。シャード数を ceil(num_tests * 30s / target_duration) として計算し(最大シャード数とプラットフォームの上限によって制限されます)、均一シャーディングと同様にテストをシャードに分散します。この最初の実行では、次のようになります。
    • テストの平均時間が 30 秒を大幅に下回る場合、実行 1 では必要以上のシャード(最大 --smart-sharding-max-shard-count)が割り当てられる可能性があります。
    • スイートに数分かかる UI テストが複数含まれている場合、2 つの遅いテストが偶然同じシャードに割り当てられ、そのシャードが実時間の完了時間のボトルネックになる可能性があります。
    • 実行 1 が完了すると、Developer Device Platform は、合格したテストの測定された所要時間を含む YAML ファイルを Cloud Storage に作成します。
  2. 2 回目の実行(1 回目の実行が完了した直後)。スマート シャーディングはすでに有効になっています。Developer Device Platform は、実行 1 で記録された時間を読み取り、スイートの実際の実行時間からシャード数を再計算し、最も遅いテストを最初に別のシャードに分離します。通常、スマート シャーディングを有効にした同日であっても、実行 2 から、実時間のセッション継続時間とシャード数の適正化が主に減少します。
  3. 第 1 週の残りと第 2 週。次の数回の実行で、次の 3 つの特定のケースでシャード バランスが引き続き強化されます。
    • 1 回の実行の分散を平滑化する。実行が成功するたびに別の TimingSample が追加されるため、実行 1 の一時的な変動が平均化され、--smart-sharding-target-duration をわずかに超えて終了するストラグラー シャードが減少します。
    • 最初に失敗した実行のテストを補完する。Developer Device Platform では、高速クラッシュやテスト タイムアウトによって過去の平均値が破損しないように、合格したテストのタイミングのみを記録します(Android では、スイート全体のステータスが PASSED であるシャードのみ)。実行 1 でタイミングが記録されなかったテストは、実行 2 でスイートの平均時間を使用し、合格すると独自の測定タイミングに切り替えます。
    • 新しいテストまたはデバイスモデルを追加する。1 週目と 2 週目に commit された新しいテストケースは、30 秒のデフォルトに戻るのではなく、スイートの平均予想期間を自動的に使用します。同じレコード名を使用して 2 つ目の --device モデルをセッションに追加すると、最初の実行では既存のデバイスのタイミングが初期フォールバックとして使用され、その後の実行では専用の shardingContext エントリが記録されます。

よくある質問

次の質問では、CI / CD パイプラインでスマート シャーディングを実行する際の一般的な運用シナリオについて説明します。

次のステップ