Playwright is a framework for Web Testing and Automation. It allows testing Chromium, Firefox and WebKit with a single API.
TypeScript automationchromechromiume2e-testingelectronend-to-end-testingfirefoxjavascriptplaywrighttesttest-automationtestingtesting-toolswebwebkit
feat(test runner): add built-in exclusive lock (#43445)
Yury Semikhatsky2b6470c6ea44
diff --git a/docs/src/test-api/class-test.md b/docs/src/test-api/class-test.mdindex 0be6108225..b6dc2bcad8 100644--- a/docs/src/test-api/class-test.md+++ b/docs/src/test-api/class-test.md@@ -100,6 +100,8 @@ test('update user settings', {});```+The built-in `exclusive` lock runs the test only when no other tests are running.+Learn more about [test locks](../test-parallel.md#test-locks).### param: Test.(call).titlediff --git a/docs/src/test-parallel-js.md b/docs/src/test-parallel-js.mdindex e59444b570..32eb0dae88 100644--- a/docs/src/test-parallel-js.md+++ b/docs/src/test-parallel-js.md@@ -163,6 +163,14 @@ test.describe.configure({ lock: 'user-settings' });Playwright acquires all the locks of a test before the test starts and releases them when it finishes.+The built-in `exclusive` lock runs a test in isolation: it starts only when no other tests are running, and no other tests start until it finishes. All other tests continue to run in parallel with each other. This is useful for a few tests that are sensitive to any concurrent activity, for example tests that measure performance or restart a shared service.++```js+test('restart the server', { lock: 'exclusive' }, async () => {+ // No other test runs while this one is running.+});+```+:::noteIn the default and [serial](#serial-mode) 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.:::diff --git a/packages/playwright/src/runner/dispatcher.ts b/packages/playwright/src/runner/dispatcher.tsindex f8a82e883d..43ac3156e3 100644--- a/packages/playwright/src/runner/dispatcher.ts+++ b/packages/playwright/src/runner/dispatcher.ts@@ -34,11 +34,12 @@ import type { TestError, TestResult, TestStep } from '../../types/testReporter';export type EnvByProjectId = Map<string, Record<string, string | undefined>>;+const exclusiveLock = 'exclusive';+export class Dispatcher {// Worker slot is claimed when it has jobDispatcher assigned.private _workerSlots: { worker?: WorkerHost, jobDispatcher?: JobDispatcher }[] = [];private _queue: TestGroup[] = [];- private _isolatedJobs = new Set<TestGroup>();private _workerLimitPerProjectId = new Map<string, number>();private _queuedOrRunningHashCount = new Map<string, number>();private _finished = new ManualPromise<void>();@@ -71,11 +72,15 @@ export class Dispatcher {private _findFirstJobToRun() {const heldLocks = this._heldLocks();+ // Nothing else runs while an exclusive job is running.+ if (heldLocks.has(exclusiveLock))+ return -1;+ const hasRunningJobs = this._workerSlots.some(w => !!w.jobDispatcher);// Always pick the first job that can be run while respecting the project worker limit.for (let index = 0; index < this._queue.length; index++) {const job = this._queue[index];- // Isolated retries only run one at a time, after all other jobs have finished.- if (this._isolatedJobs.has(job) && this._workerSlots.some(w => !!w.jobDispatcher))+ // Exclusive jobs only run one at a time, after all other jobs have finished.+ if (hasRunningJobs && job.locks.includes(exclusiveLock))continue;if (job.locks.some(lock => heldLocks.has(lock)))continue;@@ -184,7 +189,6 @@ export class Dispatcher {this._updateCounterForWorkerHash(result.remainingJob.workerHash, +1);}if (result.isolatedRetriesJob) {- this._isolatedJobs.add(result.isolatedRetriesJob);this._queue.push(result.isolatedRetriesJob);this._updateCounterForWorkerHash(result.isolatedRetriesJob.workerHash, +1);}@@ -587,7 +591,8 @@ class JobDispatcher {// This job is over, we will schedule new jobs for the remaining tests and isolated retries.const remainingJob = remaining.length ? { ...this.job, tests: remaining } : undefined;- const isolatedRetriesJob = isolatedRetries.length ? { ...this.job, tests: isolatedRetries } : undefined;+ // Isolated retries run one at a time, after all other jobs have finished.+ const isolatedRetriesJob = isolatedRetries.length ? { ...this.job, tests: isolatedRetries, locks: [...new Set([...this.job.locks, exclusiveLock])] } : undefined;this._finished({ didFail: true, remainingJob, isolatedRetriesJob });}diff --git a/packages/playwright/types/test.d.ts b/packages/playwright/types/test.d.tsindex 3224b88103..c6e2f390ed 100644--- a/packages/playwright/types/test.d.ts+++ b/packages/playwright/types/test.d.ts@@ -2898,6 +2898,8 @@ export interface TestType<TestArgs extends {}, WorkerArgs extends {}> {* });* ```*+ * The built-in `exclusive` lock runs the test only when no other tests are running.+ ** Learn more about [test locks](https://playwright.dev/docs/test-parallel#test-locks).* @param title Test title.* @param details Additional test details.@@ -2995,6 +2997,8 @@ export interface TestType<TestArgs extends {}, WorkerArgs extends {}> {* });* ```*+ * The built-in `exclusive` lock runs the test only when no other tests are running.+ ** Learn more about [test locks](https://playwright.dev/docs/test-parallel#test-locks).* @param title Test title.* @param details Additional test details.diff --git a/tests/playwright-test/test-locks.spec.ts b/tests/playwright-test/test-locks.spec.tsindex 1ee7721f21..3f9b0fa23c 100644--- a/tests/playwright-test/test-locks.spec.ts+++ b/tests/playwright-test/test-locks.spec.ts@@ -240,3 +240,50 @@ test('should validate lock in test details', async ({ runInlineTest }) => {expect(result.exitCode).toBe(1);expect(result.output).toContain('details.lock');});++test('should run tests with the exclusive lock in isolation', async ({ runInlineTest }) => {+ const result = await runInlineTest({+ 'playwright.config.ts': `+ export default { fullyParallel: true };+ `,+ 'a.test.ts': `+ import { test } from '@playwright/test';+ ${lockedTest('test1', 500)}+ ${lockedTest('test2', 500, 'exclusive')}+ ${lockedTest('test3', 500)}+ `,+ 'b.test.ts': `+ import { test } from '@playwright/test';+ ${lockedTest('test4', 500, 'other')}+ ${lockedTest('test5', 500)}+ `,+ }, { workers: 3 });+ expect(result.exitCode).toBe(0);+ expect(result.passed).toBe(5);+ const others = ['test1', 'test3', 'test4', 'test5'];+ expect(conflictingOverlaps(result.outputLines, others.map(name => ['test2', name]))).toEqual([]);+});++test('should retry tests with the exclusive lock in isolation', async ({ runInlineTest }) => {+ const result = await runInlineTest({+ 'playwright.config.ts': `+ export default { fullyParallel: true, retries: 1 };+ `,+ 'a.test.ts': `+ import { test, expect } from '@playwright/test';+ test('test1', { lock: 'exclusive' }, async ({}, testInfo) => {+ console.log('\\n%%begin:test1-' + testInfo.retry);+ await new Promise(f => setTimeout(f, 500));+ console.log('\\n%%end:test1-' + testInfo.retry);+ expect(testInfo.retry).toBe(1);+ });+ ${lockedTest('test2', 500)}+ ${lockedTest('test3', 500)}+ `,+ }, { workers: 3 });+ expect(result.exitCode).toBe(0);+ expect(result.flaky).toBe(1);+ expect(result.passed).toBe(2);+ const conflicts: [string, string][] = [['test1-0', 'test2'], ['test1-0', 'test3'], ['test1-1', 'test2'], ['test1-1', 'test3']];+ expect(conflictingOverlaps(result.outputLines, conflicts)).toEqual([]);+});