@specific.dev/spectest 0.66.0 → 0.67.0

package/dist/browser.js

@@ -34,6 +34,7 @@ import { fileURLToPath } from "node:url";
 import { generateId } from "./ids.js";
 import { recordBrowser, reserveBackdated, reserveEvent, truncateUtf8 } from "./recorder.js";
 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 { attachBrowserProbe, DEFAULT_ACTION_TIMEOUT_MS, desktopStrategy, makeLocator, mobileStrategy, } from "./locator.js";
@@ -1122,6 +1123,37 @@ function buildBackend(holder, recorder, buildOpts) {
     // when rrweb's load-deferred full snapshot is most likely to be
     // missing from the chunk we're about to drain (see `drainExpr`).
     let lastDrainUrl = null;
+    // Failed steps that captured their page. Bounded per session per case: a
+    // test that catches its own locator errors in a loop must not pay for a
+    // capture on each one, and three pages is already more than a reader will
+    // open. `ctx.poll` needs no bookkeeping here — it truncates the events of
+    // every superseded attempt, and each capture rides its own event.
+    let pageCaptures = 0;
+    const PAGE_CAPTURE_LIMIT = 3;
+    /** The page behind a failed step, for its event (see page-snapshot.ts).
+     *  Best-effort and quiet: this runs while an error is already on its way
+     *  up, and must never become the failure the author sees. */
+    async function failedPageStructure(action, error) {
+        // No recorder means nothing is recording this op (an eval, a library
+        // caller), so there is no event for the capture to ride out on.
+        if (!recorder || recordingEnded || viewClosed)
+            return undefined;
+        if (pageCaptures >= PAGE_CAPTURE_LIMIT)
+            return undefined;
+        pageCaptures += 1;
+        try {
+            return await capturePageStructure(holder.page, {
+                session: recorder.sessionName ?? "",
+                // A desktop view has no device preset; a phone-emulated one does.
+                kind: holder.device ? "mobile" : "browser",
+                action,
+                error,
+            });
+        }
+        catch {
+            return undefined;
+        }
+    }
     /** Session provenance stamped on every recorded op: which replay player
      *  the step belongs to, which named browser it acted on, and where in
      *  the player to seek (`endT`, in rrweb's clock). */
@@ -1203,12 +1235,17 @@ function buildBackend(holder, recorder, buildOpts) {
         catch (err) {
             const e = err;
             const endT = Date.now();
+            const error = e?.message ?? String(err);
+            // Captured after the clock stops, so the diagnostic is not billed to
+            // the step, and before the event is recorded, so it rides it.
+            const pageStructure = await failedPageStructure(action, error);
             recordBrowser({
                 action,
                 ...fields,
                 ...sessionFields(endT),
                 durationMs: endT - t,
-                error: e?.message ?? String(err),
+                error,
+                ...(pageStructure ? { pageStructure } : {}),
             }, resv);
             // Still try to drain — the failure itself may have produced
             // useful rrweb events (mutations from a half-loaded page, etc.).
@@ -1536,12 +1573,16 @@ function buildBackend(holder, recorder, buildOpts) {
             // where the matcher started polling, since that's what `tOffsetMs` means
             // everywhere else (the ops that reserve up front stamp their start).
             const endT = Date.now();
+            // A matcher that ran out of budget is the other half of a failed
+            // browser step, and the page it settled on is the same evidence.
+            const pageStructure = error ? await failedPageStructure(action, error) : undefined;
             const seq = recordBrowser({
                 action,
                 ...fields,
                 ...sessionFields(endT),
                 durationMs: waitedMs,
                 ...(error ? { error } : {}),
+                ...(pageStructure ? { pageStructure } : {}),
             }, reserveBackdated(waitedMs));
             // Drain the rrweb the page buffered while the matcher waited into this
             // step's chunk, so `settledTarget` has bounds to seek into.

package/dist/components/supabase.d.ts

@@ -33,20 +33,6 @@ export interface SupabaseOptions {
     storage?: boolean;
     /** Include Realtime (`<name>-realtime`). Default `true`. */
     realtime?: boolean;
-    /**
-     * Edge functions. `isolation` picks how they run on the edge runtime:
-     * `"shared"` (default) loads every function into **one** isolate, so a
-     * shared module graph (`_shared/`, npm packages) is loaded once rather than
-     * once per function — measured on a 51-function project as 230 MB against
-     * 3.6 GB. Hosted Supabase runs one isolate per function, and the one thing
-     * that differs is module-level state: a singleton in `_shared` is one
-     * object for all functions here, one per function there. `"per-function"`
-     * runs it the hosted way. Either way the runtime, the request each
-     * function sees and the per-function `verify_jwt` are the same.
-     */
-    functions?: {
-        isolation?: "shared" | "per-function";
-    };
     /**
      * Also serve the gateway over **HTTPS** at `https://<hostname>` via the
      * daemon's CA-trusted TLS reverse proxy (in addition to the plain

package/dist/components/supabase.js

@@ -698,9 +698,6 @@ async function validJwt(token: string): Promise<boolean> {
   }
 }
 
-/** How the functions run: every function in one isolate (the default), or
- *  one isolate per function as hosted Supabase does — see sharedWorker. */
-const ISOLATION = Deno.env.get("FUNCTIONS_ISOLATION") === "per-function" ? "per-function" : "shared";
 /** Where the generated entry of the shared isolate lives — outside the repo
  *  mount, which is read-only and the user's checkout, and NOT under /tmp:
  *  the runtime gives its workers an in-memory /tmp, so a file the main
@@ -780,7 +777,8 @@ async function stdServerUrls(dir: string, out: Set<string>): Promise<void> {
 // what differs from hosted Supabase is that module-level state is one
 // object for every function rather than one per function.
 //
-// It stands in only where it can be exact. A function with its own
+// There is deliberately no opt-out: it stands in wherever it can be exact,
+// and where it cannot the per-function isolates are used. A function with its own
 // deno.json / import map (per-function resolution the one config cannot
 // express), a functions/deno.jsonc (comments; not merged) or a config that
 // names an importMap keep the per-function isolates, and so does a shared
@@ -929,7 +927,6 @@ async function writeShared(names: string[]): Promise<string | null> {
 /** The shared isolate (pooled by the runtime under SHARED_DIR), or null when
  *  the functions run one isolate each — decided once, with the reason logged. */
 async function sharedWorker(): Promise<any | null> {
-  if (ISOLATION !== "shared") return null;
   if (!sharedSpec) {
     sharedSpec = (async () => {
       const names = await functionNames();
@@ -1729,9 +1726,6 @@ export function supabase(opts = {}) {
                         JWT_SECRET: jwtSecret,
                         // Where the router looks for `<name>/`, inside the repo mount.
                         FUNCTIONS_DIR: fnServePath,
-                        // One isolate for all functions (default) or one each — see the
-                        // `functions` option and the router's shared-isolate notes.
-                        FUNCTIONS_ISOLATION: opts.functions?.isolation ?? "shared",
                         // The default a function inherits when the config says nothing:
                         // reject an unauthenticated call, as hosted Supabase does.
                         VERIFY_JWT: "true",

package/dist/daemon.js

@@ -42,7 +42,7 @@ import { pollUntilReady } from "./harness/ready-poll.js";
 import { APP_DIR, WORKSPACE, resolveProjectPath } from "./project-files.js";
 import { isTextualContentType, looksBinary, omittedBody, parseContentLength, } from "./harness/http-body.js";
 import { encodeRegistry } from "./harness/names-registry.js";
-import { InterceptRegistry, runChain, } from "./harness/intercept.js";
+import { InterceptRegistry, parseTarget, runChain, } from "./harness/intercept.js";
 import { HOP_BY_HOP_HEADERS, augmentCorsResponse, corsPreflightResponse, isCorsPreflight, } from "./harness/http-proxy.js";
 import { certCovers as hostmatchCertCovers, hostWithoutPort, matchRoute, wildcardSuffix, } from "./harness/hostmatch.js";
 import { INGRESS_HTTPS_PORT, INGRESS_HTTP_PORT, bindRoute, certEntries, clearTables, emptyTables, planBind, registryTarget, routesFor, unbindRoute, } from "./harness/ingress-table.js";
@@ -2301,35 +2301,61 @@ function ingressClaimsHostname(hostname) {
     }
     return false;
 }
-/** Record one request an interceptor saw, nested under its `intercept` step. */
+/** Record one request an interceptor saw, nested under its `intercept` step.
+ *
+ * A forced 503 is the step doing exactly what its description says, so it is
+ * **not** marked failed — reddening the outcome the test asked for trains the
+ * reader to ignore the colour. Only a handler that threw is marked, because
+ * that 500 is a bug in the middleware rather than the outage it stands for. */
 function recordInterceptedRequest(it, rec, durationMs) {
     const parentSeq = INTERCEPT_STEP_SEQ.get(it.id);
     if (parentSeq === undefined || !isRecording())
         return;
-    const by = rec.answeredBy === "handler"
-        ? "answered by the interceptor"
-        : rec.answeredBy === "modified"
-            ? "upstream answer replaced by the interceptor"
-            : "passed through to the upstream";
+    const by = rec.threw
+        ? "the interceptor threw — 500 from spectest, not from your handler"
+        : rec.answeredBy === "handler"
+            ? "answered by the interceptor"
+            : rec.answeredBy === "modified"
+                ? "upstream answer replaced by the interceptor"
+                : "passed through to the upstream";
     recordStep({
         kind: "intercept-request",
         parentSeq,
         title: `${rec.method} ${rec.path} → ${rec.status}`,
-        status: rec.status >= 500 && rec.answeredBy !== "upstream" ? "failed" : "passed",
+        status: rec.threw ? "failed" : "passed",
+        // Method, path and status are already the title; the one thing the row
+        // cannot say for itself is who produced that status.
         blocks: [
-            {
-                type: "kv",
-                rows: [
-                    { label: "Host", value: it.hostname },
-                    { label: "Request", value: `${rec.method} ${rec.path}` },
-                    { label: "Status", value: String(rec.status) },
-                    { label: "Answered", value: by },
-                ],
-            },
+            { type: "kv", rows: [{ label: "Answered", value: by, error: rec.threw === true }] },
         ],
         durationMs,
     });
 }
+/** The handler's own source, which is what the interceptor actually does.
+ *
+ * Free and impossible to let rot: Bun runs the project's TypeScript
+ * directly, so `toString()` is the text the author wrote. It is the step's
+ * body, under the description — a mechanism the reader can check against
+ * the intent the description claims. A handler long enough to be a wall of
+ * code folds into a disclosure instead of pushing the requests off screen.
+ */
+function handlerBlocks(handler) {
+    let src;
+    try {
+        src = String(handler);
+    }
+    catch {
+        return [];
+    }
+    const code = { type: "code", lang: "ts", label: "Handler", code: src };
+    return src.split("\n").length > HANDLER_FOLD_LINES
+        ? [{ type: "details", summary: "Handler", blocks: [code] }]
+        : [code];
+}
+/** Past this many lines the handler source is folded away. Chosen so the
+ *  shapes this feature is for — a one-line forced status, a short
+ *  fail-twice-then-pass — always show, and only a real program hides. */
+const HANDLER_FOLD_LINES = 15;
 /**
  * Put middleware in front of a hostname the ingress serves — the
  * implementation behind `ctx.intercept`.
@@ -2338,15 +2364,19 @@ function recordInterceptedRequest(it, rec, durationMs) {
  * the daemon (DNS does not point here), so the interceptor could only be
  * silent — and silence is the failure mode this whole layer is designed
  * against. The message names the two ways to get a route.
+ *
+ * The `description` is required because it is the step's whole title in the
+ * timeline and in the CLI's failure detail: it is what tells a reader why
+ * the UI under test went to its error state. The handler source says how;
+ * only the author can say what it means.
  */
-function registerInterceptor(hostname, pathOrHandler, maybeHandler) {
-    const path = typeof pathOrHandler === "string" ? pathOrHandler : undefined;
-    const handler = typeof pathOrHandler === "function" ? pathOrHandler : maybeHandler;
-    if (typeof hostname !== "string" || hostname.length === 0) {
-        throw new Error("ctx.intercept: a hostname is required");
-    }
-    const host = hostname.toLowerCase().replace(/^https?:\/\//, "").replace(/\/.*$/, "");
-    if (!handler) {
+function registerInterceptor(target, description, handler) {
+    const { hostname: host, path } = parseTarget(target);
+    if (typeof description !== "string" || description.trim() === "") {
+        throw new Error(`ctx.intercept(${JSON.stringify(target)}): a description is required — what the ` +
+            `environment now does, as the timeline reads it, e.g. "the sync endpoint returns 503".`);
+    }
+    if (typeof handler !== "function") {
         throw new Error("ctx.intercept: a handler (req, next) => Response is required");
     }
     if (!ingressClaimsHostname(host)) {
@@ -2357,19 +2387,41 @@ function registerInterceptor(hostname, pathOrHandler, maybeHandler) {
     }
     const resv = reserveEvent();
     const it = INTERCEPTORS.register(host, path, handler);
+    const where = `${host}${it.path === "/" ? "" : it.path}`;
     const seq = recordStep({
         kind: "intercept",
-        title: `intercept ${host}${it.path === "/" ? "" : it.path}`,
+        // The description alone. The pill already says INTERCEPT, and the
+        // target is in the panel — a row that repeats both spends its width
+        // on what the reader can already see and none of it on the one thing
+        // only the author knows.
+        title: description.trim(),
         blocks: [
+            ...handlerBlocks(handler),
             {
-                type: "kv",
-                rows: [
-                    { label: "Host", value: host },
-                    { label: "Path", value: it.path === "/" ? "/ (every path)" : `${it.path} and below` },
+                // The target IS the summary line, so the closed disclosure still
+                // says where the interceptor sits — a generic "Target" label
+                // would spend the one visible line saying nothing.
+                type: "details",
+                summary: where,
+                blocks: [
+                    {
+                        type: "kv",
+                        rows: [
+                            {
+                                label: "Matches",
+                                value: it.path === "/" ? "every path on this host" : `${it.path} and below`,
+                            },
+                            {
+                                label: "Until",
+                                value: it.scope === undefined ? "remove()" : "the end of this test",
+                            },
+                        ],
+                    },
                 ],
             },
         ],
-        durationMs: 0,
+        // No duration: this is a marker for the moment the interceptor went
+        // up, and "(0 ms)" reads as a step that did nothing.
     }, resv);
     if (seq !== undefined)
         INTERCEPT_STEP_SEQ.set(it.id, seq);

package/dist/harness/intercept.d.ts

@@ -48,6 +48,12 @@ export interface InterceptedRequest {
      *  upstream via `next()` untouched (`upstream`), or the upstream's answer
      *  replaced by the interceptor after `next()` (`modified`). */
     answeredBy: "handler" | "upstream" | "modified";
+    /** The handler threw (or returned something that is not a `Response`), so
+     *  the 500 below is a bug in the test's own middleware rather than the
+     *  outage it was asked to produce. The distinction cannot be recovered
+     *  from the status: a deliberate 500 and a crashed handler are the same
+     *  number, and only this tells the timeline which one to mark as wrong. */
+    threw?: boolean;
 }
 export interface Interceptor {
     id: number;
@@ -61,6 +67,22 @@ export interface Interceptor {
     calls: number;
     requests: InterceptedRequest[];
 }
+/**
+ * Split an intercept target — `app.test`, `app.test/api/sync`,
+ * `*.example.com/v1` — into the hostname and the mount path.
+ *
+ * The path rides the target rather than a second argument because that is
+ * what it is: part of what the interceptor claims, not a separate knob. It
+ * also keeps the signature down to one string, so the description that
+ * follows can never be mistaken for a path.
+ *
+ * A scheme is tolerated (`https://app.test/api`) since that is how the same
+ * address is written everywhere else.
+ */
+export declare function parseTarget(target: string): {
+    hostname: string;
+    path: string;
+};
 /** Mount semantics (`app.use(path, fn)`): `/api` matches `/api`, `/api/`, `/api/x`, and
  *  never `/apix`. `/` matches everything. Query strings do not take part. */
 export declare function pathMounts(mount: string, pathname: string): boolean;

package/dist/harness/intercept.js

@@ -33,6 +33,34 @@
  * plain `Request`/`Response` objects.
  */
 import { isWildcard, wildcardSuffix } from "./hostmatch";
+/**
+ * Split an intercept target — `app.test`, `app.test/api/sync`,
+ * `*.example.com/v1` — into the hostname and the mount path.
+ *
+ * The path rides the target rather than a second argument because that is
+ * what it is: part of what the interceptor claims, not a separate knob. It
+ * also keeps the signature down to one string, so the description that
+ * follows can never be mistaken for a path.
+ *
+ * A scheme is tolerated (`https://app.test/api`) since that is how the same
+ * address is written everywhere else.
+ */
+export function parseTarget(target) {
+    if (typeof target !== "string" || target.trim() === "") {
+        throw new Error("intercept: a target hostname is required, e.g. \"app.test\" or \"app.test/api\"");
+    }
+    const bare = target.trim().toLowerCase().replace(/^[a-z][a-z0-9+.-]*:\/\//, "");
+    const slash = bare.indexOf("/");
+    const hostname = slash === -1 ? bare : bare.slice(0, slash);
+    const rest = slash === -1 ? undefined : bare.slice(slash);
+    if (hostname === "") {
+        throw new Error(`intercept: target ${JSON.stringify(target)} names no hostname — write it as "app.test/api", not "/api"`);
+    }
+    if (hostname.includes("?") || hostname.includes("#")) {
+        throw new Error(`intercept: target ${JSON.stringify(target)} cannot carry a query or fragment`);
+    }
+    return { hostname, path: normalizeMount(rest) };
+}
 /** Mount semantics (`app.use(path, fn)`): `/api` matches `/api`, `/api/`, `/api/x`, and
  *  never `/apix`. `/` matches everything. Query strings do not take part. */
 export function pathMounts(mount, pathname) {
@@ -159,6 +187,7 @@ export async function runChain(chain, req, upstream, observe) {
             res = new Response(`spectest-daemon: interceptor for ${it.hostname} threw: ${e?.message ?? String(err)}\n`, { status: 500, headers: { "content-type": "text/plain" } });
             record.answeredBy = "handler";
             record.status = 500;
+            record.threw = true;
             it.calls++;
             it.requests.push(record);
             observe?.(it, record, Date.now() - started);

package/dist/index.d.ts

@@ -14,6 +14,7 @@ export { McpHttpError, McpRpcError, McpAuthDeniedError, type Mcp, type McpOption
 import type { Mcp, McpOptions } from "./mcp.js";
 export type { Locator, GetByRoleOptions, GetByTextOptions, FilterOptions, ClickOptions, BoundingBox, FilePayload, InputFiles, } from "./locator.js";
 import type { Locator } from "./locator.js";
+import { type TextMatchOptions } from "./text-match.js";
 export type { UrlPattern } from "./url-match.js";
 import type { UrlPattern } from "./url-match.js";
 export type { Mobile, MobileApp } from "./mobile.js";
@@ -34,7 +35,8 @@ export type { InterceptHandler, InterceptNext, InterceptedRequest };
  */
 export interface Interception {
     hostname: string;
-    /** The normalised mount path (`"/"` when none was given). */
+    /** The normalised mount path parsed off the target (`"/"` when the
+     *  target was a bare hostname). */
     path: string;
     /** How many requests the interceptor has seen. Provenance-wrapped, so an
      *  `expect(outage.calls)` nests under the intercept step; `.unwrap()` for
@@ -381,12 +383,23 @@ export interface SpectestContext<S extends ServicesMap = ServicesMap, F extends
      * make your **own** backend misbehave for one test: force a 500 from an
      * API route, add latency, fail twice then pass, or just count calls.
      *
+     * `target` is the hostname, optionally with a mount path:
+     * `"app.test"` claims every request to that host, `"app.test/api/sync"`
+     * claims that path and everything below it (like `app.use(path, fn)`).
+     *
+     * `description` is what the environment now **does**, in the present
+     * tense — it is the step's whole title in the timeline and in the CLI's
+     * failure detail, so it is what tells a reader why the page under test
+     * went to its error state. Write the effect, not the act of intercepting
+     * (the step is already labelled INTERCEPT) and not the test's goal:
+     * `"the sync endpoint returns 503"`, not `"intercept sync"`, `"mock the
+     * API"` or `"test error handling"`. The handler's own source is shown
+     * under it, so the description carries the intent, never the mechanism.
+     *
      * Hono/Koa-style middleware: `(req, next)` where `next()` returns the real upstream's
      * response (a proxied service, or a fake). Return a `Response` to answer
      * yourself, `next()` to pass through, or change what `next()` returned.
-     * An optional mount `path` limits it to that path and everything below
-     * (`"/functions/v1/sync"`), like `app.use(path, fn)`. Interceptors run in
-     * registration order.
+     * Interceptors run in registration order.
      *
      * Only traffic that reaches the daemon can be intercepted: the browser,
      * `ctx.fetch`, and any container that calls the hostname — so the service
@@ -400,16 +413,18 @@ export interface SpectestContext<S extends ServicesMap = ServicesMap, F extends
      * `remove()`. Every request it sees is recorded under the intercept step.
      *
      * ```ts
-     * const outage = ctx.intercept("api.test", "/functions/v1/sync", () =>
-     *   new Response("boom", { status: 500 }));
+     * const outage = ctx.intercept(
+     *   "api.test/functions/v1/sync",
+     *   "the sync function returns 500",
+     *   () => new Response("boom", { status: 500 }),
+     * );
      * await page.getByRole("button", { name: "Sync" }).click();
      * await expect(page.getByText("Retry")).toBeVisible();
      * expect(outage.calls).toBe(1);
      * outage.remove();                           // the retry now reaches the real function
      * ```
      */
-    intercept(hostname: string, handler: InterceptHandler): Interception;
-    intercept(hostname: string, path: string, handler: InterceptHandler): Interception;
+    intercept(target: string, description: string, handler: InterceptHandler): Interception;
     /**
      * Mint a leaf certificate from the in-VM root CA and return the PEMs.
      *
@@ -1672,6 +1687,14 @@ interface Matchers {
 export interface Expectation extends Matchers {
     not: Matchers;
 }
+/** Options for the text matchers — playwright's set, same names, same
+ *  meanings. */
+export interface TextMatcherOptions extends TextMatchOptions {
+    timeout?: number;
+    /** Read `innerText` (what the page renders — hidden elements dropped,
+     *  `text-transform` applied) instead of `textContent`. */
+    useInnerText?: boolean;
+}
 /**
  * Auto-retrying web-first assertions for a {@link Locator} — Playwright's
  * `expect(locator)` matchers. Each polls the element until it passes or a
@@ -1687,14 +1710,27 @@ export interface LocatorMatchers {
     toBeHidden(opts?: {
         timeout?: number;
     }): Promise<void>;
-    /** The element's (trimmed) text equals `expected` (or matches a RegExp). */
-    toHaveText(expected: string | RegExp, opts?: {
-        timeout?: number;
-    }): Promise<void>;
-    /** The element's text contains `expected`. */
-    toContainText(expected: string, opts?: {
-        timeout?: number;
-    }): Promise<void>;
+    /**
+     * 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.
+     * 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.
+     *
+     * Pass an **array** to assert over every element the locator matches, in
+     * order; the counts must then agree.
+     */
+    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}.
+     *
+     * An **array** asserts that the matched elements contain these texts in
+     * order; unlike `toHaveText` extra elements between them are allowed.
+     */
+    toContainText(expected: string | RegExp | Array<string | RegExp>, opts?: TextMatcherOptions): Promise<void>;
     /** The input's value equals `expected` (or matches a RegExp). */
     toHaveValue(expected: string | RegExp, opts?: {
         timeout?: number;