What does Playwright's --shard=1/4 flag do to the set of tests a run executes?

## What `--shard` divides Playwright Test first builds the list of tests a run will execute, after project selection and any path or `--grep` filters have been applied. `--shard` slices that list. `--shard=1/4` says *this process is slice one of four*. The slices are disjoint and their union is the whole selected list, so no test is dropped and no test runs twice. The division is **static and computed before anything executes**. Every shard walks the same repository, produces the same ordered list of units, applies the same arithmetic, keeps its own slice and discards the rest. That is what makes the scheme safe across machines that never talk to each other: it needs no coordinator, no queue and no lock, only the same code and the same total. ## The index is one-based A four-way split is `--shard=1/4`, `--shard=2/4`, `--shard=3/4` and `--shard=4/4`. There is no shard zero. The second number is the **total**, and it is the part a pipeline most often gets wrong: if one job passes `1/4` while another passes `2/5`, the slices stop being a partition of the suite, and the run quietly executes some tests twice and never executes others. ## Declaring it in the config instead The same split exists as a config option, which is useful when a wrapper script rather than a raw CLI call starts the run: ```ts import { defineConfig } from '@playwright/test'; export default defineConfig({ fullyParallel: true, shard: { current: Number(process.env.SHARD_INDEX), total: 4 }, }); ``` The option takes an object with `current` and `total`, not the `1/4` string the flag uses. Command-line options override the config, so a `--shard` argument wins over a `shard` block if both are present. ## What a shard is not - It is **not** a worker. Workers are the parallel processes inside one machine's run; a shard is the subset of tests one machine was handed. A single shard still starts several workers of its own. - It is **not** a retry pool. A test that fails in shard 2 is never attempted by shard 3, because shards do not see each other's results. - It is **not** shared state. Each shard is a fresh process on its own machine, with its own browsers, its own storage state and its own setup work. - It is **not** self-balancing. Nothing is moved at run time, so a shard that finishes early simply exits and its machine goes idle. - It is **not** a verdict for the suite. Exit code zero from `--shard=1/4` means one quarter passed. ## What one shard reports A shard's console output counts only the tests it was given, and an HTML report written by a single shard contains only that shard's tests, with that shard's totals. Four shards therefore produce four partial reports and four exit codes. That is exactly why the `blob` reporter and `npx playwright merge-reports` exist: they let the four runs be stitched into one report for the whole suite. ## Turning four jobs back into one answer For a large payroll regression suite in CI the run reads: 1. Launch four jobs, each with the same `total` and a distinct `current`. 2. Give every job the `blob` reporter, so each emits a mergeable archive instead of a finished report. 3. Collect the four archives into one directory once all jobs have ended. 4. Run `npx playwright merge-reports --reporter=html ./all-blob-reports` once to get a single report with the suite's real totals. 5. Gate the pipeline on the combination of the four exit codes, never on one of them. Step 5 is not automatic. Playwright reports per shard; the pipeline is what decides that *the suite passed* means *all four shard jobs passed*. ## Why the model is shaped this way Sharding trades coordination for simplicity. Because the division is a pure function of the test list and the two numbers, a shard needs nothing from its peers and can start the moment a machine is free. The price is that the split is only as even as the units being split, and that stitching results back together is a separate step you have to run yourself.