---
title: "Shard tests in GitHub Actions to parallelize a long suite"
description: "Split a long test job into parallel shards with a matrix. How to shard Playwright, Jest, Vitest, and pytest in GitHub Actions, with copyable YAML."
url: https://starsling.dev/best-practices/github-actions/shard-tests
canonicalUrl: https://starsling.dev/best-practices/github-actions/shard-tests
---

# Shard tests across parallel jobs in GitHub Actions

Best practice: Parallelization. Last updated: 2026-07-06

Split one long test job into parallel shards with a matrix so the suite finishes in a fraction of the wall-clock time.

## Do this

A test job that would run for many minutes as a single sequential run is split into N parallel shards via a `matrix`, each running its slice with the framework's native sharding flag (`--shard` for Playwright/Vitest/Jest, `--partition` for cargo-nextest, `pytest-split` for pytest). The critical path drops toward `total / N` plus per-job setup.

_Matrix sharding across 4 parallel jobs_

```yaml
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
      - run: npm ci
      - run: npx playwright install --with-deps chromium
      - run: npx playwright test --shard=${{ matrix.shard }}/4
```

## Avoid this

The whole suite runs on one runner, so the PR waits on a single long pole.

_One sequential job for the whole suite_

```yaml
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npx playwright test   # every spec, one runner, one long pole
```

## Why it matters

Sharding is a top wall-clock lever: it directly parallelizes your slowest test job. The honest tradeoff is that it trades runner-minutes for speed, the same tests still run, and each extra shard adds fixed setup overhead (checkout, install), so your bill goes up even as the critical path comes down. Stack it with dependency and build caching so per-shard setup doesn't eat the gains, and make sure your runners have enough concurrency to start every shard at once instead of queueing.

## When to use

**Use it when:** Any test job whose wall-clock is over ~5 minutes and whose framework supports sharding.

**Be careful when:** When the suite is short, or when per-job setup already dominates the runtime, past a point, adding shards stops moving wall-clock because the setup tax floors it. Fix caching first, then shard.

## Verify on your repo

Hand this prompt to your coding agent to audit and fix this practice in your own repo:

Inspect this repo's .github/workflows for a long test job that runs the whole suite on a single runner with no `matrix` shard axis. Identify the slowest test job (wall-clock over ~5 minutes) and confirm its framework supports sharding (`--shard` for Playwright / Jest / Vitest, `--partition` for cargo-nextest, `pytest-split` for pytest). Add a `matrix` with a `shard` axis and pass the framework's native sharding flag so the suite splits across N parallel jobs, and make sure dependency and build caching is in place so per-shard setup does not eat the gains. Show me the diff and open a PR rather than applying it blindly.

Prefer to check by hand:

- Identify test jobs with wall-clock over ~5 minutes.
- Check whether the framework supports sharding (`--shard` for Playwright/Jest/Vitest, `--partition` for nextest, `pytest-split`).
- Confirm no `matrix` shard axis is configured, a single job running the whole suite is the flag.

## FAQ

### Does sharding save money or just time?

Just time. Sharding lowers wall-clock (the critical path) but raises runner-minutes, because the same test work runs across more jobs and each shard repeats setup. It's the right lever when speed matters more than the bill, pair it with caching to keep the added overhead small.

### How many shards should I use?

Increase shards until the per-shard setup overhead (checkout, install, browser download) starts to dominate, that's the floor. Caching that setup lets you shard further before diminishing returns kick in.

## More best practices for GitHub Actions

- [Build and test only what changed in GitHub Actions](https://starsling.dev/best-practices/github-actions/build-only-affected)
- [Cache dependencies in GitHub Actions](https://starsling.dev/best-practices/github-actions/cache-dependencies)
- [All CI best practices](https://starsling.dev/best-practices/github-actions)

## Sources

1. [Playwright - test sharding](https://playwright.dev/docs/test-sharding)
2. [GitHub Actions - matrix strategy](https://docs.github.com/en/actions/using-jobs/using-a-matrix-for-your-jobs)
3. [cargo-nextest - test partitioning](https://nexte.st/docs/ci-features/partitioning/)