Resource-Lease Architecture for Collision-Free Playwright Test Data

Parallel Playwright tests need more than unique random strings when they share scarce accounts, devices, subscriptions, or preloaded records. Collision-free data requires an authority that knows which resource is assigned, to whom, for how long, and how it returns after failure. That authority is a lease service or an equivalent atomic partition.

Keep lease coordination outside the browser scenario. A fixture acquires and releases the resource, while each test mutates only its namespace and proves its own cleanup contract. The service remains responsible for concurrency and recovery when the worker disappears.

Inventory resources by collision behavior

Classify data before designing the pool. Ephemeral records can usually be created per test and deleted by API. Scarce reusable resources need leases. Immutable reference data can be shared. Singleton environment state, such as one global feature toggle, should be serialized or moved to an isolated environment rather than disguised as a pool.

The Playwright fixture documentation makes setup and teardown composable around use(). That lifecycle is the right client boundary for a lease, but it is not a distributed lock. Atomic acquisition and crash recovery belong in the lease authority.

Define the lease contract before the client

An acquire request needs a globally unique owner and eligibility constraints. A useful owner combines pipeline run, shard, Playwright project, and stable parallel slot. Constraints describe what the test requires: tenant, role, region, device capability, seeded plan, or other immutable traits.

The response should include a lease ID, safe resource reference, expiry, and only the credentials required by the worker. Repeating the same acquire request should return the owner's active lease. Reusing the owner with different constraints should fail, because silently changing resources during retry makes attempts incomparable.

Release accepts lease ID and owner, is idempotent, and refuses to release another owner's active assignment. Renewal extends only a healthy active lease and has a maximum horizon tied to the run. Include a broker-generated reason when no eligible capacity exists.

Make acquisition atomic at the storage boundary

Two workers can read the same available row before either writes it. Prevent that race in the broker database with a transaction, conditional update, row lock, or uniqueness constraint on active resource assignment. Application-side "check then set" logic without storage enforcement is not sufficient.

Keep resource status separate from lease status. A resource can be available, quarantined, resetting, or retired. A lease can be active, released, expired, or revoked. If reset fails, quarantine the resource instead of returning it to the pool and causing unrelated tests to inherit damaged state.

Audit lease transitions with safe owner metadata. This is operational test infrastructure, so administrators need to distinguish capacity exhaustion, broker outage, leaked lease, and product cleanup failure without opening Playwright traces one by one.

Encapsulate broker transport in a typed client

Fixtures should not duplicate endpoint shapes and error handling. A small client converts transport failures into lifecycle-specific errors and centralizes redaction. Keep it independent of Page; the broker is a control-plane API.

// test-support/lease-client.ts
import type { APIRequestContext } from '@playwright/test';

export type ResourceLease = {
  leaseId: string;
  resourceId: string;
  expiresAt: string;
  capabilities: string[];
};

export class LeaseClient {
  constructor(private readonly request: APIRequestContext) {}

  async acquire(input: {
    owner: string;
    kind: 'seller-account';
    capabilities: string[];
  }): Promise<ResourceLease> {
    const response = await this.request.post('/leases', { data: input });
    if (!response.ok()) {
      throw new Error(`Lease acquisition failed with ${response.status()}`);
    }
    return await response.json() as ResourceLease;
  }

  async release(lease: ResourceLease, owner: string): Promise<void> {
    const response = await this.request.delete(`/leases/${lease.leaseId}`, {
      data: { owner },
    });
    if (!response.ok() && response.status() !== 404) {
      throw new Error(`Lease release failed with ${response.status()}`);
    }
  }
}

Do not place a pool administrator token in the lease object. Configure the control-plane request context from CI secrets and ensure error bodies are sanitized before they reach attachments.

Bind one lease to a stable worker owner

A worker-scoped fixture is efficient when tests in a worker run sequentially and can isolate their mutations. Use parallelIndex for the stable slot across worker replacement, then add run, shard, and project identity so separate runners cannot collide.

// test-support/resource-test.ts
import { test as base } from '@playwright/test';
import { LeaseClient, type ResourceLease } from './lease-client';

type WorkerFixtures = { sellerLease: ResourceLease };

export const test = base.extend<{}, WorkerFixtures>({
  sellerLease: [async ({ playwright }, use, workerInfo) => {
    const runId = process.env.QA_RUN_ID;
    const shardId = process.env.QA_SHARD_ID ?? 'local';
    const brokerURL = process.env.QA_LEASE_BROKER_URL;
    const brokerToken = process.env.QA_LEASE_BROKER_TOKEN;
    if (!runId || !brokerURL || !brokerToken) {
      throw new Error('Resource lease configuration is incomplete');
    }

    const owner = [
      runId,
      shardId,
      workerInfo.project.name,
      `slot-${workerInfo.parallelIndex}`,
    ].join(':');

    const request = await playwright.request.newContext({
      baseURL: brokerURL,
      extraHTTPHeaders: { Authorization: `Bearer ${brokerToken}` },
    });
    const client = new LeaseClient(request);
    const lease = await client.acquire({
      owner,
      kind: 'seller-account',
      capabilities: ['catalog-write'],
    });

    try {
      await use(lease);
    } finally {
      await client.release(lease, owner);
      await request.dispose();
    }
  }, { scope: 'worker' }],
});

If a test changes the account password, membership, role, billing plan, or other account-level property, worker reuse is unsafe. Move that lease to test scope or lease a disposable account. Scope follows mutation risk, not setup cost alone.

Namespace every mutation inside the lease

Exclusive account ownership prevents concurrent workers from sharing the account, but sequential tests can still leak records to each other. Give each test a namespace derived from run identity and testInfo.testId, then use it in created names, idempotency keys, and cleanup queries. Do not use only the retry number; retries should reconcile the same logical scenario state.

Create through APIRequestContext when UI creation is not under test, and assert through the UI when rendering or workflow behavior is. On retry, a create endpoint should return the existing namespaced record or the fixture should delete and recreate it through an explicit reset contract.

Avoid broad cleanup such as "delete every order for this seller." That can remove a neighboring scenario's data after a broker bug and conceal the very collision the architecture should expose. Delete by resource owner and exact test namespace.

Design release for partial failure

Normal teardown must attempt domain reset before releasing the resource. If reset fails, tell the broker to quarantine the resource or leave the lease marked unhealthy. Releasing it as available transfers contamination to the next worker.

Process termination bypasses finally, so leases need expiry. A lightweight heartbeat can renew long runs, but cap renewal and stop it when the worker loses broker connectivity. A run-level reconciliation job should release or quarantine all remaining leases after shards finish or are cancelled.

Keep cleanup errors visible without replacing the original assertion evidence. Attach the cleanup outcome, then report both failures through a fixture step or aggregated error policy. A product defect followed by a reset outage requires two owners, not one overwritten stack trace.

Apply backpressure instead of oversubscribing

The worker count cannot exceed eligible resource capacity without a queue or failure policy. Decide a bounded acquisition wait and expose current safe capacity to CI. Waiting forever consumes runner time and turns infrastructure exhaustion into test timeouts.

Reducing Playwright workers is often the correct temporary response when the shared environment has fewer resources. Creating more aliases for the same account is not additional capacity. For a large suite, partition inventory by tenant, role, or shard so one noisy class cannot starve every job.

Treat repeated acquisition latency as a capacity signal. It may indicate stale leases, slow resets, or an oversized CI matrix. Keep that telemetry in the broker rather than adding sleeps in test fixtures.

Separate broker failures from product failures

Acquisition, renewal, reset, and release should appear as named fixture steps with lease-safe metadata. A scenario must not begin after partial acquisition or run with a resource whose capabilities do not satisfy the request. Fail before browser navigation with owner, requested kind, and non-sensitive broker reason.

On product failure, attach lease ID, resource ID, test namespace, and relevant created record IDs. These identifiers let an operator correlate application and broker logs. Never attach account secrets or full API responses merely because the test is already failing.

Test the lease service itself with concurrent acquisition, idempotent reacquisition, wrong-owner release, expiry, quarantine, and recovery cases. End-to-end tests should consume those guarantees, not be the only place they are exercised.

Adopt leases through a controlled rollout

Start with the resource class causing the most collisions. Measure its real mutation boundary, create an eligibility inventory, implement atomic acquisition, and migrate one test group. Force a worker crash during a non-production run to prove expiry and reconciliation before increasing parallelism.

Use this readiness checklist:

• Resource classes distinguish shareable, ephemeral, scarce, and singleton state.
• Owner identity is unique across runs, shards, projects, and parallel slots.
• Atomic storage rules prevent two active leases for one resource.
• Fixture scope matches account-level and record-level mutation behavior.
• Per-test namespaces make creation, retry, reset, and deletion idempotent.
• Failed reset quarantines the resource instead of returning dirty capacity.
• Expiry and reconciliation recover leases when teardown never runs.

Scale workers only after the broker can prove ownership and recovery under interruption. Collision-free test data is not achieved when failures merely become rarer; it is achieved when every mutable resource has one accountable owner and a deterministic path back to a known state.