@sdods/core 0.3.2 → 0.5.2

package/dist/evidence/trace-redact.js

@@ -0,0 +1,297 @@
+import { readdirSync, readFileSync, renameSync, lstatSync, writeFileSync } from 'node:fs';
+import { basename, join } from 'node:path';
+import { SECRET_HEADER } from '../har/api-har.js';
+import { entryContent, isZip, readZip, withContent, writeZip } from './zip.js';
+/**
+ * Strip credentials out of Playwright traces (#101).
+ *
+ * A trace records every request and response header, the context's options (`extraHTTPHeaders`,
+ * `httpCredentials`, `storageState`), every `storageState()` / `addCookies()` call with its result,
+ * DOM snapshots and the arguments of every action. For a project that signs in with pool accounts
+ * that is the session cookie, the `Authorization` bearer and — for Firebase — the long-lived
+ * refresh token in localStorage/IndexedDB.
+ *
+ * What is replaced with `[redacted]`:
+ * - credential headers (`Cookie`, `Set-Cookie`, `Authorization`, `Proxy-Authorization`,
+ *   `X-Api-Key` and similar) wherever a `{ name, value }` header or a header map appears —
+ *   `.network` request/response entries, context options, route and fetch parameters;
+ * - every cookie value, localStorage/sessionStorage value and IndexedDB record;
+ * - `password` / `passphrase` fields (`httpCredentials`, `proxy`, client certificates);
+ * - the value of password inputs in DOM snapshots, and values typed by `fill`/`type` into a field
+ *   whose locator names a password, secret, token or one-time code (best effort).
+ *
+ * Not covered: response and request bodies (`resources/`), page text and screenshots. A redacted
+ * trace is safer to keep, not safe to publish.
+ *
+ * Only `*.trace` and `*.network` entries are rewritten; everything else (sources, screenshots,
+ * resources, stacks) is copied through unchanged, so the trace viewer opens the result as before.
+ */
+export const REDACTED = '[redacted]';
+export const TRACE_SECRET_HEADER = new RegExp(`${SECRET_HEADER.source}|^(x-auth-token|x-access-token|x-refresh-token|x-id-token|x-session-token|x-csrf-token|x-xsrf-token|x-amz-security-token|x-goog-api-key|x-firebase-appcheck|api-key|apikey)$`, 'i');
+/** A locator or selector that names a field whose typed value is a credential. */
+const SECRET_FIELD = /pass(word|wd|code|phrase)?\b|passw|secret|token|\botp\b|one-time|\bpin\b/i;
+const TYPING_METHODS = new Set(['fill', 'type', 'pressSequentially']);
+const isObject = (v) => typeof v === 'object' && v !== null && !Array.isArray(v);
+function blank(holder, key) {
+    const v = holder[key];
+    if (v === undefined || v === null || v === '' || v === REDACTED)
+        return 0;
+    holder[key] = REDACTED;
+    return 1;
+}
+/**
+ * Redact one parsed trace event in place. Returns the number of values replaced.
+ *
+ * `typed` carries values redacted from typing actions across the events of one stream, by call id,
+ * so the action's `log` lines (`fill("…")`) lose the value too.
+ */
+export function redactTraceEvent(event, typed = new Map()) {
+    let n = walk(event, undefined);
+    if (!isObject(event))
+        return n;
+    const value = redactTypedSecret(event);
+    if (value !== undefined) {
+        n++;
+        if (typeof event.callId === 'string')
+            typed.set(event.callId, value);
+    }
+    if (event.type === 'log' &&
+        typeof event.callId === 'string' &&
+        typeof event.message === 'string') {
+        const secret = typed.get(event.callId);
+        if (secret && event.message.includes(secret)) {
+            event.message = event.message.split(secret).join(REDACTED);
+            n++;
+        }
+    }
+    return n;
+}
+function walk(node, key) {
+    let n = 0;
+    if (Array.isArray(node)) {
+        if (key === 'cookies' || key === 'localStorage' || key === 'sessionStorage') {
+            for (const item of node)
+                if (isObject(item))
+                    n += blank(item, 'value');
+        }
+        if (key === 'indexedDB') {
+            for (const db of node) {
+                const stores = isObject(db) && Array.isArray(db.stores) ? db.stores : [];
+                for (const store of stores) {
+                    const records = isObject(store) && Array.isArray(store.records) ? store.records : [];
+                    for (const record of records) {
+                        if (!isObject(record))
+                            continue;
+                        for (const f of ['key', 'keyEncoded', 'value', 'valueEncoded'])
+                            n += blank(record, f);
+                    }
+                }
+            }
+        }
+        // DOM snapshot node: ["INPUT", { type: "password", __playwright_value_: "..." }, ...children]
+        if (typeof node[0] === 'string' &&
+            node[0].toUpperCase() === 'INPUT' &&
+            isObject(node[1]) &&
+            String(node[1].type ?? '').toLowerCase() === 'password') {
+            n += blank(node[1], '__playwright_value_') + blank(node[1], 'value');
+        }
+        for (const item of node)
+            n += walk(item, undefined);
+        return n;
+    }
+    if (!isObject(node))
+        return 0;
+    if (typeof node.name === 'string' && 'value' in node && TRACE_SECRET_HEADER.test(node.name))
+        n += blank(node, 'value');
+    if (key !== undefined && /headers$/i.test(key)) {
+        for (const [header, value] of Object.entries(node))
+            if (typeof value === 'string' && TRACE_SECRET_HEADER.test(header))
+                n += blank(node, header);
+    }
+    for (const f of ['password', 'passphrase'])
+        if (typeof node[f] === 'string')
+            n += blank(node, f);
+    for (const [k, v] of Object.entries(node))
+        if (typeof v === 'object')
+            n += walk(v, k);
+    return n;
+}
+/** Returns the typed value when it was redacted. */
+function redactTypedSecret(event) {
+    if (event.type !== 'before' || !isObject(event.params))
+        return undefined;
+    const params = event.params;
+    if (typeof params.value !== 'string' || !params.value || params.value === REDACTED)
+        return undefined;
+    const method = String(event.method ?? '');
+    const title = typeof event.title === 'string' ? event.title : '';
+    const typing = TYPING_METHODS.has(method) ||
+        (method === 'pw:api' && /^(fill|type|press sequentially)\b/i.test(title));
+    if (!typing)
+        return undefined;
+    const target = [params.selector, params.locator, event.subtitle]
+        .filter((s) => typeof s === 'string')
+        .join(' ');
+    if (!SECRET_FIELD.test(target))
+        return undefined;
+    const typed = params.value;
+    params.value = REDACTED;
+    if (title.includes(typed))
+        event.title = title.split(typed).join(REDACTED);
+    return typed;
+}
+/** Redact every JSON line of a `.trace` / `.network` entry. Unparseable lines are kept as they are. */
+export function redactTraceJsonl(text) {
+    let changed = 0;
+    const typed = new Map();
+    const lines = text.split('\n').map((line) => {
+        if (!line.trim())
+            return line;
+        let event;
+        try {
+            event = JSON.parse(line);
+        }
+        catch {
+            return line;
+        }
+        const n = redactTraceEvent(event, typed);
+        if (!n)
+            return line;
+        changed += n;
+        return JSON.stringify(event);
+    });
+    return { text: changed ? lines.join('\n') : text, changed };
+}
+const isTraceEvents = (name) => /\.(trace|network)$/.test(name);
+/** True when the buffer is a zip holding a Playwright trace (or a zip that nests one). */
+export function isTraceZip(entries) {
+    return entries.some((e) => isTraceEvents(e.name));
+}
+/**
+ * Redact a trace zip held in memory. Zips nested inside (blob shard reports keep attachments as
+ * `resources/<sha>.zip`) are redacted too. Non-trace zips come back untouched with `trace: false`.
+ */
+export function redactTraceZip(buf) {
+    if (!isZip(buf))
+        return { buffer: buf, changed: 0, trace: false };
+    const entries = readZip(buf);
+    let changed = 0;
+    let trace = isTraceZip(entries);
+    const out = entries.map((entry) => {
+        if (isTraceEvents(entry.name)) {
+            const res = redactTraceJsonl(entryContent(entry).toString('utf8'));
+            if (!res.changed)
+                return entry;
+            changed += res.changed;
+            return withContent(entry, Buffer.from(res.text, 'utf8'));
+        }
+        if (entry.name.endsWith('.zip')) {
+            const inner = entryContent(entry);
+            const res = redactTraceZip(inner);
+            if (res.trace)
+                trace = true;
+            if (!res.changed)
+                return entry;
+            changed += res.changed;
+            return withContent(entry, res.buffer);
+        }
+        return entry;
+    });
+    return { buffer: changed ? writeZip(out) : buf, changed, trace };
+}
+function writeAtomically(file, data) {
+    const tmp = join(file, '..', `.${basename(file)}.redacting-${process.pid}`);
+    writeFileSync(tmp, data);
+    renameSync(tmp, file);
+}
+/** Redact a trace zip on disk in place. Returns values replaced (0 when not a trace). */
+export function redactTraceFile(file) {
+    const res = redactTraceZip(readFileSync(file));
+    if (res.changed)
+        writeAtomically(file, res.buffer);
+    return res.changed;
+}
+/**
+ * Cucumber messages embed each trace as a BASE64 attachment body, and ingest writes `trace.zip`
+ * from those bytes — so the copy in `messages*.ndjson` is redacted as well.
+ */
+export function redactMessagesFile(file) {
+    const text = readFileSync(file, 'utf8');
+    if (!text.includes('"application/zip"'))
+        return 0;
+    let changed = 0;
+    const lines = text.split('\n').map((line) => {
+        if (!line.includes('"application/zip"'))
+            return line;
+        let env;
+        try {
+            env = JSON.parse(line);
+        }
+        catch {
+            return line;
+        }
+        const a = env.attachment;
+        if (!a || a.mediaType !== 'application/zip' || a.contentEncoding !== 'BASE64' || !a.body)
+            return line;
+        const res = redactTraceZip(Buffer.from(a.body, 'base64'));
+        if (!res.changed)
+            return line;
+        changed += res.changed;
+        a.body = res.buffer.toString('base64');
+        return JSON.stringify(env);
+    });
+    if (changed)
+        writeAtomically(file, lines.join('\n'));
+    return changed;
+}
+/**
+ * Redact every trace a run left behind: `runner-output/<test>/trace.zip`, the HTML report's copies
+ * under `html-report/data/`, blob shard reports, and the BASE64 bodies in `messages*.ndjson`.
+ */
+export function redactRunTraces(runDir, maxDepth = 10) {
+    const result = { files: [], values: 0, errors: [] };
+    const visit = (dir, depth) => {
+        if (depth > maxDepth)
+            return;
+        let names;
+        try {
+            names = readdirSync(dir);
+        }
+        catch {
+            return;
+        }
+        for (const name of names) {
+            const file = join(dir, name);
+            let st;
+            try {
+                st = lstatSync(file);
+            }
+            catch {
+                continue;
+            }
+            if (st.isSymbolicLink())
+                continue;
+            if (st.isDirectory()) {
+                if (name !== 'node_modules')
+                    visit(file, depth + 1);
+                continue;
+            }
+            const isMessages = /^messages.*\.ndjson$/.test(name);
+            if (!name.endsWith('.zip') && !isMessages)
+                continue;
+            try {
+                const n = isMessages ? redactMessagesFile(file) : redactTraceFile(file);
+                if (n) {
+                    result.files.push(file);
+                    result.values += n;
+                }
+            }
+            catch (e) {
+                result.errors.push({ file, error: e.message });
+            }
+        }
+    };
+    visit(runDir, 0);
+    return result;
+}
+//# sourceMappingURL=trace-redact.js.map

package/dist/evidence/zip.d.ts

@@ -0,0 +1,36 @@
+/**
+ * The smallest zip reader/writer that round-trips a Playwright trace.
+ *
+ * Playwright writes traces with yazl: DEFLATE entries whose local headers set the data-descriptor
+ * flag and leave sizes and CRC zero, so sizes are read from the central directory. Entries that are
+ * not rewritten are copied through compressed, byte for byte. ZIP64 archives (over 4 GB or 65,535
+ * entries) are refused rather than misread.
+ */
+export interface ZipEntry {
+    name: string;
+    /** raw name bytes, preserved as written */
+    nameBytes: Buffer;
+    method: number;
+    flags: number;
+    time: number;
+    date: number;
+    crc: number;
+    compressedSize: number;
+    size: number;
+    versionMadeBy: number;
+    versionNeeded: number;
+    internalAttr: number;
+    externalAttr: number;
+    /** compressed payload */
+    data: Buffer;
+}
+export declare class ZipFormatError extends Error {
+}
+export declare function isZip(buf: Buffer): boolean;
+export declare function readZip(buf: Buffer): ZipEntry[];
+export declare function entryContent(entry: ZipEntry): Buffer;
+/** Replace an entry's content, recompressing with DEFLATE. */
+export declare function withContent(entry: ZipEntry, content: Buffer): ZipEntry;
+export declare function writeZip(entries: ZipEntry[]): Buffer;
+export declare function crc32(buf: Buffer): number;
+//# sourceMappingURL=zip.d.ts.map

package/dist/evidence/zip.js

@@ -0,0 +1,148 @@
+import { deflateRawSync, inflateRawSync } from 'node:zlib';
+const SIG_LOCAL = 0x04034b50;
+const SIG_CENTRAL = 0x02014b50;
+const SIG_END = 0x06054b50;
+const FLAG_DATA_DESCRIPTOR = 0x0008;
+export class ZipFormatError extends Error {
+}
+export function isZip(buf) {
+    return buf.length >= 22 && buf.readUInt32LE(0) === SIG_LOCAL;
+}
+export function readZip(buf) {
+    let end = -1;
+    for (let i = buf.length - 22; i >= Math.max(0, buf.length - 22 - 0xffff); i--) {
+        if (buf.readUInt32LE(i) === SIG_END) {
+            end = i;
+            break;
+        }
+    }
+    if (end < 0)
+        throw new ZipFormatError('not a zip archive (no end of central directory)');
+    const count = buf.readUInt16LE(end + 10);
+    const cdSize = buf.readUInt32LE(end + 12);
+    const cdOffset = buf.readUInt32LE(end + 16);
+    if (count === 0xffff || cdOffset === 0xffffffff || cdSize === 0xffffffff)
+        throw new ZipFormatError('ZIP64 archives are not supported');
+    const entries = [];
+    let p = cdOffset;
+    for (let i = 0; i < count; i++) {
+        if (buf.readUInt32LE(p) !== SIG_CENTRAL)
+            throw new ZipFormatError(`bad central directory header at ${p}`);
+        const nameLen = buf.readUInt16LE(p + 28);
+        const extraLen = buf.readUInt16LE(p + 30);
+        const commentLen = buf.readUInt16LE(p + 32);
+        const localOffset = buf.readUInt32LE(p + 42);
+        const compressedSize = buf.readUInt32LE(p + 20);
+        const nameBytes = Buffer.from(buf.subarray(p + 46, p + 46 + nameLen));
+        if (buf.readUInt32LE(localOffset) !== SIG_LOCAL)
+            throw new ZipFormatError(`bad local header at ${localOffset}`);
+        const dataStart = localOffset + 30 + buf.readUInt16LE(localOffset + 26) + buf.readUInt16LE(localOffset + 28);
+        entries.push({
+            name: nameBytes.toString('utf8'),
+            nameBytes,
+            versionMadeBy: buf.readUInt16LE(p + 4),
+            versionNeeded: buf.readUInt16LE(p + 6),
+            flags: buf.readUInt16LE(p + 8),
+            method: buf.readUInt16LE(p + 10),
+            time: buf.readUInt16LE(p + 12),
+            date: buf.readUInt16LE(p + 14),
+            crc: buf.readUInt32LE(p + 16),
+            compressedSize,
+            size: buf.readUInt32LE(p + 24),
+            internalAttr: buf.readUInt16LE(p + 36),
+            externalAttr: buf.readUInt32LE(p + 38),
+            data: buf.subarray(dataStart, dataStart + compressedSize),
+        });
+        p += 46 + nameLen + extraLen + commentLen;
+    }
+    return entries;
+}
+export function entryContent(entry) {
+    if (entry.method === 0)
+        return Buffer.from(entry.data);
+    if (entry.method === 8)
+        return inflateRawSync(entry.data);
+    throw new ZipFormatError(`unsupported compression method ${entry.method} for ${entry.name}`);
+}
+/** Replace an entry's content, recompressing with DEFLATE. */
+export function withContent(entry, content) {
+    const data = deflateRawSync(content);
+    return {
+        ...entry,
+        method: 8,
+        versionNeeded: Math.max(entry.versionNeeded, 20),
+        crc: crc32(content),
+        size: content.length,
+        compressedSize: data.length,
+        data,
+    };
+}
+export function writeZip(entries) {
+    const parts = [];
+    const central = [];
+    let offset = 0;
+    for (const e of entries) {
+        // Sizes and CRC are known, so the local header carries them and no data descriptor follows.
+        const flags = e.flags & ~FLAG_DATA_DESCRIPTOR;
+        const local = Buffer.alloc(30);
+        local.writeUInt32LE(SIG_LOCAL, 0);
+        local.writeUInt16LE(e.versionNeeded, 4);
+        local.writeUInt16LE(flags, 6);
+        local.writeUInt16LE(e.method, 8);
+        local.writeUInt16LE(e.time, 10);
+        local.writeUInt16LE(e.date, 12);
+        local.writeUInt32LE(e.crc >>> 0, 14);
+        local.writeUInt32LE(e.compressedSize, 18);
+        local.writeUInt32LE(e.size, 22);
+        local.writeUInt16LE(e.nameBytes.length, 26);
+        local.writeUInt16LE(0, 28);
+        const cd = Buffer.alloc(46);
+        cd.writeUInt32LE(SIG_CENTRAL, 0);
+        cd.writeUInt16LE(e.versionMadeBy, 4);
+        cd.writeUInt16LE(e.versionNeeded, 6);
+        cd.writeUInt16LE(flags, 8);
+        cd.writeUInt16LE(e.method, 10);
+        cd.writeUInt16LE(e.time, 12);
+        cd.writeUInt16LE(e.date, 14);
+        cd.writeUInt32LE(e.crc >>> 0, 16);
+        cd.writeUInt32LE(e.compressedSize, 20);
+        cd.writeUInt32LE(e.size, 24);
+        cd.writeUInt16LE(e.nameBytes.length, 28);
+        cd.writeUInt16LE(0, 30);
+        cd.writeUInt16LE(0, 32);
+        cd.writeUInt16LE(0, 34);
+        cd.writeUInt16LE(e.internalAttr, 36);
+        cd.writeUInt32LE(e.externalAttr >>> 0, 38);
+        cd.writeUInt32LE(offset, 42);
+        parts.push(local, e.nameBytes, e.data);
+        central.push(cd, e.nameBytes);
+        offset += local.length + e.nameBytes.length + e.data.length;
+        if (offset > 0xffffffff)
+            throw new ZipFormatError('archive too large (ZIP64 not supported)');
+    }
+    const cdSize = central.reduce((n, b) => n + b.length, 0);
+    const end = Buffer.alloc(22);
+    end.writeUInt32LE(SIG_END, 0);
+    end.writeUInt16LE(entries.length, 8);
+    end.writeUInt16LE(entries.length, 10);
+    end.writeUInt32LE(cdSize, 12);
+    end.writeUInt32LE(offset, 16);
+    return Buffer.concat([...parts, ...central, end]);
+}
+let crcTable;
+export function crc32(buf) {
+    if (!crcTable) {
+        crcTable = new Uint32Array(256);
+        for (let n = 0; n < 256; n++) {
+            let c = n;
+            for (let k = 0; k < 8; k++)
+                c = c & 1 ? 0xedb88320 ^ (c >>> 1) : c >>> 1;
+            crcTable[n] = c >>> 0;
+        }
+    }
+    let c = 0xffffffff;
+    for (let i = 0; i < buf.length; i++)
+        c = crcTable[(c ^ buf[i]) & 0xff] ^ (c >>> 8);
+    return (c ^ 0xffffffff) >>> 0;
+}
+//# sourceMappingURL=zip.js.map

package/dist/fixtures/api-context.d.ts

@@ -30,6 +30,13 @@ export declare class ApiContext {
         name: string;
         value: string;
     } | null | undefined;
+    /**
+     * Send through a request context with an empty cookie jar instead of the shared `request`
+     * fixture. On @ui/@hybrid the shared context starts from the leased role's storageState, so a
+     * "credential X alone is refused" assertion would otherwise pass on the session cookie.
+     * Set by `I use an isolated API client`.
+     */
+    isolated: boolean;
     /** step index → number of calls made during that step (for attachment numbering) */
     readonly callsByStep: Map<number, number>;
     get lastResponse(): ApiSnapshot['response'] | undefined;

package/dist/fixtures/api-context.js

@@ -18,6 +18,13 @@ export class ApiContext {
      * refused. Any suite whose env declared `api.auth` had a no-op step.
      */
     auth;
+    /**
+     * Send through a request context with an empty cookie jar instead of the shared `request`
+     * fixture. On @ui/@hybrid the shared context starts from the leased role's storageState, so a
+     * "credential X alone is refused" assertion would otherwise pass on the session cookie.
+     * Set by `I use an isolated API client`.
+     */
+    isolated = false;
     /** step index → number of calls made during that step (for attachment numbering) */
     callsByStep = new Map();
     get lastResponse() {

package/dist/fixtures/auth.js

@@ -1,6 +1,77 @@
 import { closeSync, existsSync, mkdirSync, openSync, readFileSync, readdirSync, renameSync, rmSync, statSync, writeFileSync, } from 'node:fs';
 import { join } from 'node:path';
 import { Logger } from '../logger.js';
+function originOf(url) {
+    try {
+        const o = new URL(url).origin;
+        return o === 'null' ? undefined : o;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Restore one origin's localStorage into a live context without navigating (#99).
+ *
+ * This used to `page.goto(origin)` and write the keys from there. An app that sends a signed-in
+ * visitor away from `/` on the client then had a redirect chain still running when the step
+ * returned, and the scenario's first `page.goto` was aborted (`net::ERR_ABORTED`). The context
+ * already exists by the time a step leases a user, so `newContext({ storageState })` is not an
+ * option here (the `@user:<role>` tag path does use it, via `ensure`).
+ *
+ * - Page already on the origin: write the keys straight into it. Nothing navigates.
+ * - Otherwise: a context init script writes them in the first document of that origin, before the
+ *   app's own scripts run, in any page of the context.
+ *
+ * Planted ONCE per context, not on every navigation. An init script left in place would run again
+ * on each document, so an app that signs out (clears storage) and navigates would be silently
+ * signed back in and a logout scenario would pass while proving nothing. The script is therefore
+ * disposed once a document of that origin has reached DOMContentLoaded (by then it has certainly
+ * run). A navigation that commits in the short window before the dispose lands can run it again;
+ * it only writes keys that are absent, so it never overwrites what the app wrote meanwhile.
+ *
+ * Only localStorage is restored, as before: storageState carries no sessionStorage or IndexedDB.
+ */
+async function plantLocalStorage(context, page, origin, items) {
+    if (originOf(page.url()) === origin) {
+        await page.evaluate((entries) => {
+            for (const { name, value } of entries)
+                window.localStorage.setItem(name, value);
+        }, items);
+        return;
+    }
+    const script = await context.addInitScript(({ origin: target, entries }) => {
+        if (location.origin !== target)
+            return;
+        try {
+            for (const { name, value } of entries) {
+                if (window.localStorage.getItem(name) === null)
+                    window.localStorage.setItem(name, value);
+            }
+        }
+        catch {
+            // storage disabled for this document (sandboxed frame): nothing to plant into
+        }
+    }, { origin, entries: items });
+    const watched = new Set();
+    let disposed = false;
+    const onLoaded = (p) => {
+        if (disposed || originOf(p.url()) !== origin)
+            return;
+        disposed = true;
+        context.off('page', watch);
+        for (const w of watched)
+            w.off('domcontentloaded', onLoaded);
+        void script.dispose().catch(() => undefined);
+    };
+    const watch = (p) => {
+        watched.add(p);
+        p.on('domcontentloaded', onLoaded);
+    };
+    context.on('page', watch);
+    for (const p of context.pages())
+        watch(p);
+}
 /** How long another worker may hold the refresh lock before we treat it as crashed. */
 const LOCK_STALE_MS = 90_000;
 const LOCK_POLL_MS = 250;
@@ -142,11 +213,7 @@ export class AuthStateCache {
         for (const origin of state.origins ?? []) {
             if (!origin.localStorage?.length)
                 continue;
-            await page.goto(origin.origin, { waitUntil: 'domcontentloaded' }).catch(() => undefined);
-            await page.evaluate((items) => {
-                for (const { name, value } of items)
-                    window.localStorage.setItem(name, value);
-            }, origin.localStorage);
+            await plantLocalStorage(context, page, origin.origin, origin.localStorage);
         }
         return true;
     }

package/dist/fixtures/test.js

@@ -3,7 +3,7 @@ import { test as base, createBdd } from 'playwright-bdd';
 import { ProjectRegistry } from '../config/registry.js';
 import { parseTagValue, scenarioSkipReason } from '../config/tags.js';
 import { noopAuth } from '../auth/index.js';
-import { ApiClient } from '../api/client.js';
+import { ApiClient, isolatedRequestFactory } from '../api/client.js';
 import { CompositeDataProvider } from '../data/provider.js';
 import { FileUserPool } from '../data/user-pool.js';
 import { apiHarForScenario } from '../har/hooks.js';
@@ -151,9 +151,15 @@ export const test = base.extend({
     apiContext: async ({}, use) => {
         await use(new ApiContext());
     },
-    api: async ({ request, config, apiContext, scenario, harMode, $bddContext, $tags }, use, testInfo) => {
+    // `request` is Playwright's shared APIRequestContext. It is seeded from the test's context
+    // options, so on @ui/@hybrid it carries the leased role's storageState cookies (plus any cookie
+    // a response sets); on @api storageState is undefined and it starts empty. The isolated context
+    // behind `I use an isolated API client` is only created when a scenario asks for it.
+    api: async ({ request, playwright, config, apiContext, scenario, harMode, $bddContext, $tags }, use, testInfo) => {
+        const isolated = isolatedRequestFactory(playwright.request);
         await use(new ApiClient({
             request,
+            isolatedRequest: isolated.get,
             config,
             ctx: apiContext,
             testInfo,
@@ -161,6 +167,7 @@ export const test = base.extend({
             stepIndex: () => $bddContext.stepIndex,
             har: apiHarForScenario({ $tags, config, harMode }),
         }));
+        await isolated.dispose();
     },
     data: async ({ config, scenario, apiContext }, use, testInfo) => {
         const provider = new CompositeDataProvider(config, { seed: scenario.fingerprint });

package/dist/heal/healer.d.ts

@@ -46,11 +46,22 @@ export declare class Healer {
     select(primary: Locator, ctx: HealContext, value: string): Promise<void>;
     expectVisible(primary: Locator, ctx: HealContext): Promise<void>;
     expectText(primary: Locator, ctx: HealContext, text: string | RegExp): Promise<void>;
+    /**
+     * The first of `locators`, in preference order, that matches anything. Waits up to
+     * primaryTimeoutMs for the LAST one to attach — callers list the loosest locator last, a
+     * superset of the others — so an element that renders a moment late is still judged by the
+     * most precise locator. When nothing matches, the most precise one is returned for resolve()
+     * to wait on and heal from.
+     */
+    prefer(...locators: [Locator, ...Locator[]]): Promise<Locator>;
     /**
      * Wait briefly for the primary locator; on failure probe all candidates in parallel,
-     * score them and pick the best above minScore. Records a HealEvent either way.
+     * score them and pick the best above minScore. A primary that is visible but matches several
+     * elements is healed too, for actions that have a role to prefer. Records a HealEvent whenever
+     * it heals.
      */
     resolve(primary: Locator, ctx: HealContext, action: HealAction): Promise<Locator>;
+    private heal;
     private probe;
     private record;
 }