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

package/src/testing/e2e/fixture.ts

@@ -17,7 +17,12 @@ import {
 export interface FixtureOptions {
   /** Absolute or cwd-relative path to the consumer app under test. */
   root: string;
-  mode?: "dev" | "build";
+  /**
+   * Server mode. Required: omitting it would spawn no server in beforeAll and
+   * surface only as a bare "Invalid URL" from `url()` at first use, so we fail
+   * eagerly at useFixture time instead.
+   */
+  mode: "dev" | "build";
   /** Override the server command (default: `pnpm dev` for dev, `pnpm preview` for build). */
   command?: string;
   /** Override the build command (default: `pnpm build`). */
@@ -32,7 +37,7 @@ export interface FixtureOptions {
 }
 
 export interface Fixture {
-  mode: "dev" | "build" | undefined;
+  mode: "dev" | "build";
   root: string;
   /** Resolve a path against the running server's base URL. */
   url: (url?: string) => string;
@@ -49,6 +54,11 @@ export function createUseFixture(
   test: TestType<any, any>,
 ): (options: FixtureOptions) => Fixture {
   return function useFixture(options: FixtureOptions): Fixture {
+    if (options.mode !== "dev" && options.mode !== "build") {
+      throw new Error(
+        `useFixture: mode is required: 'dev' | 'build' (got ${JSON.stringify(options.mode)}).`,
+      );
+    }
     let cleanup: (() => Promise<void>) | undefined;
     let baseURL!: string;
 
@@ -79,6 +89,14 @@ export function createUseFixture(
           ...options.cliOptions,
           env: cliEnv,
         });
+        // Assign cleanup immediately after spawn, before any await that can
+        // throw (findPort/waitForReady). Otherwise a beforeAll failure leaves
+        // afterAll's cleanup a no-op and orphans the dev server (plus workerd
+        // children) for the rest of the run.
+        cleanup = async () => {
+          proc!.kill();
+          await proc!.done;
+        };
         const port = await proc.findPort();
         baseURL = `http://localhost:${port}`;
         const readyUrl = options.readyPath
@@ -96,10 +114,6 @@ export function createUseFixture(
         if (options.isolatedServer) {
           await warmupDevServer(readyUrl);
         }
-        cleanup = async () => {
-          proc!.kill();
-          await proc!.done;
-        };
       }
 
       if (options.mode === "build") {
@@ -112,7 +126,25 @@ export function createUseFixture(
             ...options.cliOptions,
             env: cliEnv,
           });
-          await buildProc.done;
+          // The build is a finite process, but assign cleanup before the await
+          // so a hung build is still killed if beforeAll is torn down.
+          cleanup = async () => {
+            buildProc.kill();
+            await buildProc.done;
+          };
+          // Fail loudly on a nonzero build exit. Without this a failed build is
+          // swallowed and preview serves the previous stale dist/ (green
+          // production tests against old code), or times out with "Server not
+          // ready" that never mentions the build failure. The captured build
+          // output (stdout/stderr above) precedes this throw.
+          const code = await buildProc.exitCode;
+          if (code !== 0) {
+            throw new Error(
+              `Build failed with exit code ${code} for "${options.root}" ` +
+                `(command: ${options.buildCommand ?? "pnpm build"}). ` +
+                `See the captured build output above for the cause.`,
+            );
+          }
         }
         proc = runCli({
           command: options.command ?? `pnpm preview`,
@@ -121,6 +153,12 @@ export function createUseFixture(
           ...options.cliOptions,
           env: cliEnv,
         });
+        // Switch cleanup to the preview process immediately after spawn, before
+        // findPort/waitForReady can throw and orphan it.
+        cleanup = async () => {
+          proc!.kill();
+          await proc!.done;
+        };
         const port = await proc.findPort();
         baseURL = `http://localhost:${port}`;
         const buildReadyUrl = options.readyPath
@@ -130,10 +168,6 @@ export function createUseFixture(
           stdout: proc!.stdout(),
           stderr: proc!.stderr(),
         }));
-        cleanup = async () => {
-          proc!.kill();
-          await proc!.done;
-        };
       }
     });
 

package/src/testing/e2e/index.ts

@@ -1,8 +1,3 @@
-// Public entry for the consumer e2e harness. `createRangoE2E({ test, expect })`
-// wires the server fixture, page helpers, parity helpers, and matchers around
-// the consumer's Playwright `test`/`expect` objects so this module never
-// imports `@playwright/test` at runtime (type-only imports are erased).
-
 import type { Expect, TestType } from "@playwright/test";
 import {
   createUseFixture,
@@ -35,14 +30,9 @@ import {
 } from "./parity.js";
 import { createRangoMatchers, type RangoMatchers } from "./matchers.js";
 
-// Cache-status helpers are pure (cache-status.ts imports only TYPES), so they
-// are safe to surface from this Playwright-runnable entry. Importing them from
-// the `@rangojs/router/testing` barrel does NOT work in a plain Playwright
-// runner — the barrel transitively pulls the build-only `@rangojs/router:version`
-// virtual via the route-manifest path. Asserting cache status on a real
-// response is an e2e activity, so this is their Playwright-safe home.
 export {
   assertCacheStatus,
+  assertCacheDecision,
   parseCacheHeader,
   createCacheSink,
   filterCacheDecisions,
@@ -50,9 +40,6 @@ export {
   type ExpectedCacheStatus,
   type CacheStatusTarget,
 } from "../cache-status.js";
-
-// Re-export standalone helpers and all public types so the barrel can re-export
-// them from a single module.
 export {
   testId,
   waitForHydration,
@@ -87,7 +74,6 @@ export interface RangoE2E extends PageHelpers, Parity {
   useFixture: (options: FixtureOptions) => Fixture;
   testNoJs: TestType<any, any>;
   rangoMatchers: RangoMatchers;
-  // Standalone helpers, re-surfaced for convenience.
   testId: typeof testId;
   waitForHydration: typeof waitForHydration;
   waitForNavigation: typeof waitForNavigation;
@@ -102,12 +88,6 @@ export interface RangoE2E extends PageHelpers, Parity {
   measureTime: typeof measureTime;
 }
 
-/**
- * Wire the full e2e harness around a consumer's Playwright `test`/`expect`.
- *
- * @param defaultRoot - fallback app root for `parityDescribe` when a call omits
- *   `options.root`.
- */
 export function createRangoE2E({
   test,
   expect,
@@ -132,7 +112,6 @@ export function createRangoE2E({
     rangoMatchers,
     ...parity,
     ...pageHelpers,
-    // Standalone helpers.
     testId,
     waitForHydration,
     waitForNavigation,

package/src/testing/e2e/matchers.ts

@@ -1,6 +1,3 @@
-// Custom Playwright matchers for Rango assertions. Returned as an object
-// suitable for `expect.extend(...)`. v1 ships only `toHaveRangoPathname`.
-
 import type { Expect, Page } from "@playwright/test";
 
 interface MatcherResult {
@@ -12,17 +9,6 @@ export interface RangoMatchers {
   toHaveRangoPathname: (page: Page, expected: string) => MatcherResult;
 }
 
-/**
- * Build the matcher object for `expect.extend(createRangoMatchers(expect))`.
- *
- * `toHaveRangoPathname(page, expected)` asserts that the pathname of the page's
- * current URL equals `expected`.
- *
- * TODO: `toHaveSegments` / `toHaveParams` are intentionally not implemented.
- * They require a client-emitted signal (the active segment chain / resolved
- * params exposed on the page) that does not exist yet; implementing them by
- * scraping the DOM would be a guess. Add them once the router emits that signal.
- */
 export function createRangoMatchers(_expect: Expect): RangoMatchers {
   return {
     toHaveRangoPathname(page: Page, expected: string): MatcherResult {
@@ -39,8 +25,6 @@ export function createRangoMatchers(_expect: Expect): RangoMatchers {
   };
 }
 
-// Type augmentation so consumers can call `await expect(page).toHaveRangoPathname("/x")`
-// after `expect.extend(rangoMatchers)`, without re-declaring the matcher.
 declare global {
   // eslint-disable-next-line @typescript-eslint/no-namespace
   namespace PlaywrightTest {

package/src/testing/e2e/parity.ts

@@ -6,6 +6,7 @@
 
 import type { Expect, Page, TestType } from "@playwright/test";
 import type { Fixture, FixtureOptions } from "./fixture.js";
+import { DEFAULT_STATE_COOKIE_PREFIX } from "../../browser/cookie-name.js";
 
 export interface ParityDescribeOptions extends Partial<
   Omit<FixtureOptions, "mode">
@@ -30,6 +31,15 @@ export interface ExpectParityOptions {
    * transport being snapshotted.
    */
   waitFor?: (page: Page) => Promise<void>;
+  /**
+   * Cookie NAMES to exclude from the JS-vs-no-JS jar comparison, matched exactly
+   * (string) or by pattern (RegExp). The rango state cookie (default prefix
+   * `rango-state`) is ALWAYS excluded — it is written/rotated only by the client
+   * runtime, so it is JS-only by design and never appears in the no-JS jar. Use
+   * this for a custom `stateCookiePrefix` (e.g. `[/^myapp-state_/]`) or any other
+   * volatile/JS-only cookie (analytics, CSRF) that should not break parity.
+   */
+  ignoreCookies?: ReadonlyArray<string | RegExp>;
 }
 
 export interface Parity {
@@ -76,6 +86,31 @@ export interface Parity {
    * are therefore NOT compared — a PE/JS divergence in an HttpOnly cookie will
    * not be caught here. Assert on those via `read_network_requests` / response
    * Set-Cookie headers in a dedicated test, not expectParity.
+   *
+   * Submit-intent requirements (the `submit` path runs the intent TWICE against
+   * the same server, and compares whole cookie jars from two contexts):
+   * - DOUBLE EXECUTION: the JS path submits, then the no-JS pass reloads the
+   *   same `originUrl` in a fresh context and submits AGAIN. Both hit the one
+   *   running server, so a non-idempotent action runs twice. The no-JS snapshot
+   *   then observes BOTH mutations unless the mutated state is per-session /
+   *   per-context — e.g. an add-to-cart count only reaches the same value on
+   *   both transports if the cart is session-scoped (the JS context and the
+   *   fresh no-JS context are distinct sessions). A globally-shared counter
+   *   would read N after the JS submit and N+1 after the no-JS submit and
+   *   false-mismatch. Make the action's observable state session/context-scoped,
+   *   or assert the submit path some other way.
+   * - COOKIE JAR vs DELTA: the cookie check compares the WHOLE `document.cookie`
+   *   of two different contexts. The JS context carries every cookie accumulated
+   *   before the intent (consent, analytics, prior navigations); the fresh no-JS
+   *   context starts empty. Unrelated pre-existing cookies therefore false-
+   *   mismatch — expectParity compares jars, not the per-submit cookie delta.
+   *   Keep the JS context's pre-intent cookie state minimal, or assert the
+   *   specific Set-Cookie elsewhere.
+   * - RANGO STATE COOKIE: the rango state cookie (default prefix `rango-state`)
+   *   is written/rotated only by the client runtime, so it is JS-only by design
+   *   and would always diverge — it is excluded from the comparison
+   *   automatically. A custom `stateCookiePrefix` (or any other volatile/JS-only
+   *   cookie) is excluded via `opts.ignoreCookies`.
    */
   expectParity: (
     page: Page,
@@ -178,8 +213,16 @@ async function settleSubmit(
         `\`observe\`, or pass \`waitFor\` to express the precise post-submit wait.`,
     );
   }
-  // Landed but never stabilized within the ceiling: fall through and snapshot
-  // the last-read state; the parity equality assertion surfaces any mismatch.
+  // Landed but never stabilized within the ceiling: warn (so a slow/flaky action
+  // is visible rather than silently snapshotting a mid-flight DOM), then fall
+  // through and snapshot the last-read state — the parity equality assertion
+  // still surfaces any JS-vs-no-JS mismatch. A throw here would risk failing a
+  // slow-but-correct submit, so this stays a warning.
+  console.warn(
+    `expectParity: the observed testids [${observe.join(", ")}] did not stabilize ` +
+      `within 5s; snapshotting the last-read state. If this is flaky, pass ` +
+      `\`waitFor\` to express the precise post-submit wait.`,
+  );
 }
 
 async function snapshot(
@@ -188,7 +231,13 @@ async function snapshot(
 ): Promise<ParitySnapshot> {
   const testIds: Record<string, string | null> = {};
   for (const id of observe) {
-    testIds[id] = await page.locator(`[data-testid="${id}"]`).textContent();
+    // Match readObserved: .first() (a testid may repeat) + .catch (a missing
+    // testid yields null, not an unhandled rejection).
+    testIds[id] = await page
+      .locator(`[data-testid="${id}"]`)
+      .first()
+      .textContent()
+      .catch(() => null);
   }
   return {
     testIds,
@@ -197,6 +246,35 @@ async function snapshot(
   };
 }
 
+// Reduce a `document.cookie` string to the cookies that should match across the
+// JS and no-JS transports. The rango state cookie (default prefix `rango-state`)
+// is always dropped — it is written/rotated only by the client runtime, so it
+// exists in the JS jar but never the no-JS one. `ignore` drops additional names
+// (a custom stateCookiePrefix, or other JS-only/volatile cookies) by exact
+// string or RegExp match. Returns a normalized, sorted `name=value; ...` string.
+function parityCookies(
+  cookieString: string,
+  ignore: ReadonlyArray<string | RegExp>,
+): string {
+  const isIgnored = (name: string): boolean => {
+    if (name.startsWith(DEFAULT_STATE_COOKIE_PREFIX)) return true;
+    return ignore.some((m) =>
+      typeof m === "string" ? m === name : m.test(name),
+    );
+  };
+  return cookieString
+    .split(";")
+    .map((c) => c.trim())
+    .filter((c) => c.length > 0)
+    .filter((c) => {
+      const eq = c.indexOf("=");
+      const name = eq === -1 ? c : c.slice(0, eq);
+      return !isIgnored(name);
+    })
+    .sort()
+    .join("; ");
+}
+
 export function createParity({
   test: _test,
   expect,
@@ -296,7 +374,10 @@ export function createParity({
         return url.pathname + url.search + url.hash;
       };
       expect(locationOf(noJsSnapshot.url)).toEqual(locationOf(jsSnapshot.url));
-      expect(noJsSnapshot.cookies).toEqual(jsSnapshot.cookies);
+      const ignore = opts.ignoreCookies ?? [];
+      expect(parityCookies(noJsSnapshot.cookies, ignore)).toEqual(
+        parityCookies(jsSnapshot.cookies, ignore),
+      );
     } finally {
       await noJsContext.close();
     }

package/src/testing/e2e/server.ts

@@ -12,6 +12,12 @@ export type { SpawnOptions };
 export interface RunCliHandle {
   proc: ReturnType<typeof x>["process"];
   done: Promise<void>;
+  /**
+   * Resolves with the process's exit code (null if killed by signal) when it
+   * exits. Unlike `done`, callers can branch on a nonzero code. Used to fail
+   * the build step loudly; the long-running serve processes never inspect it.
+   */
+  exitCode: Promise<number | null>;
   findPort: (timeoutMs?: number) => Promise<number>;
   kill: () => void;
   stdout: () => string;
@@ -49,11 +55,16 @@ export function runCli(
       console.log(styleText("magenta", label), data.toString());
     }
   });
+  let resolveExitCode!: (code: number | null) => void;
+  const exitCode = new Promise<number | null>((resolve) => {
+    resolveExitCode = resolve;
+  });
   const done = new Promise<void>((resolve) => {
     child.on("exit", (code) => {
       if (code !== 0 && code !== 143 && process.platform !== "win32") {
         console.log(styleText("magenta", `${label}`), `exit code ${code}`);
       }
+      resolveExitCode(code);
       resolve();
     });
   });
@@ -106,6 +117,7 @@ export function runCli(
   return {
     proc: child,
     done,
+    exitCode,
     findPort,
     kill,
     stdout: () => stdout,

package/src/testing/flight-matchers.ts

@@ -29,21 +29,19 @@
  */
 
 import { expect } from "vitest";
-import { normalizeFlight } from "./flight.js";
+// Import from the serializer-free module, NOT ./flight.js: that module
+// top-level imports the vendored react-server-dom serializer, which throws when
+// loaded outside the `react-server` condition. flight-matchers must be
+// importable under the plain node condition (a consumer's shared setupFiles
+// does `expect.extend(flightMatchers)`), so it cannot transitively pull in the
+// serializer.
+import { normalizeFlight } from "./flight-normalize.js";
 
 interface MatcherResult {
   pass: boolean;
   message: () => string;
 }
 
-/**
- * Matcher object for `expect.extend(flightMatchers)`.
- *
- * - `toMatchFlight(received, expected)` — `received` is a rendered Flight
- *   string; passes if its normalized form contains `expected`.
- * - `toMatchFlightSnapshot(received)` — delegates to vitest's snapshot on the
- *   normalized Flight string.
- */
 export const flightMatchers: {
   toMatchFlight(received: string, expected: string): MatcherResult;
   toMatchFlightSnapshot(received: string): MatcherResult;
@@ -72,12 +70,7 @@ export const flightMatchers: {
   },
 
   toMatchFlightSnapshot(received: string): MatcherResult {
-    // Delegate to vitest's snapshot engine on the normalized string. The
-    // snapshot is keyed by the current test file/title (vitest tracks this via
-    // the active test context), not by this call site, so delegating through a
-    // freshly imported `expect` is reliable.
     expect(normalizeFlight(received)).toMatchSnapshot();
-    // toMatchSnapshot throws on mismatch; reaching here means it passed.
     return {
       pass: true,
       message: () => "Flight snapshot matched.",

package/src/testing/flight-normalize.ts

@@ -0,0 +1,11 @@
+// Volatile leading reference row: `:N<timestamp>` (dev only).
+const REFERENCE_ROW_RE = /^:N[\d.]+\n/;
+// Absolute file:// paths in dev stack rows. Pattern matches frames
+// `["Component","file:///path",<line>,<col>...]` and scrubs the path only.
+const FILE_URL_RE = /file:\/\/[^"\\]+(?=",\d+,\d+)/g;
+
+export function normalizeFlight(flight: string): string {
+  return flight
+    .replace(REFERENCE_ROW_RE, "")
+    .replace(FILE_URL_RE, "file://<path>");
+}

package/src/testing/flight-runtime.d.ts

@@ -18,4 +18,40 @@ declare module "@vitejs/plugin-rsc/vendor/react-server-dom/server.edge" {
     clientManifest: unknown,
     options?: { onError?: (error: unknown) => string | void },
   ): ReadableStream<Uint8Array>;
+
+  /**
+   * Tag a value as a client reference. Mutates `impl` in place (defining
+   * `$$typeof`/`$$id`/`$$async`) and returns it, so a server tree that imports
+   * the same module binding renders it as a client boundary (an `I` row) rather
+   * than inlining it. `$$id` becomes `${id}#${exportName}`.
+   */
+  export function registerClientReference<T>(
+    impl: T,
+    id: string,
+    exportName: string,
+  ): T;
+}
+
+/**
+ * Vendored react-server-dom CLIENT deserializer wrappers shipped inside
+ * @vitejs/plugin-rsc. Used by renderServerTree to turn a Flight wire string
+ * back into an inspectable React element tree. These run in the same
+ * `react-server`-condition worker as the serializer (deserialize-only never
+ * renders, so the client React/react-dom imports they pull are inert).
+ */
+declare module "@vitejs/plugin-rsc/react/browser" {
+  export function createFromReadableStream<T = unknown>(
+    stream: ReadableStream<Uint8Array>,
+    options?: { temporaryReferences?: unknown },
+  ): Promise<T>;
+}
+
+declare module "@vitejs/plugin-rsc/core/browser" {
+  /**
+   * Install the module loader the client deserializer resolves client
+   * references through. Init-once per worker (first call wins).
+   */
+  export function setRequireModule(options: {
+    load: (id: string) => unknown;
+  }): void;
 }