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

package/src/testing/run-loader.ts

@@ -1,10 +1,13 @@
 /**
- * runLoader — unit-test a raw loader function in isolation.
+ * runLoader — unit-test a loader function in isolation.
  *
- * Consumers pass the RAW async loader body `(ctx) => ...`, NOT a createLoader()
- * handle. This sidesteps the Vite `$$id` injection that createLoader() relies on
- * for RSC registration: the function is invoked directly with a constructed
- * LoaderContext, so no build step is required.
+ * Pass the RAW async loader body `(ctx) => ...`, or a registered `createLoader()`
+ * handle (its fn is recovered from the fetchable registry by `$$id`). The raw
+ * body needs no build step; the handle works because `createLoader` assigns a
+ * runtime-fallback `$$id` and registers its fn even without the Vite plugin (when
+ * imported through the server build — the consumer's `@rangojs/router` under the
+ * `rangoTestConfig()` preset). Either way the function is invoked directly with a
+ * constructed LoaderContext.
  *
  * The LoaderContext mirrors the canonical shape the router builds at runtime
  * (see createUseFunction in server/request-context.ts). The loader runs inside
@@ -35,16 +38,20 @@ import {
   type RequestContext,
 } from "../server/request-context.js";
 import { createReverseFunction } from "../router/handler-context.js";
+import { getFetchableLoader } from "../server/fetchable-loader-store.js";
 import type { LoaderContext, LoaderDefinition } from "../types.js";
 import type { ContextVar } from "../context-var.js";
 import { isHandle, type Handle } from "../handle.js";
+import { collectHandle } from "./collect-handle.js";
 import type { ThemeConfig } from "../theme/types.js";
 import type { SegmentCacheStore } from "../cache/types.js";
 import type { CacheProfile } from "../cache/profile-registry.js";
 import {
   createTestRequestContext,
+  buildRunSnapshot,
   type CreateTestContextOptions,
   type VarsInit,
+  type StateCookieSeed,
 } from "./internal/context.js";
 
 /**
@@ -99,7 +106,9 @@ export interface RunLoaderOptions<TEnv = any> {
   basename?: string;
   /**
    * Theme config in the same shape `createRouter({ theme })` takes (e.g. `true`
-   * or `{ themes: [...] }`). Without it `ctx.theme`/`ctx.setTheme` are inert.
+   * or `{ themes: [...] }`). Seeds the request's theme config so nested handler
+   * or cache contexts created from this loader observe it. Loaders themselves do
+   * not expose `ctx.theme`/`ctx.setTheme` (those are handler/middleware-only).
    */
   theme?: ThemeConfig | true;
   /** Environment bindings surfaced as `ctx.env`. */
@@ -118,7 +127,15 @@ export interface RunLoaderOptions<TEnv = any> {
   body?: unknown;
   /** Form data surfaced as `ctx.formData`. */
   formData?: FormData;
-  /** Resolver for `ctx.use(OtherLoader)` composition. */
+  /**
+   * Seed the data `ctx.use(OtherLoader)` returns, by loader REFERENCE — the same
+   * tuple form `renderHandler` / `renderRoute` use (`[[OtherLoader, data]]`).
+   * Matched by reference, so a real `createLoader()` handle resolves regardless
+   * of its build-injected `$$id`. For dynamic resolution (compute per dependency)
+   * use `use` instead; `loaders` is checked first.
+   */
+  loaders?: ReadonlyArray<readonly [LoaderDefinition<any, any>, unknown]>;
+  /** Resolver for `ctx.use(OtherLoader)` composition (dynamic; `loaders` wins if both match). */
   use?: UseResolver;
   /**
    * Cache store backing `use cache` functions the loader invokes. Without it,
@@ -129,6 +146,13 @@ export interface RunLoaderOptions<TEnv = any> {
   cacheStore?: SegmentCacheStore;
   /** Cache profiles (the `createRouter({ cacheProfiles })` shape). */
   cacheProfiles?: Record<string, CacheProfile>;
+  /**
+   * Customize the rango state cookie a loader that calls
+   * `invalidateClientCache()` rotates (the name is always seeded — default
+   * `rango-state_router_0` — so it rotates like production). Assert via the
+   * `Set-Cookie` on the request context's response.
+   */
+  stateCookie?: StateCookieSeed;
   /**
    * Mock the `ctx.rendered()` render barrier so a loader that does
    * `await ctx.rendered()` (to read handle data pushed during render) can be
@@ -155,10 +179,6 @@ export interface RunLoaderOptions<TEnv = any> {
   handles?: ReadonlyArray<readonly [Handle<any, any>, unknown]>;
 }
 
-/**
- * Merge `search` into a request's URL, returning a value `toRequest` can build.
- * Keeps the original method/headers/body when a Request was passed.
- */
 function withSearch(
   request: Request | string | undefined,
   search: Record<string, string> | undefined,
@@ -179,26 +199,37 @@ function withSearch(
   return url.toString();
 }
 
-/**
- * Run a raw loader body and return its resolved data.
- *
- * @example
- * ```ts
- * const data = await runLoader(
- *   async (ctx) => ({ id: ctx.params.id, user: ctx.get("user") }),
- *   { params: { id: "42" }, vars: { user: { name: "Ada" } } },
- * );
- * ```
- */
-export async function runLoader<T>(
-  loaderFn: (ctx: TestLoaderContext) => Promise<T> | T,
-  opts: RunLoaderOptions = {},
-): Promise<T> {
-  const ctxOpts: CreateTestContextOptions<any> = {
+/** A raw loader body, or a registered `createLoader()` handle (its fn is recovered). */
+export type RunnableLoader<T> =
+  | ((ctx: TestLoaderContext) => Promise<T> | T)
+  | LoaderDefinition<T, any>;
+
+function resolveLoaderFn<T>(
+  loader: RunnableLoader<T>,
+): (ctx: TestLoaderContext) => Promise<T> | T {
+  if (typeof loader === "function") {
+    return loader as (ctx: TestLoaderContext) => Promise<T> | T;
+  }
+  const def = loader as LoaderDefinition<T, any>;
+  const fn = def.fn ?? getFetchableLoader(def.$$id)?.fn;
+  if (!fn) {
+    throw new Error(
+      `runLoader() received a createLoader() handle whose function could not be ` +
+        `recovered (id "${def.$$id || "<empty>"}"). The loader was likely imported ` +
+        `through the CLIENT build, which drops the body. Either import it through ` +
+        `@rangojs/router with the rangoTestConfig() preset (resolves to the server ` +
+        `build that registers the fn), or pass the raw loader body directly: ` +
+        `runLoader((ctx) => ...).`,
+    );
+  }
+  return fn as (ctx: TestLoaderContext) => Promise<T> | T;
+}
+
+function buildLoaderCtxOpts(
+  opts: RunLoaderOptions,
+): CreateTestContextOptions<any> {
+  return {
     env: opts.env,
-    // Bake opts.search into the request URL itself so ctx.request.url, ctx.url,
-    // and ctx.searchParams all agree (production carries the query string on the
-    // real request — a loader reading ctx.request.url must see it too).
     request: withSearch(opts.request, opts.search),
     requestInit: opts.method ? { method: opts.method } : undefined,
     vars: opts.vars,
@@ -209,27 +240,23 @@ export async function runLoader<T>(
     theme: opts.theme,
     cacheStore: opts.cacheStore,
     cacheProfiles: opts.cacheProfiles,
+    stateCookie: opts.stateCookie,
   };
+}
 
-  const { ctx } = createTestRequestContext(ctxOpts);
-
-  const reqCtx = ctx as RequestContext<any>;
-
-  // Seed values for ctx.use(SomeHandle), matched by handle reference (so a real
-  // handle resolves regardless of its build-injected $$id).
+function runWithLoaderContext<R>(
+  reqCtx: RequestContext<any>,
+  opts: RunLoaderOptions,
+  fn: (ctx: TestLoaderContext) => R,
+): R {
   const handleSeeds = new Map<unknown, unknown>(opts.handles ?? []);
-
-  // Tracks whether the mocked render barrier has settled. ctx.use(handle)
-  // reads are gated on this, matching production (loader-resolution.ts).
+  const loaderSeeds = new Map<unknown, unknown>(opts.loaders ?? []);
   let renderedResolved = false;
 
   return runWithRequestContext(reqCtx, () => {
     const reverse = opts.routeMap
       ? createReverseFunction(opts.routeMap, opts.routeName, opts.params ?? {})
       : ((() => {
-          // Documented contract: reverse requires routeMap. Do NOT fall back to
-          // reqCtx.reverse (the global route map) — that leaks whichever routes
-          // another test registered and contradicts the documented behavior.
           throw new Error(
             "ctx.reverse() requires the `routeMap` option in runLoader(). " +
               "Pass { routeMap: { name: pattern, ... } } to enable reverse().",
@@ -240,7 +267,7 @@ export async function runLoader<T>(
       params: opts.params ?? {},
       routeParams: (opts.params ?? {}) as Record<string, string>,
       request: reqCtx.request,
-      searchParams: ctx.searchParams,
+      searchParams: reqCtx.searchParams,
       search: opts.searchData ?? {},
       pathname: reqCtx.pathname,
       url: reqCtx.url,
@@ -250,10 +277,6 @@ export async function runLoader<T>(
       executionContext: reqCtx.executionContext,
       get: reqCtx.get as TestLoaderContext["get"],
       use: ((dep: LoaderDefinition<any, any> | Handle<any, any>) => {
-        // Match production (loader-resolution.ts): reading a handle in a loader
-        // requires the render barrier to have settled. Gate BEFORE returning a
-        // seed, so a loader that forgets `await ctx.rendered()` fails in the
-        // test exactly as it would at runtime.
         if (isHandle(dep) && !renderedResolved) {
           throw new Error(
             `ctx.use(handle) in a loader requires "await ctx.rendered()" first. ` +
@@ -261,9 +284,15 @@ export async function runLoader<T>(
               `the render tree has settled.`,
           );
         }
-        // Handle reads (ctx.use(SomeHandle)) resolve from the seeded map first.
         if (handleSeeds.has(dep)) return handleSeeds.get(dep);
-        if (opts.use) return opts.use(dep as LoaderDefinition<any, any>);
+        if (isHandle(dep)) return collectHandle(dep, []);
+        // Production ctx.use(Loader) ALWAYS returns a Promise (the cached loader
+        // promise). The seeded path must match, so a consumer composing on the
+        // result (ctx.use(Dep).then(...), Promise.race, etc.) works the same as
+        // production and the real-fn delegate path below.
+        if (loaderSeeds.has(dep)) return Promise.resolve(loaderSeeds.get(dep));
+        if (opts.use)
+          return Promise.resolve(opts.use(dep as LoaderDefinition<any, any>));
         return reqCtx.use(dep as LoaderDefinition<any, any>);
       }) as LoaderContext<any, any>["use"],
       method: opts.method ?? "GET",
@@ -276,7 +305,6 @@ export async function runLoader<T>(
               if (typeof opts.rendered === "function") {
                 await opts.rendered();
               }
-              // Barrier has settled: subsequent ctx.use(handle) reads resolve.
               renderedResolved = true;
             }
           : () => {
@@ -291,6 +319,67 @@ export async function runLoader<T>(
             },
     };
 
-    return Promise.resolve(loaderFn(loaderCtx));
+    return fn(loaderCtx);
   });
 }
+
+export async function runLoader<T>(
+  loader: RunnableLoader<T>,
+  opts: RunLoaderOptions = {},
+): Promise<T> {
+  const loaderFn = resolveLoaderFn(loader);
+  const { ctx } = createTestRequestContext(buildLoaderCtxOpts(opts));
+  return runWithLoaderContext(ctx as RequestContext<any>, opts, (loaderCtx) =>
+    Promise.resolve(loaderFn(loaderCtx)),
+  );
+}
+
+export interface RunLoaderResult<T> {
+  /**
+   * The loader's resolved data (the value bare `runLoader` returns), or
+   * `undefined` if it threw (see {@link thrown}). Named `result` for parity with
+   * `runInRequestContext`'s envelope.
+   */
+  result: T | undefined;
+  /**
+   * What the loader threw (commonly a `Response` from `throw redirect(...)` on a
+   * success path) — captured, NOT re-thrown; assert on it. `undefined` if the
+   * loader returned normally.
+   */
+  thrown: unknown;
+  /**
+   * The merged `Response` (status + headers + Set-Cookie). On a thrown redirect,
+   * that redirect's `Location` merged with the accumulated cookies/headers — so a
+   * loader that sets a session cookie then `throw redirect("/")` exposes BOTH.
+   */
+  response: Response;
+  /** Effective cookie view: request cookies + the loader's mutations, last-write-wins. */
+  cookies: Record<string, string>;
+  /** Response headers as `{ name: value }`, EXCLUDING set-cookie (use `cookies`). Lowercased. */
+  headers: Record<string, string>;
+  /** Location state the loader set (`ctx.setLocationState()` / `redirect({ state })`). */
+  locationState: Record<string, unknown>;
+  /** The resolved rango state cookie name seeded for the run (default `rango-state_router_0`). */
+  stateCookieName: string;
+}
+
+export async function runLoaderResult<T>(
+  loader: RunnableLoader<T>,
+  opts: RunLoaderOptions = {},
+): Promise<RunLoaderResult<T>> {
+  const loaderFn = resolveLoaderFn(loader);
+  const { ctx, stateCookieName } = createTestRequestContext(
+    buildLoaderCtxOpts(opts),
+  );
+  const reqCtx = ctx as RequestContext<any>;
+  let result: T | undefined;
+  let thrown: unknown;
+  try {
+    result = await runWithLoaderContext(reqCtx, opts, (loaderCtx) =>
+      Promise.resolve(loaderFn(loaderCtx)),
+    );
+  } catch (error) {
+    thrown = error;
+  }
+  return { result, ...buildRunSnapshot(reqCtx, thrown, stateCookieName) };
+}

package/src/testing/run-middleware.ts

@@ -24,9 +24,11 @@ import { createReverseFunction } from "../router/handler-context.js";
 import type { MiddlewareFn } from "../router/middleware-types.js";
 import {
   createTestRequestContext,
+  headersToObject,
   snapshotRunEffects,
   type CreateTestContextOptions,
   type VarsInit,
+  type StateCookieSeed,
 } from "./internal/context.js";
 import type { ThemeConfig } from "../theme/types.js";
 import type { SegmentCacheStore } from "../cache/types.js";
@@ -36,6 +38,13 @@ import type { CacheProfile } from "../cache/profile-registry.js";
  * Options for runMiddleware.
  */
 export interface RunMiddlewareOptions<TEnv = any> {
+  /**
+   * The request the chain runs under: a `Request`, or a URL string (absolute or
+   * path). Optional for parity with `runLoader`/`runInRequestContext` — when
+   * omitted it defaults to `http://localhost/`. Pass it for path-, header-, or
+   * cookie-driven middleware.
+   */
+  request?: Request | string;
   /** Environment bindings surfaced as `ctx.env`. */
   env?: TEnv;
   /** Route params surfaced as `ctx.params`. */
@@ -44,7 +53,12 @@ export interface RunMiddlewareOptions<TEnv = any> {
   vars?: VarsInit;
   /** Route name -> pattern map enabling `ctx.reverse()`. */
   routeMap?: Record<string, string>;
-  /** Matched route name for scoped `.name` reverse resolution. */
+  /**
+   * Matched route name surfaced as `ctx.routeName`. Does NOT scope `.name`
+   * reverse: the chain receives a map-only `reverse` (built from `routeMap`
+   * alone), matching production app/response middleware — see the reverse
+   * construction below.
+   */
   routeName?: string;
   /** Router basename surfaced on the context (drives redirect() prefixing). */
   basename?: string;
@@ -64,6 +78,13 @@ export interface RunMiddlewareOptions<TEnv = any> {
   cacheStore?: SegmentCacheStore;
   /** Cache profiles (the `createRouter({ cacheProfiles })` shape). */
   cacheProfiles?: Record<string, CacheProfile>;
+  /**
+   * Customize the rango state cookie a middleware that calls
+   * `invalidateClientCache()` rotates (the name is always seeded — default
+   * `rango-state_router_0` — so it rotates like production). Assert via the
+   * `Set-Cookie` on `result.response` / `result.cookies`.
+   */
+  stateCookie?: StateCookieSeed;
 }
 
 /**
@@ -88,34 +109,39 @@ export interface RunMiddlewareResult<TEnv = any> {
    * the `@internal` `ctx.cookies()`. Set-Cookie headers are also on `response`.
    */
   cookies: Record<string, string>;
+  /**
+   * The final response's headers as a plain `{ name: value }` object (the same
+   * view as `response.headers`), EXCLUDING `set-cookie` (use `cookies`). The
+   * public way to assert a header a middleware set (e.g. a security header)
+   * without reading `ctx.res.headers`. Header names are lowercased.
+   */
+  headers: Record<string, string>;
+  /**
+   * Location state the chain set via `ctx.setLocationState()` / `redirect({ state })`,
+   * resolved to the flat `{ key: value }` shape the client reads off
+   * `history.state` (empty object when none) — parity with `runInRequestContext`
+   * and `renderHandler`.
+   */
+  locationState: Record<string, unknown>;
+  /**
+   * The resolved rango state cookie name seeded for the run (default
+   * `rango-state_router_0`, or composed from `opts.stateCookie`). Assert a
+   * middleware's `invalidateClientCache()` rotation against it without
+   * recomputing — parity with `runInRequestContext` / `runLoaderResult` /
+   * `renderHandler`.
+   */
+  stateCookieName: string;
 }
 
-/**
- * Run a middleware chain and return the response plus observable context.
- *
- * @example
- * ```ts
- * const { response, ctx, nextCalled } = await runMiddleware(
- *   async (ctx, next) => {
- *     if (!ctx.get("user")) return new Response(null, { status: 401 });
- *     return next();
- *   },
- *   "/dashboard",
- *   { vars: [["user", { id: 1 }]] },
- * );
- * // nextCalled === 1, response.status === 200
- * ```
- */
 export async function runMiddleware<TEnv = any>(
   mw: MiddlewareFn<TEnv> | MiddlewareFn<TEnv>[],
-  request: Request | string,
-  opts: RunMiddlewareOptions<TEnv> = {},
+  opts: RunMiddlewareOptions<TEnv>,
 ): Promise<RunMiddlewareResult<TEnv>> {
   const mwArray = Array.isArray(mw) ? mw : [mw];
 
   const ctxOpts: CreateTestContextOptions<TEnv> = {
     env: opts.env,
-    request,
+    request: opts.request,
     vars: opts.vars,
     routeMap: opts.routeMap,
     routeName: opts.routeName,
@@ -124,12 +150,14 @@ export async function runMiddleware<TEnv = any>(
     theme: opts.theme,
     cacheStore: opts.cacheStore,
     cacheProfiles: opts.cacheProfiles,
+    stateCookie: opts.stateCookie,
   };
 
   const {
     ctx,
     request: builtRequest,
     variables,
+    stateCookieName,
   } = createTestRequestContext<TEnv>(ctxOpts);
 
   let nextCalled = 0;
@@ -138,11 +166,6 @@ export async function runMiddleware<TEnv = any>(
     return opts.next?.() ?? new Response(null, { status: 200 });
   };
 
-  // Match production: app/response middleware receive ctx.reverse built from the
-  // route map ALONE (no matched route name or current params), so reversing a
-  // parameterized route without explicit params does NOT auto-fill from the
-  // current request. Passing routeName/params here would recreate the
-  // false-confidence class fixed in dispatch.
   const reverse = opts.routeMap
     ? (createReverseFunction(opts.routeMap) as (
         name: string,
@@ -151,12 +174,6 @@ export async function runMiddleware<TEnv = any>(
       ) => string)
     : undefined;
 
-  // Keep the RETURNED ctx.reverse consistent with the map-only reverse the
-  // chain receives. createTestRequestContext installs an auto-fill reverse
-  // (correct for the loader phase) when routeName/params are passed, but
-  // production app/response middleware see a map-only reverse. Without this,
-  // a middleware reading getRequestContext().reverse — or a consumer asserting
-  // on result.ctx.reverse — would observe auto-fill that production never does.
   if (reverse) {
     (ctx as RequestContext<TEnv>).reverse =
       reverse as RequestContext<TEnv>["reverse"];
@@ -174,6 +191,15 @@ export async function runMiddleware<TEnv = any>(
     ),
   );
 
-  const { cookies } = snapshotRunEffects(ctx);
-  return { response, ctx, nextCalled, cookies };
+  const { cookies, locationState } = snapshotRunEffects(ctx);
+  const headers = headersToObject(response.headers);
+  return {
+    response,
+    ctx,
+    nextCalled,
+    cookies,
+    headers,
+    locationState,
+    stateCookieName,
+  };
 }

package/src/testing/run-transition-when.ts

@@ -0,0 +1,164 @@
+/**
+ * runTransitionWhen — unit-test a transition({ when }) predicate in isolation.
+ *
+ * Runs the SAME two server functions the router uses — applyViewTransitionDefault
+ * (strips the `when` function from the serialized config and records the
+ * predicate on the request context) and gateTransitions (assembles the
+ * TransitionWhenContext and evaluates the predicate post-handler). So the
+ * predicate sees exactly the navigation/action metadata it would at runtime
+ * (currentUrl/currentParams/fromRouteName, nextUrl/nextParams/toRouteName,
+ * actionId/actionUrl/actionResult/formData/method, get/env), and `kept` reflects
+ * whether the transition would apply this request. The result also exposes the
+ * assembled `whenContext` so tests can assert the exact fields without reaching
+ * into private request-context state.
+ *
+ * This is the public way to exercise a transition gate: the full
+ * match -> render pipeline that wires these together only runs under real RSC
+ * rendering (which the Flight primitives do not drive), so without this primitive
+ * a consumer could not test their predicate through @rangojs/router/testing.
+ *
+ * Synchronous: a transition predicate returns a boolean and the gate has no I/O.
+ */
+
+import {
+  runWithRequestContext,
+  type RequestContext,
+} from "../server/request-context.js";
+import { applyViewTransitionDefault } from "../router/segment-resolution/view-transition-default.js";
+import { gateTransitions } from "../rsc/transition-gate.js";
+import { createTestRequestContext, type VarsInit } from "./internal/context.js";
+import type {
+  ResolvedSegment,
+  TransitionConfig,
+  TransitionWhenContext,
+} from "../types/segments.js";
+import type { OnErrorCallback } from "../types/error-types.js";
+
+const toURL = (v: string | URL, base: URL): URL =>
+  typeof v === "string" ? new URL(v, base.origin) : v;
+
+/**
+ * Options for runTransitionWhen. All navigation/action fields are optional and
+ * default to "absent", matching what the gate sees for an initial full load with
+ * no action: omit `currentUrl`/`currentParams`/`fromRouteName` to model the
+ * navigation source being unavailable, and omit the `action*` fields to model a
+ * plain (non-action) navigation.
+ */
+export interface RunTransitionWhenOptions<TEnv = any> {
+  /** The navigation TARGET request (drives `nextUrl`): a Request or URL/path string. Defaults to `http://localhost/`. */
+  request?: Request | string;
+  /** Route params for the target (`nextParams`). */
+  params?: Record<string, string>;
+  /** Target route name (`toRouteName`). */
+  toRouteName?: string;
+  /** Environment bindings surfaced as `env` (and `ctx.env`). */
+  env?: TEnv;
+  /** Variables a handler/middleware would have set this request, readable via the predicate's `get()`. */
+  vars?: VarsInit;
+  /** Navigation SOURCE url (`currentUrl`): a URL or path string. */
+  currentUrl?: string | URL;
+  /** Source route params (`currentParams`). */
+  currentParams?: Record<string, string>;
+  /** Source route name (`fromRouteName`). */
+  fromRouteName?: string;
+  /** Id of the action that triggered a revalidation (`actionId`). */
+  actionId?: string;
+  /** Url the action was submitted from (`actionUrl`). */
+  actionUrl?: string | URL;
+  /** The action's return value (`actionResult`). */
+  actionResult?: unknown;
+  /** FormData from a form action (`formData`). */
+  formData?: FormData;
+  /** Receives an error thrown by the predicate (the gate reports to `router.onError`, phase `"rendering"`). */
+  onError?: OnErrorCallback;
+}
+
+/**
+ * Result of runTransitionWhen.
+ */
+export interface RunTransitionWhenResult<TEnv = any> {
+  /** True if the transition would apply this request (predicate returned non-false, or there is no `when`). */
+  kept: boolean;
+  /** Convenience inverse of `kept`. */
+  dropped: boolean;
+  /**
+   * The production-assembled predicate context. Undefined when the config has
+   * no `when` predicate.
+   */
+  whenContext?: TransitionWhenContext<Record<string, string>, TEnv>;
+  /** The underlying RequestContext, for additional assertions (`ctx.get(...)`, etc.). */
+  ctx: RequestContext<TEnv>;
+}
+
+export function runTransitionWhen<TEnv = any>(
+  config: TransitionConfig,
+  opts: RunTransitionWhenOptions<TEnv> = {},
+): RunTransitionWhenResult<TEnv> {
+  const { ctx } = createTestRequestContext<TEnv>({
+    env: opts.env,
+    request: opts.request,
+    vars: opts.vars,
+    params: opts.params,
+  });
+  const reqCtx = ctx as unknown as RequestContext<TEnv>;
+
+  // Target route name (the public field the gate reads for `toRouteName`).
+  if (opts.toRouteName !== undefined)
+    reqCtx.routeName = opts.toRouteName as RequestContext<TEnv>["routeName"];
+  // Source (match-time) data the gate reads for currentUrl/currentParams/fromRouteName.
+  if (opts.currentUrl !== undefined)
+    reqCtx._gateCurrentUrl = toURL(opts.currentUrl, reqCtx.url);
+  if (opts.currentParams !== undefined)
+    reqCtx._gateCurrentParams = opts.currentParams;
+  if (opts.fromRouteName !== undefined)
+    reqCtx._prevRouteKey = opts.fromRouteName;
+  // Action data the gate reads at the action-bearing call sites.
+  if (opts.actionId !== undefined) reqCtx._gateActionId = opts.actionId;
+  if (opts.actionUrl !== undefined)
+    reqCtx._gateActionUrl = toURL(opts.actionUrl, reqCtx.url);
+  if (opts.actionResult !== undefined)
+    reqCtx._gateActionResult = opts.actionResult;
+  if (opts.formData !== undefined) reqCtx._gateFormData = opts.formData;
+
+  let whenContext:
+    | TransitionWhenContext<Record<string, string>, TEnv>
+    | undefined;
+  const when = config.when;
+  const configForGate: TransitionConfig = when
+    ? {
+        ...config,
+        when: (c) => {
+          whenContext = c as TransitionWhenContext<
+            Record<string, string>,
+            TEnv
+          >;
+          return when(c);
+        },
+      }
+    : config;
+
+  return runWithRequestContext(reqCtx, () => {
+    // The real resolution-time collection + post-handler gate, so the predicate
+    // sees the production-assembled TransitionWhenContext.
+    const serialized = applyViewTransitionDefault(
+      configForGate,
+      undefined,
+      "tx-when-seg",
+    );
+    const segment = {
+      id: "tx-when-seg",
+      namespace: "r",
+      type: "route",
+      index: 0,
+      component: null,
+      transition: serialized,
+    } as ResolvedSegment;
+    gateTransitions(
+      [segment],
+      reqCtx as Parameters<typeof gateTransitions>[1],
+      opts.onError,
+    );
+    const kept = segment.transition !== undefined;
+    return { kept, dropped: !kept, whenContext, ctx: reqCtx };
+  });
+}

package/src/testing/vitest-stubs/cloudflare-email.ts

@@ -1,5 +1,5 @@
 // Stub for the `cloudflare:email` runtime virtual, shipped for Cloudflare
-// consumers (enable via `rangoTestAliases({ cloudflare: true })`).
+// consumers (enable via `rangoTestAliases({ preset: "cloudflare" })`).
 export class EmailMessage {
   constructor(
     public from: string,

package/src/testing/vitest-stubs/cloudflare-workers.ts

@@ -1,5 +1,5 @@
 // Stub for the `cloudflare:workers` runtime virtual, shipped for Cloudflare
-// consumers (enable via `rangoTestAliases({ cloudflare: true })`). A CF app's
+// consumers (enable via `rangoTestAliases({ preset: "cloudflare" })`). A CF app's
 // route tree commonly imports `cloudflare:workers` (e.g. `import { env } from
 // "cloudflare:workers"`), which does not resolve in a bare Vitest process.
 export const env: Record<string, unknown> = {};