Playwright 1.63 Test Locks: Safer Parallel Proxy and Geo QA

Playwright 1.63, released September 4, 2026, adds named test locks. Tests that declare the same lock do not run concurrently, even when they live in different files, workers or projects; unrelated tests can continue in parallel. For proxy-backed browser QA, this is a useful control for scarce or stateful resources that cannot safely handle simultaneous mutations.

The feature does not make proxy traffic correct by itself. It gives teams a narrower alternative to forcing an entire project into serial mode. The operational value comes from choosing the right resource boundary, keeping tests independently repeatable and preserving enough evidence to tell resource contention from a network failure.

Public source note: Microsoft Playwright, “Playwright v1.63.0,” released September 4, 2026; Microsoft Playwright, “Parallelism — Test locks,” reviewed September 10, 2026.

Why shared proxy tests collide

Parallel browser jobs are usually desirable, but several proxy and localization workflows contain shared mutable state:

• one sticky session identifier reused to verify continuity;
• one test account whose locale, currency or consent choice is modified;
• one limited-concurrency gateway or allowlisted source;
• one test phone number, inbox or checkout basket;
• one administrative fixture that changes the target’s global setting;
• one evidence collector that writes to a single exclusive artifact.

Without coordination, two individually valid tests can corrupt each other. One worker rotates a session while another expects it to remain sticky. One project changes an account to Canada while another is asserting German prices. The resulting failure may be blamed on the proxy pool even though the route was healthy.

What the new lock actually guarantees

A Playwright test can declare one lock or multiple locks. A test.describe() group can also apply a lock to every test in that group. Playwright waits until all requested locks are available before starting the test, then releases them when it finishes.

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

test('validate a sticky session', {
  lock: ['proxy-session:qa-a', 'account:market-check'],
}, async ({ page }) => {
  await page.goto(process.env.AUTHORIZED_TEST_URL!);
  await expect(page.getByTestId('market')).toHaveText('CA');
});

The names above should identify logical resources, not contain credentials, customer data or real proxy endpoints. Use stable pseudonymous IDs that are useful in reports without revealing secrets.

Choose the lock boundary deliberately

Lock the smallest resource that truly cannot be shared.

Avoid a single global name such as proxy. It can serialize unrelated regions, products and accounts, hiding concurrency defects while making the suite unnecessarily slow. A better key describes the actual collision domain, for example a pseudonymous session lease or test tenant.

Do not confuse a lock with isolation

A lock controls overlap; it does not reset state. Each test still needs a clean browser context, explicit proxy configuration, bounded timeouts and deterministic cleanup. If a test leaves a session, cookie, account setting or server record dirty, the next lock holder can inherit the problem.

Use the Playwright OPFS and proxy-state isolation review when storage state is part of the workflow. For sticky-route measurement, keep the acceptance criteria in the residential proxy session stickiness test.

A practical rollout plan

1. Inventory shared resources

Search for tests that mutate the same account, session, region fixture or exclusive output. Confirm the resource is genuinely shared instead of masking an avoidable fixture-design problem.

2. Establish a clean baseline

Before adding locks, run the affected tests individually and record route, region, exit fingerprint, account state, timing and content assertions. A test that fails alone is not a concurrency problem.

3. Reproduce the collision

Run the pair or group concurrently with fixed inputs. Capture both browser traces and sanitized proxy-side observations. Demonstrate the overlapping operation that changes the outcome.

4. Add a narrow named lock

Apply the same stable key only to tests sharing that collision domain. If a test needs multiple resources, list all required locks so the runner acquires them together.

5. Measure the result

Compare failure rate, queue time, total suite duration and unrelated test throughput. The expected result is that the targeted collision disappears while independent work stays parallel.

6. Test abnormal exits

Force an assertion failure, timeout and worker restart in a controlled environment. Confirm later tests can acquire the resource and that teardown restores account, session and artifact state.

Important file-mode behavior

Playwright’s parallelism documentation notes that in default and serial file modes, tests in a file run together in order. A lock declared by a test can therefore be held for the duration of that whole file. Review file organization before concluding that the lock is more restrictive than expected.

This is another reason to group by real resource ownership rather than adding locks broadly. If only one test requires an exclusive proxy lease, placing unrelated tests in the same file can extend the critical section.

Evidence to retain

For each locked test, retain a sanitized operational record:

test_id
project_id
worker_index
lock_ids
lock_wait_ms
resource_lease_id
proxy_route_id
expected_region
exit_fingerprint
account_state_before
account_state_after
result_class
cleanup_result
duration_ms

Do not store proxy passwords, authorization headers, cookies, tokens, full personal data or target secrets. A pseudonymous resource lease and route ID are enough to correlate most contention failures.

Failure interpretation

Failure disappears after a narrow lock: the strongest explanation is shared-resource contention, not automatically poor proxy quality. Re-run and confirm that state reset is deterministic.

Failure persists when run alone: inspect proxy configuration, DNS, TLS, target response and assertions. The lock is not addressing the relevant layer.

Queue time rises sharply: the lock scope may be too broad, the shared resource may be undersized, or the suite may be holding the lock during unrelated setup and reporting.

Wrong region appears despite serialization: inspect lease assignment, session semantics, redirect behavior and content validation. Mutual exclusion cannot guarantee the provider selected the expected exit.

A later test inherits state: cleanup or fixture isolation is incomplete. The fact that tests no longer overlap does not make the shared resource clean.

Deployment checklist

• [ ] Playwright 1.63 is pinned and verified in CI.
• [ ] Every lock maps to a documented collision domain.
• [ ] Lock names contain no credentials or customer data.
• [ ] Tests pass individually before concurrency diagnosis.
• [ ] The collision is reproducible without the lock.
• [ ] Independent proxy regions and accounts remain parallel.
• [ ] Browser context and account state are reset per test.
• [ ] Timeouts and worker restarts release the resource correctly.
• [ ] Lock wait time and suite duration are monitored.
• [ ] Route, exit-region and content evidence are stored separately.
• [ ] Mandatory proxy routes fail closed instead of bypassing directly.
• [ ] Provider and destination concurrency limits are still respected.

FAQ

Should every proxy test use one global lock?

No. That removes useful parallel coverage and can hide capacity or session-partitioning defects. Lock only a resource that cannot be safely partitioned.

Does a test lock reserve a proxy IP at the provider?

No. It coordinates Playwright tests that use the same name. Provider-side allocation, session leasing and concurrency limits remain separate controls.

Can locks replace per-test browser contexts?

No. Locks prevent selected tests from overlapping; they do not isolate cookies, cache, local storage, OPFS, service workers or target-side account state.

Can one test hold a session lock and an account lock?

Yes. Playwright 1.63 supports multiple locks for a test. Use this only when the test genuinely requires both resources, and keep acquisition boundaries consistent.

Compliance note

Use browser automation and proxies only for lawful, authorized testing, market research, ad verification and data collection. Respect destination terms, robots directives, consent, privacy law, rate limits and provider policies. Test locks are a coordination feature, not a reason to exceed a provider’s concurrency allowance or a destination’s permitted request rate. Do not use them to coordinate evasion, account abuse, purchase-limit bypass or access-control circumvention.