テストのシャーディング: 意味、Jest、Gradle、Bazel など
最終更新日
テストシャーディングは、1つのテストスイートを並列に実行できるスライスに分割し、それぞれを独自のランナーで実行します。テストスイートの実行に20分かかる場合、高速化の方法は2つあります。1つのジョブ内でテストを並列実行する方法と、複数のジョブに分割する方法(シャーディング)です。どちらも有効です。このガイドでは、それぞれをいつ使うべきか、一般的なフレームワーク向けにシャードのマトリックスをどう設定するか、そして不均衡なシャード、カバレッジの欠落、コストの増加といった落とし穴をどう避けるかを説明します。
ジョブ内での並列実行とジョブ間でのシャーディングの違い
ジョブ内の並列実行は、既存のコアを活用します。2 vCPUのランナーでは、ワーカープロセスは最大でも約2つしか起動できないため、より大きなランナーに切り替えない限り効果は小さくなります。
pytest -n auto # pytest-xdist, one worker per core
npx jest --maxWorkers=100%
go test ./... -p 4
シャーディングは、テストスイートをN個の別々のジョブとして実行し、それぞれが独自のランナーを持ちます。経過時間はセットアップ時間を除いておおむねNの分だけ短くなります。ただし、各シャードでチェックアウト、インストール、ビルドの費用がかかるため、課金対象の分数は増えます。
簡単な目安として、セットアップに1分、スイートに20分かかる場合、4シャードにすると経過時間は約6分、課金対象は21分ではなく24分になります。テストシャーディングプランナーを使えば、目標時間と予算に合うシャード数を計算できます。
シャードのマトリックス
GitHubのマトリックスジョブは、シャードごとに1つのジョブを生成できます。テストランナーにシャードのインデックスを渡します。
jobs:
test:
runs-on: ubuntu-latest
strategy:
fail-fast: false
matrix:
shard: [1, 2, 3, 4]
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: 22
cache: npm
- run: npm ci
- run: npx jest --shard=${{ matrix.shard }}/4
fail-fast: falseを指定すると、他のシャードの実行が完了するため、失敗を1つずつ修正するのではなく、1回の実行ですべての失敗を確認できます。なお、1つのワークフロー実行で作成できるジョブは最大256個です。シャーディングでこの上限に達することはまずありません。
他のフレームワークにも同様の考え方が適用できます。
npx playwright test --shard=2/4 # Playwright
npx vitest run --shard=2/4 # Vitest
pytest --splits 4 --group 2 # pytest-split
Goでは、パッケージリストで分割します。例えばgo list ./... | splitを使うか、シャードごとにパッケージリストを指定してgotestsumなどのツールを使います。CypressやRSpecには並列化ツール(Cypress Cloud、parallel_tests、knapsack)があり、過去の実行時間をもとに分散します。
シャードの数ではなく時間で均等に分ける
組み込みのシャーディングは、通常ファイル数やアルファベット順で分割します。1つのファイルに8分かかる場合、そのファイルを持つシャードが全体の時間を決めてしまいます。実行時間の記録を使うと、より均等に分割できます。
- タイミング出力(JUnit XMLやフレームワークのJSONレポーター)を有効にしてテストスイートを一度実行します。
- 実行時間をアーティファクトとして保存するか、タイミングファイルをコミットします。
- 貪欲法でファイルをシャードに割り当てます。実行時間の長い順に並べ、各ファイルを最も負荷の低いシャードに配置します。
pytest-splitは実行時間を.test_durationsに保存して利用します。Playwrightはテストファイル単位でシャーディングするため、大きなspecファイルを小さく分割することは、どのアルゴリズムよりも効果があります。目安として、最も遅いシャードが平均の10〜15%以内に収まるようにしてください。
レポートとカバレッジの統合
各シャードは部分的なレポートを生成します。一意の名前でアーティファクトとしてアップロードし、最後のジョブで統合します。
- uses: actions/upload-artifact@v4
if: ${{ !cancelled() }}
with:
name: junit-${{ matrix.shard }}
path: reports/
report:
needs: test
if: ${{ !cancelled() }}
runs-on: ubuntu-latest
steps:
- uses: actions/download-artifact@v4
with:
pattern: junit-*
merge-multiple: true
Playwrightには、blobレポーター用のmerge-reportsがあります。カバレッジについては、各シャードのlcovまたはカバレッジXMLをアップロードし、カバレッジサービスに送る前に統合してください。そうしないと、各シャードが自分の担当分だけを報告するため、数値が低く表示されてしまいます。
必須チェックはN個ではなく1つ
ブランチprotectionには、安定したチェック名が必要です。マトリックスはtest (1)、test (2)のような名前を生成し、シャード数を変えると名前も変わるため、必須チェックが壊れます。すべてのシャードに依存する最終ジョブを1つ追加し、そのジョブだけを必須にしてください。
tests-passed:
needs: test
if: ${{ always() }}
runs-on: ubuntu-latest
steps:
- run: |
if [ "${{ needs.test.result }}" != "success" ]; then exit 1; fi
always()が重要です。シャードが失敗した場合、依存するジョブはスキップされたと報告されますが、スキップされた必須チェックは成功として扱われることがあります。
セットアップを小さく保つ
シャーディングではセットアップのコストが掛け算で増えるため、削減が重要です。
- 依存関係をキャッシュします(ガイドを参照)。
- コンパイルに時間がかかる場合は、前のジョブで一度ビルドし、ビルド成果物をアーティファクトとして共有して、各シャードがそれをダウンロードするようにします。
- 使用しないブラウザはインストールしないでください。
npx playwright install --with-deps chromiumは、3種類すべてをインストールするよりも高速です。
コストに注意する
各シャードは、開始した分数に応じて課金され、ジョブごとに切り上げられます。小さなシャードを大量に作ると、切り上げとセットアップで無駄なコストが生じます。5分のシャードを4つ作ると、課金対象は20分となり、20分のジョブ1つと同じ費用ですが、開発者の待ち時間は4分の1になります。1分のシャードを20個作り、各シャードに1分のセットアップがかかる場合、課金対象は40分になります。予測ツールを使って、月単位の影響を試算してみてください。
テストシャーディングとは
テストシャーディング(テスト分割とも呼ばれます)とは、1つのテストスイートを重複のないN個のスライス(シャード)に分け、各スライスを独自のプロセスまたはCIジョブとして実行することを指します。すべてのテストは、全シャードを通じて正確に1回ずつ実行されます。目的は経過時間の短縮です。4つの等しい長さのシャードに分けると、スイートはおおよそ4分の1の時間で完了します。シャーディングは、1台のマシンを共有する1つのジョブ内の並列ワーカーとは異なります。シャードのマトリックスでは、各シャードが独自のランナーを持ちます。テストスイートが遅くなる理由の全体像については、CIが遅い場合のガイドとE2Eテストが遅い場合のガイドを参照してください。
フレームワーク別のテストシャーディング
ほとんどのフレームワークでは、インデックスと総数の指定が必要です。以下に、各フレームワーク向けのフラグまたは方法を示します。
Jest
Jest 28以降で組み込まれています。npx jest --shard=1/4のように指定します。テストファイル単位で分割するため、シャードの実行時間は均等になりません。詳細はJestが遅い場合を参照してください。
Playwright
組み込まれています。npx playwright test --shard=1/4のように指定します。結果を統合するには、blobレポーターとmerge-reportsを使用します。詳しくはPlaywrightテストが遅い場合を参照してください。
Vitest
組み込まれています。npx vitest run --shard=1/4のように指定します。統合可能なblobレポートを生成します。詳しくはVitestが遅い場合を参照してください。
CypressとpytestN
Cypressはテストの分散をCypress Cloudで行うか、プラグインでスペックを分割します。pytestではpytest-splitなどのプラグインを使用します。Cypressのテストが遅い場合とpytestの遅いテストを参照してください。
Gradle (JVM)
GradleではmaxParallelForksを使い、1つのビルド内でテストクラスを並列実行できますが、それ自体ではスイートをCIジョブ間で分割することはできません。ジョブ間でシャーディングするには、テストクラスの一覧を用意し、各ジョブに--testsで分担分を指定するか、実行時間に基づいて分散するプラグインを使用します。クラス名をソートして、N個ごとに取り出すなど、分割結果が毎回同じになるようにしてください。
# job INDEX of TOTAL: select every TOTAL-th class
./gradlew test $(./list-test-classes.sh | awk -v i=$INDEX -v n=$TOTAL 'NR % n == i {print "--tests " $1}')
Bazel
Bazelにはシャーディング機能が標準で備わっています。テストターゲットにshard_countを設定すると、その数のシャードが並列実行され、テストにはTEST_TOTAL_SHARDSとTEST_SHARD_INDEXが渡されます。これらの変数を読み取るテストフレームワーク(GoogleTestやJUnitランナーを含む多くのもの)は、自身で分割を行います。
java_test(
name = "integration_tests",
srcs = glob(["*.java"]),
shard_count = 4,
)
Bazelでは--test_sharding_strategyを使ってシャード数を自動で決めることもできます。お使いのバージョンで正確なフラグを確認するには、Bazelのドキュメントを参照してください。
Flutter
flutter testは--total-shardsと--shard-indexを受け付けます。
flutter test --total-shards 4 --shard-index 0
マトリックスのジョブごとに、インデックスを1つずつ(0から3)指定して実行してください。
.NET (dotnet test)
dotnet testには汎用的なシャードインデックスのフラグがありません。一般的な方法は、テストプロジェクト単位で分割する、--filterの式(名前空間や特性など)で分割する、または実行時間に基づいて分割に対応したランナーやツールを使うことです。フィルターを組み合わせてすべてのテストを確実にカバーし、どのフィルターにも該当しない新しいテストが追加された場合はビルドを失敗させるようにしてください。
dotnet test --filter "FullyQualifiedName~MyApp.Orders"
Android
計装テストは、AndroidXテストランナーの引数numShardsとshardIndexでシャーディングに対応しており、Gradleからも利用できます。
./gradlew connectedCheck \
-Pandroid.testInstrumentationRunnerArguments.numShards=4 \
-Pandroid.testInstrumentationRunnerArguments.shardIndex=0
デバイスファームも独自のシャーディングオプションを提供しているため、あわせてドキュメントを確認してください。エミュレーターの起動はシャードごとに大きな固定コストがかかるため、単体テストの場合よりも少なく、大きめのシャードを使うことをおすすめします。
よくある質問
シャードの数はいくつにすればよいですか?
プランナーを使い、スイートの実行時間を目標時間で割った値に、セットアップ用の余裕を加えた数から始めてください。その後、最も遅いシャードを確認し、負荷を再配分します。
シャーディングによって不安定なテストが増えて見つかることはありますか?
テストが1つのプロセスで実行されなくなるため、実行順序への依存が表面化することがあります。それを修正することには意味があります。不安定なテストへの対処を参照してください。
シャードを増やすより大きなランナーを使う方が良いですか?
フレームワークがコアをまたいでスケールする場合、より大きなランナーを使うことで、セットアップの繰り返しを避けられます。テストがI/O-boundであるか、単一プロセスの場合は、シャーディングのほうがよりよくスケールします。同じワークフローで両方を試してみてください。
テストシャーディングとは何ですか?
テストスイートをN個のスライス(シャード)に分割し、それぞれを個別に、通常は並列のCIジョブとして実行する手法です。各テストは1回だけ実行され、全体の実行時間が短縮されます。
テストシャーディングは並列テストと同じですか?
並列テストは1台のマシン上でテストを同時に実行するものです。シャーディングは複数のマシンやジョブにテストを分散させます。大規模なスイートの多くは両方を併用しています。
すべてのプルリクエストで同じテストを実行するにはどうすればよいですか?
上記のように、マトリックスでシャード数を固定し、必須の単一の集計ジョブを用意してください。
お使いのジョブで試す
シャーディング方式を、より高速な単一マシンと比較してみてください。compiler.devの比較モードでは、同じワークフローをより大きなランナーで実行できるため、テストを再構成する前に、実行時間とコストを並べて確認できます。
関連記事
- 不安定なテストとは何か:定義と原因不安定なテストとは、コードに変更がないにもかかわらず、成功したり失敗したりするテストのことです。一般的な原因、CIでの検出方法、修正または隔離(クォランティン)の方法を解説します。
- CIにおけるテストシャーディングとはテストシャーディングは、1つのテストスイートを複数のスライスに分割し、別々のCIマシンで並列実行することで、経過時間を短縮する手法です。仕組みと、よくある間違いを解説します。
- GitHub ActionsでTypeScriptモノレポを高速化するGitHub Actionsで TypeScriptモノレポの型チェックとリンターを高速化する: インクリメンタルtsc、プロジェクト参照、Lintキャッシュ、並列ジョブ
- GitHub ActionsでモノレポのPlaywrightを高速化するGitHub Actions で Node モノレポの Playwright E2E テストを高速化: アプリを一度だけビルドし、Web アプリに変更がないときは E2E をスキップし、シャーディングとレポートのマージを行います。