@specific.dev/spectest 0.118.0 → 0.119.0

package/dist/browser.d.ts

@@ -65,7 +65,7 @@ export interface BrowserSessionStep {
     /** rrweb events as emitted by `rrweb.record`'s `emit` callback. */
     events: unknown[];
 }
-import type { BrowserAction } from "./recorder.js";
+import type { BrowserAction, RecordedBrowserLocatorPart } from "./recorder.js";
 export type { BrowserAction } from "./recorder.js";
 /** Sink the daemon passes in to collect per-session rrweb event chunks. */
 export interface BrowserSessionRecorder {
@@ -363,6 +363,8 @@ export declare function acquirePersistentDesktop(endpoint: string, windowIndex:
     desktopChrome?: DesktopChrome;
 }>;
 export interface RecordableFields {
+    target: RecordedBrowserLocatorPart[];
+    destinationTarget: RecordedBrowserLocatorPart[];
     url: string;
     selector: string;
     description: string;
@@ -381,4 +383,11 @@ export interface RecordableFields {
     attribute: string;
     files: string[];
     targetNodeId: number;
+    checked: boolean;
+    values: string | string[] | {
+        label?: string;
+        value?: string;
+        index?: number;
+    };
+    state: string;
 }

package/dist/browser.js

@@ -1449,7 +1449,7 @@ function buildBackend(holder, recorder, buildOpts) {
         insertText(text) {
             // insertText path (no per-char keydown) — the paste path.
             const t = truncateUtf8(text);
-            return instrumented("type", { text: t.value, textTruncated: t.truncated }, () => holder.page.keyboard.insertText(text));
+            return instrumented("insertText", { text: t.value, textTruncated: t.truncated }, () => holder.page.keyboard.insertText(text));
         },
     };
     const mouse = {

package/dist/harness/network.d.ts

@@ -0,0 +1,18 @@
+export interface NetworkBinding {
+    instanceId: string;
+    token: string;
+}
+type Handler = (params: Record<string, unknown>) => Promise<unknown>;
+export declare function serveNetwork(registry: Record<string, Handler>, options: {
+    bindingPath: string;
+    hostname?: string;
+    port?: number;
+    resolverPath?: string;
+    resultLimits?: {
+        count?: number;
+        bytes?: number;
+        ttlMs?: number;
+    };
+    dispatch?: (method: string, params: Record<string, unknown>, timeoutMs?: number) => Promise<unknown>;
+}): Bun.Server<undefined>;
+export {};

package/dist/harness/network.js

@@ -0,0 +1,194 @@
+/** Experimental cloud transport. No VM agent or control-plane credential lives here.
+ * Read the binding on every request: checkpoint children inherit the process heap,
+ * but receive a new binding file before the controller dispatches work to them.
+ * Future guest-initiated forks must perform the same rebind before accepting work.
+ */
+import { readFileSync, writeFileSync } from "node:fs";
+import { timingSafeEqual } from "node:crypto";
+import { codeOf } from "./methods";
+import { describeThrow } from "./protocol";
+export function serveNetwork(registry, options) {
+    let session = "";
+    const seen = new Set();
+    let active = 0;
+    const results = new Map();
+    const maxResults = options.resultLimits?.count ?? 128;
+    const maxBytes = options.resultLimits?.bytes ?? 64 * 1024 * 1024;
+    const ttlMs = options.resultLimits?.ttlMs ?? 10 * 60_000;
+    let resultBytes = 0;
+    const forget = (id) => {
+        resultBytes -= results.get(id)?.bytes ?? 0;
+        results.delete(id);
+    };
+    const expire = () => {
+        for (const [id, result] of results)
+            if (result.completedAt !== undefined && Date.now() - result.completedAt >= ttlMs)
+                forget(id);
+    };
+    const reply = (body, status = 200) => Response.json(body, {
+        status, headers: { "Cache-Control": "no-store" },
+    });
+    return Bun.serve({
+        hostname: options.hostname ?? "0.0.0.0",
+        port: options.port ?? 4318,
+        maxRequestBodySize: 16 * 1024 * 1024,
+        async fetch(req, server) {
+            const url = new URL(req.url);
+            if (url.pathname !== "/rpc" || !["POST", "GET", "DELETE"].includes(req.method))
+                return reply({ error: "not_found" }, 404);
+            let binding;
+            try {
+                binding = JSON.parse(readFileSync(options.bindingPath, "utf8"));
+                if (!binding.instanceId || !binding.token || binding.token.length < 32)
+                    throw Error();
+            }
+            catch {
+                return reply({ error: "unbound" }, 503);
+            }
+            const supplied = Buffer.from(req.headers.get("X-Spectest-Harness-Authorization") ?? req.headers.get("Authorization") ?? "");
+            const expected = Buffer.from(`Bearer ${binding.token}`);
+            if (supplied.length !== expected.length || !timingSafeEqual(supplied, expected))
+                return reply({ error: "unauthorized" }, 401);
+            if (req.headers.get("X-Spectest-Instance") !== binding.instanceId)
+                return reply({ error: "wrong_instance" }, 409);
+            // Neither parent request IDs nor network connections are child identity.
+            const nextSession = `${binding.instanceId}:${binding.token}`;
+            if (session !== nextSession) {
+                if (active)
+                    return reply({ error: "restore_during_request" }, 409);
+                session = nextSession;
+                seen.clear();
+                results.clear();
+                resultBytes = 0;
+            }
+            expire();
+            if (req.method !== "POST") {
+                const requestId = url.searchParams.get("requestId");
+                const envelope = { instanceId: binding.instanceId, requestId };
+                const result = requestId ? results.get(requestId) : undefined;
+                if (!result)
+                    return reply({ ...envelope, error: "result_not_found" }, 404);
+                if (req.method === "GET") {
+                    const waitMs = Number(url.searchParams.get("waitMs") ?? 0);
+                    if (!Number.isSafeInteger(waitMs) || waitMs < 0 || waitMs > 25_000)
+                        return reply({ ...envelope, error: "invalid_wait" }, 400);
+                    if (result.body === undefined && waitMs > 0 && !req.signal.aborted) {
+                        server.timeout(req, 0);
+                        // Disconnecting a waiter never cancels the operation. Remove its
+                        // listener on every exit, including aborts and bounded timeouts.
+                        await new Promise(resolve => {
+                            const done = () => {
+                                clearTimeout(timer);
+                                result.waiters.delete(done);
+                                req.signal.removeEventListener("abort", done);
+                                resolve();
+                            };
+                            const timer = setTimeout(done, waitMs);
+                            result.waiters.add(done);
+                            req.signal.addEventListener("abort", done, { once: true });
+                            if (req.signal.aborted)
+                                done();
+                        });
+                        // A restored heap or a concurrent acknowledgement must not expose
+                        // a stale result to a connection admitted under the old identity.
+                        try {
+                            const current = JSON.parse(readFileSync(options.bindingPath, "utf8"));
+                            if (current.instanceId !== binding.instanceId || current.token !== binding.token)
+                                return reply({ ...envelope, error: "stale_binding" }, 409);
+                        }
+                        catch {
+                            return reply({ ...envelope, error: "unbound" }, 503);
+                        }
+                        if (results.get(requestId) !== result)
+                            return reply({ ...envelope, error: "result_not_found" }, 404);
+                    }
+                }
+                if (result.body === undefined)
+                    return reply({ ...envelope, state: "pending", resultWait: true }, 202);
+                if (req.method === "DELETE") {
+                    forget(requestId);
+                    return reply({ ...envelope, state: "acknowledged" });
+                }
+                return new Response(result.body, { status: result.status,
+                    headers: { "Content-Type": "application/json", "Cache-Control": "no-store" } });
+            }
+            let body;
+            try {
+                body = await req.json();
+                if (!body || typeof body.requestId !== "string" || body.requestId.length > 100 ||
+                    !body.requestId || typeof body.method !== "string" ||
+                    (body.async !== undefined && typeof body.async !== "boolean") ||
+                    (body.timeoutMs !== undefined && (!Number.isSafeInteger(body.timeoutMs) || body.timeoutMs <= 0)) ||
+                    (body.params !== undefined && (!body.params || typeof body.params !== "object" || Array.isArray(body.params))))
+                    throw Error();
+            }
+            catch {
+                return reply({ error: "invalid_request" }, 400);
+            }
+            // A request body may have been in flight across a restore/rebind.
+            try {
+                const current = JSON.parse(readFileSync(options.bindingPath, "utf8"));
+                if (current.instanceId !== binding.instanceId || current.token !== binding.token)
+                    return reply({ error: "stale_binding" }, 409);
+            }
+            catch {
+                return reply({ error: "unbound" }, 503);
+            }
+            const envelope = { instanceId: binding.instanceId, requestId: body.requestId };
+            if (seen.has(body.requestId))
+                return reply({ ...envelope, error: "duplicate_request" }, 409);
+            const handler = Object.hasOwn(registry, body.method) ? registry[body.method]
+                : options.dispatch ? (params) => options.dispatch(body.method, params, body.timeoutMs) : undefined;
+            if (!handler)
+                return reply({ ...envelope, error: "unimplemented" }, 400);
+            if (active >= 32)
+                return reply({ ...envelope, error: "too_many_requests" }, 429);
+            if (body.async && results.size >= maxResults)
+                return reply({ ...envelope, error: "result_capacity" }, 429);
+            seen.add(body.requestId);
+            if (seen.size > 4096)
+                seen.delete(seen.values().next().value);
+            // Long test calls are bounded by the caller and runner, not the HTTP idle timer.
+            server.timeout(req, 0);
+            active++;
+            const execute = async () => {
+                try {
+                    // Unikraft rewrites the resolver on checkpoint restore AND native wake.
+                    if (options.resolverPath) {
+                        const resolver = "nameserver 127.0.0.53\noptions edns0\n";
+                        if (readFileSync(options.resolverPath, "utf8") !== resolver)
+                            writeFileSync(options.resolverPath, resolver);
+                    }
+                    return { body: JSON.stringify({ ...envelope, result: await handler(body.params ?? {}) }), status: 200 };
+                }
+                catch (error) {
+                    return { body: JSON.stringify({ ...envelope, error: codeOf(error), message: describeThrow(error) }), status: 400 };
+                }
+                finally {
+                    active--;
+                }
+            };
+            if (body.async) {
+                const result = { bytes: 0, waiters: new Set() };
+                results.set(body.requestId, result);
+                // Retain work and its outcome independently of any one HTTP connection.
+                void execute().then(completed => {
+                    let bytes = Buffer.byteLength(completed.body);
+                    if (resultBytes + bytes > maxBytes) {
+                        completed = { body: JSON.stringify({ ...envelope, error: "result_too_large",
+                                message: "Harness result storage limit exceeded; work must not be replayed" }), status: 507 };
+                        bytes = Buffer.byteLength(completed.body);
+                    }
+                    Object.assign(result, completed, { bytes, completedAt: Date.now() });
+                    resultBytes += bytes;
+                    for (const done of result.waiters)
+                        done();
+                });
+                return reply({ ...envelope, state: "pending", resultWait: true }, 202);
+            }
+            const completed = await execute();
+            return new Response(completed.body, { status: completed.status,
+                headers: { "Content-Type": "application/json", "Cache-Control": "no-store" } });
+        },
+    });
+}

package/dist/locator.js

@@ -51,6 +51,24 @@ export function isLocator(x) {
 function chainOf(loc) {
     return loc[CHAIN];
 }
+/** Keep locator structure (including regex flags and nested filters) in the
+ * event. The old selector field remains for classic/CLI compatibility. */
+function recordedChain(chain) {
+    const argument = (v) => {
+        if (v instanceof RegExp)
+            return { regex: v.source, flags: v.flags };
+        if (isLocator(v))
+            return recordedChain(chainOf(v));
+        if (Array.isArray(v))
+            return v.map(argument);
+        if (v && typeof v === "object") {
+            return Object.fromEntries(Object.entries(v).filter(([, value]) => value !== undefined)
+                .map(([key, value]) => [key, argument(value)]));
+        }
+        return v;
+    };
+    return chain.steps.map(({ m, args }) => ({ method: m, args: args.map(argument) }));
+}
 // ────────────────────────────────────────────────────────────────────────
 // Lowering: chain → live playwright Locator
 // ────────────────────────────────────────────────────────────────────────
@@ -327,8 +345,8 @@ async function stampActionPoint(loc, rec, position) {
         /* Element not ready / gone / strict violation — the action reports it. */
     }
 }
-/** Stamp the rrweb node id of the element a settled `expect(locator)` step is
- *  about, so the dashboard can bring it into the replay's view.
+/** Stamp the rrweb node id of a locator operation's target, so the dashboard
+ *  can highlight it and bring it into the replay's view.
  *
  *  Playwright's idea of "visible" is a non-empty box that isn't hidden — it
  *  says nothing about the viewport, so an element below the fold passes
@@ -346,9 +364,11 @@ async function stampActionPoint(loc, rec, position) {
  *  leaves the step unstamped, which just means the viewer doesn't scroll. */
 async function stampRevealTarget(loc, rec) {
     try {
-        const id = await loc.evaluate((el) => {
-            if (window.top !== window)
+        const id = await loc.evaluateAll((elements) => {
+            // Never wait for a missing element or pick an arbitrary list match.
+            if (elements.length !== 1 || window.top !== window)
                 return 0;
+            const el = elements[0];
             // The bootstrap stashes rrweb's `record` here; `mirror` is its
             // node ↔ id map, shared by every snapshot it takes (see browser.ts).
             const w = window;
@@ -357,7 +377,7 @@ async function stampRevealTarget(loc, rec) {
                 return 0;
             const id = getId.call(w.__spectestRec.mirror, el);
             return typeof id === "number" && id > 0 ? id : 0;
-        }, undefined, { timeout: POINT_PROBE_MS });
+        });
         if (id)
             rec.targetNodeId = id;
     }
@@ -395,6 +415,7 @@ function lowerInputFiles(files) {
  *  through `backend.pageOp`. */
 export function makeLocator(backend, strategy, chain) {
     const label = chainLabel(chain);
+    const target = recordedChain(chain);
     const extend = (step) => makeLocator(backend, strategy, { steps: [...chain.steps, step] });
     /** The "did you mean…" block for a locator that matched nothing. Empty
      *  for a chain that must not suggest (see {@link hintTargetFromChain}) and
@@ -419,18 +440,42 @@ export function makeLocator(backend, strategy, chain) {
             throw await rewriteLocatorErrorWithHints(err, label, () => hintBlock(page));
         }
     };
+    // Capture identity before mutations (e.g. a press that removes its target).
+    // If an action auto-waits for an element that is not present yet, capture it
+    // afterwards instead. Both probes are immediate and best-effort; annotation
+    // must not change action errors, return values or locator strictness.
+    const withTarget = async (page, action, rec, fn) => {
+        const lowered = lower(page, chain);
+        const singleTarget = !["count", "all", "allTextContents", "allInnerTexts"].includes(action)
+            && !(action === "waitFor" && (rec.state === "hidden" || rec.state === "detached"));
+        if (singleTarget)
+            await stampRevealTarget(lowered, rec);
+        try {
+            return await fn(lowered, page);
+        }
+        finally {
+            if (singleTarget && !rec.targetNodeId)
+                await stampRevealTarget(lowered, rec);
+        }
+    };
     // One recorded event, result NOT wrapped (void/action).
-    const act = (action, fields, fn) => backend.pageOp(action, { selector: label, ...fields }, (page) => readable(page, () => fn(lower(page, chain), page)));
+    const act = (action, fields, fn) => {
+        const rec = { selector: label, target, ...fields };
+        return backend.pageOp(action, rec, (page) => readable(page, () => withTarget(page, action, rec, fn)));
+    };
     // One recorded event whose fields the action itself finishes filling in:
     // `rec` is the very object the recorder spreads once `fn` resolves (the
     // same mutate-in-flight seam `screenshot`'s artifact id rides), so the
     // click family can stamp the point it acted on. See stampActionPoint.
     const actAt = (action, fn) => {
-        const rec = { selector: label };
+        const rec = { selector: label, target };
         return backend.pageOp(action, rec, (page) => readable(page, () => fn(lower(page, chain), rec)));
     };
     // One recorded event, result provenance-wrapped for expect().
-    const read = (action, fn, fields = {}) => backend.pageOp(action, { selector: label, ...fields }, (page) => readable(page, () => fn(lower(page, chain))), { wrap: true });
+    const read = (action, fn, fields = {}) => {
+        const rec = { selector: label, target, ...fields };
+        return backend.pageOp(action, rec, (page) => readable(page, () => withTarget(page, action, rec, fn)), { wrap: true });
+    };
     // Silent, non-recorded reads for expect(locator) matchers to poll.
     const probe = {
         label,
@@ -445,7 +490,7 @@ export function makeLocator(backend, strategy, chain) {
         isEnabled: (timeout) => backend.silentRead((page) => lower(page, chain).isEnabled({ timeout })),
         isChecked: (timeout) => backend.silentRead((page) => lower(page, chain).isChecked({ timeout })),
         settle: async (action, waitedMs, error, opts) => {
-            const fields = { selector: label };
+            const fields = { selector: label, target };
             if (opts && opts.reveal) {
                 await backend.silentRead((page) => stampRevealTarget(lower(page, chain), fields));
             }
@@ -492,8 +537,8 @@ export function makeLocator(backend, strategy, chain) {
         },
         check: (opts) => act("check", {}, (l) => l.check({ timeout: opts?.timeout })),
         uncheck: (opts) => act("uncheck", {}, (l) => l.uncheck({ timeout: opts?.timeout })),
-        setChecked: (checked, opts) => act("setChecked", {}, (l) => l.setChecked(checked, { timeout: opts?.timeout })),
-        selectOption: (values, opts) => read("selectOption", (l) => l.selectOption(values, { timeout: opts?.timeout })),
+        setChecked: (checked, opts) => act("setChecked", { checked }, (l) => l.setChecked(checked, { timeout: opts?.timeout })),
+        selectOption: (values, opts) => read("selectOption", (l) => l.selectOption(values, { timeout: opts?.timeout }), { values }),
         setInputFiles: (files, opts) => {
             const { arg, names } = lowerInputFiles(files);
             return act("setInputFiles", { files: names }, (l) => l.setInputFiles(arg, { timeout: opts?.timeout }));
@@ -502,7 +547,7 @@ export function makeLocator(backend, strategy, chain) {
         focus: (opts) => act("focus", {}, (l) => l.focus({ timeout: opts?.timeout })),
         blur: (opts) => act("blur", {}, (l) => l.blur({ timeout: opts?.timeout })),
         scrollIntoViewIfNeeded: (opts) => act("scrollIntoViewIfNeeded", {}, (l) => l.scrollIntoViewIfNeeded({ timeout: opts?.timeout })),
-        dragTo: (target, opts) => act("dragTo", {}, (l, page) => l.dragTo(lower(page, chainOf(target)), { timeout: opts?.timeout })),
+        dragTo: (target, opts) => act("dragTo", { destinationTarget: recordedChain(chainOf(target)) }, (l, page) => l.dragTo(lower(page, chainOf(target)), { timeout: opts?.timeout })),
         // reads
         textContent: (opts) => read("textContent", (l) => l.textContent({ timeout: opts?.timeout })),
         innerText: (opts) => read("innerText", (l) => l.innerText({ timeout: opts?.timeout })),
@@ -530,8 +575,13 @@ export function makeLocator(backend, strategy, chain) {
                 out.push(extend({ m: "nth", args: [i] }));
             return out;
         },
-        evaluate: (description, fn, arg) => backend.pageOp("evaluate", { selector: label, description }, (page) => readable(page, () => lower(page, chain).evaluate(fn, arg)), { wrap: true }),
-        waitFor: (opts) => act("waitFor", {}, (l) => l.waitFor({ state: opts?.state, timeout: opts?.timeout })),
+        evaluate: (description, fn, arg) => {
+            const script = truncateUtf8(fn.toString());
+            return read("evaluate", (l) => l.evaluate(fn, arg), {
+                description, script: script.value, scriptTruncated: script.truncated,
+            });
+        },
+        waitFor: (opts) => act("waitFor", { state: opts?.state ?? "visible" }, (l) => l.waitFor({ state: opts?.state, timeout: opts?.timeout })),
     };
     // Attach the silent-read probe under its symbol (kept off the typed literal
     // so declaration order stays simple).

package/dist/recorder.d.ts

@@ -399,9 +399,17 @@ export interface EnvEvent extends BaseEvent {
     error?: string;
 }
 export type BrowserAction = string;
+/** JSON-safe locator syntax. Regexes use {regex, flags}, nested locators
+ * use another chain. Presentation is determined by the dashboard. */
+export interface RecordedBrowserLocatorPart {
+    method: string;
+    args: unknown[];
+}
 export interface BrowserEvent extends BaseEvent {
     kind: "browser";
     action: BrowserAction;
+    target?: RecordedBrowserLocatorPart[];
+    destinationTarget?: RecordedBrowserLocatorPart[];
     /** Target URL (navigate). */
     url?: string;
     /** CSS selector (click, scrollTo). */
@@ -421,6 +429,14 @@ export interface BrowserEvent extends BaseEvent {
     /** File names given to an `<input type="file">` (setInputFiles). Names
      *  only — a built file's bytes stay out of the timeline. */
     files?: string[];
+    /** Arguments used by the dashboard to describe the operation completely. */
+    checked?: boolean;
+    values?: string | string[] | {
+        label?: string;
+        value?: string;
+        index?: number;
+    };
+    state?: string;
     /** Scroll/click coordinates. */
     dx?: number;
     dy?: number;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@specific.dev/spectest",
-  "version": "0.118.0",
+  "version": "0.119.0",
   "description": "Spectest SDK for defining test environments in TypeScript.",
   "type": "module",
   "main": "./dist/index.js",

package/src/browser.ts

@@ -148,7 +148,7 @@ export interface BrowserSessionStep {
 
 // The set of actions that show up in the test event log. The session
 // step type extends this with "close" for the final drain.
-import type { BrowserAction } from "./recorder.js";
+import type { BrowserAction, RecordedBrowserLocatorPart } from "./recorder.js";
 export type { BrowserAction } from "./recorder.js";
 
 /** Sink the daemon passes in to collect per-session rrweb event chunks. */
@@ -1949,7 +1949,7 @@ function buildBackend(
     insertText(text) {
       // insertText path (no per-char keydown) — the paste path.
       const t = truncateUtf8(text);
-      return instrumented("type", { text: t.value, textTruncated: t.truncated }, () =>
+      return instrumented("insertText", { text: t.value, textTruncated: t.truncated }, () =>
         holder.page.keyboard.insertText(text),
       );
     },
@@ -2323,6 +2323,8 @@ function buildBackend(
 }
 
 export interface RecordableFields {
+  target: RecordedBrowserLocatorPart[];
+  destinationTarget: RecordedBrowserLocatorPart[];
   url: string;
   selector: string;
   description: string;
@@ -2341,4 +2343,7 @@ export interface RecordableFields {
   attribute: string;
   files: string[];
   targetNodeId: number;
+  checked: boolean;
+  values: string | string[] | { label?: string; value?: string; index?: number };
+  state: string;
 }