There are three ways to run tests faster in Playwright: workers, sharding, and project-based parallelism. People confuse these constantly. Let us clear it up once and for all.
Workers run multiple test files simultaneously on the SAME machine. If you have 4 workers, 4 test files run at the same time. Each worker gets its own browser instance. This is the simplest form of parallelism.
export default defineConfig({
// Fixed number of workers
workers: 4,
// Or percentage of available CPUs
workers: '50%',
// Or let Playwright decide (default)
workers: undefined,
// Run tests inside a file in parallel (default is sequential)
fullyParallel: true,
});Sharding distributes test files across DIFFERENT machines. Each machine runs a subset. You need CI matrix support for this. This is how you go from 20 minutes to 5 minutes.
Projects run the same tests with different configurations. Chromium, Firefox, WebKit. Desktop, mobile. Logged in, logged out. Each project runs as a separate set of tests.
export default defineConfig({
projects: [
// These three run in parallel across the worker pool
{
name: 'chromium',
use: { ...devices['Desktop Chrome'] },
},
{
name: 'firefox',
use: { ...devices['Desktop Firefox'] },
},
{
name: 'mobile-chrome',
use: { ...devices['Pixel 7'] },
},
],
});| Feature | Workers | Sharding | Projects |
|---|---|---|---|
| What it does | Parallel files on 1 machine | Splits tests across N machines | Same tests, different configs |
| Where | Same machine | Different CI machines | Same machine (or sharded) |
| Config | workers: 4 | --shard=1/4 | projects: [...] |
| Cost | Free -- uses available CPUs | N x CI machine cost | Multiplies test count |
| Use case | Speed up on single machine | Large suites (500+ tests) | Cross-browser testing |
| Combines with | Sharding, Projects | Workers, Projects | Workers, Sharding |
The ultimate setup: 3 browser projects, 4 shards, 2 workers per shard. That is 3 x 4 = 12 parallel streams, each with 2 workers. For a massive test suite, this turns a 2-hour run into 10 minutes.
By default, tests WITHIN a single file run sequentially. Only different files run in parallel. If you have a file with 20 tests, all 20 run one after another on the same worker. Set fullyParallel: true to parallelize tests within files too.
fullyParallel: true means tests within the same file can run in any order. If your tests depend on each other (test 2 expects test 1 to have created data), they will break. Make each test independent before enabling this.
Start simple. Use workers first. When single-machine parallelism is not enough, add sharding. Only add projects when you need cross-browser testing. Do not over-engineer your CI from day one.
Q: What is the difference between workers, sharding, and projects in Playwright?
A: Workers run multiple test files in parallel on the same machine -- it is free parallelism using available CPUs. Sharding splits the test suite across different CI machines using --shard=1/4 syntax -- each machine runs a subset. Projects run the same tests with different configurations (browsers, devices, viewport sizes). All three can be combined. Workers and projects are configured in playwright.config.ts. Sharding is configured in the CI workflow file. The key difference: workers = same machine, sharding = different machines, projects = different configs.
Key Point: Workers = parallel on one machine. Sharding = parallel across machines. Projects = same tests, different configs. Combine all three for maximum speed.
Key Point: Three parallelism strategies: workers (same machine), sharding (across machines), projects (different configs). They combine for maximum speed.