@specific.dev/spectest 0.131.21 → 0.132.2

package/dist/browser-coverage.d.ts

@@ -19,6 +19,9 @@ export declare function attachBrowserCoverage(cdp: CDPSession): Promise<void>;
 export declare function harvestBrowserCoverage(cdp: CDPSession, signal?: AbortSignal): Promise<void>;
 /** Fold one script's per-file counts into a service's totals. */
 export declare function foldBrowserCoverage(service: string, files: FileCounts): void;
+/** Called only after harvesting a page that the SDK is about to destroy.
+ * Keep failed collectors visible so closing a page cannot erase a gap. */
+export declare function releaseBrowserCoverage(cdp: CDPSession): void;
 /** Harvest every live session, so a capture sees the counters of code
  *  that ran since the last browser op. */
 export declare function harvestAllBrowserCoverage(signal?: AbortSignal): Promise<void>;

package/dist/browser-coverage.js

@@ -32,10 +32,11 @@ export function browserCoverageActive() {
 /** service → file → line → count, summed over every harvest. */
 const TOTALS = new Map();
 const COLLECTORS = new WeakMap();
-/** The collectors of every session attached so far, for the harvest at
- *  capture; a closed session's take fails and is dropped there. */
+/** Collectors awaiting service capture. Explicit close releases a completed
+ * collector; unexpected disconnects remain coverage failures. */
 const LIVE_COLLECTORS = new Set();
-/** Decoded maps by URL (or content hash for inline `data:` maps). */
+/** Inline maps are immutable and cached by content hash. External maps are
+ * cached only on ScriptInfo: a restarted server may reuse their URLs. */
 const SOURCE_MAPS = new Map();
 const SOURCE_MAP_FETCH_TIMEOUT_MS = 10_000;
 /** Turn coverage on for a page's CDP session. Idempotent; a no-op when no
@@ -43,18 +44,27 @@ const SOURCE_MAP_FETCH_TIMEOUT_MS = 10_000;
 export async function attachBrowserCoverage(cdp) {
     if (!CONFIG || COLLECTORS.has(cdp))
         return;
-    const collector = { cdp, scripts: new Map(), inFlight: null };
+    const collector = { cdp, document: { scripts: new Map() }, inFlight: null };
     COLLECTORS.set(cdp, collector);
     LIVE_COLLECTORS.add(collector);
+    cdp.on("Runtime.executionContextsCleared", () => {
+        // A document change may or may not replace the renderer. Buffer its
+        // metadata separately until getIsolateId identifies the new namespace.
+        collector.document = { scripts: new Map() };
+    });
     cdp.on("Debugger.scriptParsed", (ev) => {
-        // IDs belong to a renderer, not the lifetime of this CDP session. A
-        // cross-site navigation can reuse an old named ID for anonymous code.
-        // Replace anonymous entries too, invalidating the previous URL/source/map.
-        collector.scripts.set(ev.scriptId, {
+        const info = {
             url: ev.url,
+            hash: ev.hash,
+            executionContextId: ev.executionContextId,
             sourceMapURL: ev.sourceMapURL || undefined,
-        });
+        };
+        const document = collector.document;
+        setScript(document.scripts, ev.scriptId, info);
+        if (document.renderer)
+            setScript(document.renderer.scripts, ev.scriptId, info);
     });
+    await cdp.send("Runtime.enable");
     await cdp.send("Debugger.enable");
     await cdp.send("Profiler.enable");
     await cdp.send("Profiler.startPreciseCoverage", { callCount: true, detailed: true });
@@ -84,10 +94,10 @@ export async function harvestBrowserCoverage(cdp, signal) {
                 reject(c.incomplete);
             }, { once: true });
         });
-        c.inFlight = Promise.race([harvestInner(c, config, abort.signal), interrupted]).catch(() => {
-            if (c.incomplete)
-                throw c.incomplete;
-            // Preserve the existing handling of closed/navigating pages.
+        c.inFlight = Promise.race([harvestInner(c, config, abort.signal), interrupted]).catch((cause) => {
+            // A failed protocol command can leave reset or unavailable counters.
+            // Expected page closure explicitly releases its collector beforehand.
+            throw c.incomplete ??= new Error("Browser coverage collection failed; coverage is incomplete", { cause });
         }).finally(() => {
             c.inFlight = null;
             c.abort = undefined;
@@ -108,18 +118,59 @@ export async function harvestBrowserCoverage(cdp, signal) {
         signal?.removeEventListener("abort", interrupt);
     }
 }
+/** Replayed Debugger events for the same script do not invalidate a source
+ * read. A matching URL alone is insufficient: recompilations may reuse it. */
+function setScript(scripts, id, info) {
+    const before = scripts.get(id);
+    if (before && info.hash && before.hash === info.hash &&
+        before.executionContextId === info.executionContextId &&
+        before.url === info.url && before.sourceMapURL === info.sourceMapURL)
+        return;
+    scripts.set(id, info);
+}
+function identityChanged(c) {
+    return c.incomplete ??= new Error("Browser script identity changed during coverage capture; coverage is incomplete");
+}
+/** Resolve the current document's script IDs against V8's renderer identity.
+ * Numeric context IDs and script IDs are both reused across renderer swaps. */
+async function currentRenderer(c, signal) {
+    for (;;) {
+        const document = c.document;
+        const { id } = await c.cdp.send("Runtime.getIsolateId");
+        signal.throwIfAborted();
+        // Navigation overlapped this non-destructive query. Retry before taking
+        // counters; no coverage has been reset yet.
+        if (document !== c.document)
+            continue;
+        if (!id)
+            throw identityChanged(c);
+        if (c.renderer?.isolateId !== id)
+            c.renderer = { isolateId: id, scripts: new Map() };
+        const renderer = c.renderer;
+        if (!document.renderer) {
+            for (const [scriptId, info] of document.scripts)
+                setScript(renderer.scripts, scriptId, info);
+            document.renderer = renderer;
+        }
+        return renderer;
+    }
+}
 async function harvestInner(c, config, signal) {
-    const scriptsAtTake = new Map(c.scripts);
+    const renderer = await currentRenderer(c, signal);
+    const scriptsAtTake = new Map(renderer.scripts);
     let result;
     try {
         ({ result } = (await c.cdp.send("Profiler.takePreciseCoverage")));
         signal.throwIfAborted();
     }
-    catch (err) {
-        if (!signal.aborted)
-            LIVE_COLLECTORS.delete(c); // the session is gone
-        throw err;
+    catch (cause) {
+        signal.throwIfAborted();
+        throw c.incomplete ??= new Error("Browser coverage take failed; coverage is incomplete", { cause });
     }
+    // A take is destructive. Once sent, crossing a renderer boundary is
+    // ambiguous and must remain incomplete rather than retrying the take.
+    if (await currentRenderer(c, signal) !== renderer)
+        throw identityChanged(c);
     for (const script of result) {
         // The profiler's URL identifies this execution. Never supply a URL from
         // an earlier renderer to an anonymous result.
@@ -137,17 +188,14 @@ async function harvestInner(c, config, signal) {
         const service = config.serviceForHost(url.hostname);
         if (!service)
             continue;
-        let info = c.scripts.get(script.scriptId);
+        let info = renderer.scripts.get(script.scriptId);
         const before = scriptsAtTake.get(script.scriptId);
-        const changed = () => {
-            c.incomplete = new Error("Browser script identity changed during coverage capture; coverage is incomplete");
-            return c.incomplete;
-        };
+        const changed = () => identityChanged(c);
         if ((before && before !== info) || (info && info.url !== script.url))
             throw changed();
         if (!info) {
             info = { url: script.url };
-            c.scripts.set(script.scriptId, info);
+            renderer.scripts.set(script.scriptId, info);
         }
         if (info.source === undefined) {
             try {
@@ -155,15 +203,17 @@ async function harvestInner(c, config, signal) {
                     scriptId: script.scriptId,
                 }));
                 signal.throwIfAborted();
-                if (c.scripts.get(script.scriptId) !== info)
+                if (await currentRenderer(c, signal) !== renderer || renderer.scripts.get(script.scriptId) !== info)
                     throw changed();
                 info.source = r.scriptSource;
             }
-            catch {
+            catch (cause) {
                 signal.throwIfAborted();
                 if (c.incomplete)
                     throw c.incomplete;
-                continue; // script gone with its document
+                // An executed covered script whose source was lost cannot yield a
+                // trustworthy report. Keep the failure for service capture.
+                throw c.incomplete = new Error("Browser script source unavailable; coverage is incomplete", { cause });
             }
         }
         const generated = rangesToLineCounts(info.source, script.functions);
@@ -215,9 +265,6 @@ async function sourceMapFor(info, scriptUrl) {
     catch {
         return null;
     }
-    const cached = SOURCE_MAPS.get(mapUrl);
-    if (cached !== undefined)
-        return cached;
     let map = null;
     try {
         const res = await rawFetch(mapUrl, { signal: AbortSignal.timeout(SOURCE_MAP_FETCH_TIMEOUT_MS) });
@@ -227,7 +274,6 @@ async function sourceMapFor(info, scriptUrl) {
     catch {
         map = null;
     }
-    SOURCE_MAPS.set(mapUrl, map);
     return map;
 }
 function parseDataUrl(ref) {
@@ -246,6 +292,13 @@ function parseDataUrl(ref) {
         return null;
     }
 }
+/** Called only after harvesting a page that the SDK is about to destroy.
+ * Keep failed collectors visible so closing a page cannot erase a gap. */
+export function releaseBrowserCoverage(cdp) {
+    const collector = COLLECTORS.get(cdp);
+    if (collector && !collector.incomplete && !collector.inFlight)
+        LIVE_COLLECTORS.delete(collector);
+}
 /** Harvest every live session, so a capture sees the counters of code
  *  that ran since the last browser op. */
 export async function harvestAllBrowserCoverage(signal) {

package/dist/browser.d.ts

@@ -149,6 +149,10 @@ export interface Browser {
     goForward(options?: NavigationOptions): Promise<void>;
     /** Reload the current page. */
     reload(options?: NavigationOptions): Promise<void>;
+    /** Read native clipboard text from an isolated observer in the same browser.
+     * Requires a secure page and honors its clipboard Permissions-Policy.
+     * Leaves application permissions unchanged and links assertions to the read. */
+    readClipboard(): Promise<Wrapped<string>>;
     readonly keyboard: Keyboard;
     readonly mouse: Mouse;
     /** Root CSS query. */

package/dist/browser.js

@@ -1,5 +1,5 @@
 // Headless browser handle for tests. Thin wrapper around playwright-core
-// driving the guest's Headless Shell (pipe transport — `chromium.launch`
+// driving the guest's full Chromium (pipe transport — `chromium.launch`
 // with an explicit `executablePath`). Electron attaches to the app-owned
 // Chromium over CDP instead; its client also lives inside the VM. The wrapper
 // keeps the public surface stable (we swapped from Bun.WebView to Playwright without
@@ -40,7 +40,7 @@ import { recordBrowser, reserveBackdated, reserveEvent, truncateUtf8 } from "./r
 import { wrap } from "./inspect.js";
 import { capturePageStructure } from "./page-snapshot.js";
 import { describeUrlPattern, matchesUrl } from "./url-match.js";
-import { attachBrowserCoverage, browserCoverageActive, harvestBrowserCoverage, } from "./browser-coverage.js";
+import { attachBrowserCoverage, browserCoverageActive, harvestBrowserCoverage, releaseBrowserCoverage, } from "./browser-coverage.js";
 import { attachBrowserProbe, DEFAULT_ACTION_TIMEOUT_MS, desktopStrategy, makeLocator, mobileStrategy, } from "./locator.js";
 import { chromium } from "playwright-core";
 import { reduceBrowserSurfaces, awaitBrowserSurface, captureBrowserScreenshot } from "./browser-surface.js";
@@ -109,7 +109,7 @@ const NAVIGATION_TIMEOUT_MS = 30_000;
 // ────────────────────────────────────────────────────────────────────────
 // Shared Chromium (playwright-core)
 // ────────────────────────────────────────────────────────────────────────
-// Browser and mobile sessions share one Headless Shell per daemon, launched lazily and kept
+// Browser and mobile sessions share one full Chromium per daemon, launched lazily and kept
 // for the daemon's lifetime. Fixture sessions own a process because the audio
 // source is a process-wide flag. Both ride snapshots: the process, playwright's
 // pipe connection to it, and every open page freeze into the VM snapshot
@@ -127,9 +127,10 @@ const VIEW_CLEANUPS = new WeakMap();
 // the page only — cookies survived and the next session was still
 // authenticated.
 function browserExecutable() {
-    const executable = Bun.which("chromium-headless-shell") ?? Bun.which("chrome-headless-shell");
+    const executable = Bun.which("chromium") ?? Bun.which("chromium-browser") ??
+        Bun.which("google-chrome") ?? Bun.which("chrome");
     if (!executable) {
-        throw new Error("Chromium Headless Shell is required by this SDK but is missing from the runtime image. Rebuild the environment with a current Spectest golden image; for local development, install chromium-headless-shell on PATH.");
+        throw new Error("Full Chromium is required by this SDK but is missing from the runtime image. Install chromium on PATH; Chromium Headless Shell does not provide compatible browser permissions and background services.");
     }
     return executable;
 }
@@ -166,11 +167,12 @@ function deviceContextOptions(d) {
 async function newViewContext(width, height, device, opts = {}) {
     const fixture = opts.microphone === undefined ? undefined : await prepareMicrophoneFixture(opts.microphone);
     let browser;
+    let context;
     try {
         browser = fixture ? await chromium.launch({
             executablePath: browserExecutable(), headless: true, args: [...CHROME_ARGV, fixture.arg],
         }) : await ensurePlaywrightBrowser();
-        const context = await browser.newContext({
+        context = await browser.newContext({
             ...(device
                 ? deviceContextOptions(device)
                 : {
@@ -198,6 +200,7 @@ async function newViewContext(width, height, device, opts = {}) {
         return context;
     }
     catch (err) {
+        await context?.close().catch(() => { });
         if (fixture) {
             try {
                 await browser?.close();
@@ -788,7 +791,7 @@ const PAGE_INIT_SCRIPT = RRWEB_BUNDLE
     ? `if (window === window.top) {\n${RRWEB_BUNDLE}\n;\n${RRWEB_CONSOLE_PLUGIN_BUNDLE}\n;\n${RRWEB_BOOTSTRAP}\n}`
     : "";
 // Page-side expression that atomically swaps in a fresh buffer and
-// returns the old one. Wrapped as a single expression so view.evaluate's
+// returns the old batch as JSON. Wrapped as a single expression so view.evaluate's
 // `await (...)` wrapper accepts it.
 //
 // `forceFullIfMissing` (inlined by `drainExpr`) guards a recovery path
@@ -832,9 +835,11 @@ function drainExpr(forceFullIfMissing, timestamp = Date.now()) {
     window.__spectestSyncInputs(${timestamp});
   }
   var buf = window.__spectestRrwebEvents;
-  if (!buf || !buf.length) return [];
+  if (!buf || !buf.length) return "[]";
+  // Serialize before clearing: an encoding failure must leave the batch intact.
+  var json = JSON.stringify(buf);
   window.__spectestRrwebEvents = [];
-  return buf;
+  return json;
 })()`;
 }
 // Pre-opened view pool. Renderer spawn is the expensive part of
@@ -1259,12 +1264,6 @@ async function daemonResolves(url) {
  * retry once.
  */
 async function rebuildView(holder) {
-    try {
-        await holder.page.close();
-    }
-    catch {
-        /* page may already be gone */
-    }
     // The old renderer's coverage counters die with its page; harvest what
     // it had before the swap (rebuild is triggered on a fresh navigation).
     try {
@@ -1273,6 +1272,13 @@ async function rebuildView(holder) {
     catch {
         /* best-effort */
     }
+    releaseBrowserCoverage(holder.cdp);
+    try {
+        await holder.page.close();
+    }
+    catch {
+        /* page may already be gone */
+    }
     const fresh = await spawnPage(holder.context);
     holder.page = fresh.page;
     holder.cdp = fresh.cdp;
@@ -1351,12 +1357,16 @@ function buildBackend(holder, recorder, buildOpts) {
             // Finalization only reads the buffer. A timed-out evaluation may run
             // after a child/eval attaches; it must not clear that session's events.
             const expression = action === "close"
-                ? "window.__spectestRrwebEvents || []"
+                ? "JSON.stringify(window.__spectestRrwebEvents || [])"
                 : drainExpr(urlChanged, timestamp);
-            const events = (await holder.page.evaluate(expression));
+            // Replay batches are JSON data. Returning one string avoids Playwright's
+            // recursive SerializedValue validation/copying for every event field.
+            // Keep general user evaluations on Playwright's normal value transport.
+            const encoded = await holder.page.evaluate(expression);
             signal?.throwIfAborted();
             if (recordingEnded)
                 return;
+            const events = JSON.parse(encoded);
             lastDrainUrl = holder.page.url();
             if (Array.isArray(events) && events.length > 0) {
                 recorder.recordStep({
@@ -1378,6 +1388,15 @@ function buildBackend(holder, recorder, buildOpts) {
         const t = Date.now();
         const resv = reserveEvent();
         try {
+            // Any action (including a click or evaluation) can navigate and replace
+            // the renderer. Drain its counters while it is still alive. Collection
+            // failures remain on the collector and fail coverage capture later.
+            if (browserCoverageActive()) {
+                try {
+                    await harvestBrowserCoverage(holder.cdp);
+                }
+                catch { /* retained by collector */ }
+            }
             const result = await fn();
             // Refresh the sync title cache (playwright's title() is async).
             try {
@@ -1387,7 +1406,7 @@ function buildBackend(holder, recorder, buildOpts) {
                 /* page mid-navigation or closed — keep the stale cache */
             }
             if (recordingEnded)
-                return result;
+                return opts?.wrap ? wrap(result, undefined) : result;
             // `sessionTimestamp` is the post-op wall clock — that's where we
             // want the dashboard's seek to land, so clicking "type 'foo'"
             // shows the input *with* the text, not the empty field just
@@ -1401,9 +1420,7 @@ function buildBackend(holder, recorder, buildOpts) {
                 durationMs: endT - t,
             }, resv);
             await drain(action, endT);
-            // Fold this page's V8 counters into the per-service totals now — a
-            // navigation to another origin replaces the renderer and its
-            // counters, so harvesting per op is what keeps them.
+            // Collect the action's effects too, including scripts in a new renderer.
             if (browserCoverageActive()) {
                 try {
                     await harvestBrowserCoverage(holder.cdp);
@@ -1415,7 +1432,7 @@ function buildBackend(holder, recorder, buildOpts) {
             // Reads (`opts.wrap`) return user-visible JS values someone is likely to
             // assert on — provenance-wrap so `expect(...)` nests under this step.
             // Actions return void/internals; leave them raw to avoid Proxy surprises.
-            if (seq !== undefined && opts?.wrap) {
+            if (opts?.wrap) {
                 return wrap(result, seq);
             }
             return result;
@@ -1551,6 +1568,46 @@ function buildBackend(holder, recorder, buildOpts) {
                 await holder.page.reload(options);
             });
         },
+        readClipboard() {
+            return instrumented("readClipboard", {}, async () => {
+                const page = holder.page;
+                const { origin, policyAllowsRead } = await page.evaluate(() => {
+                    if (!isSecureContext || !/^https?:$/.test(location.protocol)) {
+                        throw new Error("Clipboard reads require a secure HTTP(S) page");
+                    }
+                    const policy = document.featurePolicy;
+                    return { origin: location.origin, policyAllowsRead: policy?.allowsFeature("clipboard-read") ?? true };
+                });
+                if (!policyAllowsRead)
+                    return page.evaluate(() => navigator.clipboard.readText());
+                const browser = holder.context.browser();
+                if (!browser)
+                    throw new Error("Clipboard reads require an attached Chromium browser");
+                // Native clipboard contents belong to the browser, not the context.
+                // Observe from a disposable context: overriding an app permission and
+                // restoring its queried state cannot restore native prompt behavior
+                // or preserve overrides owned by another DevTools session.
+                const observer = await browser.newContext();
+                try {
+                    const observerOrigin = "https://spectest-clipboard.invalid";
+                    await observer.route("**/*", route => route.fulfill({
+                        status: 200, contentType: "text/html", body: "<!doctype html><title>Clipboard observation</title>",
+                    }));
+                    await observer.grantPermissions(["clipboard-read"], { origin: observerOrigin });
+                    const observerPage = await observer.newPage();
+                    await observerPage.goto(observerOrigin);
+                    const text = await observerPage.evaluate(() => navigator.clipboard.readText());
+                    await page.evaluate(expectedOrigin => {
+                        if (location.origin !== expectedOrigin)
+                            throw new Error("Page navigated during clipboard read");
+                    }, origin);
+                    return text;
+                }
+                finally {
+                    await observer.close();
+                }
+            }, { wrap: true });
+        },
         locator: (css) => makeLocator(backend, strategy, { steps: [{ m: "locator", args: [css] }] }),
         getByRole: (role, opts) => makeLocator(backend, strategy, { steps: [{ m: "getByRole", args: [role, opts] }] }),
         getByText: (text, opts) => makeLocator(backend, strategy, { steps: [{ m: "getByText", args: [text, opts] }] }),
@@ -1697,6 +1754,7 @@ function buildBackend(holder, recorder, buildOpts) {
                 }
                 catch { /* capture reports the error */ }
             }
+            releaseBrowserCoverage(holder.cdp);
             viewClosed = true;
             buildOpts.onDestroy?.();
             try {

package/dist/change-rules.d.ts

@@ -0,0 +1,45 @@
+/** Portable source-change policy, evaluated identically by the SDK and controller.
+ * Globs match whole root-relative paths: *, ?, [], [!], ** and backslash escapes.
+ * Braces/extglobs have no special meaning. Directory rules explicitly use /**. */
+export type ChangeAction = "coverage" | "full" | "ignore";
+export interface ChangeRule {
+    root?: string;
+    pattern: string;
+    action: ChangeAction;
+}
+export interface ResolvedChangeRule extends ChangeRule {
+    root: string;
+}
+export interface ChangePolicy {
+    defaults: readonly (readonly ResolvedChangeRule[])[];
+    overrides: readonly ResolvedChangeRule[];
+}
+export interface ChangeRuleAdapter {
+    changeRules?: readonly ChangeRule[];
+    /** Wrappers preserve independent nested adapter policies, including roots. */
+    changeRuleGroups?: readonly (readonly ChangeRule[])[];
+    sourceOptions?: {
+        sourceRoot?: string;
+    } | ((...args: any[]) => unknown);
+}
+export interface ChangeRuleService {
+    /** Explicit rules override all defaults. false disables defaults. */
+    changeRules?: readonly ChangeRule[] | false;
+    coverage?: boolean | {
+        sourceRoot?: string;
+    };
+}
+export declare function compileChangeGlob(pattern: string): RegExp;
+export declare function matchesChangeGlob(pattern: string, path: string): boolean;
+export declare function validateChangeRules(value: unknown): asserts value is readonly ChangeRule[];
+export declare const COMMON_CHANGE_RULES: readonly ChangeRule[];
+export declare const JAVASCRIPT_CHANGE_RULES: readonly ChangeRule[];
+export declare const NODE_CHANGE_RULES: readonly ChangeRule[];
+export declare const BROWSER_CHANGE_RULES: readonly ChangeRule[];
+export declare const BUN_CHANGE_RULES: readonly ChangeRule[];
+export declare const NEXT_CHANGE_RULES: readonly ChangeRule[];
+export declare const RUST_CHANGE_RULES: readonly ChangeRule[];
+export declare function resolveChangePolicy(service: ChangeRuleService, adapters?: readonly ChangeRuleAdapter[]): ChangePolicy;
+/** Compile once for scans over a source tree; regexes carry no mutable flags. */
+export declare function compileChangePolicy(policy: ChangePolicy): (path: string) => ChangeAction | undefined;
+export declare function evaluateChangePolicy(policy: ChangePolicy, path: string): ChangeAction | undefined;