Choosing Playwright Parallelism: Workers, Shards, and Projects for Fast, Reliable CI

What Decision Do You Need to Make?

When a Playwright test suite runs in a CI pipeline, you often face three parallelism knobs:

• Worker pool size – how many Playwright workers run inside a single project.
• Sharding – split the file list across CI nodes.
• Project isolation – separate browser configurations (chromium, firefox, webkit) in the config.

Choosing the right mix determines:

• Runtime – how fast the whole suite finishes.
• Resource consumption – memory and CPU usage per CI job.
• Determinism – risk of flaky tests caused by shared state.
• Scalability – how easily you can add more CI runners.

Constraints That Shape the Choice

1. CI budget – total CPU cores and RAM available per job.
2. Test flakiness tolerance – are you willing to risk shared‑browser state?
3. Browser matrix complexity – do you need per‑browser isolation?
4. Sharding granularity – how many CI nodes can you run in parallel?
5. Setup cost – how expensive is global setup/teardown per worker or shard?

Parallelism Options in a Nutshell

Layer	Isolation	Memory Footprint	Setup Cost	Scaling Complexity
Worker Pool (—workers=N)	Shared browser pool per project; context per test can be isolated with test.use({ storageState })	Low – one browser process per worker; contexts share memory.	Global setup runs once per worker; repeatable across shards.	Simple – adjust --workers flag.
Sharding (—shard=1/3)	Full isolation between shards; each shard gets its own worker pool.	Higher – each shard launches its own browsers.	Global setup runs per shard; need idempotent logic for DB seeding.	Requires CI orchestration to distribute shards.
Project Isolation (chromium, firefox, webkit)	Each project has its own worker pool and browser instance.	Very high – three browser processes per worker.	Global setup runs per project; can be expensive.	Best for strict per‑browser isolation; less flexible for mixed‑browser shards.

Trade‑Offs Explained

• Speed vs. Isolation – Increasing workers gives the fastest startup but risks cross‑test contamination. Shards give absolute isolation but add overhead per shard.
• Memory vs. Parallelism – More workers or shards mean more browser processes, which can OOM in containerized CI. Monitor with docker stats or CI logs.
• Setup Idempotence – Global setup runs per worker; if you need a one‑time DB migration, use a file lock or external service. Shards require shard‑aware setup if you seed data.
• Reporter Merging – JSON reporter outputs per shard; use npx playwright merge-reports to combine into a single HTML report. All shards must share the same playwright.config.ts to avoid mismatched test IDs.
• Browser Launch Time – Firefox and WebKit start slower than Chromium. In a mixed‑project run, Chromium shards finish early and idle; consider separate CI jobs per browser for efficient resource use.

Concrete Implementation Example

// playwright.config.ts
import { defineConfig, devices } from '@playwright/test';

export default defineConfig({
  testDir: './tests',
  workers: process.env.PLAYWRIGHT_WORKERS || 2, // default: 2
  projects: [
    { name: 'chromium', use: { ...devices['Desktop Chrome'] } },
    { name: 'firefox', use: { ...devices['Desktop Firefox'] } },
    { name: 'webkit', use: { ...devices['Desktop Safari'] } },
  ],
  reporter: [['list'], ['json', { outputFile: 'results.json' }]],
  // Enable trace only on first retry to limit disk I/O
  retries: 1,
  trace: 'on-first-retry',
});

Run two shards on two CI nodes:

// Node A
npx playwright test \
  --workers=4 --shard=1/2 \
  --reporter=github,json \
  --output=shard-1.json

// Node B
npx playwright test \
  --workers=4 --shard=2/2 \
  --reporter=github,json \
  --output=shard-2.json

After both nodes finish, merge the reports:

npx playwright merge-reports \
  shard-1.json shard-2.json \
  --reporter=html --output=merged-report.html

Open merged-report.html in a browser to confirm all tests are present once and each test shows the browser/project name. If any test appears twice or missing, adjust --shard values or testMatch patterns.

How to Verify the Result

1. Test discovery – Run npx playwright test --list on a local machine to ensure the expected number of tests per project/shard.
2. Shard boundaries – Add a tiny test that logs process.env.PLAYWRIGHT_SHARD_INDEX and process.env.PLAYWRIGHT_WORKER_INDEX. Verify the logs show distinct shard indices across CI nodes.
3. Memory check – In your CI job, add a step to print docker stats or similar resource usage after the run. Ensure RAM stays below your container limit (e.g., 4GB).
4. Flake detection – Run npx playwright test --repeat-each=5 --workers=4 locally. If any test fails more than once, consider adding storageState isolation or reducing workers.
5. Runtime comparison – Measure the total wall‑time for the suite with different --workers and --shard combinations. Stop increasing parallelism when additional workers no longer reduce runtime.

When to Pick Which Layer

• Fastest local runs – Use --workers=CPU/2 and test.use({ storageState }) for deterministic isolation.
• Large CI budgets – Combine sharding with project isolation: run chromium shard 1/3 on node A, firefox shard 2/3 on node B, etc.
• Limited CI resources – Stick to a single project with a moderate worker count; avoid sharding to save on setup overhead.
• Mixed‑browser matrix with strict isolation – Separate CI jobs per browser; each job runs all shards sequentially to keep memory usage low.

Limitations & Caveats

• Sharding uses a deterministic hash of file paths; adding or removing tests re‑assigns shards. Pin the test list or accept minor redistribution.
• Global setup runs per worker; with many workers you may trigger duplicate DB migrations. Use idempotent logic or external locks.
• Trace collection multiplies disk I/O when many workers retry. Disable or limit retries for smoke runs.
• Report merging requires identical playwright.config.ts across shards; differing testMatch or grep patterns corrupt the merged report.
• Containerized CI may kill a worker if memory > limit. Monitor docker stats and adjust --workers accordingly.

Summary

Pick the parallelism layer that matches your CI budget and flakiness tolerance. Use a worker pool for quick local runs, sharding to scale across CI nodes, and project isolation for strict per‑browser boundaries. Validate each configuration with the steps above to ensure deterministic, isolated, and efficient test execution.