inspector/clients/web/src/test/setup.ts
cliffhall f8536cad5d docs: address Copilot review round 1
The 5000 arms of #2335's re-run each had exactly one red test — the
asyncUtilTimeout guard refusing the raised value — so "0 failures in
every arm" was a misstatement; both comments now say so. And the
AGENTS.md rule still gave the expiring-wait mechanism as the reason the
pin was measured worse, which the corrected record contradicts; it now
cites both measurements and keeps the mechanism as the hazard the rule
guards against.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01PsmUAZ6aLUAFqenjJKSSRp
Signed-off-by: cliffhall <cliff@futurescale.com>
2026-09-13 12:19:26 -04:00

281 lines
13 KiB
TypeScript

import "@testing-library/jest-dom/vitest";
import { afterEach } from "vitest";
import { cleanup, configure } from "@testing-library/react";
// Testing Library's `asyncUtilTimeout` governs every `waitFor` and `findBy*` in
// this project — 788 call sites — and is the tighter of the two bounds on any
// async assertion here, so it is stated rather than inherited (#2323). Pinning
// it also means a Testing Library upgrade that changes its default cannot move
// every one of those sites silently.
//
// ⚠️ The value is 1000 — Testing Library's own default — and that is a
// MEASURED decision, not a shrug. #2323 proposed 5000 on the reasoning that a
// contended happy-dom render is the worst case and that this becomes the
// binding constraint once the project's `testTimeout` rises. Measured on this
// machine, 5000 made the suite WORSE: three arms of three full unit runs each,
// same worktree, comparable load —
//
// • unmodified `v2/main`: 3/3 green
// • this change with 5000: 1, 4 and 0 files timing out at 15000ms
// • this change with the default: 3/3 green
//
// The failures were a different, unrelated set each time and every one passed
// in about a second in isolation, which is the shape of CPU starvation rather
// than of a slow assertion. The mechanism proposed at the time was that
// `asyncUtilTimeout` is not only a ceiling: a wait that is *meant* to expire —
// a test asserting something never appears, a poll allowed to run out — spends
// the whole budget on the happy path, so a 5x raise would be a 5x cost on
// those tests, saturating the worker pool.
//
// #2335 went looking for those tests and found none. Zero hits for every
// expiring-wait shape against Testing Library across the unit, `core/`,
// integration and story files; no test at or above 2000ms in a full unit run;
// and the same three-arm protocol re-run interleaved on a leased machine
// (1000 / 5000 / reverted, three rounds) gave 0 failures in every arm — the
// one red test in each 5000 arm being `asyncUtilTimeout.test.ts` refusing the
// raised value, which is the guard doing its job — and 0 tests at or above
// 5000ms with the raise in place. Nothing on the passing
// path spends this budget, so raising it buys nothing — and the #2323 reds
// read as ambient load the arms did not share (an inference from that data,
// not a re-measurement of the original run).
//
// So the general rule this repo now follows — a budget must be a value someone
// chose — is satisfied by choosing it, not by raising it. The pin stays at the
// default until a measurement says otherwise; `asyncUtilTimeout.test.ts`
// asserts the effective value, so moving it is deliberate by construction.
configure({ asyncUtilTimeout: 1000 });
// Node 22+ exposes an experimental `localStorage` placeholder that overrides
// happy-dom's implementation. Without `--localstorage-file`, it's an empty
// stub with no methods, which breaks anything that calls setItem/getItem.
// Install a minimal in-memory Storage shim before any test runs.
class MemoryStorage implements Storage {
private store = new Map<string, string>();
get length(): number {
return this.store.size;
}
clear(): void {
this.store.clear();
}
getItem(key: string): string | null {
return this.store.get(key) ?? null;
}
key(index: number): string | null {
return Array.from(this.store.keys())[index] ?? null;
}
removeItem(key: string): void {
this.store.delete(key);
}
setItem(key: string, value: string): void {
this.store.set(key, String(value));
}
}
Object.defineProperty(window, "localStorage", {
configurable: true,
value: new MemoryStorage(),
});
// Benign default `fetch`. Several components hit the backend on mount — e.g.
// the app reads `GET /api/config` via `useInitialConfig`.
// Under happy-dom (no server) those real requests 404 and log alarming
// `GET .../api/config 404 (Not Found)` lines that make a green run look broken.
// Returning an empty 200 keeps such *incidental* calls quiet. Tests that care
// about fetch install their own per-test spy/stub (e.g. `vi.spyOn(globalThis,
// "fetch")`), which Vitest only auto-reverts to this baseline if the test
// registers it through Vitest's mock APIs — this project doesn't set
// `restoreMocks` globally, so a test that mutates `globalThis.fetch` directly
// must restore it itself. Note the tradeoff: this default is permissive, so a
// test meaning to assert on a fetch FAILURE must set up its own rejecting/
// erroring stub rather than relying on the absence of a server.
Object.defineProperty(globalThis, "fetch", {
configurable: true,
writable: true,
value: () =>
Promise.resolve(
new Response("{}", {
status: 200,
headers: { "content-type": "application/json" },
}),
),
});
// happy-dom (v20) *does* implement `matchMedia`/`MediaQueryList`, so this isn't
// a polyfill for a missing API — it's a deliberate **override** of happy-dom's
// implementation, pinning `prefers-reduced-motion: reduce` and reporting `false`
// for every other query (preserving the historical absent-matchMedia layout
// behavior for `useMediaQuery`-driven code). Note this does *not*, on its own,
// disable Mantine transitions: `useTransition` only honors reduced motion when
// `theme.respectReducedMotion` is true, and Mantine 8 defaults it to `false`
// (the project theme doesn't override it). The actual protection against the
// #1760 post-teardown `window is not defined` leak is the leaked-timer safety
// net below — NOT `env="test"`, which an earlier version of this comment
// claimed. `env` is read only by `Transition.mjs`, and only at its *render*
// branch (`transitionDuration === 0 || env === "test"`); `useTransition()` is
// called before that check, since hooks cannot be conditional, so it still
// schedules real `window.setTimeout`s on every `mounted` change. Measured:
// opening a `<Modal>` through `renderWithMantine` schedules three 200ms timers
// (#1984). Tests that need specific media results still mock `@mantine/hooks`
// or stub `matchMedia` themselves.
Object.defineProperty(window, "matchMedia", {
configurable: true,
writable: true,
// Partial `matchMedia` override: the members below are all the app touches.
// The stub omits the rest of `MediaQueryList`, so the double cast bridges the
// deliberately-incomplete shape. The `matches` regex is anchored to the
// `reduce` form so the stub doesn't also answer `true` to
// `(prefers-reduced-motion: no-preference)` (claiming both preferences at
// once); Mantine only ever queries the `reduce` form.
value: (query: string): MediaQueryList =>
({
matches: /prefers-reduced-motion:\s*reduce/.test(query),
media: query,
onchange: null,
addEventListener: () => {},
removeEventListener: () => {},
addListener: () => {},
removeListener: () => {},
dispatchEvent: () => false,
}) as unknown as MediaQueryList,
});
// ---------------------------------------------------------------------------
// Leaked-timer safety net (#1984)
//
// A `window.setTimeout` that outlives its test file fires after happy-dom has
// disposed that file's `window`, and React's `dispatchSetState` then throws an
// uncaught `ReferenceError: window is not defined`. Vitest attributes that to
// whichever file happened to be running, and one such error fails the ENTIRE
// run with every test passing — so it reads as a defect in an innocent file.
//
// Mantine's own hooks do clear their timers on unmount (`useTransition`'s
// `clearAllTimeouts`, `useLockScroll`'s effect cleanup), so this is not a
// library bug. It is a race: `clearAllTimeouts` cancels the *pending* rAF, but
// if that rAF callback is already in flight when the unmount lands,
// `cancelAnimationFrame` is a no-op and the callback goes on to schedule a
// `setTimeout` after cleanup has already run. Nothing owns that timer. It needs
// a loaded machine to hit, which is why it only ever appears in CI.
//
// Rather than chase each component, track every timer *and every animation
// frame*, and clear whatever is still outstanding once the test's own teardown
// has had its turn. Ordering is load-bearing twice over: this runs *after*
// `cleanup()` below, so legitimate unmount cleanups clear their own timers and
// only true leaks are left; and frames are cancelled *before* timers are swept,
// because a queued frame callback would otherwise run after the sweep and
// register a fresh timer. See the ordering note on the `afterEach` itself.
//
// Under `vi.useFakeTimers()` the wrapper is swapped out for vitest's fake
// implementation, so nothing is tracked while fake timers are installed — which
// is correct, since a fake timer cannot outlive the environment.
// Handles are held as `unknown`, deliberately. The DOM lib declares these as
// `number`, but happy-dom returns objects at runtime — verified here:
// `setTimeout` yields a `Timeout` and `requestAnimationFrame` an `Immediate`.
// An earlier revision typed the sets `Set<number>` and guarded removal with
// `typeof id === "number"`; that guard never matched, so explicitly-cleared
// timers were never untracked. Harmless in effect (the teardown sweep clears
// them again and `clearTimeout` is idempotent) but the bookkeeping was a
// fiction, and the test asserting it passed vacuously. Treat the handle as
// opaque and pass it straight back to the matching canceller.
const pendingTimers = new Set<unknown>();
const pendingFrames = new Set<unknown>();
const realSetTimeout = window.setTimeout.bind(window);
const realClearTimeout = window.clearTimeout.bind(window);
const realRequestAnimationFrame = window.requestAnimationFrame.bind(window);
const realCancelAnimationFrame = window.cancelAnimationFrame.bind(window);
/** Cancel an opaque handle through the real canceller it came from. */
function cancelTimer(id: unknown): void {
// The handle came from `realSetTimeout`, so it is exactly what
// `realClearTimeout` expects; only the *declared* type disagrees.
realClearTimeout(id as Parameters<typeof realClearTimeout>[0]);
}
function cancelFrame(handle: unknown): void {
// As above, for the rAF pair.
realCancelAnimationFrame(
handle as Parameters<typeof realCancelAnimationFrame>[0],
);
}
/** Test-only introspection, so the regression tests can assert on the
* bookkeeping itself rather than on behavior that would hold anyway. */
export function pendingTimerCount(): number {
return pendingTimers.size;
}
window.setTimeout = ((
handler: TimerHandler,
timeout?: number,
...args: unknown[]
): unknown => {
const id: unknown = realSetTimeout(
(...cbArgs: unknown[]) => {
pendingTimers.delete(id);
if (typeof handler === "function") {
handler(...cbArgs);
}
},
timeout,
...args,
);
pendingTimers.add(id);
return id;
// The wrapper's public signature must match the DOM declaration the app codes
// against, while its body traffics in the runtime handle described above. TS
// cannot relate the two, hence the cast.
}) as unknown as typeof window.setTimeout;
window.clearTimeout = ((id?: unknown): void => {
// No `typeof` guard: the handle is an object here, so a numeric test would
// reject every real one. Anything defined is worth untracking.
if (id !== undefined && id !== null) {
pendingTimers.delete(id);
}
cancelTimer(id);
// Same declaration-vs-runtime mismatch as `setTimeout` above.
}) as unknown as typeof window.clearTimeout;
window.requestAnimationFrame = ((callback: FrameRequestCallback): unknown => {
const handle: unknown = realRequestAnimationFrame((time: number) => {
pendingFrames.delete(handle);
callback(time);
});
pendingFrames.add(handle);
return handle;
// Same declaration-vs-runtime mismatch as `setTimeout` above.
}) as unknown as typeof window.requestAnimationFrame;
window.cancelAnimationFrame = ((handle?: unknown): void => {
if (handle !== undefined && handle !== null) {
pendingFrames.delete(handle);
}
cancelFrame(handle);
// Same declaration-vs-runtime mismatch as `setTimeout` above.
}) as unknown as typeof window.cancelAnimationFrame;
afterEach(() => {
cleanup();
window.localStorage.clear();
// Order is the whole point, and it is not interchangeable.
//
// Cancel queued animation frames FIRST. This `afterEach` is synchronous, so a
// frame callback already queued cannot run until it returns — at which point
// it would register a fresh `setTimeout` *after* the sweep below had already
// drained, and on the file's last test that timer would survive teardown.
// That is precisely the rAF race this net exists for, so sweeping timers
// without cancelling frames first would leave the original hole open.
//
// Cancelling first closes it deterministically: JS is single-threaded and
// nothing here yields, so no frame callback can run between these two loops.
for (const handle of pendingFrames) {
cancelFrame(handle);
}
pendingFrames.clear();
// Then drop the timers. After cleanup(), anything still pending is a leak.
for (const id of pendingTimers) {
cancelTimer(id);
}
pendingTimers.clear();
});