@empiricalrun/playwright-utils 0.65.1 → 0.66.0

package/dist/kv.d.ts

@@ -1,7 +1,37 @@
+import { type KvEntryRecord } from "./api-worker-client";
+export type KvEntry<T = unknown> = Omit<KvEntryRecord, "value"> & {
+    value: T;
+};
+export type KvEntryMetadata = Omit<KvEntryRecord, "value">;
+export type KvSetOptions = {
+    ifAbsent?: boolean;
+    ifVersion?: number;
+};
+export type KvListOptions = {
+    prefix?: string;
+    cursor?: string;
+    limit?: number;
+};
+export declare class KvPreconditionFailedError extends Error {
+    readonly current: KvEntry | null;
+    constructor(key: string, current: KvEntryRecord | null);
+}
 export declare class KVClient {
     private client;
     constructor();
     get<T = unknown>(key: string): Promise<T | null>;
-    set(key: string, value: unknown, ttl: number): Promise<void>;
+    getEntry<T = unknown>(key: string): Promise<KvEntry<T> | null>;
+    set<T>(key: string, value: T, ttl: number, options?: KvSetOptions): Promise<KvEntry<T>>;
+    refresh<T = unknown>(key: string, ttl: number, options?: {
+        ifVersion?: number;
+    }): Promise<KvEntry<T> | null>;
+    delete(key: string, options?: {
+        ifVersion?: number;
+    }): Promise<boolean>;
+    list(options?: KvListOptions): Promise<{
+        entries: KvEntryMetadata[];
+        nextCursor: string | null;
+    }>;
+    entries<T = unknown>(prefix?: string): AsyncGenerator<KvEntry<T>>;
 }
 //# sourceMappingURL=kv.d.ts.map

package/dist/kv.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"kv.d.ts","sourceRoot":"","sources":["../src/kv.ts"],"names":[],"mappings":"AAEA,qBAAa,QAAQ;IACnB,OAAO,CAAC,MAAM,CAAkB;IAEhC,cAEC;IAEK,GAAG,CAAC,CAAC,GAAG,OAAO,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC,CAIrD;IAEK,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAEjE;CACF"}
+{"version":3,"file":"kv.d.ts","sourceRoot":"","sources":["../src/kv.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,aAAa,EAGnB,MAAM,qBAAqB,CAAC;AAE7B,MAAM,MAAM,OAAO,CAAC,CAAC,GAAG,OAAO,IAAI,IAAI,CAAC,aAAa,EAAE,OAAO,CAAC,GAAG;IAAE,KAAK,EAAE,CAAC,CAAA;CAAE,CAAC;AAE/E,MAAM,MAAM,eAAe,GAAG,IAAI,CAAC,aAAa,EAAE,OAAO,CAAC,CAAC;AAE3D,MAAM,MAAM,YAAY,GAAG;IAAE,QAAQ,CAAC,EAAE,OAAO,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC;AAEtE,MAAM,MAAM,aAAa,GAAG;IAC1B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB,CAAC;AAEF,qBAAa,yBAA0B,SAAQ,KAAK;IAClD,QAAQ,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAAC;IAEjC,YAAY,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,aAAa,GAAG,IAAI,EAQrD;CACF;AAoBD,qBAAa,QAAQ;IACnB,OAAO,CAAC,MAAM,CAAkB;IAEhC,cAEC;IAEK,GAAG,CAAC,CAAC,GAAG,OAAO,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC,CAGrD;IAEK,QAAQ,CAAC,CAAC,GAAG,OAAO,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,CAGnE;IAEK,GAAG,CAAC,CAAC,EACT,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,CAAC,EACR,GAAG,EAAE,MAAM,EACX,OAAO,CAAC,EAAE,YAAY,GACrB,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAUrB;IAEK,OAAO,CAAC,CAAC,GAAG,OAAO,EACvB,GAAG,EAAE,MAAM,EACX,GAAG,EAAE,MAAM,EACX,OAAO,CAAC,EAAE;QAAE,SAAS,CAAC,EAAE,MAAM,CAAA;KAAE,GAC/B,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,CAa5B;IAEK,MAAM,CACV,GAAG,EAAE,MAAM,EACX,OAAO,CAAC,EAAE;QAAE,SAAS,CAAC,EAAE,MAAM,CAAA;KAAE,GAC/B,OAAO,CAAC,OAAO,CAAC,CAMlB;IAEK,IAAI,CACR,OAAO,GAAE,aAAkB,GAC1B,OAAO,CAAC;QAAE,OAAO,EAAE,eAAe,EAAE,CAAC;QAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,CAAC,CASpE;IAEM,OAAO,CAAC,CAAC,GAAG,OAAO,EAAE,MAAM,SAAK,GAAG,cAAc,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAanE;CACF"}

package/dist/kv.js

@@ -1,18 +1,92 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.KVClient = void 0;
+exports.KVClient = exports.KvPreconditionFailedError = void 0;
 const api_worker_client_1 = require("./api-worker-client");
+class KvPreconditionFailedError extends Error {
+    current;
+    constructor(key, current) {
+        super(current
+            ? `KV condition failed for "${key}": it is at version ${current.version}`
+            : `KV condition failed for "${key}": it does not exist`);
+        this.name = "KvPreconditionFailedError";
+        this.current = current ? asEntry(current) : null;
+    }
+}
+exports.KvPreconditionFailedError = KvPreconditionFailedError;
+function asEntry(record) {
+    return { ...record, value: record.value };
+}
+function writeCondition(options) {
+    if (options?.ifAbsent && options.ifVersion !== undefined) {
+        throw new Error("Pass either ifAbsent or ifVersion, not both");
+    }
+    if (options?.ifAbsent) {
+        return { ifAbsent: true };
+    }
+    return options?.ifVersion === undefined
+        ? undefined
+        : { ifVersion: options.ifVersion };
+}
 class KVClient {
     client;
     constructor() {
         this.client = new api_worker_client_1.ApiWorkerClient();
     }
     async get(key) {
-        const response = await this.client.getProjectKv(key);
-        return response.data?.value ?? null;
+        const entry = await this.getEntry(key);
+        return entry ? entry.value : null;
+    }
+    async getEntry(key) {
+        const record = await this.client.getKvEntry(key);
+        return record ? asEntry(record) : null;
+    }
+    async set(key, value, ttl, options) {
+        const result = await this.client.putKvEntry(key, { value: value, ttl }, writeCondition(options));
+        if (!result.ok) {
+            throw new KvPreconditionFailedError(key, result.current);
+        }
+        return asEntry(result.value);
+    }
+    async refresh(key, ttl, options) {
+        const result = await this.client.refreshKvEntry(key, ttl, options?.ifVersion);
+        if (result === null) {
+            return null;
+        }
+        if (!result.ok) {
+            throw new KvPreconditionFailedError(key, result.current);
+        }
+        return asEntry(result.value);
+    }
+    async delete(key, options) {
+        const result = await this.client.deleteKvEntry(key, options?.ifVersion);
+        if (!result.ok) {
+            throw new KvPreconditionFailedError(key, result.current);
+        }
+        return result.value;
+    }
+    async list(options = {}) {
+        const page = await this.client.listKvEntries({
+            ...options,
+            include_values: "false",
+        });
+        return {
+            entries: page.entries.map(({ value: _value, ...metadata }) => metadata),
+            nextCursor: page.next_cursor,
+        };
     }
-    async set(key, value, ttl) {
-        await this.client.setProjectKv({ key, value, ttl });
+    async *entries(prefix = "") {
+        let cursor;
+        do {
+            const page = await this.client.listKvEntries({
+                prefix,
+                cursor,
+                include_values: "true",
+            });
+            for (const record of page.entries) {
+                yield asEntry(record);
+            }
+            cursor = page.next_cursor ?? undefined;
+        } while (cursor);
     }
 }
 exports.KVClient = KVClient;

package/dist/test/cross-shard-locks.d.ts

@@ -0,0 +1,22 @@
+import { type TestLocksByTestId } from "@empiricalrun/shared-types/playwright-utils";
+import type { TestInfo } from "@playwright/test";
+import { type KVClient } from "../kv";
+type LockKv = Pick<KVClient, "set" | "refresh" | "delete">;
+export declare const LOCK_LEASE_SECONDS = 60;
+export declare function lockNamesFor(testId: string, locks?: TestLocksByTestId): string[];
+export declare function lockKey(runId: string, name: string): string;
+export declare function holdLocks({ kv, runId, names, holder, annotate, now, sleep, }: {
+    kv: LockKv;
+    runId: string;
+    names: string[];
+    holder: unknown;
+    annotate: (annotation: {
+        type: string;
+        description: string;
+    }) => void;
+    now?: () => number;
+    sleep?: (ms: number) => Promise<void>;
+}): Promise<() => Promise<void>>;
+export declare function holdCrossShardLocks(testInfo: TestInfo, createKv: () => LockKv): Promise<() => Promise<void>>;
+export {};
+//# sourceMappingURL=cross-shard-locks.d.ts.map

package/dist/test/cross-shard-locks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cross-shard-locks.d.ts","sourceRoot":"","sources":["../../src/test/cross-shard-locks.ts"],"names":[],"mappings":"AAGA,OAAO,EAEL,KAAK,iBAAiB,EACvB,MAAM,6CAA6C,CAAC;AACrD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAEjD,OAAO,EAAE,KAAK,QAAQ,EAA6B,MAAM,OAAO,CAAC;AAEjE,KAAK,MAAM,GAAG,IAAI,CAAC,QAAQ,EAAE,KAAK,GAAG,SAAS,GAAG,QAAQ,CAAC,CAAC;AAI3D,eAAO,MAAM,kBAAkB,KAAK,CAAC;AAkBrC,wBAAgB,YAAY,CAC1B,MAAM,EAAE,MAAM,EACd,KAAK,GAAE,iBACa,GACnB,MAAM,EAAE,CAEV;AAED,wBAAgB,OAAO,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAI3D;AAuBD,wBAAsB,SAAS,CAAC,EAC9B,EAAE,EACF,KAAK,EACL,KAAK,EACL,MAAM,EACN,QAAQ,EACR,GAAc,EACd,KAAiE,GAClE,EAAE;IACD,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,MAAM,EAAE,OAAO,CAAC;IAChB,QAAQ,EAAE,CAAC,UAAU,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,CAAA;KAAE,KAAK,IAAI,CAAC;IACtE,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CACvC,GAAG,OAAO,CAAC,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC,CA6C/B;AAED,wBAAsB,mBAAmB,CACvC,QAAQ,EAAE,QAAQ,EAClB,QAAQ,EAAE,MAAM,MAAM,GACrB,OAAO,CAAC,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC,CAmB9B"}

package/dist/test/cross-shard-locks.js

@@ -0,0 +1,110 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LOCK_LEASE_SECONDS = void 0;
+exports.lockNamesFor = lockNamesFor;
+exports.lockKey = lockKey;
+exports.holdLocks = holdLocks;
+exports.holdCrossShardLocks = holdCrossShardLocks;
+const node_crypto_1 = require("node:crypto");
+const node_fs_1 = __importDefault(require("node:fs"));
+const playwright_utils_1 = require("@empiricalrun/shared-types/playwright-utils");
+const kv_1 = require("../kv");
+exports.LOCK_LEASE_SECONDS = 60;
+const RENEW_EVERY_MS = 20_000;
+const MAX_POLL_MS = 2_000;
+let sharedLocks;
+function readSharedLocks() {
+    const file = process.env[playwright_utils_1.TEST_LOCKS_FILE_ENV];
+    if (!file) {
+        return {};
+    }
+    try {
+        return JSON.parse(node_fs_1.default.readFileSync(file, "utf-8"));
+    }
+    catch {
+        return {};
+    }
+}
+function lockNamesFor(testId, locks = (sharedLocks ??=
+    readSharedLocks())) {
+    return [...new Set(locks[testId] ?? [])].sort();
+}
+function lockKey(runId, name) {
+    const readable = name.replace(/[^A-Za-z0-9._-]/g, "_").slice(0, 200);
+    const digest = (0, node_crypto_1.createHash)("sha256").update(name).digest("hex").slice(0, 12);
+    return `pw-lock:${runId}:${readable}:${digest}`;
+}
+async function acquire(kv, key, holder, sleep) {
+    for (let attempt = 0;; attempt++) {
+        try {
+            const entry = await kv.set(key, holder, exports.LOCK_LEASE_SECONDS, {
+                ifAbsent: true,
+            });
+            return entry.version;
+        }
+        catch (error) {
+            if (!(error instanceof kv_1.KvPreconditionFailedError)) {
+                throw error;
+            }
+            await sleep(Math.min(MAX_POLL_MS, 250 * 2 ** attempt));
+        }
+    }
+}
+async function holdLocks({ kv, runId, names, holder, annotate, now = Date.now, sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms)), }) {
+    const held = [];
+    for (const name of names) {
+        const key = lockKey(runId, name);
+        const startedAt = now();
+        const version = await acquire(kv, key, holder, sleep);
+        held.push({ name, key, version });
+        annotate({
+            type: "lock",
+            description: `${name}: waited ${Math.round((now() - startedAt) / 1000)}s across shards`,
+        });
+    }
+    const leaseLost = (lock) => annotate({ type: "lock", description: `${lock.name}: lease lost` });
+    let renewing = Promise.resolve();
+    const renewal = setInterval(() => {
+        renewing = Promise.allSettled(held.map((lock) => kv
+            .refresh(lock.key, exports.LOCK_LEASE_SECONDS, { ifVersion: lock.version })
+            .then((entry) => {
+            if (entry) {
+                lock.version = entry.version;
+            }
+            else {
+                leaseLost(lock);
+            }
+        }, () => leaseLost(lock))));
+    }, RENEW_EVERY_MS);
+    renewal.unref();
+    return async () => {
+        clearInterval(renewal);
+        await renewing;
+        await Promise.allSettled(held
+            .reverse()
+            .map((lock) => kv.delete(lock.key, { ifVersion: lock.version })));
+    };
+}
+async function holdCrossShardLocks(testInfo, createKv) {
+    const names = lockNamesFor(testInfo.testId);
+    const runId = process.env.TEST_RUN_GITHUB_ACTION_ID;
+    if (names.length === 0 || !runId || !process.env.EMPIRICALRUN_API_KEY) {
+        return async () => { };
+    }
+    return holdLocks({
+        kv: createKv(),
+        runId,
+        names,
+        holder: {
+            test_id: testInfo.testId,
+            title: testInfo.titlePath.join(" › "),
+            retry: testInfo.retry,
+            shard: testInfo.config.shard?.current ?? null,
+            worker_index: testInfo.workerIndex,
+        },
+        annotate: (annotation) => testInfo.annotations.push(annotation),
+    });
+}

package/dist/test/index.d.ts

@@ -21,6 +21,7 @@ type TestOptions = {
         page: Page;
     }>;
     saveVideos: void;
+    crossShardLocks: void;
 };
 declare const baseTestFixture: (testFn: TestType<PlaywrightTestArgs & PlaywrightTestOptions, PlaywrightWorkerArgs & PlaywrightWorkerOptions>, options?: BaseTestFixtureOpts) => TestType<PlaywrightTestArgs & PlaywrightTestOptions & TestOptions, PlaywrightWorkerArgs & PlaywrightWorkerOptions>;
 export { baseTestFixture, extendExpect, injectLocatorHighlightScripts, setVideoLabel, };

package/dist/test/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/test/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,cAAc,EACd,qBAAqB,EACrB,MAAM,EACN,IAAI,EACJ,kBAAkB,EAClB,qBAAqB,EACrB,oBAAoB,EACpB,uBAAuB,EACvB,QAAQ,EACT,MAAM,kBAAkB,CAAC;AAG1B,OAAO,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAC;AAEjC,OAAO,EAGL,KAAK,qBAAqB,EAC3B,MAAM,UAAU,CAAC;AAClB,OAAO,EAAE,6BAA6B,EAAE,MAAM,WAAW,CAAC;AAC1D,OAAO,EAAE,KAAK,mBAAmB,EAAE,MAAM,SAAS,CAAC;AACnD,OAAO,EAA8B,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAE3E,OAAO,CAAC,MAAM,CAAC;IACb,UAAU,cAAc,CAAC;QACvB,UAAU,QAAQ,CAAC,CAAC;YAClB,WAAW,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;YAC7C,qBAAqB,CAAC,OAAO,EAAE,qBAAqB,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;SACnE;KACF;CACF;AAED,QAAA,MAAM,YAAY,mBAA6B,OAAO,MAAM,0CAG3D,CAAC;AAEF,KAAK,WAAW,GAAG;IACjB,IAAI,EAAE,IAAI,CAAC;IACX,EAAE,EAAE,QAAQ,CAAC;IACb,yBAAyB,EAAE,CACzB,OAAO,CAAC,EAAE,qBAAqB,KAC5B,OAAO,CAAC;QAAE,OAAO,EAAE,cAAc,CAAC;QAAC,IAAI,EAAE,IAAI,CAAA;KAAE,CAAC,CAAC;IACtD,UAAU,EAAE,IAAI,CAAC;CAClB,CAAC;AAIF,QAAA,MAAM,eAAe,WACX,QAAQ,CACd,kBAAkB,GAAG,qBAAqB,EAC1C,oBAAoB,GAAG,uBAAuB,CAC/C,YACQ,mBAAmB,uHA6G7B,CAAC;AAEF,OAAO,EACL,eAAe,EACf,YAAY,EACZ,6BAA6B,EAC7B,aAAa,GACd,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/test/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,cAAc,EACd,qBAAqB,EACrB,MAAM,EACN,IAAI,EACJ,kBAAkB,EAClB,qBAAqB,EACrB,oBAAoB,EACpB,uBAAuB,EACvB,QAAQ,EACT,MAAM,kBAAkB,CAAC;AAG1B,OAAO,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAC;AAGjC,OAAO,EAGL,KAAK,qBAAqB,EAC3B,MAAM,UAAU,CAAC;AAClB,OAAO,EAAE,6BAA6B,EAAE,MAAM,WAAW,CAAC;AAC1D,OAAO,EAAE,KAAK,mBAAmB,EAAE,MAAM,SAAS,CAAC;AACnD,OAAO,EAA8B,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAE3E,OAAO,CAAC,MAAM,CAAC;IACb,UAAU,cAAc,CAAC;QACvB,UAAU,QAAQ,CAAC,CAAC;YAClB,WAAW,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;YAC7C,qBAAqB,CAAC,OAAO,EAAE,qBAAqB,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;SACnE;KACF;CACF;AAED,QAAA,MAAM,YAAY,mBAA6B,OAAO,MAAM,0CAG3D,CAAC;AAEF,KAAK,WAAW,GAAG;IACjB,IAAI,EAAE,IAAI,CAAC;IACX,EAAE,EAAE,QAAQ,CAAC;IACb,yBAAyB,EAAE,CACzB,OAAO,CAAC,EAAE,qBAAqB,KAC5B,OAAO,CAAC;QAAE,OAAO,EAAE,cAAc,CAAC;QAAC,IAAI,EAAE,IAAI,CAAA;KAAE,CAAC,CAAC;IACtD,UAAU,EAAE,IAAI,CAAC;IACjB,eAAe,EAAE,IAAI,CAAC;CACvB,CAAC;AAIF,QAAA,MAAM,eAAe,WACX,QAAQ,CACd,kBAAkB,GAAG,qBAAqB,EAC1C,oBAAoB,GAAG,uBAAuB,CAC/C,YACQ,mBAAmB,uHA2H7B,CAAC;AAEF,OAAO,EACL,eAAe,EACf,YAAY,EACZ,6BAA6B,EAC7B,aAAa,GACd,CAAC"}

package/dist/test/index.js

@@ -7,6 +7,7 @@ exports.setVideoLabel = exports.injectLocatorHighlightScripts = exports.extendEx
 const path_1 = __importDefault(require("path"));
 const kv_1 = require("../kv");
 const coverage_1 = require("./coverage");
+const cross_shard_locks_1 = require("./cross-shard-locks");
 const expect_1 = require("./expect");
 const scripts_1 = require("./scripts");
 Object.defineProperty(exports, "injectLocatorHighlightScripts", { enumerable: true, get: function () { return scripts_1.injectLocatorHighlightScripts; } });
@@ -112,6 +113,18 @@ const baseTestFixture = function (testFn, options = {}) {
             },
             { auto: true },
         ],
+        crossShardLocks: [
+            async ({}, use, testInfo) => {
+                const release = await (0, cross_shard_locks_1.holdCrossShardLocks)(testInfo, () => new kv_1.KVClient());
+                try {
+                    await use();
+                }
+                finally {
+                    await release();
+                }
+            },
+            { auto: true, timeout: 0 },
+        ],
     });
     return extendedTestFn;
 };

package/docs/kv.md

@@ -1,6 +1,8 @@
 # KV Store
 
-A simple key-value store for sharing data across test runs.
+A project-scoped key-value store for sharing state across tests, shards, test
+runs and agent sessions. Every entry expires, and conditional writes make it
+safe to coordinate between parallel shards.
 
 ## Fixture usage
 
@@ -17,10 +19,72 @@ test("example", async ({ page, kv }) => {
 import { KVClient } from "@empiricalrun/playwright-utils";
 
 const kv = new KVClient();
-await kv.set("my-key", { some: "data" }, 3600); // ttl in seconds, max 2 days
+await kv.set("my-key", { some: "data" }, 3600);
 const value = await kv.get<{ some: string }>("my-key");
 ```
 
+## Keys, values and expiry
+
+- Keys are 1-512 characters from `A-Z a-z 0-9 . _ : -`. Use `:` to namespace
+  them, e.g. `async-checks:analytics:1234`.
+- Values are any JSON value, up to 1 MB serialized.
+- `ttl` is required, in seconds, up to 30 days.
+
+## Entries and versions
+
+`getEntry` returns the value with its metadata. `version` increases on every
+write.
+
+```ts
+const entry = await kv.getEntry("my-key");
+// { key, value, version, expires_at, created_at, updated_at, written_by }
+```
+
+## Conditional writes
+
+`set` with `ifAbsent` writes only if the key does not exist; `ifVersion` writes
+only if the entry is still at that version. A failed condition throws
+`KvPreconditionFailedError`, whose `current` is the entry as it is now.
+
+```ts
+import { KvPreconditionFailedError } from "@empiricalrun/playwright-utils";
+
+try {
+  const lease = await kv.set("lock:checkout", testInfo.testId, 60, {
+    ifAbsent: true,
+  });
+  await kv.refresh("lock:checkout", 60, { ifVersion: lease.version });
+} catch (error) {
+  if (error instanceof KvPreconditionFailedError) {
+    console.log("held by", error.current?.value);
+  }
+}
+```
+
+## Refresh, delete and list
+
+```ts
+await kv.refresh("my-key", 600);
+await kv.delete("my-key", { ifVersion: 3 });
+
+const page = await kv.list({ prefix: "async-checks:" });
+for await (const entry of kv.entries("async-checks:")) {
+  console.log(entry.key, entry.value);
+}
+```
+
+`refresh` returns `null` and `delete` returns `false` when the key does not
+exist. `list` returns metadata only; `entries` pages through every entry with
+its value.
+
+## Locks across shards
+
+Tests declared with Playwright's `lock` option (`test("...", { lock: "name" }, ...)`)
+also hold that lock across every shard of an Empirical test run. The
+`baseTestFixture` fixtures take a KV lease per lock name while the test runs and
+add a `lock` annotation with the time spent waiting. Locks are scoped to the
+test run.
+
 ## Requirements
 
 - `EMPIRICALRUN_API_KEY` environment variable must be set

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@empiricalrun/playwright-utils",
-  "version": "0.65.1",
+  "version": "0.66.0",
   "engines": {
     "node": ">=22"
   },
@@ -56,9 +56,9 @@
     "openapi-fetch": "0.14.1",
     "puppeteer-extra-plugin-recaptcha": "^3.6.8",
     "ts-morph": "^28.0.0",
-    "@empiricalrun/cua": "^0.6.0",
     "@empiricalrun/r2-uploader": "^0.11.5",
-    "@empiricalrun/reporter": "^0.30.3"
+    "@empiricalrun/reporter": "^0.30.3",
+    "@empiricalrun/cua": "^0.6.0"
   },
   "scripts": {
     "dev": "pnpm gen:api-worker-openapi && tsc --build --watch",