Playwright test runner serializes tests sharing a named lock

Introduced 2026-09-04 · score 0.98

HOW TO USE IT

When tests access a shared resource that cannot be used concurrently, give them the same named lock. Use `test.describe()` details to apply a lock to every test in a group; tests sharing a lock wait for one another while other tests can run in parallel.

import { test } from '@playwright/test';

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

import { test } from '@playwright/test';

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

WHY THIS HELPS

Keep tests that access the same shared resource from running concurrently.

REQUIREMENTS AND LIMITATIONS

Version: v1.63.0
test lock (`details.lock`): A lock name, or an array of lock names. Tests with a shared lock name do not run concurrently; a test with multiple locks runs only when all are available.
test.describe() `title`: The group title; the API allows omitting it when using the callback form.
test.describe() `details.lock`: A lock name or array of lock names applied to the group's tests. The docs do not state that lock names are mutually exclusive; multiple locks are supported.
test.describe() `callback` (required): Function whose declared tests belong to the group.
Prerequisite: Use Playwright Test v1.63.0 or later for test locks.
Docs conflict: Current API docs mark `test.describe.configure({ lock })` as added in v1.64. That scope-level form is newer than v1.63.0; use the documented `test.describe()` details form for a group lock in this card’s version.

FIRST-PARTY EVIDENCE

Check the installed version and the source before using it. Entry JSON

Report a problem with this card

Tools change faster than your agent’s training data.

Changes

Playwright test runner serializes tests sharing a named lock