Zum Inhalt springen

Test-Sharding: Bedeutung, Jest, Gradle, Bazel und mehr

Zuletzt aktualisiert am

Test-Sharding teilt eine Test-Suite in Abschnitte auf, die parallel laufen, jeweils auf einem eigenen Runner. Wenn eine Test-Suite 20 Minuten dauert, gibt es zwei Wege, sie zu beschleunigen: Tests innerhalb eines Jobs parallel ausführen oder auf mehrere Jobs verteilen (Sharding). Beide funktionieren. Dieser Leitfaden zeigt, wann welcher Weg sinnvoll ist, wie Sie eine Shard-Matrix für gängige Frameworks einrichten und wie Sie typische Fallstricke vermeiden: unausgewogene Shards, verlorene Testabdeckung und höhere Kosten.

Parallel innerhalb eines Jobs versus Sharding über Jobs

Parallelisierung innerhalb eines Jobs nutzt die Kerne, die Sie bereits haben. Ein Runner mit 2 vCPUs bringt höchstens etwa zwei Worker-Prozesse, der Gewinn ist also gering, sofern Sie nicht auf einen größeren Runner wechseln:

pytest -n auto            # pytest-xdist, one worker per core
npx jest --maxWorkers=100%
go test ./... -p 4

Sharding führt die Suite als N getrennte Jobs aus, jeder mit eigenem Runner. Die reale Laufzeit sinkt grob um den Faktor N, abzüglich der Einrichtungszeit. Die abgerechneten Minuten steigen, weil jeder Shard Checkout, Installation und eventuelle Builds bezahlt.

Eine einfache Faustregel: Dauert die Einrichtung 1 Minute und die Suite 20 Minuten, ergeben 4 Shards etwa 6 Minuten Laufzeit und 24 abgerechnete Minuten statt 21. Mit dem Test-Sharding-Planer berechnen Sie die Shard-Anzahl, die zu Ihrer Zielzeit und Ihrem Budget passt.

Eine Shard-Matrix

Matrix-Jobs in GitHub können für jeden Shard einen eigenen Job erzeugen. Übergeben Sie den Shard-Index an den Test-Runner:

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 lässt die übrigen Shards zu Ende laufen, sodass Sie in einem Lauf alle Fehler sehen, statt sie nacheinander zu beheben. Beachten Sie die Grenze: Eine Matrix kann pro Workflow-Lauf höchstens 256 Jobs erzeugen, für Sharding ist das aber unproblematisch.

Andere Frameworks folgen derselben Idee:

npx playwright test --shard=2/4          # Playwright
npx vitest run --shard=2/4               # Vitest
pytest --splits 4 --group 2              # pytest-split

Bei Go teilen Sie nach Paketliste auf, zum Beispiel mit go list ./... | split oder einem Tool wie gotestsum mit einer Paketliste pro Shard. Cypress und RSpec bieten Werkzeuge zur Parallelisierung (Cypress Cloud, parallel_tests, knapsack), die anhand früherer Laufzeiten ausbalancieren.

Shards nach Zeit, nicht nach Anzahl ausbalancieren

Integriertes Sharding teilt meist nach Dateianzahl oder alphabetischer Reihenfolge auf. Dauert eine Datei 8 Minuten, bestimmt der Shard, der sie enthält, Ihre Gesamtzeit. Besser ist eine Verteilung auf Basis gemessener Laufzeiten:

  1. Führen Sie die Suite einmal mit Zeitausgabe aus (JUnit XML oder der JSON-Reporter des Frameworks).
  2. Speichern Sie die Laufzeiten als Artefakt oder committen Sie eine Timings-Datei.
  3. Weisen Sie Dateien mit einem Greedy-Algorithmus den Shards zu: nach Dauer sortieren und jede Datei dem am wenigsten belasteten Shard geben.

pytest-split speichert Laufzeiten in .test_durations und nutzt sie. Playwright teilt nach Testdatei auf, daher hilft das Aufteilen großer Spec-Dateien in kleinere mehr als jeder Algorithmus. Ein gutes Ziel ist, dass der langsamste Shard höchstens 10 bis 15 Prozent über dem Durchschnitt liegt.

Berichte und Coverage zusammenführen

Jeder Shard erzeugt einen Teilbericht. Laden Sie diese als Artefakte mit eindeutigen Namen hoch und führen Sie sie in einem abschließenden Job zusammen:

      - 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 bietet merge-reports für seinen Blob-Reporter. Bei der Coverage laden Sie für jeden Shard die lcov- oder Coverage-XML-Datei hoch und führen sie vor dem Senden an Ihren Coverage-Dienst zusammen. Andernfalls meldet jeder Shard nur seinen Ausschnitt, und die Zahl wirkt zu niedrig.

Ein Pflicht-Check statt N

Branch-Protection benötigt stabile Check-Namen. Eine Matrix erzeugt Namen wie test (1), test (2), und eine Änderung der Shard-Anzahl ändert diese Namen, wodurch Pflicht-Checks brechen. Fügen Sie einen abschließenden Job hinzu, der von allen Shards abhängt, und verlangen Sie nur diesen einen Check:

  tests-passed:
    needs: test
    if: ${{ always() }}
    runs-on: ubuntu-latest
    steps:
      - run: |
          if [ "${{ needs.test.result }}" != "success" ]; then exit 1; fi

Das always() ist wichtig: Schlägt ein Shard fehl, meldet ein übersprungener abhängiger Job den Status „übersprungen“, und ein übersprungener Pflicht-Check kann als bestanden gelten.

Die Einrichtung schlank halten

Sharding vervielfacht die Einrichtungskosten, also kürzen Sie sie:

  • Cachen Sie Abhängigkeiten (Leitfaden).
  • Wenn das Kompilieren langsam ist, bauen Sie einmal in einem vorgelagerten Job und teilen das Build-Ergebnis als Artefakt, das die Shards dann herunterladen.
  • Überspringen Sie Browser, die Sie nicht nutzen. npx playwright install --with-deps chromium ist schneller, als alle drei zu installieren.

Die Kosten im Blick behalten

Jeder Shard wird pro begonnene Minute abgerechnet, pro Job aufgerundet. Viele winzige Shards verschwenden Geld durch Rundung und Einrichtung. Bei 4 Shards zu je 5 Minuten zahlen Sie 20 Minuten, genau wie für einen 20-Minuten-Job, und Entwickler warten nur ein Viertel so lange. Bei 20 Shards zu je 1 Minute plus 1 Minute Einrichtung zahlen Sie 40 Minuten. Testen Sie den Forecaster, um den monatlichen Effekt zu modellieren.

Was Test-Sharding bedeutet

Test-Sharding (auch Test-Splitting) bedeutet, eine Test-Suite in N disjunkte Abschnitte, sogenannte Shards, zu teilen und jeden Abschnitt als eigenen Prozess oder CI-Job auszuführen. Jeder Test läuft über alle Shards hinweg genau einmal. Das Ziel ist die reale Laufzeit: Bei vier gleich langen Shards ist die Suite in etwa einem Viertel der Zeit fertig. Sharding unterscheidet sich von parallelen Workern innerhalb eines Jobs, die sich eine Maschine teilen. In einer Shard-Matrix hat jeder Shard seinen eigenen Runner. Einen Überblick, warum Suites langsam werden, finden Sie im Leitfaden zu langsamer CI und im Leitfaden zu langsamen E2E-Tests.

Test-Sharding nach Framework

Die meisten Frameworks benötigen einen Index und eine Anzahl. Hier sind Flag oder Vorgehen für jedes.

Jest

Seit Jest 28 integriert: npx jest --shard=1/4. Es teilt nach Testdatei auf, die Shards sind also nicht zeitlich ausbalanciert. Details unter Jest langsam.

Playwright

Integriert: npx playwright test --shard=1/4. Nutzen Sie den Blob-Reporter und merge-reports, um Ergebnisse zusammenzuführen. Siehe Playwright-Tests langsam.

Vitest

Integriert: npx vitest run --shard=1/4, mit Blob-Berichten, die sich zusammenführen lassen. Siehe Vitest langsam.

Cypress und pytest

Cypress verteilt Specs über Cypress Cloud oder teilt sie mit einem Plugin auf; pytest nutzt Plugins wie pytest-split. Siehe Cypress-Tests langsam und langsame pytest-Tests.

Gradle (JVM)

Gradle führt Testklassen innerhalb eines Builds parallel aus, und zwar mit maxParallelForks. Eine Suite über mehrere CI-Jobs zu verteilen, übernimmt Gradle aber nicht von selbst. Um über Jobs zu sharden, listen Sie Ihre Testklassen auf und geben jedem Job einen Ausschnitt mit --tests vor, oder Sie verwenden ein Plugin, das anhand von Laufzeiten verteilt. Halten Sie die Aufteilung deterministisch, etwa indem Sie die Klassennamen sortieren und jede n-te Klasse nehmen.

# 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 unterstützt Sharding nativ. Setzen Sie shard_count an einem Test-Target, dann führt Bazel so viele Shards parallel aus und übergibt TEST_TOTAL_SHARDS und TEST_SHARD_INDEX an den Test. Testframeworks, die diese Variablen auswerten (viele tun das, darunter GoogleTest und JUnit-Runner), teilen sich selbst auf.

java_test(
    name = "integration_tests",
    srcs = glob(["*.java"]),
    shard_count = 4,
)

Bazel kann die Shard-Anzahl auch automatisch mit --test_sharding_strategy bestimmen. Die genauen Flags für Ihre Version finden Sie in der Bazel-Dokumentation.

Flutter

flutter test akzeptiert --total-shards und --shard-index:

flutter test --total-shards 4 --shard-index 0

Führen Sie pro Matrix-Job einen Index aus (0 bis 3).

.NET (dotnet test)

dotnet test hat kein allgemeines Shard-Index-Flag. Übliche Ansätze sind das Aufteilen nach Testprojekt, das Aufteilen mit --filter-Ausdrücken (etwa nach Namespace oder Trait) oder ein Runner bzw. Tool, das eine Aufteilung nach Laufzeit unterstützt. Achten Sie darauf, dass die Filter zusammen jeden Test abdecken, und lassen Sie den Build fehlschlagen, wenn ein neuer Test außerhalb aller Filter liegt.

dotnet test --filter "FullyQualifiedName~MyApp.Orders"

Android

Instrumentierte Tests unterstützen Sharding über die Argumente des AndroidX-Test-Runners numShards und shardIndex, was auch über Gradle funktioniert:

./gradlew connectedCheck \
  -Pandroid.testInstrumentationRunnerArguments.numShards=4 \
  -Pandroid.testInstrumentationRunnerArguments.shardIndex=0

Device-Farmen bieten eigene Sharding-Optionen, schauen Sie also auch in deren Dokumentation. Der Start eines Emulators verursacht pro Shard erhebliche feste Kosten, verwenden Sie daher weniger, dafür größere Shards als bei Unit-Tests.

FAQ

Wie viele Shards sollte ich verwenden?

Beginnen Sie mit der Anzahl, die Ihr Zeitziel mit dem Planer erreicht: Suite-Laufzeit geteilt durch das Ziel, plus einen Puffer für das Setup. Prüfen Sie dann den langsamsten Shard und verteilen Sie neu.

Findet Sharding mehr flaky Tests?

Das kann es, denn Abhängigkeiten von der Reihenfolge fallen auf, weil die Tests nicht mehr in einem Prozess laufen. Diese zu beheben lohnt sich. Siehe Umgang mit flaky Tests.

Ist ein größerer Runner besser als mehr Shards?

Wenn das Framework über mehrere Kerne skaliert, vermeidet ein größerer Runner wiederholte Einrichtungsschritte. Sind die Tests I/O-bound oder laufen sie in einem einzigen Prozess, skalieren Shards besser. Probieren Sie beides in einem Workflow aus.

Was bedeutet Test-Sharding?

Eine Testsuite wird in N Abschnitte (Shards) aufgeteilt, die jeweils separat laufen, meist als parallele CI-Jobs. So läuft jeder Test genau einmal und die Gesamtzeit sinkt.

Ist Test-Sharding dasselbe wie paralleles Testen?

Paralleles Testen führt Tests gleichzeitig auf einer Maschine aus. Sharding verteilt sie auf mehrere Maschinen oder Jobs. Die meisten großen Suiten nutzen beides.

Wie stelle ich sicher, dass auf jedem PR dieselben Tests laufen?

Fixieren Sie die Shard-Anzahl in der Matrix und behalten Sie einen einzigen, erforderlichen Zusammenfassungs-Job bei, wie oben gezeigt.

Testen Sie es mit Ihren Jobs

Vergleichen Sie den Shard-Ansatz mit einer schnelleren Einzelmaschine: Der Vergleichsmodus von compiler.dev führt denselben Workflow auf größeren Runnern aus, sodass Sie Zeit und Kosten nebeneinander sehen, bevor Sie Ihre Tests umstrukturieren.

Diesen Workflow auf compiler.dev ausführen Keine Karte nötig · 200 kostenlose Minuten

Kostenlos testen