Playwright "--shard" Misconfigured - Tests Skipped or Double-Run in CI

Playwright splits a suite across machines with --shard=<index>/<total>. When the matrix indices and the total disagree, or blob reports are not merged, some tests are skipped, run twice, or the final report is incomplete.

What this error means

A sharded run finishes "green" but the total test count is lower than expected, or a flaky test seems to run on two shards. The merged report is missing results because not every shard’s blob was collected.

CI log

# matrix shard: [1, 2, 3] but command says total 4
npx playwright test --shard=${{ matrix.shard }}/4
# shard 4 never dispatched -> ~25% of tests never run

Common causes

Index/total mismatch with the CI matrix

The total in --shard=index/total must equal the number of matrix jobs. A matrix of 3 with total 4 leaves one shard undispatched, so a quarter of tests never run.

Blob reports not merged

Each shard emits a partial blob report. Without uploading every shard’s blob and running merge-reports, the combined report omits some shards’ results.

How to fix it

Drive index and total from one matrix value

Compute both from the same source so they can never drift.

.github/workflows/ci.yml

# .github/workflows/ci.yml
strategy:
  matrix:
    shardIndex: [1, 2, 3, 4]
    shardTotal: [4]
steps:
  - run: npx playwright test --shard=${{ matrix.shardIndex }}/${{ matrix.shardTotal }}

Collect and merge blob reports

Terminal

# each shard: --reporter=blob (uploads blob-report/)
# final job:
npx playwright merge-reports --reporter=html ./all-blob-reports

How to prevent it

Derive --shard index and total from the same matrix definition.
Use the blob reporter and a dedicated merge-reports job.
Assert the merged test count matches the expected total.