Run Playwright Test once in each concurrent CI job, giving every job a different 1-based shard index and the same shard total. For example, four jobs run npx playwright test --shard=1/4 through --shard=4/4. Set up the blob reporter in CI, save each job’s blob report, then merge them into one HTML report. Sharding divides the suite across machines; the worker count controls concurrency inside each machine.
How Playwright sharding and workers work together
Sharding assigns portions of a test suite to separate CI jobs or machines. The --shard=current/total option identifies a job’s shard: the index starts at 1, and all jobs must use the same total. Workers are separate processes that run tests concurrently within one job. You can combine both layers, but their total resource use matters: adding shards consumes more runners, while adding workers increases concurrency on each runner.
As an Amazon Associate I earn from qualifying purchases.
By default, Playwright parallelizes test files, while tests within an individual file run sequentially. With fullyParallel: true, it can distribute tests at the individual-test level, which may improve balance when a few large files dominate the suite. See the Playwright sharding guide and parallelism guide. The sharding page is Next documentation, so check the stable documentation and the version installed in your project before relying on version-sensitive details.
Crashes, No Sound, or Screen Glitches?
Random freezes, missing sound and display glitches usually trace back to one bad driver. Find and replace yours safely.Free scan · under a minuteWindows Errors? Fix Them Before They Spread
Repair common Windows errors and clear accumulated junk for a smoother, more stable PC - no reinstall needed.Free scan · no reinstallConfigure parallelism for local runs and CI
This configuration uses Playwright’s blob reporter in CI so shard results can be combined, and the HTML reporter for local runs:
import { defineConfig } from '@playwright/test';
export default defineConfig({
workers: process.env.CI ? 1 : undefined,
reporter: process.env.CI ? 'blob' : 'html',
});Playwright recommends starting with one worker in CI to prioritize stability and reproducibility; that is a conservative starting point, not a universal speed optimum. Once the suite is stable, adjust the worker limit according to runner CPU and memory and validate that tests remain reliable. The CI guide covers CI setup, and the parallelism guide documents worker configuration.
Run one shard in each CI job
- Use your CI provider’s matrix or parallel-job facility to start the desired number of concurrent jobs.
- In each job, run the same commit, test configuration, and total shard count, but assign a distinct shard index from 1 through that total.
- For four jobs, run one command per job:
npx playwright test --shard=1/4 npx playwright test --shard=2/4 npx playwright test --shard=3/4 npx playwright test --shard=4/4
Map the provider’s job or matrix index to Playwright’s 1-based index. Provider variable names and matrix syntax differ; Playwright’s CI documentation includes examples for GitHub Actions, CircleCI, and GitLab CI. The command-line reference documents --shard at Playwright’s command line guide.
Improve uneven shard times safely
Shard duration depends on how work is divided. If a few files contain most of the slow tests, default file-level sharding may leave some jobs with substantially more work. Enabling fullyParallel: true gives Playwright finer test-level distribution, but only use it when tests can safely run independently.
Quick wins for a faster PC:
Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →Clear out junk files and repair common Windows errorsFree Scan →Playwright workers are separate processes, and browser contexts isolate browser state. That does not isolate shared backend records, accounts, queues, or other external data. Give tests unique data or otherwise prevent workers and shards from changing the same shared state. The sharding guide also notes that static skips and fixmes are not counted in shard balancing.
There is no universally optimal shard count, worker count, or guaranteed speedup. Measure your own suite: job startup overhead, runner capacity, test duration distribution, resource contention, and test behavior all affect wall-clock time. More shards require more concurrent CI capacity; more workers can expose shared-state races or contend for resources.
Collect and merge reports from all shards
- Use the
blobreporter for CI runs. Each shard produces a blob archive with run details and attachments. - Upload each shard’s blob output as a CI artifact. Give artifacts unique names that include the shard index so one job cannot overwrite another.
- In a merge job, download or collect all shard artifacts into a single directory, such as
all-blob-reports. - Run the merge command from a location where that directory is available:
npx playwright merge-reports --reporter html ./all-blob-reports
By default, the merged HTML report is written under playwright-report. Preserve and gather blob artifacts even when a test job fails or is cancelled if your CI provider allows it; this helps retain completed shard results. For merges across distinct environments rather than shards, distinguish those environments as described in the reporters guide. Playwright’s sharding guide describes the shard merge workflow.
Rank #4
Common problems and fixes
- A shard is empty or work is missing: Check that every job uses the intended 1-based index, that indices are distinct, and that all commands use the same total. Also verify that every job checks out the same tests and configuration.
- Some jobs finish much later: File-level sharding can be uneven when a few files contain long tests. Consider
fullyParallel: trueif tests are independent, then check for shared backend state before increasing concurrency. - Tests become flaky with more workers or shards: Look for shared accounts, records, or other mutable external state. Isolate data per test or worker, or reduce concurrency. Separate browser contexts do not prevent backend collisions.
- The merge command finds no reports: Confirm that every shard uploaded its blob artifact and that the merge job downloaded all of them into the directory passed to
merge-reports. - One shard’s report replaces another: Use a unique artifact name per shard, then collect each artifact before merging.
- The merged report is incomplete after a failure: Configure artifact upload to run after failures where supported, and have the merge job run unless cancelled when your CI provider permits.
Reduce browser-install work in CI
Install only the browser engines your suite actually uses when that fits your setup. Playwright’s Best Practices guide recommends limiting browser downloads to those needed, which can reduce CI installation work.
Or skip the browser setup
If your task is to capture a website screenshot rather than execute browser tests, ScreenshotNeo offers a one-request screenshot API. It can return PNG, JPEG, WebP, or PDF; it is not a replacement for running Playwright tests.
Best Value
For a quick cURL request, replace the example URL as needed and use your API key. See the ScreenshotNeo API documentation for request options.
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpScreenshotNeo removes cookie and consent banners, newsletter popups, and chat widgets before capture; those steps can be turned off. Bot checks, blank pages, failed loads, timeouts, and cache hits are not billed, with response headers indicating the page verdict and billing status. Its MCP server lets AI agents use screenshot, page-info, and PDF-capture tools. The free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000 shots.
Sign up for ScreenshotNeo’s free plan to get 1,000 screenshots a month with no card.
Frequently Asked Questions
Can I use Playwright sharding without enabling fullyParallel?
Yes. Sharding works with the default file-level distribution; fullyParallel is optional and changes the distribution granularity.
Does Playwright guarantee equal runtime for every shard?
No. Actual duration depends on the suite’s test distribution, runner resources, and job overhead.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
