@rangojs/router 0.0.0-experimental.d7eeaa75 → 0.0.0-experimental.d98a8e9d

package/src/testing/e2e/fixture.ts

@@ -0,0 +1,188 @@
+// Consumer-facing server-lifecycle fixture. Parameterized lift of the internal
+// e2e/fixture.ts: the test-app-specific shared-server reuse and default-root
+// build skipping are removed; a consumer points `root` at their own app.
+
+import { rm } from "node:fs/promises";
+import path from "node:path";
+import type { TestType } from "@playwright/test";
+import {
+  createIsolatedViteCacheDir,
+  runCli,
+  type RunCliHandle,
+  type SpawnOptions,
+  waitForReady,
+  warmupDevServer,
+} from "./server.js";
+
+export interface FixtureOptions {
+  /** Absolute or cwd-relative path to the consumer app under test. */
+  root: string;
+  /**
+   * 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`). */
+  buildCommand?: string;
+  cliOptions?: SpawnOptions;
+  /** Spawn a per-suite server with an isolated Vite cache dir (dev only warmup). */
+  isolatedServer?: boolean;
+  /** Path to poll for readiness (default: "/"). Use when a basename moves routes off "/". */
+  readyPath?: string;
+  /** Skip the production build step (assumes an existing build). */
+  skipBuild?: boolean;
+}
+
+export interface Fixture {
+  mode: "dev" | "build";
+  root: string;
+  /** Resolve a path against the running server's base URL. */
+  url: (url?: string) => string;
+  /** The underlying spawned process handle (undefined before beforeAll). */
+  proc: () => RunCliHandle | undefined;
+}
+
+/**
+ * Build a `useFixture` bound to a consumer-provided Playwright `test` object.
+ * The returned function registers `beforeAll`/`afterAll` hooks that spawn and
+ * tear down a dev or preview server for the app at `options.root`.
+ */
+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;
+
+    const cwd = path.resolve(options.root);
+    let proc: RunCliHandle | undefined;
+    let isolatedViteCacheDir: string | undefined;
+
+    test.beforeAll(async ({}, testInfo) => {
+      if (options.isolatedServer) {
+        isolatedViteCacheDir = createIsolatedViteCacheDir(
+          cwd,
+          testInfo.project.name,
+          options.mode,
+        );
+      }
+      const cliEnv = {
+        ...options.cliOptions?.env,
+        ...(isolatedViteCacheDir
+          ? { RANGO_E2E_VITE_CACHE_DIR: isolatedViteCacheDir }
+          : {}),
+      };
+
+      if (options.mode === "dev") {
+        proc = runCli({
+          command: options.command ?? `pnpm dev`,
+          label: `${options.root}:dev`,
+          cwd,
+          ...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
+          ? `${baseURL}${options.readyPath}`
+          : baseURL;
+        await waitForReady(readyUrl, () => ({
+          stdout: proc!.stdout(),
+          stderr: proc!.stderr(),
+        }));
+        // Isolated dev servers need a warmup SSR request to trigger Vite's
+        // dep optimizer before real tests run. The first full SSR request
+        // discovers deps -> `ERR_OUTDATED_OPTIMIZED_DEP` -> module
+        // re-evaluation -> loss of in-memory cache. Without this, cache
+        // tests see different values on the second request.
+        if (options.isolatedServer) {
+          await warmupDevServer(readyUrl);
+        }
+      }
+
+      if (options.mode === "build") {
+        const skipBuild = options.skipBuild || !!process.env.TEST_SKIP_BUILD;
+        if (!skipBuild) {
+          const buildProc = runCli({
+            command: options.buildCommand ?? `pnpm build`,
+            label: `${options.root}:build`,
+            cwd,
+            ...options.cliOptions,
+            env: cliEnv,
+          });
+          // 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`,
+          label: `${options.root}:preview`,
+          cwd,
+          ...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
+          ? `${baseURL}${options.readyPath}`
+          : baseURL;
+        await waitForReady(buildReadyUrl, () => ({
+          stdout: proc!.stdout(),
+          stderr: proc!.stderr(),
+        }));
+      }
+    });
+
+    test.afterAll(async () => {
+      await cleanup?.();
+      if (isolatedViteCacheDir) {
+        await rm(isolatedViteCacheDir, { recursive: true, force: true });
+      }
+    });
+
+    return {
+      mode: options.mode,
+      root: cwd,
+      url: (url: string = "./") => new URL(url, baseURL).href,
+      proc: () => proc,
+    };
+  };
+}

package/src/testing/e2e/index.ts

@@ -0,0 +1,149 @@
+// 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,
+  type Fixture,
+  type FixtureOptions,
+} from "./fixture.js";
+import {
+  createPageHelpers,
+  createStopwatch,
+  getHistoryState,
+  getNumericContent,
+  goBack,
+  goForward,
+  isVisibleInViewport,
+  measureTime,
+  type PageHelpers,
+  parseNumber,
+  type Stopwatch,
+  testId,
+  waitForElement,
+  waitForHydration,
+  waitForNavigation,
+} from "./page-helpers.js";
+import {
+  createParity,
+  type ExpectParityOptions,
+  type Parity,
+  type ParityDescribeOptions,
+  type ParityIntent,
+} 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,
+  parseCacheHeader,
+  createCacheSink,
+  filterCacheDecisions,
+  type CacheSink,
+  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,
+  waitForNavigation,
+  goBack,
+  goForward,
+  getHistoryState,
+  waitForElement,
+  isVisibleInViewport,
+  parseNumber,
+  getNumericContent,
+  createStopwatch,
+  measureTime,
+  createPageHelpers,
+  createUseFixture,
+  createParity,
+  createRangoMatchers,
+};
+export type {
+  Fixture,
+  FixtureOptions,
+  PageHelpers,
+  Stopwatch,
+  Parity,
+  ParityIntent,
+  ParityDescribeOptions,
+  ExpectParityOptions,
+  RangoMatchers,
+};
+
+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;
+  goBack: typeof goBack;
+  goForward: typeof goForward;
+  getHistoryState: typeof getHistoryState;
+  waitForElement: typeof waitForElement;
+  isVisibleInViewport: typeof isVisibleInViewport;
+  parseNumber: typeof parseNumber;
+  getNumericContent: typeof getNumericContent;
+  createStopwatch: typeof createStopwatch;
+  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,
+  defaultRoot,
+}: {
+  test: TestType<any, any>;
+  expect: Expect;
+  defaultRoot?: string;
+}): RangoE2E {
+  const useFixture = createUseFixture(test);
+  const pageHelpers = createPageHelpers(expect);
+  const parity = createParity({ test, expect, useFixture, defaultRoot });
+  const rangoMatchers = createRangoMatchers(expect);
+  const testNoJs = test.extend({
+    javaScriptEnabled: ({}, use: (value: boolean) => Promise<void>) =>
+      use(false),
+  });
+
+  return {
+    useFixture,
+    testNoJs,
+    rangoMatchers,
+    ...parity,
+    ...pageHelpers,
+    // Standalone helpers.
+    testId,
+    waitForHydration,
+    waitForNavigation,
+    goBack,
+    goForward,
+    getHistoryState,
+    waitForElement,
+    isVisibleInViewport,
+    parseNumber,
+    getNumericContent,
+    createStopwatch,
+    measureTime,
+  };
+}

package/src/testing/e2e/matchers.ts

@@ -0,0 +1,51 @@
+// 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 {
+  pass: boolean;
+  message: () => string;
+}
+
+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 {
+      const actual = new URL(page.url()).pathname;
+      const pass = actual === expected;
+      return {
+        pass,
+        message: () =>
+          pass
+            ? `Expected pathname not to be "${expected}"`
+            : `Expected pathname "${expected}" but got "${actual}"`,
+      };
+    },
+  };
+}
+
+// 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 {
+    interface Matchers<R, T> {
+      toHaveRangoPathname(expected: string): R;
+    }
+  }
+}

package/src/testing/e2e/page-helpers.ts

@@ -0,0 +1,272 @@
+// Page helpers for the consumer e2e harness. Type-only Playwright imports keep
+// this module loadable in a plain-node process. Helpers needing assertions are
+// returned from `createPageHelpers(expect)`; the rest are standalone.
+
+import type { ConsoleMessage, Expect, Locator, Page } from "@playwright/test";
+
+// ============================================================================
+//  Standalone helpers (need only a page/locator)
+// ============================================================================
+
+/** Get a locator by data-testid attribute. */
+export function testId(page: Page, id: string): Locator {
+  return page.locator(`[data-testid="${id}"]`);
+}
+
+/**
+ * Wait for React hydration to complete and verify no hydration errors.
+ * Rango sets `data-hydrated` on `<html>` after hydration via useEffect; this
+ * is a stable readiness signal that does not rely on React internals.
+ */
+export async function waitForHydration(page: Page): Promise<void> {
+  const hydrationErrors: string[] = [];
+
+  const isHydrationError = (text: string) =>
+    text.includes("Hydration failed") ||
+    text.includes("hydration mismatch") ||
+    text.includes("Text content does not match") ||
+    text.includes("did not match") ||
+    text.includes("server rendered HTML") ||
+    text.includes("Hydration error");
+
+  const consoleHandler = (msg: ConsoleMessage) => {
+    const text = msg.text();
+    if (isHydrationError(text)) hydrationErrors.push(text);
+  };
+
+  // React throws hydration errors as page errors.
+  const pageErrorHandler = (error: Error) => {
+    if (isHydrationError(error.message)) hydrationErrors.push(error.message);
+  };
+
+  page.on("console", consoleHandler);
+  page.on("pageerror", pageErrorHandler);
+
+  try {
+    await page.waitForLoadState("domcontentloaded");
+    await page.waitForFunction(
+      () => document.documentElement.hasAttribute("data-hydrated"),
+      { timeout: 20000 },
+    );
+    // Small delay to catch any async hydration errors.
+    await page.waitForTimeout(100);
+    if (hydrationErrors.length > 0) {
+      throw new Error(
+        `Hydration errors detected:\n${hydrationErrors.join("\n")}`,
+      );
+    }
+  } finally {
+    page.off("console", consoleHandler);
+    page.off("pageerror", pageErrorHandler);
+  }
+}
+
+/** Wait for navigation to complete (URL change + network idle). */
+export async function waitForNavigation(
+  page: Page,
+  expectedUrl: string | RegExp,
+): Promise<void> {
+  await page.waitForURL(expectedUrl, { waitUntil: "networkidle" });
+}
+
+/** Navigate back and wait for navigation to complete. */
+export async function goBack(page: Page): Promise<void> {
+  // Wait for the URL to actually CHANGE. A `/.*/ ` pattern matches the current
+  // URL immediately, so it would resolve before the history navigation happened.
+  const from = page.url();
+  await Promise.all([
+    page.waitForURL((url) => url.toString() !== from, {
+      waitUntil: "networkidle",
+    }),
+    page.goBack(),
+  ]);
+}
+
+/** Navigate forward and wait for navigation to complete. */
+export async function goForward(page: Page): Promise<void> {
+  const from = page.url();
+  await Promise.all([
+    page.waitForURL((url) => url.toString() !== from, {
+      waitUntil: "networkidle",
+    }),
+    page.goForward(),
+  ]);
+}
+
+/** Get the current history state. */
+export async function getHistoryState(page: Page): Promise<unknown> {
+  return page.evaluate(() => window.history.state);
+}
+
+/** Wait for an element to appear and be visible. */
+export async function waitForElement(
+  page: Page,
+  selector: string,
+  timeout = 10000,
+): Promise<void> {
+  await page.locator(selector).waitFor({ state: "visible", timeout });
+}
+
+/** Check if an element is visible. */
+export async function isVisibleInViewport(
+  page: Page,
+  selector: string,
+): Promise<boolean> {
+  return page.locator(selector).isVisible();
+}
+
+/**
+ * Parse a number from text content (finds first number in string).
+ *
+ * @example
+ * parseNumber("Load count: 42") // 42
+ * parseNumber(null) // 0
+ */
+export function parseNumber(text: string | null | undefined): number {
+  return parseInt(text?.match(/\d+/)?.[0] || "0", 10);
+}
+
+/** Get the numeric value from an element's text content. */
+export async function getNumericContent(locator: Locator): Promise<number> {
+  const text = await locator.textContent();
+  return parseNumber(text);
+}
+
+export interface Stopwatch {
+  elapsed: () => number;
+  checkpoint: () => number;
+}
+
+/** Create a stopwatch for timing multiple checkpoints. */
+export function createStopwatch(): Stopwatch {
+  const startTime = Date.now();
+  return {
+    elapsed: () => Date.now() - startTime,
+    checkpoint: () => Date.now() - startTime,
+  };
+}
+
+/**
+ * Measure elapsed time for an async operation. Returns `{ elapsed, result }`
+ * where `elapsed` is in milliseconds.
+ */
+export async function measureTime<T>(
+  fn: () => Promise<T>,
+): Promise<{ elapsed: number; result: T }> {
+  const startTime = Date.now();
+  const result = await fn();
+  const elapsed = Date.now() - startTime;
+  return { elapsed, result };
+}
+
+// ============================================================================
+//  Factory-bound helpers (need the injected `expect`)
+// ============================================================================
+
+export interface PageHelpers {
+  /** Assert that no full page reload occurred between scope entry and exit. */
+  expectNoReload: (page: Page) => AsyncDisposable;
+  /** Collect page errors and assert none occurred on scope exit. */
+  expectNoPageError: (page: Page) => Disposable;
+  /** Wait for an element's text to change from its initial value. */
+  waitForTextChange: (
+    locator: Locator,
+    initialText: string,
+    timeout?: number,
+  ) => Promise<void>;
+  /** Wait for a numeric value in an element to change. */
+  waitForNumericChange: (
+    locator: Locator,
+    initialValue: number,
+    timeout?: number,
+  ) => Promise<void>;
+  /** Assert timing is within `expected +/- tolerance`. */
+  expectTiming: (elapsed: number, expected: number, tolerance: number) => void;
+  /** Assert timing is at least `minimum`. */
+  expectMinTiming: (elapsed: number, minimum: number) => void;
+  /** Assert timing is less than `maximum`. */
+  expectMaxTiming: (elapsed: number, maximum: number) => void;
+}
+
+export function createPageHelpers(expect: Expect): PageHelpers {
+  function expectNoReload(page: Page): AsyncDisposable {
+    const setup = page.evaluate(() => {
+      const el = document.createElement("meta");
+      el.setAttribute("name", "x-reload-check");
+      document.head.append(el);
+    });
+    return {
+      [Symbol.asyncDispose]: async () => {
+        await setup;
+        // Keep the timeout small so a real reload is reported quickly, but not
+        // so small that a busy page produces a spurious failure (which would
+        // mask the real test error as a SuppressedError under `await using`).
+        await expect(page.locator(`meta[name="x-reload-check"]`)).toBeAttached({
+          timeout: 100,
+        });
+        await page.evaluate(() => {
+          document.querySelector(`meta[name="x-reload-check"]`)!.remove();
+        });
+      },
+    };
+  }
+
+  function expectNoPageError(page: Page): Disposable {
+    const errors: Error[] = [];
+    page.on("pageerror", (error) => {
+      errors.push(error);
+    });
+    return {
+      [Symbol.dispose]: () => {
+        expect(errors).toEqual([]);
+      },
+    };
+  }
+
+  async function waitForTextChange(
+    locator: Locator,
+    initialText: string,
+    timeout = 10000,
+  ): Promise<void> {
+    await expect
+      .poll(async () => await locator.textContent(), { timeout })
+      .not.toBe(initialText);
+  }
+
+  async function waitForNumericChange(
+    locator: Locator,
+    initialValue: number,
+    timeout = 10000,
+  ): Promise<void> {
+    await expect
+      .poll(async () => parseNumber(await locator.textContent()), { timeout })
+      .not.toBe(initialValue);
+  }
+
+  function expectTiming(
+    elapsed: number,
+    expected: number,
+    tolerance: number,
+  ): void {
+    expect(elapsed).toBeGreaterThan(expected - tolerance);
+    expect(elapsed).toBeLessThan(expected + tolerance);
+  }
+
+  function expectMinTiming(elapsed: number, minimum: number): void {
+    expect(elapsed).toBeGreaterThan(minimum);
+  }
+
+  function expectMaxTiming(elapsed: number, maximum: number): void {
+    expect(elapsed).toBeLessThan(maximum);
+  }
+
+  return {
+    expectNoReload,
+    expectNoPageError,
+    waitForTextChange,
+    waitForNumericChange,
+    expectTiming,
+    expectMinTiming,
+    expectMaxTiming,
+  };
+}