@rangojs/router 0.0.0-experimental.f3c21dba → 0.0.0-experimental.f4a8e8de

package/src/testing/flight.entry.ts

@@ -0,0 +1,52 @@
+/**
+ * @rangojs/router/testing/flight
+ *
+ * Real React Server Component (Flight) rendering for unit tests. This entry is
+ * SEPARATE from the main ./testing barrel because its serializer (the vendored
+ * react-server-dom build) can only be imported under the `react-server` node
+ * condition; importing it elsewhere throws. Use it only from a Vitest project
+ * configured with that condition (see vitest.rsc.config.ts) — name those test
+ * files `*.rsc-test.{ts,tsx}` and run `pnpm test:unit:rsc`.
+ *
+ * This entry deliberately does NOT pull in Vitest. The `toMatchFlight` /
+ * `toMatchFlightSnapshot` matchers (which import `vitest`) live at the separate
+ * `@rangojs/router/testing/flight-matchers` subpath, so a consumer can import
+ * `renderToFlightString` without taking a hard dependency on Vitest.
+ *
+ * `renderToFlightString` returns the wire STRING (for `toMatchFlight`).
+ * `renderServerTree` additionally deserializes it back to an inspectable React
+ * element tree, so you can assert typed prop fidelity across the client boundary
+ * (a `Date` comes back a `Date`) and detect inlined-vs-island. Serialize +
+ * deserialize only — no hydration/interaction (that is the e2e tier).
+ */
+
+export {
+  renderToFlightString,
+  normalizeFlight,
+  assertFlightRuntimeAvailable,
+} from "./flight.js";
+export type { RenderToFlightStringOptions } from "./flight.js";
+
+export {
+  renderServerTree,
+  findClientBoundaries,
+  findElements,
+  textContent,
+  assertFlightTreeRuntimeAvailable,
+} from "./flight-tree.js";
+export type {
+  RenderServerTreeOptions,
+  RenderServerTreeResult,
+  ClientBoundary,
+  BoundarySelector,
+  FoundElement,
+  ElementSelector,
+} from "./flight-tree.js";
+
+export { renderHandler } from "./render-handler.js";
+export type {
+  TestableHandler,
+  RenderHandlerOptions,
+  RenderHandlerResult,
+  StateCookieSeed,
+} from "./render-handler.js";

package/src/testing/flight.ts

@@ -0,0 +1,257 @@
+/// <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.
+ *   To inspect a client boundary's deserialized props instead, use
+ *   `renderServerTree` (flight-tree.ts). Interactive hydration stays at the e2e tier.
+ * - 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 { seedVariables, type VarsInit } from "./internal/seed-vars.js";
+import { normalizeFlight } from "./flight-normalize.js";
+import { resolveThemeConfig } from "../theme/constants.js";
+import type { ThemeConfig } from "../theme/types.js";
+import type { SegmentCacheStore } from "../cache/types.js";
+import type { CacheProfile } from "../cache/profile-registry.js";
+import type { RscPayload } from "../rsc/types.js";
+import type { ResolvedSegment } from "../types.js";
+
+// Re-export from the serializer-free module so this entry's public surface is
+// unchanged while flight-matchers can import normalizeFlight without pulling in
+// the vendored serializer (which throws outside the react-server condition).
+export { normalizeFlight };
+
+/**
+ * Options for {@link renderToFlightString}.
+ */
+export interface RenderToFlightStringOptions {
+  /**
+   * The request the render runs under: a `Request`, or a URL string (absolute or
+   * path). Defaults to `http://localhost/`. A server component reading
+   * `getRequestContext()` sees this request's url/cookies. When a `Request` is
+   * passed, its headers are used and `headers` below is ignored.
+   */
+  request?: Request | string;
+  /** Request headers (e.g. Cookie) visible to the server tree (when `request` is a string). */
+  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;
+  /**
+   * Route name -> pattern map enabling a SCOPED `ctx.reverse()` (like
+   * `renderHandler`). Without it, a server component that reverses resolves
+   * against the GLOBAL route map and is order-dependent on whatever router
+   * registered last. Pass the router-under-test's map to make reversing
+   * deterministic.
+   */
+  routeMap?: Record<string, string>;
+  /**
+   * Context variables visible to the rendered tree via `ctx.get(...)` — as a
+   * prior middleware would have set them. Seeds the SAME way the handler-test
+   * primitives (`runInRequestContext`/`runLoader`) do, so a server component
+   * that reads `getRequestContext().get(MyVar)` during render is testable.
+   * Object form (`{ user }`) or `[key, value]` tuples (`[[userVar, u]]`).
+   */
+  vars?: VarsInit;
+  /**
+   * Theme config in the same shape `createRouter({ theme })` takes (e.g. `true`
+   * or `{ themes: [...] }`). Without it `getRequestContext().theme` is `undefined`
+   * and `ctx.setTheme` is inert — pass one to render a server component that
+   * reads `ctx.theme`. Threaded into the SAME createRequestContext renderHandler
+   * uses, so the two Flight primitives expose theme identically.
+   */
+  theme?: ThemeConfig | true;
+  /**
+   * Cache store backing a `"use cache"` function the rendered server tree
+   * invokes. Without it, `registerCachedFunction` takes the uncached bypass and
+   * the cached path is NOT exercised. Pair with `cacheProfiles` so a
+   * `"use cache: profileName"` directive resolves its profile.
+   */
+  cacheStore?: SegmentCacheStore;
+  /** Cache profiles in the `createRouter({ cacheProfiles })` shape. */
+  cacheProfiles?: Record<string, CacheProfile>;
+}
+
+const DEFAULT_URL = "http://localhost/";
+
+/**
+ * True when `error` is the out-of-react-server stub thrown by index.ts's
+ * server-only exports (getRequestContext/cookies/headers/...) — i.e. the bare
+ * `@rangojs/router` specifier resolved to index.ts, not index.rsc.ts, because
+ * the rsc Vitest project is missing the `rangoTestAliases` alias. Matches both
+ * substrings of `serverOnlyStubError` (index.ts) so a normal app error cannot
+ * over-match. Shared with render-handler.ts so the two Flight primitives report
+ * the same misconfiguration identically.
+ */
+export function isServerOnlyStubError(error: unknown): boolean {
+  return (
+    error instanceof Error &&
+    error.message.includes("is only available from") &&
+    error.message.includes("react-server")
+  );
+}
+
+/**
+ * Rethrow a server tree render error. When it is the missing-rsc-alias stub
+ * (above), rethrow an actionable message naming `rangoTestAliases` instead of
+ * the opaque stub text; otherwise rethrow the original unchanged. Classify the
+ * ORIGINAL error before constructing the wrapper so the wrapper's `Original: ...`
+ * echo (which re-embeds the matched substrings) never re-triggers the predicate.
+ */
+function rethrowFlightRenderError(error: unknown): never {
+  if (isServerOnlyStubError(error)) {
+    throw new Error(
+      `The server component called a server-only API ` +
+        `(getRequestContext/cookies/headers/...) but "@rangojs/router" resolved to ` +
+        `the out-of-react-server stub. Add rangoTestAliases({ preset }) to your ` +
+        `vitest.rsc.config.ts \`resolve.alias\` so the bare specifier maps to ` +
+        `index.rsc.ts (the real react-server implementations). ` +
+        `Original: ${(error as Error).message}`,
+    );
+  }
+  throw error;
+}
+
+export function assertNoLegacyUrlOption(opts: object, fnName: string): void {
+  if ("url" in opts) {
+    throw new Error(
+      `${fnName}: the \`url\` option was renamed to \`request\`. Pass ` +
+        `{ request: "<url-or-path>" } (or a Request) instead of { url }. ` +
+        `The legacy \`url\` key is ignored, so the render would silently use ` +
+        `the default origin.`,
+    );
+  }
+}
+
+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> {
+  assertNoLegacyUrlOption(opts, "renderToFlightString");
+  return serializeToFlightString(element, opts, {});
+}
+
+export async function serializeToFlightString(
+  element: ReactNode,
+  opts: RenderToFlightStringOptions,
+  clientManifest: unknown,
+): Promise<string> {
+  const request =
+    opts.request instanceof Request
+      ? opts.request
+      : new Request(new URL(opts.request ?? DEFAULT_URL, DEFAULT_URL), {
+          headers: opts.headers,
+        });
+  const url = new URL(request.url);
+  const ctx = createRequestContext({
+    env: opts.env ?? {},
+    request,
+    url,
+    variables: seedVariables({}, opts.vars),
+    themeConfig:
+      opts.theme === undefined ? undefined : resolveThemeConfig(opts.theme),
+    cacheStore: opts.cacheStore,
+    cacheProfiles: opts.cacheProfiles,
+  });
+
+  return runWithRequestContext(ctx, () => {
+    setRequestContextParams(opts.params ?? {}, opts.routeName, opts.routeMap);
+    return serializeNodeToFlight(element, clientManifest, url.pathname);
+  });
+}
+
+export async function serializeNodeToFlight(
+  node: ReactNode,
+  clientManifest: unknown,
+  pathname: string,
+): Promise<string> {
+  const payload = wrapAsPayload(node, pathname);
+  let renderError: unknown;
+  let didError = false;
+  const stream = RSDServer.renderToReadableStream(payload, clientManifest, {
+    onError(error: unknown) {
+      if (!didError) {
+        didError = true;
+        renderError = error;
+      }
+    },
+  });
+  const text = await new Response(stream).text();
+  if (didError) rethrowFlightRenderError(renderError);
+  return text;
+}
+
+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,199 @@
+/**
+ * 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 is async (it may await an async include provider's import before
+  // the route's names are spliced into routeMap), so expandLazyIncludes awaits
+  // it. Typed `unknown` (not `unknown | Promise<unknown>`, which collapses to
+  // the same thing) — the awaited value is never read, only its side effect.
+  findMatch?: (pathname: string) => unknown;
+}
+
+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, "/") || "/"
+  );
+}
+
+async function expandLazyIncludes(
+  router: RouterWithRouteMap,
+  patterns: Iterable<string>,
+): Promise<void> {
+  const findMatch = router.findMatch;
+  if (typeof findMatch !== "function") return;
+  for (const pattern of patterns) {
+    try {
+      // Await: an async include(`() => import()`) resolves its module + splices
+      // its routes into routeMap only after findMatch's Promise settles. Without
+      // the await, the routeMap read below races the import and reports the
+      // split-group routes as missing.
+      await findMatch.call(router, concretePath(pattern));
+    } catch (e) {
+      // A findMatch throw here is almost always a failing async include()
+      // provider (its `() => import()` rejected). Surface it — swallowed, it
+      // resurfaces downstream as a misleading "missing route" in the diff.
+      console.warn(
+        `[@rangojs/router] assertGeneratedRoutesMatch: could not expand include ` +
+          `for "${pattern}": ${(e as Error)?.message ?? String(e)}`,
+      );
+    }
+  }
+}
+
+/**
+ * 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;
+}
+
+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);
+}
+
+export async function diffGeneratedRoutes(
+  router: RouterWithRouteMap,
+  generatedMap?: Record<string, unknown>,
+): Promise<GeneratedRoutesDiff> {
+  const generated = generatedMap ?? getGlobalRouteMap();
+
+  await 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)) {
+    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";
+ *
+ * await assertGeneratedRoutesMatch(router, generated);
+ * ```
+ */
+export async function assertGeneratedRoutesMatch(
+  router: RouterWithRouteMap,
+  generatedMap?: Record<string, unknown>,
+): Promise<void> {
+  const diff = await 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,121 @@
+/**
+ * @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, assertShellStatus, assertGeneratedRoutesMatch
+ * - Component:   see @rangojs/router/testing/dom (renderRoute)
+ * - E2E:         see @rangojs/router/testing/e2e
+ * - RSC:         see @rangojs/router/testing/flight
+ */
+
+export { runMiddleware } from "./run-middleware.js";
+export type {
+  RunMiddlewareOptions,
+  RunMiddlewareResult,
+} from "./run-middleware.js";
+export { runLoader, runLoaderResult } from "./run-loader.js";
+export type {
+  RunLoaderOptions,
+  RunLoaderResult,
+  UseResolver,
+  TestLoaderContext,
+} from "./run-loader.js";
+
+export { runTransitionWhen } from "./run-transition-when.js";
+export type {
+  RunTransitionWhenOptions,
+  RunTransitionWhenResult,
+} from "./run-transition-when.js";
+
+export { dispatch } from "./dispatch.js";
+export type { DispatchOptions } from "./dispatch.js";
+
+export {
+  assertCacheStatus,
+  assertCacheDecision,
+  parseCacheHeader,
+  createCacheSink,
+  filterCacheDecisions,
+} from "./cache-status.js";
+export type {
+  ExpectedCacheStatus,
+  CacheStatusTarget,
+  CacheSink,
+} from "./cache-status.js";
+export type {
+  TelemetryEvent,
+  TelemetrySink,
+  CacheDecisionEvent,
+  CacheSegmentSignal,
+  CacheSegmentStatus,
+} from "../router/telemetry.js";
+
+export {
+  assertPprReplayStatus,
+  assertShellStatus,
+  parsePprReplayStatus,
+  parseShellStatus,
+  PPR_REPLAY_STATUS_HEADER,
+  shellCacheKey,
+  SHELL_STATUS_HEADER,
+} from "./shell-status.js";
+export type {
+  PprReplayBypassReason,
+  PprReplayStatus,
+  ShellStatus,
+  ShellStatusTarget,
+} from "./shell-status.js";
+
+export { collectHandle } from "./collect-handle.js";
+
+export {
+  diffGeneratedRoutes,
+  assertGeneratedRoutesMatch,
+} from "./generated-routes.js";
+export type {
+  GeneratedRoutesDiff,
+  GeneratedRouteMismatch,
+} from "./generated-routes.js";
+
+export {
+  createTestRequestContext,
+  runInRequestContext,
+  toRequest,
+  seedVariables,
+} from "./internal/context.js";
+export type {
+  CreateTestContextOptions,
+  TestRequestContext,
+  TestRequestContextObject,
+  RunInRequestContextResult,
+  VarsInit,
+  StateCookieSeed,
+} from "./internal/context.js";
+
+export { runWithRequestContext } from "../server/request-context.js";