Skip to content

Commit 163f5e6

Browse files
committed
refactor(testing)!: rangoTestConfig/rangoTestAliases take preset, not cloudflare:true
The boolean did not extend. Mirror the rango() Vite plugin's preset: "node" | "cloudflare" (default "node") so future presets are an additive VALUE, not a new option. `{ preset: "cloudflare" }` stubs the CF runtime virtuals (cloudflare:workers / cloudflare:email); `{}` / "node" does not. Pre-stable rename, no deprecated alias (API-hygiene rule). Updated the 3 in-repo vitest configs, the installed-vitest-config quickstart guard (+ its load.mjs), docs/testing.md (incl. the reference signature), SKILL.md, and feature-map.md. Also corrected a stale SKILL decision-tree row that still said runLoader takes the raw fn only (it accepts a registered createLoader since the prior commit). BREAKING (experimental/preview only): consumers on `{ cloudflare: true }` switch to `{ preset: "cloudflare" }`.
1 parent 4fba1c4 commit 163f5e6

7 files changed

Lines changed: 22 additions & 20 deletions

File tree

‎packages/rangojs-router/docs/internal/feature-map.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -32,7 +32,7 @@ Related docs:
3232
| `./host` | Host-based multi-app routing: `createHostRouter`, `defineHosts`, host matching types. Route builder splits intent: `.map((request) => Response)` (inline handler) vs `.lazy(() => import("./sub-app"))` (lazy mount) |
3333
| `./host/testing` | Host router test helpers |
3434
| `./testing` | Consumer unit + integration primitives (Vite-driven Vitest): unit (`runMiddleware`, `runLoader`), integration (`dispatch`), cache/prerender signals (`assertCacheStatus`, `parseCacheHeader`, `createCacheSink`, `filterCacheDecisions`), generated-route drift (`diffGeneratedRoutes`, `assertGeneratedRoutesMatch`), handle collect (`collectHandle`), advanced context (`runInRequestContext`, `runWithRequestContext`, `createTestRequestContext`, `toRequest`, `seedVariables`). Never references React, `@testing-library/react`, `@playwright/test`, or the RSC runtime — those live at the entries below. Pulls the router-manifest virtuals, so it needs the rango Vite plugin (or a `@rangojs/router:version` alias). |
35-
| `./testing/vitest` | Vitest setup helper. `rangoTestConfig({ cloudflare? })` -> the `test`-block fragment `{ alias, server: { deps: { inline } } }` (recommended; spread into `test`); `rangoTestAliases({ cloudflare? })` -> just the `resolve.alias` entries; `rangoInlineDeps` -> the `server.deps.inline` patterns. Aliases bare `@rangojs/router` to its react-server entry (real impls, client React kept) and stubs the `@rangojs/router:version` / `@vitejs/plugin-rsc/rsc` (and optionally `cloudflare:workers`/`cloudflare:email`) virtuals. `deps.inline` is required for an installed consumer (rango ships TS source; Node >= 23 won't type-strip `.ts` under node_modules). UNLIKE every other entry, this one SHIPS AS COMPILED JS (`dist/testing/vitest.js`, built by `pnpm build`) because a `vitest.config.ts` is loaded directly by Node — same reason `./vite` is compiled. Imports just `node:url`; alias targets are anchored at the package root so they resolve to `src/*.ts` from both the source and `dist` layouts. |
35+
| `./testing/vitest` | Vitest setup helper. `rangoTestConfig({ preset? })` -> the `test`-block fragment `{ alias, server: { deps: { inline } } }` (recommended; spread into `test`); `rangoTestAliases({ preset? })` -> just the `resolve.alias` entries (`preset: "node" \| "cloudflare"`, default `"node"`, mirrors `rango({ preset })`; `"cloudflare"` also stubs the CF runtime virtuals); `rangoInlineDeps` -> the `server.deps.inline` patterns. Aliases bare `@rangojs/router` to its react-server entry (real impls, client React kept) and stubs the `@rangojs/router:version` / `@vitejs/plugin-rsc/rsc` (and optionally `cloudflare:workers`/`cloudflare:email`) virtuals. `deps.inline` is required for an installed consumer (rango ships TS source; Node >= 23 won't type-strip `.ts` under node_modules). UNLIKE every other entry, this one SHIPS AS COMPILED JS (`dist/testing/vitest.js`, built by `pnpm build`) because a `vitest.config.ts` is loaded directly by Node — same reason `./vite` is compiled. Imports just `node:url`; alias targets are anchored at the package root so they resolve to `src/*.ts` from both the source and `dist` layouts. |
3636
| `./testing/dom` | Component-render testing: `renderRoute` (RTL-style client-tree stub) + its types. Separate so the `./testing` barrel never references React/`@testing-library/react`; `renderRoute` lazy-loads `@testing-library/react` at call time. Run in a DOM env (happy-dom/jsdom). |
3737
| `./testing/e2e` | Playwright harness factory `createRangoE2E({ test, expect })` -> `useFixture`, `parityDescribe`, `expectParity`, page helpers (`waitForHydration`, `expectNoReload`, …), `testNoJs`, `rangoMatchers` (`toHaveRangoPathname` + type augmentation). Also re-exports the pure cache-status helpers (`assertCacheStatus`, `parseCacheHeader`, `createCacheSink`, `filterCacheDecisions`) so they are usable in a Playwright e2e — the `./testing` barrel can't be imported in a plain Playwright runner (it pulls the build-only `@rangojs/router:version` virtual). Separate so it loads in a plain (non-Vite) Playwright runner; takes the consumer's `test`/`expect`, never importing `@playwright/test` at runtime. |
3838
| `./testing/flight` | Real Flight (RSC) rendering, `react-server` condition only: `renderToFlightString`, `normalizeFlight`, `assertFlightRuntimeAvailable`. Separate entry because its vendored react-server-dom serializer loads only under that node condition. A thrown Server Component surfaces as a rejected promise (the stream still completes), not a hang. |

‎packages/rangojs-router/docs/testing.md‎

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -173,9 +173,9 @@ export default defineConfig({
173173
globals: true,
174174
include: ["test/**/*.{test,spec}.{ts,tsx}"],
175175
environment: "node", // renderRoute tests use a `// @vitest-environment happy-dom` pragma
176-
// `cloudflare: true` also stubs the cloudflare:workers / cloudflare:email
177-
// runtime virtuals a Cloudflare app's route tree imports.
178-
...rangoTestConfig({ cloudflare: true }),
176+
// `preset: "cloudflare"` also stubs the cloudflare:workers / cloudflare:email
177+
// runtime virtuals a Cloudflare app's route tree imports (default: "node").
178+
...rangoTestConfig({ preset: "cloudflare" }),
179179
},
180180
});
181181
```
@@ -834,9 +834,9 @@ the Flight helpers from `@rangojs/router/testing/flight`.
834834

835835
```ts
836836
// Setup — @rangojs/router/testing/vitest (ships as compiled JS; node-loadable in vitest.config.ts)
837-
rangoTestConfig(opts?: { cloudflare?: boolean }): { alias: TestAlias[]; server: { deps: { inline: RegExp[] } } };
838-
// test: { ..., ...rangoTestConfig({ cloudflare: true }) } // aliases + the required deps.inline
839-
rangoTestAliases(opts?: { cloudflare?: boolean }): { find: string|RegExp; replacement: string }[]; // aliases only
837+
rangoTestConfig(opts?: { preset?: "node" | "cloudflare" }): { alias: TestAlias[]; server: { deps: { inline: RegExp[] } } };
838+
// test: { ..., ...rangoTestConfig({ preset: "cloudflare" }) } // aliases + the required deps.inline
839+
rangoTestAliases(opts?: { preset?: "node" | "cloudflare" }): { find: string|RegExp; replacement: string }[]; // aliases only
840840
rangoInlineDeps: RegExp[]; // the server.deps.inline patterns, if wiring them yourself
841841

842842
// Unit

‎packages/rangojs-router/skills/testing/SKILL.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -90,7 +90,7 @@ The single rule that drives everything:
9090
| The behavior is… | Layer | Primitive | Import root |
9191
| --------------------------------------------------------------------------------------------------------- | ------------ | ---------------------------------------------------------------- | -------------------------------- |
9292
| a pure function / `reverse` / a predicate (`revalidate`, `isAction`) | unit (node) | call it directly; `runMiddleware`/`runLoader` for ctx | `@rangojs/router/testing` |
93-
| one loader's data logic | unit (node) | `runLoader` (pass the **raw fn**, not `createLoader`) | `@rangojs/router/testing` |
93+
| one loader's data logic | unit (node) | `runLoader` (a registered `createLoader` handle, or the raw fn) | `@rangojs/router/testing` |
9494
| one middleware's ordering / short-circuit / cookie+header merge | unit (node) | `runMiddleware` | `@rangojs/router/testing` |
9595
| a CLIENT component reading router context (`useParams`/`useReverse`/`Outlet`/`useNavigation`/`useLoader`) | unit (DOM) | `renderRoute` (needs happy-dom/jsdom + `@testing-library/react`) | `@rangojs/router/testing/dom` |
9696
| a redirect / status / headers / cookies / **response route** (json/text/html/xml/md), no Flight | integration | `dispatch` (router -> Response) | `@rangojs/router/testing` |
@@ -486,7 +486,7 @@ export default defineConfig({
486486
globals: true,
487487
include: ["test/**/*.test.{ts,tsx}"],
488488
environment: "node",
489-
...rangoTestConfig({ cloudflare: true }),
489+
...rangoTestConfig({ preset: "cloudflare" }),
490490
},
491491
});
492492
```

‎packages/rangojs-router/src/__tests__/installed-vitest-config.test.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -73,7 +73,7 @@ describe("installed vitest config (real node_modules realpath)", () => {
7373
join(tmp, "load.mjs"),
7474
`import { rangoTestConfig } from "@rangojs/router/testing/vitest";
7575
import { existsSync } from "node:fs";
76-
const cfg = rangoTestConfig({ cloudflare: true });
76+
const cfg = rangoTestConfig({ preset: "cloudflare" });
7777
if (cfg.alias.length !== 5) throw new Error("expected 5 aliases, got " + cfg.alias.length);
7878
if (!cfg.server.deps.inline.length) throw new Error("missing server.deps.inline");
7979
if (!cfg.alias.every((a) => existsSync(a.replacement)))

‎packages/rangojs-router/src/testing/vitest.ts‎

Lines changed: 10 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -20,7 +20,7 @@
2020
* - The build-only `@rangojs/router:version` virtual and `@vitejs/plugin-rsc/rsc`
2121
* (whose real body imports unresolvable Vite virtuals) are stubbed.
2222
* - Cloudflare apps additionally import the `cloudflare:workers` /
23-
* `cloudflare:email` runtime virtuals; pass `{ cloudflare: true }` to stub them.
23+
* `cloudflare:email` runtime virtuals; pass `{ preset: "cloudflare" }` to stub them.
2424
*
2525
* Usage (recommended one-call form — see {@link rangoTestConfig}):
2626
*
@@ -34,7 +34,7 @@
3434
* globals: true,
3535
* include: ["test/**\/*.test.{ts,tsx}"],
3636
* environment: "node",
37-
* ...rangoTestConfig({ cloudflare: true }),
37+
* ...rangoTestConfig({ preset: "cloudflare" }),
3838
* },
3939
* });
4040
* ```
@@ -70,11 +70,13 @@ export interface TestAlias {
7070
/** Options for {@link rangoTestAliases}. */
7171
export interface RangoTestAliasOptions {
7272
/**
73-
* Stub the Cloudflare Workers runtime virtuals (`cloudflare:workers` /
74-
* `cloudflare:email`). Enable for a Cloudflare app whose route tree imports
75-
* them. Default: false.
73+
* Deployment preset, matching `rango({ preset })` in the Vite plugin. With
74+
* `"cloudflare"` the helper additionally stubs the Cloudflare Workers runtime
75+
* virtuals (`cloudflare:workers` / `cloudflare:email`) a CF app's route tree
76+
* imports. A string (not a boolean) so more presets can be added without an
77+
* API change. Default: `"node"`.
7678
*/
77-
cloudflare?: boolean;
79+
preset?: "node" | "cloudflare";
7880
}
7981

8082
/**
@@ -113,7 +115,7 @@ export function rangoTestAliases(
113115
},
114116
];
115117

116-
if (opts.cloudflare) {
118+
if (opts.preset === "cloudflare") {
117119
aliases.push(
118120
{
119121
find: "cloudflare:workers",
@@ -166,7 +168,7 @@ export interface RangoTestConfig {
166168
* globals: true,
167169
* include: ["test/**\/*.test.{ts,tsx}"],
168170
* environment: "node",
169-
* ...rangoTestConfig({ cloudflare: true }),
171+
* ...rangoTestConfig({ preset: "cloudflare" }),
170172
* },
171173
* });
172174
* ```

‎tests/cloudflare-basic/test/FINDINGS.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -20,7 +20,7 @@ items are inherent limitations (full-router import; flight ctx) documented below
2020

2121
> **Resolution:** the manual setup below is now packaged as the
2222
> `@rangojs/router/testing/vitest` preset — `vitest.config.ts` here is just
23-
> `resolve: { alias: rangoTestAliases({ cloudflare: true }) }`. The notes below
23+
> `resolve: { alias: rangoTestAliases({ preset: "cloudflare" }) }`. The notes below
2424
> explain what that preset does and why.
2525
2626
The docs' setup for `dispatch` is "`vi.mock('@vitejs/plugin-rsc/rsc')` then

‎tests/cloudflare-basic/vitest.config.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -18,6 +18,6 @@ export default defineConfig({
1818
include: ["test/**/*.{test,spec}.{ts,tsx}"],
1919
exclude: ["node_modules", "dist", "e2e", "test/**/*.rsc-test.*"],
2020
environment: "node",
21-
...rangoTestConfig({ cloudflare: true }),
21+
...rangoTestConfig({ preset: "cloudflare" }),
2222
},
2323
});

0 commit comments

Comments
 (0)