Parallelism, Workers & Sharding

📌 Definition:

📖 Detailed Explanation:

By default, files run in parallel across workers (roughly one per CPU core); tests within a single file run sequentially unless you opt into test.describe.configure({ mode: 'parallel' }). Each worker is a separate process with its own browser, so tests are isolated as long as they don't share external state (same DB row, same user account). Sharding (--shard=1/4) partitions the test list into N slices so four CI machines each run a quarter, and you merge the blob reports afterward into one HTML report. The main caveats: ensure test data isolation (unique users/records per test or per worker) so parallel tests don't collide, and mark truly order-dependent tests as serial deliberately.

🔑 Key Points:

• Files run in parallel across workers by default (~one per core); use workers to tune
• Tests in one file are serial unless mode:'parallel' is set for that describe
• Sharding (--shard=k/n) splits the suite across machines; merge blob reports after
• Each worker is isolated — but shared external state (DB rows, accounts) can still collide
• Give each test/worker unique data; mark order-dependent tests serial on purpose

🌍 Real-World Example:

📎 Code Example:

# Local: run with 6 workers
npx playwright test --workers=6

# Opt a file into intra-file parallelism
# test.describe.configure({ mode: 'parallel' });

# CI: shard across 5 machines (matrix job sets shardIndex)
npx playwright test --shard=1/5
npx playwright test --shard=2/5
# ...

# Merge the per-shard blob reports into one HTML report
npx playwright merge-reports --reporter=html ./all-blob-reports