@rangojs/router 0.0.0-experimental.bd6e11bc → 0.0.0-experimental.bdaf10aa

package/src/testing/render-route.tsx

@@ -14,14 +14,19 @@
  * (de)serialization. Consequences:
  *   - It will NOT catch server/client boundary reference-identity remount bugs
  *     (a server-serialized component reference differing from the client
- *     reference). Use renderServer / e2e for those.
+ *     reference). Use renderServerTree / e2e for those.
  *   - It will NOT catch real Flight serialization errors (non-serializable
  *     props crossing the RSC boundary), loader execution on the server,
- *     middleware, or handler ordering. Those are renderServer / e2e territory.
+ *     middleware, or handler ordering. Those are renderServerTree / renderHandler
+ *     / e2e territory.
  *   - Loader data, location state, and handle output are SEEDED directly into
  *     client context (see the `loaders` / `locationState` / `handles` options) —
  *     nothing is executed on the server. This exercises the read path
  *     (useLoader / useLocationState / useHandle from context), not the run path.
+ *   - navigate() commits synchronously, so it does NOT drive the navigation
+ *     lifecycle: useNavigation().state, useLinkStatus().pending, and
+ *     useAction().state stay "idle". Assert pending/loading/submitting transition
+ *     states with renderServerTree / e2e instead (navigate() warns once if used).
  * What it DOES cover: client hooks that read NavigationProvider /
  * OutletContext — useParams, useReverse, useHref, useMount, useNavigation,
  * useRouter, usePathname, useSearchParams, Outlet nesting, useLoader /
@@ -41,17 +46,22 @@ import {
   generateHistoryKey,
 } from "../browser/navigation-store.js";
 import { createEventController } from "../browser/event-controller.js";
+import { resolveDeferredHandleValues } from "../handles/deferred-resolution.js";
 import type { NavigationStore, NavigationBridge } from "../browser/types.js";
 import type { EventController } from "../browser/event-controller.js";
 import type { ResolvedSegment, RscMetadata } from "../browser/types.js";
 import { NavigationProvider } from "../browser/react/NavigationProvider.js";
-import { compilePattern } from "../router/pattern-matching.js";
+import {
+  compilePattern,
+  buildParamsFromMatch,
+} from "../router/pattern-matching.js";
 import { normalizeBasename } from "../router/basename.js";
 import type { LoaderDefinition } from "../types.js";
 import type { LocationStateDefinition } from "../browser/react/location-state-shared.js";
 import type { Handle } from "../handle.js";
 import type { ThemeConfig } from "../theme/types.js";
 import { resolveThemeConfig } from "../theme/constants.js";
+import { isUnderTestRunner } from "../runtime-env.js";
 
 const TEST_ORIGIN = "http://localhost";
 
@@ -62,11 +72,6 @@ const TEST_ORIGIN = "http://localhost";
  */
 export type HandleDataSeed = Record<string, Record<string, unknown[]>>;
 
-// Loaders and location-state defs carry an id (`$$id` / `__rsc_ls_key`) that the
-// Vite plugin injects at build time; in a bare test it is "". These helpers
-// assign a synthetic stable id (mutating the handle, tracked per-object) so that
-// seeding by reference lines up with the read path (useLoader / useLocationState
-// both read the id off the handle at call time).
 const syntheticIds = new WeakMap<object, string>();
 let syntheticIdCounter = 0;
 
@@ -85,7 +90,6 @@ function ensureSyntheticId(
   return id;
 }
 
-/** One-level clone of a raw handle seed so we don't mutate the caller's object. */
 function cloneHandleSeed(seed?: HandleDataSeed): HandleDataSeed {
   const out: HandleDataSeed = {};
   for (const [name, segMap] of Object.entries(seed ?? {})) {
@@ -94,17 +98,11 @@ function cloneHandleSeed(seed?: HandleDataSeed): HandleDataSeed {
   return out;
 }
 
-/**
- * One node of the route definition passed to renderRoute. The array models a
- * single matched route plus its optional layout chain — element order is
- * outermost layout first, the leaf route last (the same root-to-leaf order the
- * real matcher produces).
- */
 export interface RenderRouteSpec {
   /**
    * The route pattern this node matches, e.g. "/products/:productId". The LAST
    * spec in the array is treated as the leaf route; earlier specs are layouts
-   * wrapping it. Only the leaf pattern is matched against `initialUrl` to
+   * wrapping it. Only the leaf pattern is matched against the `request` URL to
    * extract params; layout patterns are informational.
    */
   path: string;
@@ -131,8 +129,13 @@ export interface RenderRouteSpec {
  * Options for renderRoute.
  */
 export interface RenderRouteOptions {
-  /** Initial URL to render at. Defaults to the leaf spec's static prefix or "/". */
-  initialUrl?: string;
+  /**
+   * The initial location to render at: a `Request`, or a URL string (absolute or
+   * path). Only the URL is read (this is a client render — headers/method are
+   * ignored); named `request` for parity with the other primitives. Defaults to
+   * the leaf spec's static prefix or "/".
+   */
+  request?: Request | string;
   /**
    * Loader data to seed into client context, keyed by loader id ($$id). A
    * component calling useLoader(SomeLoader) reads `loaderData[SomeLoader.$$id]`.
@@ -148,16 +151,28 @@ export interface RenderRouteOptions {
    * Passing `[loader, data]` pairs lets renderRoute assign a synthetic stable id
    * and wire `useLoader` to it. Prefer this over `loaderData` for real handles.
    *
+   * NOTE: when a real handle has no `$$id`, renderRoute MUTATES it to assign a
+   * synthetic stable id (so repeat renders key consistently). This is a side
+   * effect on your input object; a handle reused across tests keeps that id.
+   *
    * @example
+   * // useLoader returns an ENVELOPE — destructure `data`, it is not the bare value.
+   * function CartBadge() {
+   *   const { data } = useLoader(CartLoader); // NOT `useLoader(CartLoader).itemCount`
+   *   return <span>{data.itemCount}</span>;
+   * }
    * renderRoute([{ path: "/cart", Component: CartBadge }], {
    *   loaders: [[CartLoader, { itemCount: 3, total: 89.97 }]],
    * });
    */
   loaders?: ReadonlyArray<readonly [LoaderDefinition<any>, unknown]>;
   /**
-   * Explicit params. Merged over (and overriding) params extracted from
-   * `initialUrl`. Use this when the URL alone cannot express the params, or to
-   * avoid relying on URL parsing.
+   * Explicit params. Merged over (and overriding) params extracted from the
+   * `request` URL. Use this when the URL alone cannot express the params, or to
+   * avoid relying on URL parsing. Supplying params also OPTS OUT of the
+   * request/leaf match check: a `request` whose pathname does not resolve the
+   * leaf is normally rejected under the test runner, but passing params here
+   * tells renderRoute the request is intentionally not the param source.
    */
   params?: Record<string, string>;
   /**
@@ -221,6 +236,10 @@ export interface RenderRouteOptions {
    * exactly as `renderSegments` does in production (a segment whose `mountPath`
    * is set is wrapped in a MountContextProvider). Normalized like a path prefix
    * (leading slash forced, trailing stripped, bare "/" -> root). Defaults to "/".
+   * An explicitly-passed `request` must match the leaf `path` directly (paths are
+   * include-RELATIVE; the mount does NOT rewrite the request) — pass the relative
+   * path, not the mount-prefixed one, or renderRoute throws rather than silently
+   * rendering empty params.
    *
    * @example
    * renderRoute([{ path: "/c/wine", Component: ProductPage }], { mount: "/shop" });
@@ -235,6 +254,20 @@ export interface RenderRouteOptions {
    * component.
    */
   theme?: ThemeConfig | true;
+  /**
+   * CSP nonce to seed via NonceContext, so a component calling `useNonce()`
+   * (e.g. an analytics/GTM head-script component) sees this value — mirroring
+   * what the SSR renderer provides per request. Defaults to undefined (the
+   * browser default), matching production client behavior.
+   *
+   * @example
+   * const { getByTestId } = await renderRoute(
+   *   [{ path: "/", Component: NonceProbe }],
+   *   { nonce: "test-nonce" },
+   * );
+   * expect(getByTestId("nonce").textContent).toBe("test-nonce");
+   */
+  nonce?: string;
 }
 
 /**
@@ -266,11 +299,6 @@ interface ResolvedMatch {
   pathname: string;
 }
 
-/**
- * Match a pathname against the leaf spec's pattern and extract params.
- * Returns null when the pattern does not match (params then fall back to the
- * caller-provided `options.params`).
- */
 function matchLeaf(
   pattern: string,
   pathname: string,
@@ -278,17 +306,11 @@ function matchLeaf(
   const compiled = compilePattern(pattern);
   const match = compiled.regex.exec(pathname);
   if (!match) return null;
-  const params: Record<string, string> = {};
-  compiled.paramNames.forEach((name, index) => {
-    const value = match[index + 1];
-    if (value !== undefined) {
-      params[name] = decodeURIComponent(value);
-    }
-  });
-  return params;
+  // Reuse the production param builder so the harness matches the real matcher
+  // exactly (named catch-all "" binding, decoding) instead of forking it.
+  return buildParamsFromMatch(match, compiled.paramNames, compiled.catchAll);
 }
 
-/** Derive a usable initial pathname from a leaf pattern when none is given. */
 function staticPrefix(pattern: string): string {
   const out: string[] = [];
   for (const part of pattern.split("/")) {
@@ -299,13 +321,6 @@ function staticPrefix(pattern: string): string {
   return "/" + out.join("/");
 }
 
-/**
- * Build the synthetic ResolvedSegment[] for a matched route. Produces, in
- * root-to-leaf order: one layout segment per non-leaf spec, then the leaf route
- * segment, plus a loader segment for each seeded loader id attached to the
- * owning spec. Segment ids follow the real convention (L0, L0L1, ..., the leaf
- * route as L0...R{n}; loaders as {parentId}D{i}.{loaderId}).
- */
 function buildSegments(
   routes: RenderRouteSpec[],
   params: Record<string, string>,
@@ -338,20 +353,13 @@ function buildSegments(
       params,
       belongsToRoute: true,
     };
-    // Model an include() mount: every component segment in the chain shares the
-    // same prefix, so renderSegments wraps each in a MountContextProvider and
-    // useMount() resolves the mounted prefix (production sets mountPath on every
-    // segment of an included subtree). Must be applied identically at both
-    // buildSegments call sites or segment-structure-assert flags a remount.
     if (mount) node.mountPath = mount;
-    // A leaf-owned layout component wraps the route via its own layout element.
     if (isLeaf && spec.layout) {
       const Layout = spec.layout;
       node.layout = <Layout />;
     }
     segments.push(node);
 
-    // Determine which seeded loader ids this spec owns.
     const ownedIds = spec.loaderIds
       ? spec.loaderIds.filter((id) => id in loaderData)
       : isLeaf
@@ -375,30 +383,6 @@ function buildSegments(
   return segments;
 }
 
-/**
- * Render a CLIENT component (and its layout chain) inside the router's
- * NavigationProvider for unit testing. Exported from `@rangojs/router/testing/dom`
- * (its own entry, kept out of the main `@rangojs/router/testing` barrel so that
- * barrel never references React/@testing-library/react). Async so the heavy
- * @testing-library/react dependency is loaded only at call time.
- *
- * @example
- * ```tsx
- * // @vitest-environment happy-dom
- * import { renderRoute } from "@rangojs/router/testing/dom";
- *
- * function Product() {
- *   const { productId } = useParams<{ productId: string }>();
- *   const reverse = useReverse({ product: "/products/:productId" });
- *   return <a href={reverse("product", { productId: "2" })}>{productId}</a>;
- * }
- *
- * const { getByText, router } = await renderRoute(
- *   [{ path: "/products/:productId", Component: Product }],
- *   { initialUrl: "/products/1" },
- * );
- * ```
- */
 export async function renderRoute(
   routes: RenderRouteSpec[],
   options: RenderRouteOptions = {},
@@ -406,37 +390,34 @@ export async function renderRoute(
   if (routes.length === 0) {
     throw new Error("renderRoute: `routes` must contain at least one entry");
   }
+  if ("initialUrl" in options) {
+    throw new Error(
+      "renderRoute: the `initialUrl` option was renamed to `request`. " +
+        "Pass { request: <Request | url> } instead.",
+    );
+  }
 
   const { render, act } = await import("@testing-library/react");
 
   const leaf = routes[routes.length - 1];
-  const initialUrl = options.initialUrl ?? staticPrefix(leaf.path) ?? "/";
+  const requestUrl =
+    options.request instanceof Request ? options.request.url : options.request;
+  const initialUrl = requestUrl ?? staticPrefix(leaf.path) ?? "/";
   const url = new URL(initialUrl, TEST_ORIGIN);
 
-  // Seed loader data: explicit-id entries from `loaderData`, plus by-reference
-  // entries from `loaders` (assigning synthetic ids to real handles whose `$$id`
-  // is empty in a bare test).
   const loaderData: Record<string, unknown> = { ...(options.loaderData ?? {}) };
   for (const [loader, data] of options.loaders ?? []) {
     loaderData[ensureSyntheticId(loader as object, "$$id")] = data;
   }
 
-  // Seed location state into history.state so useLocationState(def) resolves.
-  // Keyed defs read history.state[def.__rsc_ls_key]; assign a synthetic key when
-  // the injected one is empty (bare test). RESET history.state to only this
-  // call's seeds (not a merge) so a previous render's seeded state does not leak
-  // into a later render in the same DOM environment.
   if (typeof window !== "undefined") {
     const stateObj: Record<string, unknown> = {};
     for (const [def, value] of options.locationState ?? []) {
       stateObj[ensureSyntheticId(def as object, "__rsc_ls_key")] = value;
     }
-    // No URL arg: useLocationState reads history.state (not the URL), and passing
-    // a TEST_ORIGIN URL would trip the DOM env's same-origin check.
     window.history.replaceState(stateObj, "");
   }
 
-  // Resolve params: URL-extracted params first, explicit params override.
   const resolve = (pathname: string): ResolvedMatch => {
     const matched = matchLeaf(leaf.path, pathname) ?? {};
     return {
@@ -446,11 +427,34 @@ export async function renderRoute(
   };
   const initialMatch = resolve(url.pathname);
 
-  // Reuse the real browser primitives so context shape matches production.
   const historyKey = generateHistoryKey(url.href);
-  // Normalize the include() mount prefix once and apply it at BOTH buildSegments
-  // call sites (initial + navigate) so mountPath is consistent across renders.
   const mount = normalizeBasename(options.mount);
+  // Fail loud on a request that cannot resolve the leaf route (a typo, or the
+  // mount-prefixed-vs-relative confusion) instead of silently rendering empty
+  // params (matchLeaf -> null -> {}). renderRoute paths are include-RELATIVE and
+  // resolve() matches the request against the leaf as-is, so the request must be
+  // the relative form — a mount does NOT rewrite it. Only checked when `request`
+  // was passed explicitly (a defaulted request is staticPrefix of the leaf and
+  // always matches). Skipped when explicit `params` are supplied: those are
+  // merged over the URL-extracted params in resolve(), so the request is
+  // intentionally not the param source and an empty matchLeaf is not the trap.
+  // Gated on the test runner so it can never affect production.
+  if (
+    options.request !== undefined &&
+    Object.keys(options.params ?? {}).length === 0 &&
+    isUnderTestRunner() &&
+    matchLeaf(leaf.path, url.pathname) === null
+  ) {
+    throw new Error(
+      `renderRoute: request "${url.pathname}" does not match the leaf route ` +
+        `"${leaf.path}"${mount ? ` (mount "${mount}")` : ""}. renderRoute paths ` +
+        `are include-RELATIVE: pass a request that matches "${leaf.path}" ` +
+        `(e.g. "${staticPrefix(leaf.path)}"). A mount does NOT auto-rewrite the ` +
+        `request — pass the relative path, not the mount-prefixed one. If the ` +
+        `request URL intentionally does not carry the params, pass them ` +
+        `explicitly via the \`params\` option to bypass this check.`,
+    );
+  }
   const initialSegments = buildSegments(
     routes,
     initialMatch.params,
@@ -464,36 +468,44 @@ export async function renderRoute(
     initialSegments,
     crossTabSync: false,
   });
-  // Seed handle data: raw `handle` entries plus by-reference `handles` attached
-  // to the leaf route segment under each handle's id (so useHandle(handle)
-  // resolves the pushed values).
   const leafRouteSegmentId =
     [...initialSegments].reverse().find((s) => s.type === "route")?.id ??
     initialSegments[initialSegments.length - 1]?.id;
   const handleSeed: HandleDataSeed = cloneHandleSeed(options.handle);
   for (const [handle, values] of options.handles ?? []) {
     if (leafRouteSegmentId === undefined) continue;
-    // createHandle always has a non-empty $$id (the Vite plugin injects one, and
-    // createHandle assigns a runtime fallback otherwise) with its REAL collect
-    // registered — so seeding under handle.$$id makes useHandle(handle) run the
-    // handle's actual collect/accumulator (custom collects included), not just a
-    // default flatten.
     const id = (handle as unknown as { $$id: string }).$$id;
     (handleSeed[id] ??= {})[leafRouteSegmentId] = values;
   }
 
   const eventController = createEventController({ initialLocation: url });
   eventController.setParams(initialMatch.params);
+  // Resolve-by-default: resolve any deferred (Promise) seeded handle values
+  // before applying, so the seeded handles reach collect/useHandle resolved —
+  // matching what the server/client do in a real app.
+  const resolvedSeed = await resolveDeferredHandleValues(handleSeed);
   eventController.setHandleData(
-    handleSeed,
+    resolvedSeed,
     initialSegments.map((s) => s.id),
   );
 
-  // Client-only navigation: re-resolve against the in-memory routes and emit a
-  // re-render. No server fetch — only routes passed to renderRoute exist. The
-  // store update is flushed inside act() so React commits before callers
-  // assert, mirroring how a real navigation lands a single payload swap.
+  let warnedNavLifecycle = false;
   const navigate = async (target: string): Promise<void> => {
+    // renderRoute commits navigations synchronously (no server fetch, no Flight
+    // stream), so it never drives the navigation lifecycle. The transition state
+    // useNavigation()/useLinkStatus()/useAction() read stays "idle" — asserting a
+    // pending/loading/submitting state here proves nothing. Warn once (per render)
+    // under the test runner so that false-confidence trap is loud, not silent.
+    if (isUnderTestRunner() && !warnedNavLifecycle) {
+      warnedNavLifecycle = true;
+      console.warn(
+        "renderRoute: navigate()/useRouter().push commit synchronously and do " +
+          "NOT drive the navigation lifecycle. useNavigation().state, " +
+          'useLinkStatus().pending, and useAction().state stay "idle" here. ' +
+          "Assert params/pathname/content after navigate(); use renderServerTree " +
+          "or e2e to assert pending/loading/submitting transition states.",
+      );
+    }
     const nextUrl = new URL(target, TEST_ORIGIN);
     const match = resolve(nextUrl.pathname);
     const segments = buildSegments(routes, match.params, loaderData, mount);
@@ -515,7 +527,6 @@ export async function renderRoute(
     registerLinkInterception: () => () => {},
     getVersion: () => undefined,
     updateVersion: () => {},
-    updateAppShell: () => {},
   };
 
   const initialMetadata = makeMetadata(
@@ -525,18 +536,27 @@ export async function renderRoute(
   );
   const initialTree = await renderSegments(initialSegments);
 
-  const result = render(
-    <NavigationProvider
-      store={store}
-      eventController={eventController}
-      initialPayload={{ root: initialTree, metadata: initialMetadata }}
-      bridge={bridge}
-      basename={normalizeBasename(options.basename)}
-      themeConfig={
-        options.theme === undefined ? null : resolveThemeConfig(options.theme)
-      }
-    />,
-  );
+  // Wrap render in an awaited async act so a tree that suspends (async loaders,
+  // loading states, deferred handle entries that arrive as a Promise) settles its
+  // Suspense within act — otherwise React orphans the resolution ("a component
+  // suspended inside an act scope, but the act call was not awaited") and the
+  // resolved content never reaches the asserted DOM.
+  let result!: Awaited<ReturnType<typeof render>>;
+  await act(async () => {
+    result = render(
+      <NavigationProvider
+        store={store}
+        eventController={eventController}
+        initialPayload={{ root: initialTree, metadata: initialMetadata }}
+        bridge={bridge}
+        basename={normalizeBasename(options.basename)}
+        themeConfig={
+          options.theme === undefined ? null : resolveThemeConfig(options.theme)
+        }
+        nonce={options.nonce}
+      />,
+    );
+  });
 
   const router: TestRouterHandle = {
     navigate,
@@ -549,7 +569,6 @@ export async function renderRoute(
   return Object.assign(result, { router });
 }
 
-/** Minimal RscMetadata for client-side re-renders (no server-only fields). */
 function makeMetadata(
   pathname: string,
   segments: ResolvedSegment[],