How to Shard Playwright Tests and Merge Reports in CI

Playwright shards with --shard=i/n and recombines the per-shard blob reports into a single report via merge-reports.

Run playwright test --shard=i/n on each machine with the blob reporter, then a final job runs playwright merge-reports to produce one HTML report.

Steps

Add a shardIndex/shardTotal matrix and pass --shard.
Set the reporter to blob and upload blob-report/ as an artifact per shard.
In a dependent job, download all blobs and run npx playwright merge-reports.

Workflow

.github/workflows/ci.yml

jobs:
  test:
    runs-on: ubuntu-latest
    strategy:
      fail-fast: false
      matrix:
        shardIndex: [1, 2, 3, 4]
        shardTotal: [4]
    steps:
      - uses: actions/checkout@v4
      - run: npm ci
      - run: npx playwright test --shard=${{ matrix.shardIndex }}/${{ matrix.shardTotal }}
        env:
          PLAYWRIGHT_BLOB_OUTPUT_DIR: blob-report
      - uses: actions/upload-artifact@v4
        with:
          name: blob-report-${{ matrix.shardIndex }}
          path: blob-report/
  merge:
    needs: test
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npm ci
      - uses: actions/download-artifact@v4
        with:
          path: all-blobs
          pattern: blob-report-*
          merge-multiple: true
      - run: npx playwright merge-reports --reporter=html all-blobs

Gotchas

Artifact names must be unique per shard in upload-artifact v4; suffix with the shard index.
merge-reports needs every shard blob present, so gate it on needs: and download all patterns.

How to Shard Playwright Tests and Merge Reports in CI

Steps

Workflow

Gotchas

Related guides