Test sharding

Sharding divides a suite into N roughly equal parts and runs each part as a separate job, usually on separate CI machines. It is a level above parallel workers: workers run tests concurrently inside one machine, while shards spread the suite across several machines. Combining both is how large UI suites stay within a reasonable pipeline time.

Example (Playwright and GitHub Actions)

Playwright supports sharding with a single flag:

npx playwright test --shard=1/4
npx playwright test --shard=2/4

In CI, a matrix starts one job per shard. Each shard writes a blob report, and a final job merges them into one HTML report:

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
      - run: npx playwright test --shard=${{ matrix.shard }}/4 --reporter=blob
      - uses: actions/upload-artifact@v4
        with:
          name: blob-report-${{ matrix.shard }}
          path: blob-report

The merge job downloads every blob-report-* artifact into one folder and runs npx playwright merge-reports --reporter html ./all-blob-reports.

How tests are distributed

Playwright splits by test file unless fullyParallel: true is set, in which case it balances individual tests across shards. With file-level splitting, one huge spec file can make one shard much slower than the others, so keep files reasonably small.

Common mistakes

• Sharding a suite that isn’t isolated. Tests that share data or depend on order pass on one machine and fail when split. Fix isolation first.
• Losing the overall result. Without a merge step, failures are scattered across N job logs and N reports.
• Too many shards. Every shard pays the fixed cost of checkout, install and browser download. Past a point, more shards add cost without saving time.
• fail-fast left on. One failing shard cancels the others, and you lose the rest of the results.