feat(testing): #542 capability + coverage polish for @rangojs/router/testing - #581

Closes #542 (follow-up to #533, the consumer testing primitives).

Problem

@rangojs/router/testing shipped in #533 with the right abstractions, but four documented "false-confidence traps" still passed green while proving nothing, and the dual cache-telemetry surface had no one-call assert. From a consumer's seat:

• A test that calls renderRoute(...).navigate(...) and asserts useNavigation().state === "loading" passed — but the lifecycle is frozen at idle, so it was asserting a constant.
• A handler that calls a "use cache" function tested under renderHandler ran the uncached body (no cacheStore was reachable through the primitive at all) and the test went green, "covering" caching while exercising none of it.
• An rsc-project test missing the rangoTestAliases alias surfaced the context-stub failure as an opaque tree: undefined with no hint about the fix.
• renderRoute({ request }) with a typo'd or mount-prefixed path silently rendered empty params (matchLeaf -> null -> {}) instead of failing.

This PR turns each trap into a loud, actionable failure (test-runner-gated, zero production effect), closes the renderHandler cache-capability gap, and adds assertCacheDecision so the telemetry path has a one-call assert symmetric with assertCacheStatus.

What a consumer writes / sees differently

B — renderHandler can now exercise the cached path

Before, there was no way to reach the cached branch from renderHandler; the handler's "use cache" fn always ran uncached and the test silently proved nothing.

// BEFORE — runs UNCACHED, green but meaningless
const { tree } = await renderHandler(ProductPage, { params: { slug: "wine" } });

// AFTER — seed the store (+ profiles) and the real cached path runs
import { MemorySegmentCacheStore } from "@rangojs/router/testing";
const { tree } = await renderHandler(ProductPage, {
  params: { slug: "wine" },
  cacheStore: new MemorySegmentCacheStore(),
  cacheProfiles: { default: { ttl: 60 } }, // needed for "use cache: default"
});

If you forget to seed it, the runtime now tells you (once per cached-fn id, under the test runner only):

[rango] "use cache" function "ProductPage#0" executed but no cacheStore was seeded;
the cached path is NOT under test (it ran uncached). Pass { cacheStore, cacheProfiles }
to runLoader/runMiddleware/renderHandler/runInRequestContext (or configure
createRouter({ cache }) for dispatch) to exercise it.

G — one-call telemetry assert

import { createCacheSink, assertCacheDecision } from "@rangojs/router/testing";

const { sink, events } = createCacheSink();
const router = createRouter({ telemetry: sink }).routes(urlpatterns);
// ...drive an RSC request through router.fetch...

// BEFORE — hand-filter and dig into segment shape
const decision = filterCacheDecisions(events)[0];
expect(decision.segments?.find((s) => s.id === "product.detail")?.cacheStatus).toBe("hit");

// AFTER — one call, parallel to assertCacheStatus(res, routeKey, expected)
assertCacheDecision(events, "product.detail", "hit");

filterCacheDecisions stays for when you need the raw per-segment shouldRevalidate field.

A / C / D — traps now fail loud

// A: relying on a non-idle transition state — now warns once, naming the hooks
const { getByTestId } = await renderRoute(routes, { request: "/p/1" });
// console.warn: "...useNavigation().state, useLinkStatus().pending, and
// useAction().state stay 'idle' here. ...use renderServerTree or e2e to assert
// pending/loading/submitting transition states."

// D: a request that cannot resolve the leaf — now throws instead of empty params
await renderRoute([{ path: "/c/:slug", Component: Probe }], { request: "/typo/wine" });
// Error: renderRoute: request "/typo/wine" does not match the leaf route "/c/:slug".
//   renderRoute paths are include-RELATIVE ... A mount does NOT auto-rewrite the
//   request ... If the request URL intentionally does not carry the params, pass
//   them explicitly via the `params` option to bypass this check.

// C (rsc project): a context-reading handler with no rangoTestAliases — the
// Flight path now rethrows naming the fix instead of an opaque tree: undefined.
await renderToFlightString(<ReadsContext />); // throws, message names rangoTestAliases

Semantics

The last two rows are the review follow-up: the D guard merges options.params over the URL-extracted params in resolve(), and the params docstring blesses passing them "to avoid relying on URL parsing", so a test seeding params by hand must not be rejected. The guard fires only when no params are supplied.

Code-change summary

• src/cache/cache-runtime.ts — in the if (!store?.getItem) uncached bypass, a isUnderTestRunner()-gated console.warn deduped via a module-level warnedUncachedUnderTest: Set<string> (once per fn id). Chosen here because this is the single seam every "use cache" invocation funnels through, regardless of which primitive drove it.
• src/testing/render-handler.ts — RenderHandlerOptions gains cacheStore?: SegmentCacheStore + cacheProfiles?: Record<string, CacheProfile>, threaded into createRequestContext so the real cached path is reachable.
• src/testing/flight.ts — extracted isServerOnlyStubError(error) (shared with renderHandler) and a private rethrowFlightRenderError; the serializeNodeToFlight rethrow seam now rethrows an actionable rangoTestAliases-naming message for the stub error, original error otherwise. Both renderToFlightString and renderServerTree route through it.
• src/testing/render-route.tsx — A: one-time navigate() lifecycle warn + a fidelity-contract bullet. D: a leaf-match guard that throws on an unresolvable explicit request, skipped when explicit params are present (the documented escape hatch). Both isUnderTestRunner()-gated.
• src/testing/cache-status.ts — new assertCacheDecision(events, routeKey, expected) export (the telemetry counterpart of assertCacheStatus); module header reframed as "pick by transport".
• src/testing/index.ts, src/testing/e2e/index.ts — export assertCacheDecision.
• E was already code-complete in feat(testing): consumer testing primitives (@rangojs/router/testing) #533 (the $$id runtime fallback); this PR promotes the include-relative dispatch/assertGeneratedRoutesMatch recipe to a canonical quickstart and reframes F (steer to renderServerTree; renderToFlightString is the wire-shape escape hatch).
• Docs/skills: docs/testing.md, docs/README.md, docs/internal/feature-map.md + feature-file-map.md (new export), and the skills/testing/* set (SKILL.md, render-handler.md, cache-prerender.md, flight.md, server-tree.md, setup.md).

Test plan

• Userland through the public primitives (the dogfood guarantee):
  • src/testing/__tests__/cache-status.test.ts — assertCacheDecision pass / mismatch / missing-routeKey (lists seen ids) / "(none)".
  • src/testing/__tests__/render-route.test.tsx (29 tests) — navigation frozen-idle warns once; request/leaf validation rejects a typo and a mount-prefixed request, accepts the relative form under a dynamic mount and an omitted :locale?; accepts a non-matching request when explicit params are supplied, still rejects when params: {}; inert with no request; silent off the runner (vi.stubEnv("VITEST","")).
  • src/testing/__tests__/flight.rsc-test.tsx / flight-tree.rsc-test.tsx — the stub error is reclassified (/rangoTestAliases/); a genuine error is NOT (non-vacuity).
  • src/testing/__tests__/render-handler.rsc-test.tsx — cacheStore/cacheProfiles forwarded into the request context.
  • src/__tests__/public-consumer-imports.test.ts — assertCacheDecision/filterCacheDecisions importable from the public barrel.
• Internal pin — src/cache/__tests__/cache-runtime-stale.test.ts: the uncached-bypass warn fires once for a given fn id; the body still ran.
• pnpm run typecheck — 12/12.
• pnpm run test:unit:all (repo root, recursive) — EXIT 0 (router node 217 files + rsc 54 tests; all consumer apps green).
• pnpm run lint — 0 warnings / 0 errors.
• pnpm run format — clean.
• N/A e2e (dev + production) — every new guard is test-harness-only and isUnderTestRunner()-gated, so it has no runtime behavior to exercise in a browser; coverage is the unit/rsc userland suites above.

Notes / call-outs

• Production is untouched. Every warn/throw is gated on isUnderTestRunner() (process.env.VITEST, deliberately not folded like NODE_ENV). The B path is purely advisory — a test that intends to run uncached keeps working, just with one warn.
• Why the warn lives in cache-runtime.ts, not in renderHandler: the !store?.getItem bypass is the one seam every "use cache" call passes through (runLoader, runMiddleware, renderHandler, runInRequestContext, and dispatch). The B test asserts the option THREADING via getRequestContext rather than importing registerCachedFunction, because @vitejs/plugin-rsc/rsc does not resolve in a bare vitest worker; the warn-once behavior is pinned separately in cache-runtime-stale.test.ts (which mocks the plugin).
• Review follow-up folded in: the D guard initially rejected an unresolvable request even when explicit params were supplied, contradicting the params "avoid relying on URL parsing" contract. Fixed to skip when params are present; two tests pin both sides.
• Deliberately deferred: the literal "validate the mount prefix against the routes" item — renderRoute has no route tree and an existing test forbids policing mount-vs-path, so the real silent failure (request-vs-leaf) is what's guarded instead.