Parallel Tests in Playwright

Workers and File Parallelism

Each worker is a separate Node process with its own browser instances. By default, different spec files run in parallel; tests within the same file run serially unless you enable fullyParallel: true.

Set workers: 4 in config or pass --workers=4 on the CLI. In CI, workers: undefined uses half the CPU cores — a sensible default for shared runners.

// playwright.config.ts
export default defineConfig({
  fullyParallel: true,
  workers: process.env.CI ? 4 : undefined,
});

// CLI override
npx playwright test --workers=2

More workers mean faster suites but higher memory — monitor CI runner limits.

Parallelism Controls

test.describe.configure({ mode: 'parallel' }); // within file
test.describe.configure({ mode: 'serial' });   // force serial
npx playwright test --shard=2/5               // split across machines

• fullyParallel: true — tests in the same file may run concurrently.
• mode: 'serial' — use when tests share a non-isolated resource.
• --shard=i/n — split suite across CI machines.
• Each test gets a fresh context by default — safe for parallel runs.

Parallelism Reference

Config and CLI for speed.

When to Force Serial Execution

Use test.describe.configure({ mode: 'serial' }) when tests mutate shared external state that cannot be isolated — a single admin account, a rate-limited API, or a database without per-test cleanup.

Sharding Across CI Nodes

Four CI jobs each running --shard=1/4 through --shard=4/4 finish roughly four times faster than one job running everything. Merge blob reports afterward for a unified view.

npx playwright test --shard=$SHARD_INDEX/$SHARD_TOTAL

Common Mistakes

• Enabling fullyParallel when tests share one hard-coded user account.
• Too many workers on memory-limited CI — browsers OOM and crash.
• Shared file-system fixtures written concurrently without unique paths.
• Assuming serial order within a file when fullyParallel is on.

Key Takeaways

• Playwright parallelizes by file across worker processes by default.
• fullyParallel enables within-file parallelism when tests are isolated.
• Shard with --shard=i/n across CI machines for large suites.
• Use serial mode only when tests truly share non-isolated resources.