@specific.dev/spectest 0.26.0 → 0.28.0

package/dist/index.js

@@ -0,0 +1,769 @@
+// Spectest SDK. The user's single `spectest/index.ts` calls
+// `defineEnvironment({ name, services })` once, defines test cases via
+// the returned `env.test(...)`, and default-exports `env.project([...])`.
+// The daemon loads this file on boot and the control plane talks to it
+// over HTTP.
+import { strict as nodeAssert } from "node:assert";
+import { recordAssertion, safeSerialize } from "./recorder.js";
+import { adoptNullishTag, readRaw, readTag } from "./inspect.js";
+// `field` — a provenance-preserving, null-safe selector: a `null`/`undefined`
+// leaf read off a wrapped op result is raw and untagged, so an `expect(...)` on
+// it renders detached from its source op; `field` tags from the container so the
+// assertion still nests. (A decoded value loses provenance the same way — that
+// case is the `.transform(label, fn)` method every wrapped value carries, which
+// runs the still-tagged value through `fn` and re-wraps the result.)
+// To recover a raw value, call `.unwrap()` on it — spectest op results are
+// always wrapped (in every context), so the method is always there; there is no
+// `unwrap(x)` free function. See the `.unwrap()` discipline section of `spectest docs`.
+export { field } from "./inspect.js";
+// Instrumented client primitives — drop-in replacements for Bun's native
+// clients that record each operation on the test event log and return their
+// results inspect-wrapped, so `expect(...)` on a result links back to the op
+// in the timeline (same provenance mechanism as the wrapped `fetch`). Reach
+// for these over the raw `Bun.*` clients in service `helpers` and tests so
+// assertions stay tracked. See `sql.ts` / `redis.ts` / `s3.ts`.
+export { SQL } from "./sql.js";
+export { RedisClient } from "./redis.js";
+export { S3Client } from "./s3.js";
+import { isLocator, getLocatorProbe, DEFAULT_ACTION_TIMEOUT_MS } from "./locator.js";
+// Low-level ingress primitives + the framework lowering that the friendly
+// `tls` / `hostnames` fields and `defineFake(...)` are built on. See
+// `ingress.ts`.
+export { certificate, dnsName, proxy, provides, lowerIngress, isWildcard, SELF_SERVICE_TOKEN, } from "./ingress.js";
+// ──────────────────────────────────────────────────────────────────────────
+// Service groups — one services-map entry that expands to several services.
+//
+// A single container is a `ServiceConfig`/`ServiceDefinition`; a component
+// that is inherently a *constellation* of containers (Supabase ≈ 7 of them)
+// is a `ServiceGroup`. The user mounts the whole group under ONE key:
+//
+//   services: { supabase: sb.group, app: { ... } }
+//
+// and `defineEnvironment` expands it: the group's `primary` part takes the
+// group's own key (`supabase`), every other part lands at `<key>-<part>`
+// (`supabase-db`, `supabase-auth`, …). Inside the group, `dependsOn`
+// entries naming a relative part are rewritten to the final keys, so a
+// group author never manually prefixes anything. Groups are pure sugar —
+// they expand to plain services before validation, so the wire config the
+// control plane sees is unchanged.
+// ──────────────────────────────────────────────────────────────────────────
+/** Symbol marking a value in the services map as a group to expand.
+ * Enumerable-symbol convention (like the ingress `provides` decls): it
+ * survives object spread but `JSON.stringify` drops it — not that a group
+ * ever reaches the wire; expansion happens before the config exists. */
+const SERVICE_GROUP = Symbol.for("spectest.service.group");
+/**
+ * Define a multi-service group. See {@link ServiceGroupInput} for the
+ * fields; the result goes straight into a services map:
+ *
+ * ```ts
+ * const stack = serviceGroup({
+ *   primary: "gateway",
+ *   services: (g) => ({
+ *     db:      { image: ..., ... },
+ *     gateway: { image: ..., env: { DB_URL: `postgres://${g.key("db")}:5432/db` },
+ *                dependsOn: ["db"] },
+ *   }),
+ *   helpers: () => ({ url: "http://..." }),
+ * });
+ *
+ * defineEnvironment({ name: "app", services: { stack } });
+ * // expands to services `stack` (the gateway) + `stack-db`;
+ * // ctx.svc.stack is the helpers record.
+ * ```
+ */
+export function serviceGroup(input) {
+    if (typeof input.services !== "function") {
+        throw new Error("serviceGroup: `services` must be a factory function");
+    }
+    if (!input.primary || typeof input.primary !== "string") {
+        throw new Error("serviceGroup: `primary` (a relative part name) is required");
+    }
+    const group = { ...input };
+    Object.defineProperty(group, SERVICE_GROUP, {
+        value: true,
+        enumerable: true,
+        configurable: true,
+        writable: false,
+    });
+    return group;
+}
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+function isServiceGroup(v) {
+    return (typeof v === "object" &&
+        v !== null &&
+        v[SERVICE_GROUP] === true);
+}
+/**
+ * Runtime counterpart of {@link ExpandServices}: expand every group entry
+ * into plain services. Throws on key collisions, a missing primary,
+ * nested groups, a violated `expectKey`, and members depending on the
+ * primary (the primary is the group's sink — see
+ * {@link ServiceGroupInput.primary}).
+ */
+function expandServiceGroups(input) {
+    const out = {};
+    const ownerOf = new Map();
+    const claim = (key, owner) => {
+        const prior = ownerOf.get(key);
+        if (prior !== undefined) {
+            throw new Error(`service key ${JSON.stringify(key)} is produced by both ${prior} and ${owner}`);
+        }
+        ownerOf.set(key, owner);
+    };
+    for (const [key, entry] of Object.entries(input)) {
+        if (!isServiceGroup(entry)) {
+            claim(key, "the services map");
+            out[key] = entry;
+            continue;
+        }
+        const owner = `group ${JSON.stringify(key)}`;
+        if (entry.expectKey !== undefined && entry.expectKey !== key) {
+            throw new Error(`service group at key ${JSON.stringify(key)} expects to be mounted at ` +
+                `${JSON.stringify(entry.expectKey)} — its derived names (URLs, app env) were built ` +
+                `from that name. Mount it at ${JSON.stringify(entry.expectKey)}, or pass ` +
+                `\`name: ${JSON.stringify(key)}\` to the component so both agree.`);
+        }
+        const naming = {
+            name: key,
+            key: (part) => (part === entry.primary ? key : `${key}-${part}`),
+        };
+        const parts = entry.services(naming);
+        const partKeys = new Set(Object.keys(parts));
+        if (!partKeys.has(entry.primary)) {
+            throw new Error(`${owner}: primary part ${JSON.stringify(entry.primary)} is not in the parts the ` +
+                `services factory returned (${[...partKeys].join(", ")})`);
+        }
+        // No member may depend on the primary (directly or transitively within
+        // the group): the primary is about to become the group's sink.
+        const reachesPrimary = (part, seen = new Set()) => {
+            if (seen.has(part))
+                return false;
+            seen.add(part);
+            for (const dep of parts[part]?.dependsOn ?? []) {
+                if (!partKeys.has(dep))
+                    continue;
+                if (dep === entry.primary || reachesPrimary(dep, seen))
+                    return true;
+            }
+            return false;
+        };
+        for (const part of partKeys) {
+            if (isServiceGroup(parts[part])) {
+                throw new Error(`${owner}: part ${JSON.stringify(part)} is itself a group — groups don't nest`);
+            }
+            if (part !== entry.primary && reachesPrimary(part)) {
+                throw new Error(`${owner}: part ${JSON.stringify(part)} depends on the primary ` +
+                    `${JSON.stringify(entry.primary)} — the primary must be the group's sink ` +
+                    `(everything else becomes its dependency so "primary ready" means "group up")`);
+            }
+        }
+        for (const [part, svc] of Object.entries(parts)) {
+            const finalKey = naming.key(part);
+            claim(finalKey, owner);
+            // Rewrite relative dependsOn to final keys; a spread keeps function
+            // fields (helpers/setup) and the enumerable-symbol ingress decls.
+            const final = { ...svc };
+            if (svc.dependsOn?.length) {
+                final.dependsOn = svc.dependsOn.map((d) => partKeys.has(d) ? naming.key(d) : d);
+            }
+            if (part === entry.primary) {
+                // Sink: the primary waits for every other member, so an outside
+                // `dependsOn: ["<groupKey>"]` (and the group `setup` below) means
+                // the whole group. Members already in dependsOn stay put.
+                const deps = new Set(final.dependsOn ?? []);
+                for (const other of partKeys) {
+                    if (other !== entry.primary)
+                        deps.add(naming.key(other));
+                }
+                final.dependsOn = [...deps];
+                const def = final;
+                if (entry.helpers) {
+                    if (def.helpers) {
+                        throw new Error(`${owner}: both the group and its primary part declare \`helpers\` — ` +
+                            `declare them once, on the group`);
+                    }
+                    def.helpers = entry.helpers;
+                }
+                if (entry.setup) {
+                    const partSetup = def.setup;
+                    const groupSetup = entry.setup;
+                    def.setup = async (args) => {
+                        if (partSetup)
+                            await partSetup(args);
+                        await groupSetup(args);
+                    };
+                }
+            }
+            out[finalKey] = final;
+        }
+    }
+    return out;
+}
+function validateEnvironmentConfig(config) {
+    const entries = Object.entries(config.services);
+    const serviceNames = new Set(entries.map(([n]) => n));
+    const claimedBy = new Map();
+    const claimBy = (h, name, kind) => {
+        const prior = claimedBy.get(h);
+        if (prior !== undefined && prior !== name) {
+            throw new Error(`hostname ${JSON.stringify(h)} is claimed by both "${prior}" and "${name}"`);
+        }
+        if (serviceNames.has(h)) {
+            throw new Error(`${kind} ${JSON.stringify(h)} collides with service name "${h}"`);
+        }
+        claimedBy.set(h, name);
+    };
+    for (const [name, svc] of entries) {
+        if (name.length === 0) {
+            throw new Error("service name (services map key) must be a non-empty string");
+        }
+        for (const dep of svc.dependsOn ?? []) {
+            if (!serviceNames.has(dep)) {
+                throw new Error(`service "${name}" dependsOn "${dep}" which is not a service in this environment`);
+            }
+        }
+        for (const vol of svc.volumes ?? []) {
+            if (vol.name !== undefined && vol.source !== undefined) {
+                throw new Error(`service "${name}" volume for ${JSON.stringify(vol.target)} sets both \`name\` and \`source\` — a named shared volume derives its backing dir from the name`);
+            }
+            if (vol.name !== undefined && !/^[A-Za-z0-9][A-Za-z0-9_.-]*$/.test(vol.name)) {
+                throw new Error(`service "${name}" volume name ${JSON.stringify(vol.name)} must be alphanumeric plus [._-]`);
+            }
+        }
+        for (const raw of svc.hostnames ?? []) {
+            const h = raw.toLowerCase();
+            if (!HOSTNAME_RE.test(h)) {
+                throw new Error(`service "${name}" declares invalid hostname ${JSON.stringify(raw)} — must be a multi-label DNS name (e.g. "api.stripe.com")`);
+            }
+            if (h === "internal" || h.endsWith(".internal")) {
+                throw new Error(`service "${name}" declares hostname ${JSON.stringify(raw)} — the ".internal" TLD is reserved; every service already answers to "<name>.internal" automatically`);
+            }
+            claimBy(h, name, "hostname");
+        }
+        for (const entry of svc.tls ?? []) {
+            if (!entry || typeof entry.hostname !== "string" || typeof entry.port !== "number") {
+                throw new Error(`service "${name}" tls entry must be { hostname: string, port: number }; got ${JSON.stringify(entry)}`);
+            }
+            const h = entry.hostname.toLowerCase();
+            if (!HOSTNAME_RE.test(h)) {
+                throw new Error(`service "${name}" tls hostname ${JSON.stringify(entry.hostname)} is not a multi-label DNS name (e.g. "app.test")`);
+            }
+            if (h === "internal" || h.endsWith(".internal")) {
+                throw new Error(`service "${name}" tls hostname ${JSON.stringify(entry.hostname)} ends in reserved ".internal" TLD`);
+            }
+            if (!Number.isInteger(entry.port) || entry.port <= 0 || entry.port > 65535) {
+                throw new Error(`service "${name}" tls hostname ${JSON.stringify(entry.hostname)} has invalid port ${entry.port}`);
+            }
+            claimBy(h, name, "tls");
+        }
+    }
+}
+// Multi-label hostname: at least one dot, each label 1–63 chars of
+// [a-z0-9-], no leading/trailing hyphen.
+const HOSTNAME_RE = /^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?(\.[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?)+$/;
+/**
+ * Define a fake. `defineFake({ ... })` is a thin wrapper that pins the
+ * generic `S` and `H` so `helpers`/`handler` see the inferred state type
+ * without the caller having to spell it out twice.
+ */
+export function defineFake(opts) {
+    if (!opts.name || opts.name.length === 0) {
+        throw new Error("defineFake: `name` is required");
+    }
+    if (!Array.isArray(opts.hostnames) || opts.hostnames.length === 0) {
+        throw new Error(`defineFake(${opts.name}): at least one hostname is required`);
+    }
+    for (const h of opts.hostnames) {
+        const lower = h.toLowerCase();
+        if (!HOSTNAME_RE.test(lower)) {
+            throw new Error(`defineFake(${opts.name}): invalid hostname ${JSON.stringify(h)} — must be a multi-label DNS name (e.g. "api.stripe.com")`);
+        }
+        if (lower === "internal" || lower.endsWith(".internal")) {
+            throw new Error(`defineFake(${opts.name}): hostname ${JSON.stringify(h)} ends in reserved ".internal" TLD`);
+        }
+    }
+    if (typeof opts.handler !== "function") {
+        throw new Error(`defineFake(${opts.name}): \`handler\` is required`);
+    }
+    return opts;
+}
+/**
+ * Define an environment and get back a builder you can hang tests off.
+ * The builder's `.test(...)` returns test cases typed against the
+ * environment's services (and any declared `fakes`), and `.project([...])`
+ * produces the file's default export.
+ */
+export function defineEnvironment(input) {
+    // Split fakes off the wire config and expand service groups; only
+    // { name, services, timeoutSecs } — with plain, fully-expanded services —
+    // is stored as `config` and shipped to the control plane.
+    const { fakes, services: rawServices, ...rest } = input;
+    const config = {
+        ...rest,
+        services: expandServiceGroups(rawServices),
+    };
+    validateEnvironmentConfig(config);
+    if (fakes)
+        validateFakes(config, fakes);
+    // Every test created via this env's `.test(...)` is registered here. A
+    // split-layout project keeps its tests in `spectest/tests/**` — each file
+    // imports this `env` (for types + `dependsOn` refs) and calls `env.test`,
+    // which appends to `registry`. The daemon imports those files and then
+    // reads the suite back off the default-exported Project's lazy `tests`
+    // getter (installed in `project()` below). Keeping the env definition
+    // itself free of test bodies is what lets the warm-template cache key
+    // ignore test edits — see `project_content_hash` in the control plane.
+    const registry = [];
+    const test = ((name, optsOrFn, maybeFn) => {
+        const tc = buildTestCase(name, optsOrFn, maybeFn);
+        registry.push(tc);
+        return tc;
+    });
+    function project(arg) {
+        const opts = Array.isArray(arg)
+            ? { tests: arg }
+            : (arg ?? {});
+        const proj = { environment: config };
+        if (opts.setup)
+            proj.setup = opts.setup;
+        if (fakes)
+            proj.fakes = fakes;
+        if (opts.tests && opts.tests.length > 0) {
+            // Explicit suite (single-file / legacy layout): the tests are listed
+            // right here, so freeze them now.
+            proj.tests = validateSuite({ tests: opts.tests });
+        }
+        else {
+            // Split layout: tests are defined in separate files and collected from
+            // the registry as those files are imported. Expose them lazily so the
+            // daemon sees whatever has registered by the time it reads `.tests`
+            // (i.e. after it has imported `spectest/tests/**` on `/load-tests`).
+            Object.defineProperty(proj, "tests", {
+                enumerable: true,
+                configurable: true,
+                get() {
+                    return registry.length > 0
+                        ? validateSuite({ tests: [...registry] })
+                        : undefined;
+                },
+            });
+        }
+        return proj;
+    }
+    return {
+        config,
+        test,
+        project,
+    };
+}
+/**
+ * Cross-check fakes against the environment's services: no duplicate
+ * hostnames, no collisions with service names or service hostnames, and
+ * each fake's name is unique (the user passed a map, so JS guarantees
+ * the second condition — but we re-check defensively for the case where
+ * an object literal is built programmatically).
+ */
+function validateFakes(env, fakes) {
+    const claimedByService = new Map();
+    for (const [svcName, svc] of Object.entries(env.services)) {
+        claimedByService.set(svcName.toLowerCase(), svcName);
+        claimedByService.set(`${svcName.toLowerCase()}.internal`, svcName);
+        for (const h of svc.hostnames ?? []) {
+            claimedByService.set(h.toLowerCase(), svcName);
+        }
+        for (const entry of svc.tls ?? []) {
+            claimedByService.set(entry.hostname.toLowerCase(), svcName);
+        }
+    }
+    const claimedByFake = new Map();
+    for (const [key, fake] of Object.entries(fakes)) {
+        if (!fake || typeof fake !== "object" || typeof fake.handler !== "function") {
+            throw new Error(`fake ${JSON.stringify(key)} is not a FakeDefinition — pass the result of defineFake({...})`);
+        }
+        for (const raw of fake.hostnames) {
+            const h = raw.toLowerCase();
+            const owningSvc = claimedByService.get(h);
+            if (owningSvc !== undefined) {
+                throw new Error(`fake ${JSON.stringify(key)} hostname ${JSON.stringify(raw)} collides with service ${JSON.stringify(owningSvc)}`);
+            }
+            const owningFake = claimedByFake.get(h);
+            if (owningFake !== undefined && owningFake !== key) {
+                throw new Error(`hostname ${JSON.stringify(raw)} is claimed by both fake ${JSON.stringify(owningFake)} and fake ${JSON.stringify(key)}`);
+            }
+            claimedByFake.set(h, key);
+        }
+    }
+}
+// `buildTestCase` is the runtime implementation behind every typed
+// `env.test(...)`. The DefinedEnvironment exposes it cast to TypedTest<S>
+// so callers see the strongly-typed overloads while the body stays
+// generic — TestFn is contravariant in `ctx`, so a single implementation
+// satisfies every TypedTest<S>.
+function buildTestCase(name, 
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+optsOrFn, 
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+maybeFn) {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const [opts, fn] = typeof optsOrFn === "function" ? [{}, optsOrFn] : [optsOrFn, maybeFn];
+    if (typeof fn !== "function") {
+        throw new TypeError(`test(${JSON.stringify(name)}): missing test function`);
+    }
+    return {
+        id: slugify(name),
+        name,
+        dependsOn: opts.dependsOn,
+        timeoutMs: opts.timeoutMs,
+        run: fn,
+    };
+}
+function validateSuite(suite) {
+    const seenIds = new Map();
+    for (const t of suite.tests) {
+        const prior = seenIds.get(t.id);
+        if (prior !== undefined) {
+            throw new Error(`duplicate test id "${t.id}" (from ${JSON.stringify(prior)} and ${JSON.stringify(t.name)}) — rename one`);
+        }
+        seenIds.set(t.id, t.name);
+    }
+    // Validate that each dependsOn ref is in the suite. Catches typos /
+    // imports forgotten in the tests array.
+    for (const t of suite.tests) {
+        if (t.dependsOn && !suite.tests.includes(t.dependsOn)) {
+            throw new Error(`test "${t.name}" depends on "${t.dependsOn.name}" which is not in the suite`);
+        }
+    }
+    return suite;
+}
+function slugify(name) {
+    const slug = name
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "");
+    if (!slug) {
+        throw new Error(`cannot derive id from test name ${JSON.stringify(name)}`);
+    }
+    return slug;
+}
+// ──────────────────────────────────────────────────────────────────────────
+// Assertions
+// ──────────────────────────────────────────────────────────────────────────
+export class ExpectationError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "ExpectationError";
+    }
+}
+export function expect(actual, message) {
+    if (isLocator(actual))
+        return buildLocatorAssertion(actual, message);
+    return expectValue(actual, message);
+}
+function expectValue(actual, message) {
+    // The first parameter is typed to the {@link Provenanced} family so a raw
+    // value (`expect(res.status === 200)`, `expect(2 + 2)`) is a *compile error* —
+    // every assertion that reaches the timeline this way carries a provenance link
+    // back to the op that produced it. Assert on a genuinely raw value with
+    // `expectRaw(value, message)` instead.
+    //
+    // `message` is an **optional** human label for the assertion. The UI already
+    // renders the target, matcher, and expected value, so a message that just
+    // restates them is noise — supply one *only* when the check's intent isn't
+    // obvious from those alone (e.g.
+    // `expect(res.status, "blocked once the rate limit trips").toBe(429)`). When
+    // present it leads the assertion's summary, the same way `expectRaw`'s does.
+    //
+    // A `null`/`undefined` read off a wrapped op result reaches here untagged
+    // (a symbol can't ride on nullish). `adoptNullishTag` recovers the tag from
+    // the proxy's most-recent nullish-leaf note and mints a tagged holder, so
+    // `expect(dep.status.readyReplicas).toBeFalsy()` nests under its op just like
+    // a non-nullish read. Done once here (not in `buildMatchers`) so the `.not`
+    // re-pass reuses the same tagged holder instead of re-consuming the note.
+    return buildMatchers(adoptNullishTag(actual), false, message);
+}
+// ── expect(locator): auto-retrying web-first matchers ─────────────────────
+/** Poll interval for locator matchers. */
+const LOCATOR_POLL_MS = 50;
+function buildLocatorAssertion(loc, message) {
+    return Object.assign(buildLocatorMatchers(loc, false, message), {
+        not: buildLocatorMatchers(loc, true, message),
+    });
+}
+function buildLocatorMatchers(loc, negated, message) {
+    const probe = getLocatorProbe(loc);
+    // Poll `check` (a silent, non-recorded read) until the desired condition
+    // holds or the deadline elapses, then emit ONE settled browser step (the
+    // locator label + replay seek point) and record ONE assertion nested under
+    // it via `sourceSeq` — so a web-first `expect(locator)` assertion carries
+    // the same provenance a value assertion does (`expect(await loc.isVisible())`
+    // renders identically). Without the anchor step these assertions floated as
+    // disconnected top-level "value ✓" rows with no element and no replay seek.
+    // `check` returns whether the base condition is satisfied plus the observed
+    // value for the timeline.
+    const run = async (matcher, timeout, check, describe, expected) => {
+        const started = Date.now();
+        const deadline = started + (timeout ?? DEFAULT_ACTION_TIMEOUT_MS);
+        let actual;
+        for (;;) {
+            let satisfied;
+            try {
+                const r = await check();
+                satisfied = r.satisfied;
+                actual = r.actual;
+            }
+            catch (err) {
+                if (Date.now() < deadline) {
+                    await new Promise((r) => setTimeout(r, LOCATOR_POLL_MS));
+                    continue;
+                }
+                satisfied = false;
+                actual = `<error: ${err?.message ?? String(err)}>`;
+            }
+            const passed = satisfied !== negated;
+            if (passed) {
+                const sourceSeq = await probe.settle(matcher, Date.now() - started);
+                recordAssertion({
+                    matcher,
+                    negated,
+                    passed: true,
+                    actual: safeSerialize(actual),
+                    expected: expected === undefined ? undefined : safeSerialize(expected),
+                    message,
+                    sourceSeq,
+                });
+                return;
+            }
+            if (Date.now() >= deadline) {
+                const msg = describe(actual);
+                const sourceSeq = await probe.settle(matcher, Date.now() - started, msg);
+                recordAssertion({
+                    matcher,
+                    negated,
+                    passed: false,
+                    actual: safeSerialize(actual),
+                    expected: expected === undefined ? undefined : safeSerialize(expected),
+                    error: msg,
+                    message,
+                    sourceSeq,
+                });
+                throw new ExpectationError(msg);
+            }
+            await new Promise((r) => setTimeout(r, LOCATOR_POLL_MS));
+        }
+    };
+    const not = negated ? " not" : "";
+    const matchesText = (v, expected) => expected instanceof RegExp ? expected.test(v) : v === expected;
+    return {
+        toBeVisible: (opts) => run("toBeVisible", opts?.timeout, async () => {
+            const v = await probe.isVisible();
+            return { satisfied: v, actual: v };
+        }, () => `expected ${probe.label}${not} to be visible`),
+        toBeHidden: (opts) => run("toBeHidden", opts?.timeout, async () => {
+            const v = await probe.isVisible();
+            return { satisfied: !v, actual: v };
+        }, () => `expected ${probe.label}${not} to be hidden`),
+        toHaveText: (expected, opts) => run("toHaveText", opts?.timeout, async () => {
+            const t = (await probe.textContent(opts?.timeout)) ?? "";
+            return { satisfied: matchesText(t.trim(), expected), actual: t };
+        }, (a) => `expected ${probe.label}${not} to have text ${fmt(expected)}, got ${fmt(a)}`, expected instanceof RegExp ? String(expected) : expected),
+        toContainText: (expected, opts) => run("toContainText", opts?.timeout, async () => {
+            const t = (await probe.textContent(opts?.timeout)) ?? "";
+            return { satisfied: t.includes(expected), actual: t };
+        }, (a) => `expected ${probe.label}${not} to contain text ${fmt(expected)}, got ${fmt(a)}`, expected),
+        toHaveValue: (expected, opts) => run("toHaveValue", opts?.timeout, async () => {
+            const v = await probe.inputValue(opts?.timeout);
+            return { satisfied: matchesText(v, expected), actual: v };
+        }, (a) => `expected ${probe.label}${not} to have value ${fmt(expected)}, got ${fmt(a)}`, expected instanceof RegExp ? String(expected) : expected),
+        toHaveCount: (expected, opts) => run("toHaveCount", opts?.timeout, async () => {
+            const c = await probe.count();
+            return { satisfied: c === expected, actual: c };
+        }, (a) => `expected ${probe.label}${not} to have count ${expected}, got ${fmt(a)}`, expected),
+        toBeEnabled: (opts) => run("toBeEnabled", opts?.timeout, async () => {
+            const v = await probe.isEnabled(opts?.timeout);
+            return { satisfied: v, actual: v };
+        }, () => `expected ${probe.label}${not} to be enabled`),
+        toBeDisabled: (opts) => run("toBeDisabled", opts?.timeout, async () => {
+            const v = await probe.isEnabled(opts?.timeout);
+            return { satisfied: !v, actual: v };
+        }, () => `expected ${probe.label}${not} to be disabled`),
+        toBeChecked: (opts) => run("toBeChecked", opts?.timeout, async () => {
+            const v = await probe.isChecked(opts?.timeout);
+            return { satisfied: v, actual: v };
+        }, () => `expected ${probe.label}${not} to be checked`),
+    };
+}
+/**
+ * Assert on a value with **no provenance** — a computed number, a raw
+ * WebSocket frame, anything that didn't flow from a recorded op. `message` is
+ * required (it's the second argument) and reads as the natural follow-on to
+ * "assert …" (e.g. `expectRaw(id, "id matches the generated value")`); it
+ * renders as the assertion's label in the CLI/dashboard ("ASSERT <message>")
+ * since a raw assertion has no op to nest under. Prefer `expect(...)` whenever
+ * the value carries provenance — only reach for this when the type gate would
+ * (rightly) reject the value. (`expect`'s own `message` is optional; here it is
+ * mandatory, since the label is the only human-meaningful summary a raw
+ * assertion has.)
+ */
+export function expectRaw(actual, message) {
+    // Force the raw form so no stray tag is read even if a wrapped value is
+    // passed: an `expectRaw` assertion is *deliberately* unlinked, rendered at
+    // top level under its own message rather than nested beneath an op.
+    return buildMatchers(readRaw(actual), false, message);
+}
+function buildMatchers(wrapped, negated, message) {
+    // If `wrapped` is an inspect-tagged value (from fetch / db / browser),
+    // pull its origin metadata and run matchers against the raw underlying
+    // value. Plain `expect(value)` is unaffected. Tag + raw are read once here
+    // and threaded explicitly into `buildCore`, so `.not` and transforms re-pass
+    // them directly instead of re-reading the wrapper (and re-consuming any
+    // adopted nullish note).
+    return buildCore(readRaw(wrapped), readTag(wrapped), negated, message);
+}
+/**
+ * The matcher/transform factory, working off an already-unwrapped `actual` and
+ * an explicit `tag`. `pendingError`, when set, marks a transform that failed
+ * upstream: every matcher then records a failed assertion carrying that error
+ * (irrespective of negation) and throws, and further transforms propagate it.
+ */
+function buildCore(actual, tag, negated, message, pendingError) {
+    // Wraps a matcher: it computes the raw condition, the failure message,
+    // records the assertion event, then throws iff the result is a failure.
+    // `expectedFor` lets matchers record their expected value where it
+    // makes sense (toBe / toEqual / toContain / toMatch) while matchers
+    // like toBeTruthy leave it unset.
+    const run = (matcher, cond, msg, expectedFor, opts) => {
+        // A failed upstream transform short-circuits every matcher to a failure —
+        // there is no meaningful value to match, and negation can't rescue a value
+        // that never decoded — so we record `pendingError` and throw regardless of
+        // `cond`/`negated`.
+        if (pendingError !== undefined) {
+            recordAssertion({
+                matcher,
+                negated,
+                passed: false,
+                actual: safeSerialize(actual),
+                expected: expectedFor === undefined ? undefined : safeSerialize(expectedFor),
+                error: pendingError,
+                message,
+                sourceSeq: tag?.sourceSeq,
+                path: tag ? [...tag.path] : undefined,
+            });
+            throw new ExpectationError(pendingError);
+        }
+        const passed = cond !== negated;
+        recordAssertion({
+            matcher,
+            negated,
+            passed,
+            actual: safeSerialize(opts && "actual" in opts ? opts.actual : actual),
+            expected: expectedFor === undefined ? undefined : safeSerialize(expectedFor),
+            error: passed ? undefined : msg,
+            message,
+            sourceSeq: tag?.sourceSeq,
+            path: tag ? [...tag.path] : undefined,
+        });
+        if (!passed)
+            throw new ExpectationError(msg);
+    };
+    return {
+        toBe(expected) {
+            const exp = readRaw(expected);
+            run("toBe", Object.is(actual, exp), `expected ${fmt(actual)}${negated ? " not" : ""} to be ${fmt(exp)}`, exp);
+        },
+        toEqual(expected) {
+            const exp = readRaw(expected);
+            let equal = true;
+            try {
+                nodeAssert.deepStrictEqual(actual, exp);
+            }
+            catch {
+                equal = false;
+            }
+            run("toEqual", equal, `expected ${fmt(actual)}${negated ? " not" : ""} to deep-equal ${fmt(exp)}`, exp);
+        },
+        toBeTruthy() {
+            run("toBeTruthy", !!actual, `expected ${fmt(actual)}${negated ? " not" : ""} to be truthy`);
+        },
+        toBeFalsy() {
+            run("toBeFalsy", !actual, `expected ${fmt(actual)}${negated ? " not" : ""} to be falsy`);
+        },
+        toBeGreaterThan(n) {
+            run("toBeGreaterThan", typeof actual === "number" && actual > n, `expected ${fmt(actual)}${negated ? " not" : ""} to be > ${n}`, n);
+        },
+        toBeLessThan(n) {
+            run("toBeLessThan", typeof actual === "number" && actual < n, `expected ${fmt(actual)}${negated ? " not" : ""} to be < ${n}`, n);
+        },
+        toBeGreaterThanOrEqual(n) {
+            run("toBeGreaterThanOrEqual", typeof actual === "number" && actual >= n, `expected ${fmt(actual)}${negated ? " not" : ""} to be >= ${n}`, n);
+        },
+        toBeLessThanOrEqual(n) {
+            run("toBeLessThanOrEqual", typeof actual === "number" && actual <= n, `expected ${fmt(actual)}${negated ? " not" : ""} to be <= ${n}`, n);
+        },
+        toContain(expected) {
+            const exp = readRaw(expected);
+            let contained = false;
+            if (typeof actual === "string" && typeof exp === "string") {
+                contained = actual.includes(exp);
+            }
+            else if (Array.isArray(actual)) {
+                contained = actual.some((v) => {
+                    try {
+                        nodeAssert.deepStrictEqual(v, exp);
+                        return true;
+                    }
+                    catch {
+                        return false;
+                    }
+                });
+            }
+            run("toContain", contained, `expected ${fmt(actual)}${negated ? " not" : ""} to contain ${fmt(exp)}`, exp);
+        },
+        toMatch(re) {
+            run("toMatch", typeof actual === "string" && re.test(actual), `expected ${fmt(actual)}${negated ? " not" : ""} to match ${re}`, String(re));
+        },
+        toHaveLength(n) {
+            // Provenance-preserving count assertion. A wrapped array's `.length`
+            // is deliberately raw (so `rows.length === 1` works), which means
+            // `expect(rows.length)` can't link back to the originating op —
+            // pass the container itself instead: `expect(rows).toHaveLength(1)`
+            // keeps the tag, and we read the length off the raw value here.
+            const len = typeof actual === "string" || Array.isArray(actual)
+                ? actual.length
+                : actual !== null &&
+                    typeof actual === "object" &&
+                    typeof actual.length === "number"
+                    ? actual.length
+                    : undefined;
+            // The provenance `path` stays the container's own path — `.length` is
+            // the matcher's internal read, not a property access the author wrote,
+            // so it doesn't belong in the path (recording it produced a redundant
+            // "length toHaveLength N" in the UI, since the matcher name already says
+            // "length"). `actual` is still the length number: that's what's worth
+            // showing on failure, and the `toHaveLength` matcher disambiguates it.
+            run("toHaveLength", len === n, `expected ${fmt(actual)}${negated ? " not" : ""} to have length ${n}` +
+                (len === undefined ? " (value has no length)" : ` (got ${len})`), n, { actual: len });
+        },
+        get not() {
+            // Re-pass the already-unwrapped value, tag and message so the tag and raw
+            // label are preserved for the negated branch's AssertionEvent.
+            return buildCore(actual, tag, !negated, message, pendingError);
+        },
+    };
+}
+function fmt(v) {
+    if (typeof v === "string")
+        return JSON.stringify(v);
+    if (typeof v === "bigint")
+        return `${v}n`;
+    if (v === undefined)
+        return "undefined";
+    try {
+        return JSON.stringify(v);
+    }
+    catch {
+        return String(v);
+    }
+}
+/** `node:assert/strict` re-exported for users who prefer Node's built-in API. */
+export const assert = nodeAssert;