@rangojs/router 0.0.0-experimental.fb4fdc18 → 0.0.0-experimental.fce7fbd1

package/src/testing/flight.ts

@@ -0,0 +1,182 @@
+/// <reference path="./flight-runtime.d.ts" />
+/**
+ * renderToFlightString — REAL React Server Component (Flight) rendering for
+ * unit tests of @rangojs/router consumer apps.
+ *
+ * This module renders a server component tree to its Flight wire string using
+ * the same react-server-dom serializer the router uses at runtime. It runs in
+ * plain node (no Vite, no browser), but ONLY under the `react-server` export
+ * condition. The serializer is the VENDORED build shipped with
+ * @vitejs/plugin-rsc — the public `@vitejs/plugin-rsc/rsc` entry top-level
+ * imports Vite virtual modules and is not usable outside a Vite build.
+ *
+ * Run the example/tests for this module via the dedicated rsc vitest project
+ * (vitest.rsc.config.ts), which forces `--conditions=react-server` on the
+ * worker. The main vitest project must NOT use that condition (it would flip
+ * React to the no-hooks server build and break the ~50 tests that mock
+ * @vitejs/plugin-rsc/rsc).
+ *
+ * Scope / limitations (v1):
+ * - Server-only / leaf trees. A tree containing a CLIENT component emits an
+ *   `I[...]` import row whose module id will not resolve against the empty `{}`
+ *   client manifest used here — fine for snapshotting the SHAPE of the payload,
+ *   but the client reference cannot be executed/hydrated. The interactive DOM
+ *   render (`renderServer`) is deferred (see module TODO at bottom of report).
+ * - The vendored subpath is a private plugin-rsc path; a minor bump could move
+ *   it. `assertFlightRuntimeAvailable()` provides a smoke check.
+ * - For stable snapshots, run under NODE_ENV=production: the production
+ *   serializer drops the dev-only debug-info rows (the `N<timestamp>` reference
+ *   row, the per-component `stack`/`env` rows, and `D{...}` timing rows),
+ *   leaving just the rendered tree row(s).
+ */
+
+import type { ReactNode } from "react";
+// Vendored react-server-dom serializer. Resolves via plugin-rsc's
+// `"./*": "./dist/*.js"` export to
+// dist/vendor/react-server-dom/server.edge.js. Only loadable under the
+// `react-server` export condition.
+import * as RSDServer from "@vitejs/plugin-rsc/vendor/react-server-dom/server.edge";
+import {
+  createRequestContext,
+  runWithRequestContext,
+  setRequestContextParams,
+} from "../server/request-context.js";
+import type { RscPayload } from "../rsc/types.js";
+import type { ResolvedSegment } from "../types.js";
+
+/**
+ * Options for {@link renderToFlightString}.
+ */
+export interface RenderToFlightStringOptions {
+  /** Request URL. Defaults to `http://localhost/`. */
+  url?: string;
+  /** Request headers (e.g. Cookie) visible to the server tree. */
+  headers?: HeadersInit;
+  /** Env / bindings exposed as `ctx.env`. Defaults to `{}`. */
+  env?: unknown;
+  /** Route params exposed via `ctx.params` and loader contexts. */
+  params?: Record<string, string>;
+  /** Matched route name (drives `ctx.routeName` and scoped reverse). */
+  routeName?: string;
+}
+
+const DEFAULT_URL = "http://localhost/";
+
+/**
+ * Wrap a single element in the minimal ResolvedSegment + RscPayload shape that
+ * mirrors Rango's wire format, so the serialized output matches what a real
+ * route segment would emit.
+ */
+function wrapAsPayload(element: ReactNode, pathname: string): RscPayload {
+  const segment: ResolvedSegment = {
+    id: "test",
+    namespace: "",
+    type: "route",
+    index: 0,
+    component: element,
+  };
+  return {
+    metadata: {
+      pathname,
+      segments: [segment],
+      version: "test",
+    },
+  };
+}
+
+/**
+ * Render a server component (or any ReactNode) to its Flight wire string.
+ *
+ * The element is wrapped in a minimal Rango segment + payload, then serialized
+ * with the vendored react-server-dom server. A request context is active for
+ * the duration of the render (drained INSIDE runWithRequestContext) so async
+ * server components can call getRequestContext(), read params, cookies, etc.
+ *
+ * Must run under the `react-server` export condition (see module header).
+ */
+export async function renderToFlightString(
+  element: ReactNode,
+  opts: RenderToFlightStringOptions = {},
+): Promise<string> {
+  const url = new URL(opts.url ?? DEFAULT_URL);
+  const request = new Request(url, { headers: opts.headers });
+  const ctx = createRequestContext({
+    env: opts.env ?? {},
+    request,
+    url,
+    variables: {},
+  });
+
+  const payload = wrapAsPayload(element, url.pathname);
+
+  return runWithRequestContext(ctx, async () => {
+    setRequestContextParams(opts.params ?? {}, opts.routeName);
+    // Capture (do NOT rethrow) the first render error. The serializer calls
+    // onError from its own scheduled work; throwing there escapes as an
+    // unhandled rejection AND leaves the stream un-closed, so the drain below
+    // would hang until the test times out. Production's onError returns void
+    // (rsc-rendering.ts) so the stream completes with an error row. We mirror
+    // that — let the stream finish — then surface the error as a clean
+    // rejection after draining, so `await expect(...).rejects.toThrow()` works.
+    let renderError: unknown;
+    let didError = false;
+    const stream = RSDServer.renderToReadableStream(
+      payload,
+      {},
+      {
+        onError(error: unknown) {
+          if (!didError) {
+            didError = true;
+            renderError = error;
+          }
+        },
+      },
+    );
+    // Drain inside the context so async components see ctx during streaming.
+    const text = await new Response(stream).text();
+    if (didError) throw renderError;
+    return text;
+  });
+}
+
+// Volatile leading reference row: `:N<timestamp>` (dev debug-info anchor).
+const REFERENCE_ROW_RE = /^:N[\d.]+\n/;
+// Absolute file:// paths embedded in dev STACK rows. The serializer emits stack
+// frames as `["Component","file:///abs/path.tsx",<line>,<col>,...]`, so the
+// path is a quoted JSON string immediately followed by `",<line>,<col>`. The
+// lookahead scopes the scrub to exactly that frame shape, leaving a legitimate
+// `file://` href in RENDERED content (e.g. `{"href":"file:///x"}`) untouched.
+const FILE_URL_RE = /file:\/\/[^"\\]+(?=",\d+,\d+)/g;
+
+/**
+ * Scrub volatile bits from a Flight string so snapshots are stable across runs
+ * and machines:
+ * - the leading `:N<timestamp>` reference row (dev only),
+ * - absolute `file://...` paths inside dev stack rows.
+ *
+ * Under NODE_ENV=production these rows are already absent; normalize is a
+ * no-op safety net there. In dev mode it removes the machine/clock-specific
+ * noise while leaving the rendered tree intact.
+ */
+export function normalizeFlight(flight: string): string {
+  return flight
+    .replace(REFERENCE_ROW_RE, "")
+    .replace(FILE_URL_RE, "file://<path>");
+}
+
+/**
+ * Smoke check that the vendored serializer subpath still resolves and exposes
+ * `renderToReadableStream`. The vendored path is private to plugin-rsc; a minor
+ * bump could relocate it. Call this in a test to fail loudly with a clear
+ * message instead of an opaque import error.
+ */
+export function assertFlightRuntimeAvailable(): void {
+  if (typeof RSDServer.renderToReadableStream !== "function") {
+    throw new Error(
+      "Vendored react-server-dom serializer not available: " +
+        "@vitejs/plugin-rsc/vendor/react-server-dom/server.edge did not export " +
+        "renderToReadableStream. The private vendored subpath may have moved in " +
+        "a plugin-rsc upgrade.",
+    );
+  }
+}

package/src/testing/generated-routes.ts

@@ -0,0 +1,223 @@
+/**
+ * assertGeneratedRoutesMatch — pin the generated named-routes map against the
+ * router's runtime route map.
+ *
+ * The Vite plugin writes a `*.named-routes.gen.ts` file mapping route names to
+ * URL patterns; consumers import that map and pass it here. The check compares
+ * it to the router's runtime `routeMap`, catching drift when a route is added,
+ * removed, renamed, or its pattern changes without regenerating the file.
+ *
+ * Directionality (relative to the generated map):
+ * - missing:  present in the generated map but NOT at runtime (stale entry).
+ * - extra:    present at runtime but NOT in the generated map (ungenerated route).
+ *             Auto-generated internal names (the "$path_" / "$prefix_" prefixes)
+ *             are excluded — they live in the runtime map but are never written
+ *             to the generated file, so they are not drift.
+ * - mismatch: present in both under the same name, but the patterns differ.
+ *
+ * When `generatedMap` is omitted, the global route map (getGlobalRouteMap()) is
+ * used as the generated side — useful when a single router has registered into
+ * the global map.
+ */
+
+import { getGlobalRouteMap } from "../route-map-builder.js";
+import { isAutoGeneratedRouteName } from "../route-name.js";
+
+/**
+ * Router shape this check depends on: a runtime route map, plus the optional
+ * `findMatch` used to force-expand lazy `include()`d routes (see below).
+ */
+interface RouterWithRouteMap {
+  routeMap: Record<string, unknown>;
+  findMatch?: (pathname: string) => unknown;
+}
+
+/**
+ * Derive a best-effort concrete path from a route pattern so `findMatch` can be
+ * invoked to expand a lazy include. `:param`, `:param(constraint)`, optional
+ * `:param?`, and `*` are all replaced with a literal segment. A constrained
+ * param may not match its constraint (so that one route's match fails), but
+ * since matching ANY route in an include expands ALL of the include's routes,
+ * a sibling route in the same include will still trigger expansion.
+ */
+function concretePath(pattern: string): string {
+  return (
+    pattern
+      .replace(/:[A-Za-z0-9_]+\([^)]*\)\??/g, "x") // :p(constraint) / optional
+      .replace(/:[A-Za-z0-9_]+\??/g, "x") // :p or :p?
+      .replace(/\*/g, "x") // wildcard
+      .replace(/\/{2,}/g, "/") || "/"
+  );
+}
+
+/**
+ * Force-expand the router's lazy `include()`d routes into `router.routeMap`.
+ *
+ * All Rango includes are lazy — their child routes only populate `routeMap` when
+ * the router first matches a path inside them (in production the build-time
+ * manifest virtual carries the full map; in a bare test that virtual is absent).
+ * To make the whole-app drift check work in a unit test, we trigger expansion by
+ * calling `findMatch` on a concrete path derived from each known pattern. This is
+ * idempotent and side-effect-free beyond populating the route map. Routers that
+ * don't expose `findMatch` (e.g. a plain `{ routeMap }` object) are left as-is.
+ */
+function expandLazyIncludes(
+  router: RouterWithRouteMap,
+  patterns: Iterable<string>,
+): void {
+  const findMatch = router.findMatch;
+  if (typeof findMatch !== "function") return;
+  for (const pattern of patterns) {
+    try {
+      findMatch.call(router, concretePath(pattern));
+    } catch {
+      // A pattern that fails to match (constrained param, etc.) is fine — a
+      // sibling route in the same include still triggers expansion.
+    }
+  }
+}
+
+/**
+ * A single name/pattern mismatch: [routeName, generatedPattern, runtimePattern].
+ */
+export type GeneratedRouteMismatch = [
+  name: string,
+  generated: string,
+  runtime: string,
+];
+
+/**
+ * Structured diff between the generated route map and the runtime route map.
+ */
+export interface GeneratedRoutesDiff {
+  /** Names in the generated map but absent at runtime. */
+  missing: string[];
+  /** Names at runtime but absent from the generated map. */
+  extra: string[];
+  /** Names in both with differing patterns. */
+  mismatch: GeneratedRouteMismatch[];
+  /** True when missing, extra, and mismatch are all empty. */
+  ok: boolean;
+}
+
+/**
+ * Normalize a route map value to its pattern string. Route maps may carry
+ * either a bare pattern string or a `{ path, ... }` object (for response/search
+ * routes); compare on the `path`.
+ */
+function patternOf(value: unknown): string {
+  if (typeof value === "string") return value;
+  if (
+    value &&
+    typeof value === "object" &&
+    "path" in value &&
+    typeof (value as { path: unknown }).path === "string"
+  ) {
+    return (value as { path: string }).path;
+  }
+  return String(value);
+}
+
+/**
+ * Compute the diff between a router's runtime route map and a generated map.
+ */
+export function diffGeneratedRoutes(
+  router: RouterWithRouteMap,
+  generatedMap?: Record<string, unknown>,
+): GeneratedRoutesDiff {
+  const generated = generatedMap ?? getGlobalRouteMap();
+
+  // Lazy `include()`d routes are absent from `routeMap` until first matched, so
+  // expand them first (using the generated patterns to drive the matches) —
+  // otherwise every included route is a false `missing`. No-op for plain
+  // `{ routeMap }` objects that don't expose `findMatch`.
+  expandLazyIncludes(
+    router,
+    Object.values(generated).map((v) => patternOf(v)),
+  );
+
+  const runtime = router.routeMap as Record<string, unknown>;
+
+  const missing: string[] = [];
+  const extra: string[] = [];
+  const mismatch: GeneratedRouteMismatch[] = [];
+
+  for (const name of Object.keys(generated)) {
+    if (!(name in runtime)) {
+      missing.push(name);
+      continue;
+    }
+    const gen = patternOf(generated[name]);
+    const run = patternOf(runtime[name]);
+    if (gen !== run) {
+      mismatch.push([name, gen, run]);
+    }
+  }
+
+  for (const name of Object.keys(runtime)) {
+    // Auto-generated internal names ($path_*/$prefix_*) live in the runtime
+    // mergedRouteMap but are deliberately excluded from the generated
+    // *.named-routes.gen.ts file (route-types-writer / runtime-discovery skip
+    // them). Reporting them as `extra` would throw on a perfectly in-sync app
+    // that simply uses an unnamed path()/include() route, so skip them here to
+    // match exactly the surface the generator emits.
+    if (isAutoGeneratedRouteName(name)) continue;
+    if (!(name in generated)) {
+      extra.push(name);
+    }
+  }
+
+  return {
+    missing,
+    extra,
+    mismatch,
+    ok: missing.length === 0 && extra.length === 0 && mismatch.length === 0,
+  };
+}
+
+/**
+ * Assert the router's runtime route map matches the generated map. Throws a
+ * descriptive Error listing every missing, extra, and mismatched route when
+ * they diverge.
+ *
+ * @example
+ * ```ts
+ * import generated from "./router.named-routes.gen";
+ * import { router } from "./router";
+ *
+ * assertGeneratedRoutesMatch(router, generated);
+ * ```
+ */
+export function assertGeneratedRoutesMatch(
+  router: RouterWithRouteMap,
+  generatedMap?: Record<string, unknown>,
+): void {
+  const diff = diffGeneratedRoutes(router, generatedMap);
+  if (diff.ok) return;
+
+  const lines: string[] = [
+    "Generated routes do not match the router's runtime route map.",
+  ];
+
+  if (diff.missing.length > 0) {
+    lines.push(
+      `  Missing (generated but not at runtime): ${diff.missing.join(", ")}`,
+    );
+  }
+  if (diff.extra.length > 0) {
+    lines.push(
+      `  Extra (at runtime but not generated): ${diff.extra.join(", ")}`,
+    );
+  }
+  if (diff.mismatch.length > 0) {
+    lines.push("  Pattern mismatches (name: generated -> runtime):");
+    for (const [name, gen, run] of diff.mismatch) {
+      lines.push(`    ${name}: ${gen} -> ${run}`);
+    }
+  }
+  lines.push(
+    "Re-run the build / `rango` route generation to regenerate the *.named-routes.gen.ts file.",
+  );
+
+  throw new Error(lines.join("\n"));
+}

package/src/testing/index.ts

@@ -0,0 +1,105 @@
+/**
+ * @rangojs/router/testing
+ *
+ * Consumer-facing testing primitives for apps built on @rangojs/router.
+ *
+ * This is the entry for UNIT and INTEGRATION tests, meant to run under a
+ * Vite-driven Vitest project (the rango Vite plugin must be active so the
+ * `@rangojs/router:version` and related virtual modules the router internals
+ * import can resolve; alternatively alias `@rangojs/router:version`). Importing
+ * this module references neither React, @testing-library/react, @playwright/test,
+ * nor the RSC runtime — a unit suite testing only loaders/middleware/dispatch
+ * pulls in none of them.
+ *
+ * The other surfaces are SEPARATE entries because each pulls a dependency or
+ * runtime this barrel deliberately keeps out:
+ * - `@rangojs/router/testing/dom` — `renderRoute` (the RTL component stub). Kept
+ *   separate so this barrel never references React, the browser runtime, or
+ *   `@testing-library/react` types — a unit suite testing only loaders/middleware
+ *   needs none of them.
+ * - `@rangojs/router/testing/e2e` — the Playwright harness (createRangoE2E,
+ *   useFixture, parityDescribe, expectParity, matchers). Kept separate so it is
+ *   loadable in a plain (non-Vite) Playwright runner, which cannot resolve the
+ *   router-manifest virtual modules this barrel pulls in.
+ * - `@rangojs/router/testing/flight` — real Flight rendering. Its serializer
+ *   (vendored react-server-dom) loads only under the `react-server` node
+ *   condition and would throw if pulled into this barrel.
+ *
+ * Layers:
+ * - Unit:        runMiddleware, runLoader
+ * - Integration: dispatch (request -> Response)
+ * - Cross-cut:   assertCacheStatus, assertGeneratedRoutesMatch
+ * - Component:   see @rangojs/router/testing/dom (renderRoute)
+ * - E2E:         see @rangojs/router/testing/e2e
+ * - RSC:         see @rangojs/router/testing/flight
+ */
+
+// Unit
+export { runMiddleware } from "./run-middleware.js";
+export type {
+  RunMiddlewareOptions,
+  RunMiddlewareResult,
+} from "./run-middleware.js";
+export { runLoader } from "./run-loader.js";
+export type {
+  RunLoaderOptions,
+  UseResolver,
+  TestLoaderContext,
+} from "./run-loader.js";
+
+// Integration
+export { dispatch } from "./dispatch.js";
+export type { DispatchOptions } from "./dispatch.js";
+
+// renderRoute lives at `@rangojs/router/testing/dom` — it pulls React, the
+// browser runtime, and @testing-library/react types, which this barrel keeps
+// out so node-only unit suites depend on none of them.
+
+// Cross-cutting: cache/prerender status
+export {
+  assertCacheStatus,
+  parseCacheHeader,
+  createCacheSink,
+  filterCacheDecisions,
+} from "./cache-status.js";
+export type {
+  ExpectedCacheStatus,
+  CacheStatusTarget,
+  CacheSink,
+} from "./cache-status.js";
+
+// Cross-cutting: handle collect/accumulator
+export { collectHandle } from "./collect-handle.js";
+
+// Cross-cutting: generated-route drift
+export {
+  diffGeneratedRoutes,
+  assertGeneratedRoutesMatch,
+} from "./generated-routes.js";
+export type {
+  GeneratedRoutesDiff,
+  GeneratedRouteMismatch,
+} from "./generated-routes.js";
+
+// Advanced: build a real RequestContext for bespoke loader/middleware setups
+export {
+  createTestRequestContext,
+  runInRequestContext,
+  toRequest,
+  seedVariables,
+} from "./internal/context.js";
+export type {
+  CreateTestContextOptions,
+  TestRequestContext,
+  VarsInit,
+} from "./internal/context.js";
+
+// The low-level context runner that enters a RequestContext (the same one the
+// RSC handler uses for server actions). Re-exported so a ctx built with
+// createTestRequestContext can be entered directly; runInRequestContext is the
+// one-call convenience over createTestRequestContext + runWithRequestContext.
+export { runWithRequestContext } from "../server/request-context.js";
+
+// The E2E harness is NOT re-exported here: it must be imported from
+// `@rangojs/router/testing/e2e` so it stays loadable in a plain Playwright
+// runner (this barrel pulls in router-manifest code that needs Vite virtuals).