@specific.dev/spectest 0.121.0 → 0.123.0

package/README.md

@@ -8,18 +8,46 @@ Install the SDK in your project's `spectest/` directory:
 
 ```sh
 mkdir -p spectest
-npm install --prefix spectest --save-exact @specific.dev/spectest@0.88.3
+npm install --prefix spectest --save-exact @specific.dev/spectest
 ```
 
 Install the [Spectest CLI](https://github.com/specific-dev/spectest/releases/latest)
 and run `spectest docs /installation` for project setup and authentication.
 `spectest docs` contains the complete offline authoring guide.
 
+For browser tests, read `spectest docs /tests/browser`; for phone-emulated Expo
+apps, read `spectest docs /tests/mobile`. The shared test model is in `/tests`. Prefer
+unique, scoped role/name or test-ID locators and awaited browser assertions:
+`await expect(browser.getByRole("status")).toHaveText("Saved")`. A one-time read
+inside `expect` does not retry. Observe the exact saved state before dependent
+work; do not replace readiness with sleeps or arbitrary `.first()` selections.
+SDK 0.123.0 uses native Playwright assertions while retaining Spectest's API and
+recording. Ambiguous single-element selectors fail immediately; make them unique.
+
 Pub/Sub integrations are project-owned as of SDK 0.98.0. The former
 `pubsub`/`pubsubClient` exports and `/components/gcp` entry point are removed.
 Use a local service definition or `serviceGroup()` wrapper; the repository’s
 `examples/google-pubsub` demonstrates this using public SDK APIs.
 
+## Supabase function coverage (0.122.0)
+
+`supabase({ dir: "supabase" })` automatically collects coverage for its edge
+functions, including local shared modules outside that directory. No application
+instrumentation or coverage option is needed. Custom component names and folder
+layouts work the same way. Stacks without functions have no extra collector.
+
+Coverage starts before user code in both shared and per-function isolates. Setup
+and individual test captures are separate, with source maps checked against the
+uploaded TypeScript/JavaScript. Generated startup gates let functions warm
+concurrently while preserving their Deno configuration and import maps.
+Isolate captures, source metadata reads, and report writes run concurrently.
+Lost workers or unusable source metadata fail
+collection rather than silently reporting no execution. Changes to the function
+catalogue or runtime configuration conservatively invalidate subset selection,
+including newly added functions. This collects edge function code only: SQL and
+application frontend coverage are separate, and subset enforcement remains a
+project setting.
+
 ## Interactive entrypoints (0.114.0)
 
 Choose the links shown in the interactive dashboard and PR preview comment:

package/dist/browser.js

@@ -1554,9 +1554,8 @@ function buildBackend(holder, recorder, buildOpts) {
             const fields = { description: label };
             return instrumented("waitForURL", fields, async () => {
                 try {
-                    // Always a predicate, never playwright's own glob: `matchesUrl`
-                    // is then the single matching implementation shared with
-                    // `expect(browser).toHaveURL`.
+                    // Preserve Spectest's glob dialect. URL assertions use the same
+                    // glob compiler through their native matcher adapter.
                     await holder.page.waitForURL((u) => matchesUrl(u.href, pattern), {
                         timeout: timeoutMs,
                         waitUntil: options.waitUntil ?? "commit",
@@ -1763,12 +1762,15 @@ function buildBackend(holder, recorder, buildOpts) {
             return instrumented(action, fields, () => fn(holder.page), opts);
         },
     };
-    // The seam `expect(browser).toHaveURL(...)` polls: a silent URL read plus
+    // The seam `expect(browser).toHaveURL(...)` uses: a native assertion plus
     // the single settled step its assertion nests under — the session twin of
     // the locator probe, and what brands this object as a browser session for
     // `expect`'s overload dispatch.
     attachBrowserProbe(backend, {
-        url: () => holder.page.url(),
+        assertURL: async (negated, expected, opts) => {
+            const { assertURL } = await import("./playwright-assertions.js");
+            await assertURL(holder.page, negated, expected, opts);
+        },
         settle: (action, waitedMs, error) => backend.recordSettled(action, { url: holder.page.url() }, waitedMs, error),
     });
     return { backend, detach: endRecording };

package/dist/components/supabase-coverage.d.ts

@@ -0,0 +1,7 @@
+import type { CoverageAdapter } from "../coverage.js";
+/** The inspector stays on container loopback; only the component's router
+ * talks to it. Reports use the existing, runtime-independent V8 wire format. */
+export declare function supabaseFunctionsCoverage(functionRoot: string): CoverageAdapter;
+/** Runs in the trusted main worker, not in a sandboxed user function. Keep
+ * this plain JS so the same module is exercised against the pinned runtime. */
+export declare const SUPABASE_COVERAGE_COLLECTOR: string;

package/dist/components/supabase-coverage.js

@@ -0,0 +1,375 @@
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import { createHash } from "node:crypto";
+import { rawFetch } from "../harness/raw-fetch.js";
+// Drain all work even on failure: no writes may outlive the capture boundary.
+async function finishAll(pending) {
+    const results = await Promise.allSettled(pending);
+    return results.map(result => {
+        if (result.status === "rejected")
+            throw result.reason;
+        return result.value;
+    });
+}
+/** The inspector stays on container loopback; only the component's router
+ * talks to it. Reports use the existing, runtime-independent V8 wire format. */
+export function supabaseFunctionsCoverage(functionRoot) {
+    const shippedByService = new Map();
+    return {
+        name: "supabase-functions",
+        reports: "delta",
+        sourceOptions: { sourceRoot: "." },
+        ownsReport: name => name.startsWith("edge-") || name.startsWith("edge-scripts/"),
+        async inventory(ctx) {
+            // Functions are discovered by directory, not by an import in user code.
+            // Changing the catalogue must invalidate selection even for a new file.
+            // A removed fingerprint with no executed unit conservatively runs all.
+            const prefix = functionRoot + "/";
+            const files = await ctx.projectFiles();
+            const entries = files.filter(file => {
+                if (!file.startsWith(prefix))
+                    return false;
+                const parts = file.slice(prefix.length).split("/");
+                return parts.length === 2 && !/^[_.]/.test(parts[0]) && parts[1] === "index.ts";
+            }).sort();
+            const configNames = new Set(["deno.json", "deno.jsonc", "deno.lock", "import_map.json", "package.json"]);
+            const configPaths = files.filter(file => {
+                if (!configNames.has(path.posix.basename(file)))
+                    return file === path.posix.join(path.posix.dirname(functionRoot), "config.toml");
+                const dir = path.posix.dirname(file);
+                return dir === "." || file.startsWith(prefix) || functionRoot.startsWith(dir + "/") || dir === functionRoot;
+            }).sort();
+            const configs = await Promise.all(configPaths.map(async (file) => [file, await ctx.readProjectFile(file)]));
+            const digest = createHash("sha256").update(JSON.stringify({ entries, configs })).digest("hex");
+            return [`manifest:edge-functions:${encodeURIComponent(functionRoot)}#${digest}`];
+        },
+        async capture(ctx) {
+            let shipped = shippedByService.get(ctx.service);
+            if (!shipped)
+                shippedByService.set(ctx.service, shipped = new Set());
+            const response = await rawFetch(`http://${ctx.service}:9000/_spectest/coverage`, {
+                method: "POST", signal: ctx.signal,
+            });
+            if (!response.ok)
+                throw new Error(`edge coverage: ${await response.text()}`);
+            const payload = await response.json();
+            if (!payload || !Array.isArray(payload.reports) || !payload.reports.length)
+                throw new Error("edge coverage returned no reports");
+            for (const report of payload.reports) {
+                if (!report || !/^(edge-[\w-]+\.json|edge-scripts\/[a-f0-9]+\.json)$/.test(report.name) || typeof report.content !== "string") {
+                    throw new Error("invalid edge coverage report");
+                }
+            }
+            // State and files both fork with the VM. Remove only reports that this
+            // adapter previously shipped, never another adapter's output.
+            await finishAll([...shipped].map(name => fs.rm(path.join(ctx.reportDir, name), { force: true })));
+            shipped.clear();
+            await finishAll(payload.reports.map(async (report) => {
+                // Track attempted writes too, so a failed write is cleaned up next time.
+                shipped.add(report.name);
+                await ctx.writeReport(report.name, report.content);
+            }));
+        },
+    };
+}
+/** Runs in the trusted main worker, not in a sandboxed user function. Keep
+ * this plain JS so the same module is exercised against the pinned runtime. */
+export const SUPABASE_COVERAGE_COLLECTOR = String.raw `
+const INTERNAL = /^(ext:|node:|internal:)/;
+const COMPILED = /^\/var\/tmp\/sb-compile-[^/]+\//;
+const TIMEOUT = 30000;
+// Keep failed captures fenced until every independent operation has settled.
+const finishAll = async pending => {
+  const results = await Promise.allSettled(pending);
+  return results.map(result => {
+    if (result.status === "rejected") throw result.reason;
+    return result.value;
+  });
+};
+const hash = async text => Array.from(new Uint8Array(await crypto.subtle.digest("SHA-256", new TextEncoder().encode(text))), b => b.toString(16).padStart(2, "0")).join("");
+const fileUrl = path => "file://" + path.split("/").map(encodeURIComponent).join("/");
+
+export class EdgeCoverage {
+  constructor({ inspector = "http://127.0.0.1:9229", projectRoot = "/repo", generatedRoot = "/home/deno/spectest-functions" } = {}) {
+    this.inspector = inspector;
+    this.projectRoot = projectRoot.replace(/\/$/, "");
+    this.generatedRoot = generatedRoot;
+    this.entries = new Set();
+    this.wrappers = new Map();
+    this.mirrors = new Map();
+    this.sessions = new Map();
+    this.records = new Set();
+    this.error = null;
+    this.polling = null;
+    this.capturing = false;
+    this.sequence = 0;
+    this.timer = setInterval(() => this.poll().catch(e => this.fail(e)), 100);
+  }
+  fail(error) { this.error ??= String(error?.stack ?? error); }
+  register(entry) { this.entries.add(entry); }
+  wrap(entry) {
+    if (!this.wrappers.has(entry)) this.wrappers.set(entry, this.writeEntry(entry));
+    return this.wrappers.get(entry);
+  }
+  mirrorDirectory(relative) {
+    if (this.mirrors.has(relative)) return this.mirrors.get(relative);
+    const pending = (async () => {
+      const source = this.projectRoot + (relative ? "/" + relative : "");
+      const target = this.generatedRoot + "/project" + (relative ? "/" + relative : "");
+      if (relative) {
+        await this.mirrorDirectory(relative.includes("/") ? relative.slice(0, relative.lastIndexOf("/")) : "");
+        await Deno.remove(target); // replace this directory's link with an overlay
+      }
+      await Deno.mkdir(target, { recursive: true });
+      const items = [];
+      for await (const item of Deno.readDir(source)) items.push(item.name);
+      await finishAll(items.map(name => Deno.symlink(source + "/" + name, target + "/" + name)));
+      return target;
+    })();
+    this.mirrors.set(relative, pending);
+    return pending;
+  }
+  async writeEntry(entry) {
+    const slash = entry.lastIndexOf("/");
+    let directory = entry.slice(0, slash);
+    if (entry.startsWith(this.projectRoot + "/")) {
+      // Keep the complete directory/config layout, including ancestor Deno
+      // workspaces, relative import maps and packages. Only directories along
+      // the entry's ancestry are materialized; everything else is a symlink.
+      directory = await this.mirrorDirectory(directory.slice(this.projectRoot.length + 1));
+    }
+    const wrapper = directory + "/.spectest-coverage-" + (await hash(entry)).slice(0, 16) + ".mjs";
+    const code = [
+      "// spectest-generated coverage gate. Do not edit.",
+      "const keepAlive = setInterval(() => {}, 25);",
+      "const gate = {};",
+      "globalThis[Symbol.for('spectest.edgeCoverage')] = gate;",
+      "await new Promise(resolve => { gate.release = resolve; });",
+      "clearInterval(keepAlive);",
+      "const mod = await import(" + JSON.stringify("./" + entry.slice(slash + 1)) + ");",
+      "export default ('default' in mod ? mod.default : {});",
+    ].join("\n");
+    await Deno.writeTextFile(wrapper, code, { createNew: true });
+    this.register(wrapper);
+    return fileUrl(wrapper);
+  }
+  async forgetUnstarted(entry) {
+    // Compilation can reject the shared graph before an isolate exists. That
+    // is a normal reason for the component to retry in per-function mode.
+    const wrapper = await this.wrappers.get(entry);
+    if (!wrapper) return;
+    const original = decodeURIComponent(new URL(wrapper).pathname);
+    if (![...this.sessions.values()].some(s => s.entry === original)) this.entries.delete(original);
+  }
+  async ready() {
+    const deadline = Date.now() + TIMEOUT;
+    while (true) {
+      await this.poll();
+      if (this.error) throw new Error(this.error);
+      const attached = new Set([...this.sessions.values()].map(s => s.entry));
+      if ([...this.entries].every(entry => attached.has(entry))) {
+        await Promise.all([...this.sessions.values()].map(s => s.ready));
+        return;
+      }
+      if (Date.now() >= deadline) throw new Error("edge coverage did not attach to every warmed worker");
+      await new Promise(resolve => setTimeout(resolve, 25));
+    }
+  }
+  async poll() {
+    if (this.polling) return this.polling;
+    this.polling = this.discover();
+    try { await this.polling; } finally { this.polling = null; }
+  }
+  async discover() {
+    const response = await fetch(this.inspector + "/json/list", { signal: AbortSignal.timeout(TIMEOUT) });
+    if (!response.ok) throw new Error("edge inspector discovery failed: " + response.status);
+    const targets = await response.json();
+    if (!Array.isArray(targets)) throw new Error("invalid edge inspector target list");
+    const live = new Set(targets.map(t => t.id));
+    for (const [id] of this.sessions) if (!live.has(id)) throw new Error("edge coverage lost worker " + id);
+    for (const target of targets) {
+      if (this.sessions.has(target.id)) continue;
+      const session = this.connect(target);
+      this.sessions.set(target.id, session);
+      // Discover all isolates while their sessions initialize. ready() joins
+      // initialization separately; one worker never blocks discovery of others.
+      session.ready.catch(e => this.fail(e));
+    }
+  }
+  connect(target) {
+    const url = new URL(target.url);
+    if (url.protocol !== "file:") throw new Error("unexpected edge worker entry: " + target.url);
+    const compiledPath = decodeURIComponent(url.pathname);
+    const relative = compiledPath.replace(COMPILED, "");
+    // The runtime relocates the entire module graph under sb-compile-*/.
+    // Its registered entrypoint and our exact original entrypoint establish
+    // the relocation, independently for every isolate. Never guess a source
+    // file by basename or by a repository suffix.
+    const candidates = [...this.entries].filter(entry => compiledPath === entry || entry.endsWith("/" + relative));
+    if (candidates.length !== 1) throw new Error("ambiguous edge worker entry: " + target.url);
+    const original = candidates[0];
+    const base = COMPILED.test(compiledPath) ? original.slice(0, -relative.length) : "/";
+    const prefix = COMPILED.exec(compiledPath)?.[0] ?? "/";
+    const socketUrl = new URL(target.webSocketDebuggerUrl);
+    const inspector = new URL(this.inspector);
+    socketUrl.host = inspector.host;
+    const ws = new WebSocket(socketUrl);
+    const session = { ws, base, prefix, entry: original, scripts: new Map(), descriptions: new Map(), nextId: 0, pending: new Map() };
+    session.post = (method, params = {}) => new Promise((resolve, reject) => {
+      const id = ++session.nextId;
+      const timer = setTimeout(() => { session.pending.delete(id); reject(new Error("edge inspector timeout: " + method)); }, TIMEOUT);
+      session.pending.set(id, { resolve, reject, timer });
+      ws.send(JSON.stringify({ id, method, params }));
+    });
+    ws.onmessage = event => {
+      try {
+        const message = JSON.parse(event.data);
+        if (message.id) {
+          const pending = session.pending.get(message.id);
+          if (!pending) return;
+          clearTimeout(pending.timer);
+          session.pending.delete(message.id);
+          if (message.error) pending.reject(new Error(JSON.stringify(message.error)));
+          else pending.resolve(message.result);
+        } else if (message.method === "Debugger.scriptParsed") {
+          session.scripts.set(message.params.scriptId, message.params);
+        } else if (message.method === "Debugger.paused") {
+          session.post("Debugger.resume").catch(e => this.fail(e));
+        }
+      } catch (e) { this.fail(e); }
+    };
+    ws.onclose = () => {
+      const error = new Error("edge coverage inspector disconnected: " + target.id);
+      for (const p of session.pending.values()) { clearTimeout(p.timer); p.reject(error); }
+      session.pending.clear();
+      this.fail(error);
+    };
+    session.ready = (async () => {
+      await new Promise((resolve, reject) => {
+        const timer = setTimeout(() => reject(new Error("edge inspector connection timeout")), TIMEOUT);
+        ws.onopen = () => { clearTimeout(timer); resolve(); };
+        ws.onerror = () => { clearTimeout(timer); reject(new Error("edge inspector connection failed")); };
+      });
+      await session.post("Debugger.enable", { maxScriptsCacheSize: 16 * 1024 * 1024 });
+      await session.post("Profiler.enable");
+      await session.post("Profiler.startPreciseCoverage", { callCount: true, detailed: true });
+      // --inspect-brk can park inside the pinned runtime's inspector before
+      // its pending session handshake is polled. Use a live JS gate instead:
+      // no project module executes until precise coverage is acknowledged.
+      const released = await session.post("Runtime.evaluate", {
+        expression: "(async () => { const key = Symbol.for('spectest.edgeCoverage'); while (!globalThis[key]?.release) await new Promise(resolve => setTimeout(resolve, 10)); globalThis[key].release(); await new Promise(resolve => setTimeout(resolve, 0)); })()\n//# sourceURL=spectest:edge-coverage-bootstrap",
+        awaitPromise: true,
+      });
+      if (released.exceptionDetails) throw new Error("edge coverage gate failed: " + JSON.stringify(released.exceptionDetails));
+    })();
+    return session;
+  }
+  originalPath(session, url) {
+    const parsed = new URL(url);
+    if (parsed.protocol !== "file:") return null;
+    const pathname = decodeURIComponent(parsed.pathname);
+    if (!pathname.startsWith(session.prefix)) throw new Error("unknown edge source root: " + url);
+    return session.base + pathname.slice(session.prefix.length);
+  }
+  sourcePath(file) {
+    const mirror = this.generatedRoot + "/project/";
+    return file.startsWith(mirror) ? this.projectRoot + "/" + file.slice(mirror.length) : file;
+  }
+  async describe(session, script, original) {
+    if (session.descriptions.has(script.scriptId)) return session.descriptions.get(script.scriptId);
+    const { scriptSource: text } = await session.post("Debugger.getScriptSource", { scriptId: script.scriptId });
+    if (typeof text !== "string") throw new Error("missing edge source: " + script.url);
+    const metadata = session.scripts.get(script.scriptId);
+    const mapUrl = metadata?.sourceMapURL;
+    let sourceMap = null;
+    if (mapUrl) {
+      if (!mapUrl.startsWith("data:")) throw new Error("unsupported edge source map: " + mapUrl);
+      const comma = mapUrl.indexOf(",");
+      const encoded = mapUrl.slice(comma + 1);
+      const decoded = mapUrl.slice(0, comma).endsWith(";base64")
+        ? new TextDecoder().decode(Uint8Array.from(atob(encoded), c => c.charCodeAt(0))) : decodeURIComponent(encoded);
+      const data = JSON.parse(decoded);
+      if (!Array.isArray(data.sources) || !Array.isArray(data.sourcesContent) || typeof data.mappings !== "string" || data.sections || data.sourceRoot) {
+        throw new Error("missing edge source-map identity: " + script.url);
+      }
+      // Edge Runtime's map sources are relative to the graph root, rather
+      // than the script directory. Validate their contents against the actual
+      // mounted sources before archiving the normalized identities.
+      data.sources = await finishAll(data.sources.map(async (name, i) => {
+        const source = new URL(name, fileUrl(session.base));
+        if (source.protocol !== "file:") throw new Error("unexpected mapped edge source: " + source.href);
+        const file = this.sourcePath(decodeURIComponent(source.pathname));
+        if (!file.startsWith(this.projectRoot + "/")) throw new Error("edge map escapes project: " + file);
+        if (await Deno.readTextFile(file) !== data.sourcesContent[i]) throw new Error("edge source content mismatch: " + file);
+        return fileUrl(file);
+      }));
+      delete data.sourcesContent;
+      delete data.sourceRoot;
+      sourceMap = { url: null, data };
+    } else {
+      // JavaScript may need no transpilation. TypeScript without a map must
+      // not silently attribute generated line numbers to authored source.
+      if (await Deno.readTextFile(original) !== text) throw new Error("edge source has no usable map: " + original);
+    }
+    const record = { url: fileUrl(original), sourceHash: await hash(text),
+      lineLengths: text.split(/[\n\u2028\u2029]/).map(line => line.length),
+      functions: script.functions.map(f => [f.functionName, f.ranges[0].startOffset, f.ranges[0].endOffset]), sourceMap };
+    const content = JSON.stringify({ spectestScript: record });
+    const descriptor = { id: await hash(content), content };
+    session.descriptions.set(script.scriptId, descriptor);
+    return descriptor;
+  }
+  async capture() {
+    if (this.capturing) throw new Error("edge coverage capture already in progress");
+    this.capturing = true;
+    try {
+      await this.ready();
+      if (this.error) throw new Error(this.error);
+      // Each isolate owns its counters. Take all deltas concurrently, and
+      // fetch independent script descriptors concurrently within each isolate.
+      // Join before merging so ordering/deduplication don't depend on timing.
+      const captures = await finishAll([...this.sessions.values()].map(async session => {
+        const dump = await session.post("Profiler.takePreciseCoverage");
+        return finishAll(dump.result.map(async script => {
+          if (!script.functions.some(f => f.ranges.some(r => r.count > 0))) return null;
+          if (INTERNAL.test(script.url)) return null;
+          if (script.url === "spectest:edge-coverage-bootstrap") return null;
+          if (/^(https?:|npm:|jsr:)/.test(script.url)) return { unit: "deno:" + script.url };
+          if (!script.url) throw new Error("anonymous executed edge script cannot be mapped");
+          const rawPath = this.originalPath(session, script.url);
+          if (rawPath === session.entry) return null; // the generated startup gate
+          const original = rawPath && this.sourcePath(rawPath);
+          if (original?.startsWith(this.generatedRoot + "/")) return null;
+          if (original?.includes("/node_modules/")) return { unit: "deno:" + script.url };
+          if (!original?.startsWith(this.projectRoot + "/")) throw new Error("unmapped edge script: " + script.url);
+          const descriptor = await this.describe(session, script, original);
+          return { descriptor, result: { url: fileUrl(original), spectestScript: descriptor.id,
+            functions: script.functions.filter(f => f.ranges.some(r => r.count > 0)).map(f => {
+              const start = f.ranges[0].startOffset;
+              return f.ranges.flatMap((r, i) => [i ? r.startOffset - start : start, r.endOffset - r.startOffset, r.count]);
+            }) } };
+        }));
+      }));
+      const reports = [], result = [], units = new Set();
+      for (const capture of captures) for (const item of capture) {
+        if (!item) continue;
+        if (item.unit) { units.add(item.unit); continue; }
+        const { descriptor } = item;
+        if (!this.records.has(descriptor.id)) {
+          reports.push({ name: "edge-scripts/" + descriptor.id + ".json", content: descriptor.content });
+          this.records.add(descriptor.id);
+        }
+        result.push(item.result);
+      }
+      if (this.error) throw new Error(this.error);
+      reports.push({ name: "edge-" + (++this.sequence) + ".json", content: JSON.stringify({ spectestVersion: 2, result, units: [...units] }) });
+      return { reports };
+    } catch (e) {
+      // A take resets V8 counters. If processing fails afterwards, subsequent
+      // captures cannot repair that gap. Keep the failure sticky on this fork.
+      this.fail(e);
+      throw e;
+    } finally { this.capturing = false; }
+  }
+}
+`;

package/dist/components/supabase.js

@@ -65,6 +65,7 @@ import { microsoft } from "./microsoft.js";
 import { SUPABASE_WEBHOOKS_SQL } from "./supabase-webhooks.js";
 import { postgresTls } from "./postgres-tls.js";
 import { supabasePoolerService } from "./supabase-pooler.js";
+import { SUPABASE_COVERAGE_COLLECTOR, supabaseFunctionsCoverage } from "./supabase-coverage.js";
 import { mapSupabaseConfig, parseSupabaseConfigFile, } from "./supabase-config.js";
 // ──────────────────────────────────────────────────────────────────────────
 // Pinned upstream image tags (github.com/supabase/supabase docker-compose.yml,
@@ -690,6 +691,8 @@ services:
 // with, and Web Crypto verifies it in a few lines with no dependency.
 // ──────────────────────────────────────────────────────────────────────────
 const FUNCTIONS_MAIN_TS = String.raw `// spectest-generated edge-functions router. Do not edit.
+import { EdgeCoverage } from "./coverage.js";
+const edgeCoverage = new EdgeCoverage();
 const FUNCTIONS_DIR = Deno.env.get("FUNCTIONS_DIR") ?? "/repo/supabase/functions";
 const JWT_SECRET = Deno.env.get("JWT_SECRET") ?? "";
 const VERIFY_JWT = Deno.env.get("VERIFY_JWT") === "true";
@@ -754,8 +757,10 @@ const WORKER_TIMEOUT_MS = 24 * 60 * 60 * 1000;
  *  isolates, and an isolate reaped for idleness is rebooted by the next
  *  test that calls the function — a boot's worth of dirtied memory in that
  *  test's own snapshot diff. */
-function workerFor(name: string) {
+async function workerFor(name: string) {
+  const maybeEntrypoint = await edgeCoverage.wrap(FUNCTIONS_DIR + "/" + name + "/index.ts");
   return EdgeRuntime.userWorkers.create({
+    maybeEntrypoint,
     servicePath: FUNCTIONS_DIR + "/" + name,
     memoryLimitMb: 256,
     workerTimeoutMs: WORKER_TIMEOUT_MS,
@@ -978,6 +983,7 @@ async function sharedWorker(): Promise<any | null> {
         try {
           await createShared();
         } catch (e) {
+          await edgeCoverage.forgetUnstarted(SHARED_DIR + "/index.ts");
           reason = "the shared isolate failed to boot: " + String(e);
         }
       }
@@ -989,8 +995,10 @@ async function sharedWorker(): Promise<any | null> {
   return spec.reason === null ? createShared() : null;
 }
 
-function createShared() {
+async function createShared() {
+  const maybeEntrypoint = await edgeCoverage.wrap(SHARED_DIR + "/index.ts");
   return EdgeRuntime.userWorkers.create({
+    maybeEntrypoint,
     servicePath: SHARED_DIR,
     // A cap on the one isolate that holds every function, not a reservation.
     memoryLimitMb: 2048,
@@ -1018,8 +1026,8 @@ function createShared() {
 async function warmAll(): Promise<{ mode: "shared" | "per-function"; warmed: string[]; failed: Record<string, string> }> {
   const names = await functionNames();
   if ((await sharedWorker()) !== null) return { mode: "shared", warmed: names, failed: {} };
-  // All at once: each boot is mostly module loading, and the isolates come
-  // up concurrently.
+  // Each worker starts behind a generated gate; attach and initialize them
+  // concurrently, then release each only after precise coverage has started.
   const results = await Promise.allSettled(names.map((name) => workerFor(name)));
   const warmed: string[] = [];
   const failed: Record<string, string> = {};
@@ -1036,8 +1044,16 @@ Deno.serve(async (req: Request) => {
   // Ready probe — answered before any auth check, so bring-up never needs a
   // token, and never treated as a function name.
   if (pathname === "/_spectest/health") return new Response("ok");
+  if (pathname === "/_spectest/coverage" && req.method === "POST") {
+    try { return json(await edgeCoverage.capture()); }
+    catch (error) { return json({ error: String(error) }, 500); }
+  }
   // Setup-time warm-up (see warmAll); never treated as a function name.
-  if (pathname === "/_spectest/warm") return json(await warmAll());
+  if (pathname === "/_spectest/warm") {
+    const warmed = await warmAll();
+    await edgeCoverage.ready();
+    return json(warmed);
+  }
 
   const name = pathname.split("/")[1] ?? "";
   if (name === "") return json({ msg: "missing function name in request" }, 400);
@@ -1787,8 +1803,15 @@ CREATE SCHEMA IF NOT EXISTS _supavisor AUTHORIZATION supabase_admin;
                     volumes: [{ source: projectRootPath(), target: REPO_MOUNT, readOnly: true, reachExempt: true }],
                     // Our router (see FUNCTIONS_MAIN_TS) sits outside that mount, so
                     // the project never has to carry a `main/` function of ours.
-                    files: [{ path: "/home/deno/main/index.ts", content: FUNCTIONS_MAIN_TS }],
-                    args: ["start", "--main-service", "/home/deno/main", "--port", "9000"],
+                    files: [
+                        { path: "/home/deno/main/index.ts", content: FUNCTIONS_MAIN_TS },
+                        { path: "/home/deno/main/coverage.js", content: SUPABASE_COVERAGE_COLLECTOR },
+                    ],
+                    // Generated entry gates hold project imports until coverage starts;
+                    // the inspector stays live and is not exposed to peer containers.
+                    args: ["start", "--main-service", "/home/deno/main", "--port", "9000", "--inspect=127.0.0.1:9229"],
+                    workdir: REPO_MOUNT,
+                    coverage: { adapters: [supabaseFunctionsCoverage(fnRelPath)] },
                     env: {
                         JWT_SECRET: jwtSecret,
                         // Where the router looks for `<name>/`, inside the repo mount.

package/dist/index.d.ts

@@ -363,7 +363,8 @@ export interface SpectestContext<S extends ServicesMap = ServicesMap, F extends
      */
     readonly fakes: FakeHandlesFor<F>;
     /**
-     * Poll a predicate until it returns a truthy value, then return that
+     * Poll a predicate until it returns a value other than null, undefined,
+     * or false, then return that
      * value. In a test it records one `wait` event for the whole loop (with
      * attempt count, total duration, and the description) instead of one
      * event per probe — useful for "wait until pod Running"-style checks
@@ -371,19 +372,20 @@ export interface SpectestContext<S extends ServicesMap = ServicesMap, F extends
      * timeline; it's just the loop you'd otherwise hand-roll.
      *
      * - `null`, `undefined`, or `false` from `fn` mean "not yet" — wait
-     *   `intervalMs` and try again.
+     *   `intervalMs` and try again. A directly returned wrapped value is
+     *   checked using its underlying value. Use `.unwrap()` when branching
+     *   on wrapped primitives inside `fn`; wrapper objects are truthy.
      * - Anything else is the success value and is returned, tagged with
      *   the wait event's seq. Downstream `expect(...)` on it links to
      *   the wait (one logical step), not to N suppressed HTTP calls.
-     * - Throws from `fn` propagate out immediately; the wait event is
-     *   still recorded (with `error` set) so the timeline reflects the
-     *   abort.
+     * - Instrumented fetch transport failures are retried. Other throws
+     *   from `fn` propagate immediately; the wait event records the abort.
      * - Defaults: `timeoutMs = 30_000`, `intervalMs = 1_000`.
      *
-     * Side-effect calls inside `fn` (fetch, ctx.svc.* helpers, etc.)
-     * don't show up on the event log — the recorder is paused for the
-     * duration. Use `ctx.poll` for read-only observation, not for
-     * stateful work you want recorded.
+     * The winning attempt's events, or the final failed attempt's events,
+     * are retained beneath the wait; earlier attempts are discarded. Use
+     * `ctx.poll` for read-only observation of the exact required state.
+     * Perform mutations once outside the poll so retries cannot repeat them.
      */
     poll<T>(description: string, fn: () => T | null | undefined | false | Promise<T | null | undefined | false>, opts?: {
         timeoutMs?: number;
@@ -1871,9 +1873,10 @@ export interface TextMatcherOptions extends TextMatchOptions {
 }
 /**
  * Auto-retrying web-first assertions for a {@link Locator} — Playwright's
- * `expect(locator)` matchers. Each polls the element until it passes or a
- * deadline elapses (default 5 s, `{ timeout }` overrides) and records an
- * assertion event just like a value `expect`. `await` them — they are async.
+ * `expect(locator)` matchers. Playwright re-resolves the locator until it
+ * passes or a deadline elapses (default 10 s, `{ timeout }` overrides; 0
+ * disables the assertion timeout). Records an assertion event just like a
+ * value `expect`. `await` them — they are async.
  */
 export interface LocatorMatchers {
     /** The element is present and visible. */
@@ -1887,8 +1890,9 @@ export interface LocatorMatchers {
     /**
      * The element's text equals `expected`, or matches it when it is a RegExp.
      *
-     * **Whitespace is normalized on both sides**, exactly as playwright does
-     * it: the text is trimmed and every run of whitespace becomes one space.
+     * **String expectations normalize whitespace on both sides**, as Playwright
+     * does. Regex expectations test the original text. String comparisons trim
+     * the text and collapse every run of whitespace to one space.
      * So a typed space matches the no-break space (U+00A0) that
      * `Intl.NumberFormat` puts between thousands, and a value wrapped across
      * two lines in the markup matches the one-line string you wrote.
@@ -1899,7 +1903,8 @@ export interface LocatorMatchers {
     toHaveText(expected: string | RegExp | Array<string | RegExp>, opts?: TextMatcherOptions): Promise<void>;
     /**
      * The element's text contains `expected` — a substring, or a RegExp tested
-     * against the text. Whitespace is normalized as in {@link toHaveText}.
+     * against the text. Strings normalize whitespace as in {@link toHaveText};
+     * regexes test the original text.
      *
      * An **array** asserts that the matched elements contain these texts in
      * order; unlike `toHaveText` extra elements between them are allowed.
@@ -1930,8 +1935,8 @@ export interface LocatorAssertion extends LocatorMatchers {
 /**
  * Auto-retrying assertions for a browser/mobile **session** — Playwright's
  * `expect(page)` matchers. Like the locator ones, they poll until the
- * condition holds or the deadline elapses (default 5 s) and record one
- * assertion under a settled browser step.
+ * condition holds or the deadline elapses (default 10 s; 0 disables the
+ * assertion timeout) and record one assertion under a settled browser step.
  */
 export interface BrowserMatchers {
     /**