Endform logo

Playwright test locks: what they fix and what they don't

JN
Written by Jakob Norlin

Before test locks, if you wanted to prevent Playwright tests from interfering with each other when accessing a shared resource, your options were limited. You could run tests in serial mode or reduce the number of workers, but both approaches slowed down tests that could otherwise run safely in parallel. Playwright 1.63 introduced test locks to address this issue, ensuring tests that access the same shared resource don’t run simultaneously while unrelated tests continue in parallel. It’s a welcome addition, and one we’re particularly excited about at Endform because we’ve been addressing similar challenges with our concurrency controls.

However, native Playwright locks still have two limitations worth considering, especially if you’re running tests across multiple CI jobs. First, a lock allows only one test at a time, even when the shared resource can support several. Second, locks only coordinate tests within a single Playwright run, leaving tests in separate CI jobs free to collide. In this article, we’ll look at how Playwright’s new locks work, where they fall short, and how to manage shared resources when your CI setup needs more flexibility.

What Playwright test locks fix

Playwright’s named test locks prevent tests that share a resource from running simultaneously. When you assign a lock to a test, Playwright acquires it before the test runs and releases it afterward. Any other test requiring the same lock must wait, while unrelated tests can continue running in parallel.

For example, suppose you have two tests in different files that modify the same account settings. You can prevent them from running simultaneously by assigning both the user-settings lock:

// settings.spec.ts
import { test } from "@playwright/test";

test("changes the locale", { lock: "user-settings" }, async ({ page }) => {
  // ...
});
// profile.spec.ts
import { test } from "@playwright/test";

test(
  "changes the display name",
  { lock: "user-settings" },
  async ({ page }) => {
    // ...
  },
);

Playwright prevents these tests from running simultaneously, even across different files, worker processes, or projects within the same Playwright run.

You can also use locks in a few other ways, depending on which tests need access to a shared resource.

Require multiple locks

If a test needs access to multiple shared resources, you can specify their lock names in an array. Playwright will only start the test once all the required locks are available.

// billing.spec.ts
test(
  "resets billing data",
  {
    lock: ["billing-account", "payment-sandbox"],
  },
  async ({ page }) => {
    // ...
  },
);

Lock an entire group

If multiple tests use the same shared resource, you can apply a lock to their test.describe() group rather than adding it to each test separately.

// account-admin.spec.ts
test.describe("account administration", { lock: "admin-account" }, () => {
  test("changes account owner", async ({ page }) => {
    // ...
  });

  test("changes account plan", async ({ page }) => {
    // ...
  });
});

In Playwright 1.64 and later, you can also use test.describe.configure() to apply a lock to all tests in a file or group:

// settings.spec.ts
test.describe.configure({ lock: "user-settings" });

This is useful when several tests share the same resource, as you only need to configure the lock once.

Playwright 1.65 added a built-in -exclusive- lock. A test with { lock: '-exclusive-' } runs only when no other tests are running.

How Playwright locks compare with serial mode and single-worker execution

Unlike serial mode or running tests with a single worker, named locks let you restrict concurrency to tests that share a resource. However, how narrowly those locks apply depends on your parallelism configuration.

In Playwright’s default and serial modes, a lock is held for the entire test file, even if only one test requires it. For example, if a file contains five tests and only one uses the user-settings lock from our earlier example, Playwright holds that lock until all five tests have finished running.

To apply locks at the individual test level, enable fullyParallel: true, use a parallel describe group, or move lock-protected tests into a separate file.

Here’s how the three approaches compare:

Control What it serializes Best used for
Named locks Tests sharing a lock name Protecting shared resources while preserving parallelism
Serial mode Tests within a serial group Tests that must run in a specific order
workers: 1 All tests in one Playwright invocation Debugging or suites that cannot safely run in parallel

Another important difference is how failures are handled. In serial mode, a failure causes subsequent tests in the group to be skipped, and the group retries together. Named locks don’t introduce those dependencies, so tests remain independent.

Where Playwright test locks fall short

Native Playwright locks solve the problem of tests competing for exclusive access to a shared resource. However, there are two situations where their current capabilities may be insufficient for your CI setup.

Gap 1: Locks only allow one test at a time

Native Playwright locks work well when a resource requires exclusive access, such as a global account setting that only one test should modify at a time. But what if your resource can handle more? Suppose your payment sandbox supports three concurrent sessions. A native lock would force tests to use those sessions one at a time, leaving available capacity unused. Removing the lock could cause too many tests to access the sandbox simultaneously.

Ideally, you should be able to specify how many tests can access a resource at once. Playwright doesn’t currently support configurable lock limits, although we think this is a feature the framework could eventually add. Its scheduler already manages lock acquisition, so extending that behavior to support a concurrency limit greater than one seems feasible.

Gap 2: Locks don’t coordinate across separate Playwright runs

Playwright locks work across files, workers, and projects within a single test invocation. However, if your CI pipeline splits tests into separate shard jobs, each Playwright process manages its locks independently. Two tests in different jobs can therefore acquire the same named lock and access the same resource simultaneously, bringing back the collisions you were trying to prevent.

This also affects overlapping pull requests that test against the same staging environment. Even if each run respects its own locks, the runs can still interfere with each other. We don’t expect Playwright to address this natively, since coordinating resource access across independent CI jobs requires a shared scheduler that can track tests across multiple runs. That’s a level of coordination beyond an individual Playwright process.

How Endform handles both gaps

Endform supports Playwright’s native test locks, allowing tests that share a lock to run safely across its managed runners. By default, tests using the same lock won’t overlap. However, Endform’s concurrentTestLimits setting lets you go further by specifying how many tests can access a resource simultaneously and whether that limit applies within one suite run or across all runs.

To use these controls, your CI pipeline runs npx endform test instead of invoking Playwright directly. Endform’s scheduler then coordinates access to shared resources before dispatching tests to its workers.

Suppose your payment sandbox supports three concurrent sessions, and multiple CI jobs share it. You can configure Endform to enforce that limit across all runs in your organization:

import { defineEndformConfig } from "endform";

export default defineEndformConfig({
  concurrentTestLimits: [
    {
      scope: "across-all-runs",
      label: "lock:payment-sandbox",
      limit: 3,
    },
  ],
});

Your tests can continue using Playwright’s native lock syntax:

test("completes checkout", { lock: "payment-sandbox" }, async ({ page }) => {
  // ...
});

With this configuration, Endform allows up to three tests using payment-sandbox to run simultaneously, even across separate CI jobs and suite runs. Once that limit is reached, other runs wait until a run finishes its payment-sandbox tests and releases its slots.

If you only need to enforce a limit within a single suite run, change the scope to "within-suite-run". You can also apply concurrency limits using Playwright tags or projects, which is useful if you’re working with an older Playwright version or want to control a broader group of tests. Endform introduced support for native Playwright locks and configurable lock limits in CLI 0.81.

Choosing the right approach for shared resources

Before adding locks, consider whether your tests need to share a resource at all. Playwright recommends isolating tests wherever possible, so they can run in parallel without interfering with one another.

For example, if multiple tests create orders using the same order ID, they could encounter conflicts when running simultaneously. Giving each test its own data, such as a unique order ID, avoids those conflicts without requiring a lock. However, when tests must access the same resource, such as a shared account or a payment sandbox with limited capacity, isolation alone may not be enough.

In those cases, choose a concurrency control based on how many tests the resource can support and where those tests run.

Situation Recommended approach Why
Each test can use its own data Unique test data Avoids contention and preserves parallelism
A shared resource requires exclusive access within one Playwright run Native Playwright lock Prevents tests using the same resource from overlapping
A resource supports multiple concurrent tests Endform “within-suite-run” limit Uses the available capacity without exceeding it
Separate CI jobs or runs share a constrained resource Endform “across-all-runs” limit Coordinates resource access across managed runners

Isolate test data wherever possible, use native Playwright locks for resources that require exclusive access, and introduce managed concurrency limits when you need greater flexibility or coordination across runs. This helps keep your tests reliable without unnecessarily restricting parallel execution.

Wrapping up

Test locks make it easier to manage shared resources without sacrificing parallel execution across your entire test suite. Native locks are a good starting point when tests need exclusive access to a resource within a single run. For resources that support multiple concurrent tests or are shared across CI jobs, you’ll need additional coordination to keep tests running reliably.

With Endform, you can continue using Playwright’s native lock annotations while setting concurrency limits and coordinating tests across managed runners. Explore how Endform works with Playwright to see how you can make better use of your CI capacity.

FAQ

What Playwright test configuration options are available for managing shared resources?

Playwright provides several options for managing shared resources during test execution. You can use named test locks to prevent tests from accessing the same resource simultaneously, test.describe() to apply locks to a group, and test.describe.configure() to configure locks at the file or group level. You can also adjust worker counts and parallelism settings to control how tests run.

What's the difference between test locks and serial mode?

Test locks prevent independent tests from accessing the same resource simultaneously, even across different files. Serial mode runs tests in a group sequentially and changes how failures and retries are handled. Use locks for shared-resource conflicts and serial mode when tests depend on a specific execution order.

Can a Playwright lock allow more than one test at a time?

No. Native Playwright locks allow only one test per lock at a time. If your resource supports multiple concurrent tests, Endform’s concurrentTestLimits lets you configure a higher limit.

Do Playwright test locks work across shards or separate CI jobs?

Not if the shards or jobs run separate Playwright invocations. Native locks only coordinate tests within a single invocation. For cross-job coordination, you can use Endform’s across-all-runs concurrency limits.

Related posts

Find your flaky tests

Endform records every Playwright run, so you can see which tests flake, fail or slow down, and quarantine a flaky test so it stops failing your suite. See how test analytics work

Get started for free →Trial includes 2000 free test minutes.No credit card required.