parallelism

34 notes, read out of this brain and free to use. Each one was extracted from a source and is re-checked against its exam.

Run tests in parallel within a file

Playwright runs tests in parallel by default. Tests in a single file run in order in the same worker process. If you have many independent tests in a single file, you can run them in parallel by using test.describe.configure({ mode: 'parallel' }) at the start of the describe block.

Enable parallel execution within describe block

import { test } from '@playwright/test'; test.describe.configure({ mode: 'parallel' }); test('runs in parallel 1', async ({ page }) => { /* ... */ }); test('runs in parallel 2', async ({ page }) => { /* ... */ });

Shard tests across multiple machines

Playwright can shard a test suite to execute on multiple machines. Use the --shard flag with the format --shard=X/N where X is the shard index and N is the total number of shards.

Shard tests command example

npm: npx playwright test --shard=1/3 yarn: yarn playwright test --shard=1/3 pnpm: pnpm exec playwright test --shard=1/3

Playwright Test parallel execution

Playwright Test supports running tests in isolation in parallel across multiple browsers.

Parallelism default behavior

By default, Playwright Test runs test files in parallel. Tests within a single file run in order in the same worker process.

Run tests in parallel within a single file

Use test.describe.configure({ mode: 'parallel' }) to run tests in a single file in parallel. Tests execute in separate worker processes and cannot share state or global variables. Each test executes all relevant hooks including beforeAll and afterAll.

Enable fully parallel mode globally

Set fullyParallel: true in the configuration file to run all tests in all files in parallel.

Enable fully parallel mode per project

Add fullyParallel: true to a specific project configuration object to enable fully parallel mode for just that project.

Disable parallelism

Set workers: 1 in the configuration file or pass --workers=1 on the command line to disable parallelism and run tests sequentially.

Limit the number of parallel workers

Use workers option in the configuration file or --workers flag on the command line to control the maximum number of parallel worker processes. Example: npx playwright test --workers 4 or workers: process.env.CI ? 2 : undefined in config.

Worker processes isolation

All tests run in OS worker processes that run independently. Each worker has an identical environment and starts its own browser. You cannot communicate between workers. Playwright Test reuses a single worker to make testing faster, so multiple test files usually run in a single worker one after another. Workers are always shut down after a test failure to guarantee a pristine environment for following tests.

Serial mode for dependent tests

Use test.describe.configure({ mode: 'serial' }) to run inter-dependent tests in serial. If one serial test fails, all subsequent tests are skipped. All tests in a serial group are retried together. Serial mode is not recommended; tests should be isolated and run independently.

Test locks for shared resource access

Use the lock option on test() or test.describe() to declare named locks for tests accessing shared resources that do not support concurrent access. Tests sharing a lock name never run at the same time. Locks work across files, worker processes, and projects. A test can declare multiple locks and will only run when all are available. Playwright acquires all locks before the test starts and releases them when finished.

Test lock example with single lock

test('update user settings', { lock: 'user-settings' }, async ({ page }) => { /* ... */ });

Test lock example with multiple locks

test('reset the database', { lock: ['database', 'external-api'] }, async () => { /* ... */ });

Locks in default and serial modes

In default and serial modes, all tests in a file run together in order, so a lock declared on any test is held for the duration of the whole file.

Opt out of fully parallel mode per describe block

When fullyParallel: true is set globally, override it for specific describe blocks using test.describe.configure({ mode: 'default' }) to run those tests in order.

Worker isolation prevents state sharing

Playwright runs tests in separate worker processes, each with its own isolated BrowserContext. Cookies, storage, and in-memory globals are already isolated between workers. Flakiness in parallel tests comes from state that lives outside a single test.

Create unique test identifiers using testId

Use testInfo.testId to derive unique identifiers for each test, ensuring parallel tests never collide when creating or editing the same record. Example: const orderId = `order-${testInfo.testId}`;

Write to unique file paths per test

Use testInfo.outputPath() to get a path scoped to the current test, preventing multiple tests from writing to the same path and clobbering each other. Example: const file = testInfo.outputPath('export.csv');

Keep tests isolated for parallel execution

Tests that leak state through module-level variables or depend on another test's side effects work when tests run in order but break when run in parallel or different order. Set up everything a test needs in that test or in a fixture, and never rely on another test having run first.

Limit failures with maxFailures option

Use maxFailures configuration option or --max-failures command line flag to limit the number of failed tests in the whole test suite. When this limit is reached, Playwright Test stops and skips remaining tests. Example: npx playwright test --max-failures=10 or maxFailures: process.env.CI ? 10 : undefined in config.

Worker index and parallel index identifiers

Each worker process is assigned a unique worker index starting with 1 and a parallel index between 0 and workers - 1. Access via process.env.TEST_WORKER_INDEX, process.env.TEST_PARALLEL_INDEX, testInfo.workerIndex, or testInfo.parallelIndex. When a worker restarts after a failure, the new process has the same parallelIndex and a new workerIndex.

Isolate test data between parallel workers

Use testInfo.workerIndex to create unique user data in the database for each worker. Create a fixture with scope: 'worker' that initializes and cleans up a unique user per worker. All tests run by the worker reuse the same user.

Test order within a single file

Playwright Test runs tests from a single file in the order of declaration, unless tests are parallelized within that file.

Test file execution order

There is no guarantee about the order of test execution across files because Playwright Test runs test files in parallel by default. To control order across files, disable parallelism with workers: 1. Tests will then run in alphabetical file order.

Sort test files alphabetically

When parallel execution is disabled with workers: 1, Playwright Test runs test files in alphabetical order. Use naming conventions like 001-user-signin-flow.spec.ts, 002-create-new-document.spec.ts to control test order.

Test list file usage and limitations

Test lists are discouraged and supported as best-effort only. Some features such as VS Code Extension and tracing may not work properly with test lists. Tests should be wrapped in functions and called by a test list file, not defined directly in helper files.

Test list file example structure

Create test.list.ts that imports and wraps test functions from other files in test.describe() blocks to control execution order. Set workers: 1 and testMatch: 'test.list.ts' in config. Tests must be wrapped in functions within feature files and explicitly called by the test list file.

Sharding test suite across machines

Playwright Test can shard a test suite for execution on multiple machines. Use --shard flag on command line. Example: npx playwright test --shard=2/3

test.parallel runs tests in same file in parallel

The `test.describe.parallel()` API (introduced in 1.15) runs tests in the same file in parallel. By default, tests in a single file run in order. Use describe.parallel() for independent tests that should run concurrently.

test.parallel example usage

Example of parallel test group: test.describe.parallel('group', () => { test('runs in parallel 1', async ({ page }) => { }); test('runs in parallel 2', async ({ page }) => { }); });

testInfo.parallelIndex property

The `testInfo.parallelIndex` property (introduced in 1.17) provides information about the parallel index of the test.

Give your agent this brain