Can you explain parallelism in Playwright?
Parallelism in Playwright means running several tests at the same time in separate worker processes. Each worker is its own Node.js process with its own browser, and each test inside it still gets a fresh browser context. Because workers share nothing in memory, tests can run side by side without stepping on each other's cookies or storage.
The default rule: files in parallel, tests in order
Out of the box, Playwright Test spreads test files across workers, but the tests inside one file run one after another in the same worker. So a suite of ten files can keep several workers busy, while one big file with fifty tests uses only one.
The number of workers defaults to half of the machine's logical CPU cores. You can change it:
npx playwright test --workers=4 # exactly four workers
npx playwright test --workers=50% # half the CPU cores
npx playwright test --workers=1 # no parallelism, useful when debugging
Making tests inside a file parallel
// playwright.config.ts
import { defineConfig } from '@playwright/test';
export default defineConfig({
fullyParallel: true, // every test can go to any worker
workers: process.env.CI ? 2 : undefined, // fewer workers on a small CI machine
retries: process.env.CI ? 2 : 0,
});
Or switch it on for one file or group only:
// tests/catalogue.spec.ts
import { test, expect } from '@playwright/test';
test.describe.configure({ mode: 'parallel' });
test('search finds Java courses', async ({ page }) => {
await page.goto('/courses?q=java');
await expect(page.getByRole('listitem').first()).toContainText('Java');
});
test('filter by online mode', async ({ page }) => {
await page.goto('/courses');
await page.getByLabel('Online').check();
await expect(page.getByText('Mode: Online').first()).toBeVisible();
});
The URLs and labels are placeholders. Each test must be independent for this to work, which is exactly what Playwright's isolation is for; see browser isolation.
When order matters: serial mode
For a flow that genuinely has to run step by step, use test.describe.configure({ mode: 'serial' }). The tests in that group run in order in one worker, and if one fails the remaining ones are skipped. Use it sparingly; most "dependent" tests are better rewritten to set up their own data through the API.
Beyond one machine: sharding
Workers parallelise inside a machine. Sharding splits the suite across machines, for example four CI jobs:
npx playwright test --shard=1/4 --reporter=blob
# ... jobs 2/4, 3/4 and 4/4 in parallel ...
npx playwright merge-reports --reporter=html ./all-blob-reports
With fullyParallel: true, shards are balanced per test rather than per file, which usually spreads the load more evenly. Running Playwright on CI and cloud machines is covered in running Playwright on cloud services.
Keeping parallel tests from colliding
The browser is isolated, but your backend is not. Two workers that both register test@example.com will fight. Use the worker's index to make data unique:
test('register a new student', async ({ page }, testInfo) => {
const email = `student-${testInfo.workerIndex}-${Date.now()}@example.com`;
await page.goto('/register');
await page.getByLabel('Email').fill(email);
// ...
});
testInfo.parallelIndex is a stable number from 0 to workers − 1, handy for picking one test account per worker. A worker that crashes or has a failing test is replaced by a new one with a new workerIndex, which is also why beforeAll hooks may run more than once.
Troubleshooting
- Tests pass alone but fail together. Shared data or shared accounts. Make data unique per test or per worker.
- CI is slower with more workers. The machine is overloaded. Lower
workersor shard across machines. - One file dominates the run time. Turn on
fullyParallelor split the file. - Stop early on a broken build.
--max-failures=10ends the run after ten failures.
Want to master Playwright hands-on?
Join Uncodemy's Playwright Automation Testing Course in Noida — Dedicated Placement Support.
Explore the Course →