@cosmicdrift/kumiko-testing 0.316.0 → 0.317.0

package/README.md

@@ -11,12 +11,16 @@ const persisted = await seedTenant(stack, { persist: true }); // real rows via t
 await tenant.api.writeOk("my-feature:write:thing:create", { title: "x" });
 ```
 
-- `preload/{temporal,ci-log,scrub-env,env,real}`: bunfig `preload` entries. `scrub-env` removes
+- `preload/{temporal,ci-log,scrub-env,env,real,dom}`: bunfig `preload` entries. `scrub-env` removes
   `PROVIDER_ENV_KEYS` (unit default); `env` adds the localhost service defaults (integration);
-  `real` refuses to run without `KUMIKO_REAL_PROVIDERS=1` and in CI, and keeps the keys.
+  `real` refuses to run without `KUMIKO_REAL_PROVIDERS=1` and in CI, and keeps the keys; `dom`
+  registers happy-dom (window/document/HTMLElement) while preserving Bun's native
+  fetch/Request/Response, and cleans up (`@testing-library/react` unmount, Radix DOM/style leaks,
+  `window.location`) after every test.
 - `kumiko-testing bunfig [--dom] [--coverage]`: writes `bunfig.toml`,
-  `bunfig.integration.toml` and `bunfig.real.toml` (plus `bunfig.dom.toml`). `--dom` needs your own
-  `./test-setup/dom.preload.ts`.
+  `bunfig.integration.toml` and `bunfig.real.toml` (plus `bunfig.dom.toml`). `--dom` adds
+  `preload/dom` (happy-dom + testing-library/react cleanup); `@happy-dom/global-registrator` and
+  `@testing-library/react` are optional peer dependencies, install them when you use `--dom`.
 - `kumiko-testing integration [--parallel N] [--timings <file>]`: runs `*.integration.test.ts`
   with the 15s budget. `--parallel` only when you ask for it, and then with `--no-isolate`:
   bun 1.4.0's implicit `--isolate` leaks native memory per file until CI workers are OOM-killed.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-testing",
-  "version": "0.316.0",
+  "version": "0.317.0",
   "description": "Test template for Kumiko apps: per-flow seedTenant, app test stack, canonical test preloads, bunfig generator and integration runner.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -46,6 +46,10 @@
       "types": "./src/preload/real.ts",
       "default": "./src/preload/real.ts"
     },
+    "./preload/dom": {
+      "types": "./src/preload/dom.ts",
+      "default": "./src/preload/dom.ts"
+    },
     "./scaffold": {
       "types": "./src/scaffold.ts",
       "default": "./src/scaffold.ts"
@@ -63,21 +67,31 @@
     "kumiko-testing": "./bin/kumiko-testing.ts"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-bundled-features": "0.316.0",
-    "@cosmicdrift/kumiko-dev-server": "0.316.0",
-    "@cosmicdrift/kumiko-framework": "0.316.0",
+    "@cosmicdrift/kumiko-bundled-features": "0.317.0",
+    "@cosmicdrift/kumiko-dev-server": "0.317.0",
+    "@cosmicdrift/kumiko-framework": "0.317.0",
     "zod": "^4.4.3"
   },
   "peerDependencies": {
-    "@playwright/test": "^1.62.1"
+    "@happy-dom/global-registrator": "^20.11.2",
+    "@playwright/test": "^1.62.1",
+    "@testing-library/react": "^16.3.2"
   },
   "peerDependenciesMeta": {
+    "@happy-dom/global-registrator": {
+      "optional": true
+    },
     "@playwright/test": {
       "optional": true
+    },
+    "@testing-library/react": {
+      "optional": true
     }
   },
   "devDependencies": {
-    "@playwright/test": "^1.62.1"
+    "@happy-dom/global-registrator": "^20.11.2",
+    "@playwright/test": "^1.62.1",
+    "@testing-library/react": "^16.3.2"
   },
   "publishConfig": {
     "registry": "https://registry.npmjs.org",

package/src/bunfig.ts

@@ -25,7 +25,7 @@ export type BunfigOptions = {
 };
 
 const PRELOAD_PREFIX = "@cosmicdrift/kumiko-testing/preload";
-const DOM_PRELOAD = "./test-setup/dom.preload.ts";
+const DOM_PRELOAD = `${PRELOAD_PREFIX}/dom`;
 
 const PRELOADS = {
   unit: [`${PRELOAD_PREFIX}/temporal`, `${PRELOAD_PREFIX}/scrub-env`],
@@ -125,6 +125,57 @@ export type BunfigMergeResult =
   | { readonly ok: true; readonly content: string }
   | { readonly ok: false; readonly unknownKeys: readonly UnknownBunfigKey[] };
 
+// Unlike an unknown key, which blocks the merge, an array entry the template
+// stops emitting stays on disk silently until the generator excludes it by
+// name, as it does below for the superseded DOM preload path.
+const MERGED_ARRAY_KEYS = ["preload", "pathIgnorePatterns", "coveragePathIgnorePatterns"] as const;
+type MergedArrayKey = (typeof MERGED_ARRAY_KEYS)[number];
+
+const CURRENT_PACKAGE_PRELOADS = new Set<string>([...Object.values(PRELOADS).flat(), DOM_PRELOAD]);
+
+// Old app-local path of DOM_PRELOAD; excluded so an app that hasn't
+// regenerated doesn't run DOM setup twice.
+const SUPERSEDED_PRELOADS = new Set<string>(["./test-setup/dom.preload.ts"]);
+
+function isKeepableExtra(key: MergedArrayKey, entry: string): boolean {
+  if (key !== "preload") return true;
+  if (SUPERSEDED_PRELOADS.has(entry)) return false;
+  if (entry.startsWith(PRELOAD_PREFIX)) return CURRENT_PACKAGE_PRELOADS.has(entry);
+  return true;
+}
+
+function parseTestSection(content: string): Readonly<Record<string, unknown>> {
+  const parsed = Bun.TOML.parse(content) as { test?: Record<string, unknown> };
+  return parsed.test ?? {};
+}
+
+function arrayField(
+  testSection: Readonly<Record<string, unknown>>,
+  key: MergedArrayKey,
+): readonly string[] {
+  const value = testSection[key];
+  if (typeof value === "string") return [value];
+  return Array.isArray(value)
+    ? value.filter((item): item is string => typeof item === "string")
+    : [];
+}
+
+// TOML comments attached to an extra on disk don't survive: only the parsed
+// string value is carried over, not the source lines around it.
+function appendArrayExtras(
+  generated: string,
+  key: MergedArrayKey,
+  extras: readonly string[],
+): string {
+  if (extras.length === 0) return generated;
+  const extraLines = extras.map((item) => `  ${JSON.stringify(item)},`).join("\n");
+  const pattern = new RegExp(`^(${key} = \\[\\n)([\\s\\S]*?)(\\n\\])`, "m");
+  return generated.replace(
+    pattern,
+    (_match, open: string, body: string, close: string) => `${open}${body}\n${extraLines}${close}`,
+  );
+}
+
 /**
  * Merges freshly generated bunfig content with whatever an app already has
  * on disk. A section this run's `generated` output doesn't touch at all
@@ -134,7 +185,11 @@ export type BunfigMergeResult =
  * template doesn't own this run is never silently dropped. A key inside a
  * section the template DOES emit that isn't in this run's own version of
  * that section (e.g. `concurrency`, `timeout`, kumiko-framework#3120) fails
- * the merge instead of silently disappearing.
+ * the merge instead of silently disappearing. Within an array key the
+ * template does emit on both sides (`preload`, `pathIgnorePatterns`,
+ * `coveragePathIgnorePatterns`), entries the app appended on top of the
+ * generated ones survive the regeneration instead of being overwritten with
+ * the generated array alone.
  */
 export function mergeBunfig(generated: string, existingContent: string): BunfigMergeResult {
   const generatedKeysBySection = new Map(
@@ -154,11 +209,22 @@ export function mergeBunfig(generated: string, existingContent: string): BunfigM
     }
   }
   if (unknownKeys.length > 0) return { ok: false, unknownKeys };
-  if (foreignBlocks.length === 0) return { ok: true, content: generated };
+  const generatedTest = parseTestSection(generated);
+  const existingTest = parseTestSection(existingContent);
+  let content = generated;
+  for (const key of MERGED_ARRAY_KEYS) {
+    const generatedValues = arrayField(generatedTest, key);
+    const existingValues = arrayField(existingTest, key);
+    const extras = existingValues.filter(
+      (item) => !generatedValues.includes(item) && isKeepableExtra(key, item),
+    );
+    content = appendArrayExtras(content, key, extras);
+  }
+  if (foreignBlocks.length === 0) return { ok: true, content };
   const foreignText = foreignBlocks
     .map((block) => `[${block.header}]\n${block.lines.join("\n").replace(/\n+$/, "")}\n`)
     .join("\n");
-  return { ok: true, content: `${generated}\n${foreignText}` };
+  return { ok: true, content: `${content}\n${foreignText}` };
 }
 
 export function renderBunfigFiles(opts: BunfigOptions = {}): Readonly<Record<string, string>> {

package/src/changes.json

@@ -1,4 +1,17 @@
 [
+  {
+    "version": "0.317.0",
+    "type": "fix",
+    "title": "mergeBunfig keeps app-local array extras instead of overwriting them",
+    "detail": "mergeBunfig only checked whether a key such as `preload` existed on both\nsides of the merge, not whether its array value matched. Regenerating a\nbunfig therefore silently replaced an app's `[test].preload`,\n`pathIgnorePatterns` or `coveragePathIgnorePatterns` array with the\ngenerated one, dropping any entry the app had appended by hand (measured\nagainst publicstatus's real bunfig.toml, which carries exactly this case\nfor env.preload.ts/codegen.preload.ts and says so in a comment).\nmergeBunfig now diffs the parsed array for each of these three keys and\nappends entries only present on disk after the generated ones, so\n`kumiko-testing bunfig` is safe to rerun on an app that extended one of\nthem. A `./test-setup/dom.preload.ts` entry left over from before the\nDOM preload became a package export (see the DOM-preload-package\nchangeset in this same release) is not carried forward as an extra,\nsince keeping it would preload the same DOM setup twice.\nA package preload an app deliberately adds from another variant (say\n`preload/env` in its unit bunfig) is kept; an unrecognized or superseded\npackage preload path is dropped instead of kept as an extra, so a rename\ninside the package doesn't leave both the old and new path preloaded. A\npreload written as a single string rather than an array is read the same\nas a one-item array.\nTwo known limits: a comment attached to an extra in the source bunfig is\nnot preserved, only the value; and the template can no longer remove a\n`pathIgnorePatterns`/`coveragePathIgnorePatterns` entry from a consumer,\nsince either key has no equivalent to preload's exclusion list, so a\npattern it stops emitting stays in every consumer's bunfig until removed\nby hand. Unlike an unknown key, which blocks the merge, a stale array\nentry is kept silently rather than failing loudly."
+  },
+  {
+    "version": "0.317.0",
+    "type": "breaking",
+    "title": "bunfig --dom preloads the package's own DOM setup instead of an app-local file",
+    "detail": "The package now exports `./preload/dom`, the happy-dom GlobalRegistrator\nsetup (IS_REACT_ACT_ENVIRONMENT, Bun's native fetch/Request/Response\npreserved over happy-dom's broken cookie header, testing-library/react\ncleanup, Radix pointer-capture/scrollIntoView stubs, the inspect-size\nlimit for waitFor) that each app using --dom previously copied into its\nown ./test-setup/dom.preload.ts. `kumiko-testing bunfig --dom` now generates\nbunfig.dom.toml with @cosmicdrift/kumiko-testing/preload/dom instead of\nthe app-local path. @happy-dom/global-registrator and\n@testing-library/react are optional peer dependencies, same as\n@playwright/test for ./e2e. This reverses kumiko-framework#3128, which\nkept the file as an app-local copy because at the time it was\nworkspace-internal, not a published contract. In practice the copies\nnever diverged on purpose, only by drift: publicstatus, phronexsis and\nkumiko-enterprise carried older, partial copies of the framework's own\ntest-setup/dom.preload.ts (missing the inspect-size fix for #3082), and\nonly offlot-app matched the framework's code (comments reworded, no\nfunctional diff). The framework's own copy is now deleted; the\nframework runs the same package preload it ships.",
+    "migration": "In every bunfig file that lists \"./test-setup/dom.preload.ts\"\n(publicstatus, phronexsis, offlot-app and kumiko-enterprise each have\nexactly one, their bunfig.dom.toml), replace that line with\n\"@cosmicdrift/kumiko-testing/preload/dom\", then delete the now-\nunreferenced ./test-setup/dom.preload.ts. Ensure\n@happy-dom/global-registrator and @testing-library/react are in the\napp's devDependencies (all four already have both). Running\n`kumiko-testing bunfig --dom` instead also works: mergeBunfig now keeps\nan app-local extra preload (publicstatus's\nenv.preload.ts/codegen.preload.ts) across the regen instead of dropping\nit, and treats an existing \"./test-setup/dom.preload.ts\" entry as\nsuperseded rather than an extra, so it doesn't end up preloaded twice\nalongside the new package path. The generated preload array's own\nentries stay first; a carried-over extra lands after them, which can\nmove it relative to entries that used to sit between the template's\npreloads and the app's own (publicstatus: dom.preload.ts used to run\nlast, after env/codegen; the package preload now runs before them)."
+  },
   {
     "version": "0.316.0",
     "type": "fix",

package/src/preload/dom.ts

@@ -0,0 +1,143 @@
+// DOM polyfill for tests that use testing-library/react or Radix components.
+// happy-dom's global-registrator attaches window/document/HTMLElement to
+// globalThis. Plain Node tests are unaffected, no code path changes for them.
+
+import { afterEach } from "bun:test";
+import { GlobalRegistrator } from "@happy-dom/global-registrator";
+
+declare global {
+  // React's own typings don't declare this property on globalThis.
+  var IS_REACT_ACT_ENVIRONMENT: boolean | undefined;
+}
+
+// react-dom checks IS_REACT_ACT_ENVIRONMENT to suppress act() warnings.
+// vitest set this automatically via @testing-library/react; with bun:test we
+// set it explicitly.
+globalThis.IS_REACT_ACT_ENVIRONMENT = true;
+
+// Register idempotently, so a second preload entry doesn't crash.
+if (typeof globalThis.window === "undefined") {
+  // Preserve Bun's native fetch/Request/Response/Headers before happy-dom
+  // overwrites them. happy-dom ships its own Request implementation whose
+  // headers.get("cookie") returns null, which breaks Hono's getCookie() in
+  // every auth/csrf/sse test. We only want the DOM globals (window,
+  // document, HTMLElement) from happy-dom, not the fetch API.
+  const bunRequest = globalThis.Request;
+  const bunResponse = globalThis.Response;
+  const bunHeaders = globalThis.Headers;
+  const bunFetch = globalThis.fetch;
+  const bunAbortController = globalThis.AbortController;
+  const bunAbortSignal = globalThis.AbortSignal;
+  const bunWritableStream = globalThis.WritableStream;
+  const bunTransformStream = globalThis.TransformStream;
+  // The url option sets window.location to http://localhost/. Without it
+  // happy-dom defaults to about:blank, so history.pushState/replaceState
+  // doesn't work (invalid origin) and window.location.pathname stays
+  // "blank", breaking every router/nav test.
+  GlobalRegistrator.register({ url: "http://localhost/" });
+  globalThis.Request = bunRequest;
+  globalThis.Response = bunResponse;
+  globalThis.Headers = bunHeaders;
+  globalThis.fetch = bunFetch;
+  globalThis.AbortController = bunAbortController;
+  globalThis.AbortSignal = bunAbortSignal;
+  globalThis.WritableStream = bunWritableStream;
+  globalThis.TransformStream = bunTransformStream;
+}
+
+// @testing-library/dom/dist/screen.js checks document.body at module import
+// time. A static import would evaluate screen before happy-dom registers, so
+// every screen query would throw TypeError. Hence require() only after the
+// registration above.
+const { cleanup } = require("@testing-library/react/pure") as {
+  cleanup: () => void;
+};
+
+const HTML_PRINT_LIMIT = 2000;
+
+// Pointer-capture APIs are missing in happy-dom, same as in jsdom. Radix-UI
+// (DropdownMenu/Select/Popover triggers) calls them, so nothing opens in
+// tests without the polyfill.
+if (typeof globalThis.HTMLElement !== "undefined") {
+  const proto = globalThis.HTMLElement.prototype as unknown as Record<string | symbol, unknown>;
+  if (proto["hasPointerCapture"] === undefined) proto["hasPointerCapture"] = () => false;
+  if (proto["setPointerCapture"] === undefined) proto["setPointerCapture"] = () => undefined;
+  if (proto["releasePointerCapture"] === undefined)
+    proto["releasePointerCapture"] = () => undefined;
+  if (proto["scrollIntoView"] === undefined) proto["scrollIntoView"] = () => undefined;
+
+  // Without this, printing a happy-dom node walks its whole object graph:
+  // ownerDocument plus every React fiber property, which is 15 MB of string
+  // for a two-element tree and 0.5-1.7 s per call. A failed assertion inside
+  // waitFor pays that on every poll and blocks the loop long enough to starve
+  // React's commit and waitFor's own timeout (#3082).
+  const inspect = Symbol.for("nodejs.util.inspect.custom");
+  if (proto[inspect] === undefined) {
+    proto[inspect] = function (this: HTMLElement): string {
+      const html = this.outerHTML;
+      return html.length > HTML_PRINT_LIMIT ? `${html.slice(0, HTML_PRINT_LIMIT)}…` : html;
+    };
+  }
+}
+
+// Auto-cleanup after every test (DOM pollution guard): bun test runs all
+// test files in one process, so without afterEach, React components from
+// file N stay mounted in file N+1's DOM.
+//
+// FIVE leak sources:
+//
+//   a) testing-library/react container: cleanup() unmounts and removes
+//      every container node render() created.
+//
+//   b) body.replaceChildren(): clears containers not created via
+//      testing-library/react (e.g. #root via ReactDOM.createRoot +
+//      renderShell). Must run after cleanup(), since React needs its nodes
+//      to unmount.
+//
+//   c) Radix DismissableLayer sets body.style.pointerEvents='none' when
+//      opening a Dialog/Popover/Dropdown.
+//
+//   d) Radix-injected style tags in head.
+//
+//   e) window.location / history.pushState.
+afterEach(() => {
+  // skip: this preload module runs its own afterEach unconditionally; plain
+  // unit test files (no --dom) never get happy-dom registered, so document
+  // stays undefined and there is nothing to clean up.
+  if (typeof globalThis.document === "undefined") return;
+
+  // (a) React cleanup first: unmounts every testing-library-rendered
+  //     component via ReactDOM.unmountComponentAtNode. Must happen before
+  //     any DOM manipulation because React needs its nodes.
+  cleanup();
+
+  const doc = globalThis.document;
+  // skip: happy-dom always creates body, but a defensive guard keeps this
+  // afterEach from throwing if a future registration option removes it.
+  if (!doc.body) return;
+
+  // (b) Remaining nodes are not actively removed: cleanup() from
+  //     testing-library/react clears all render() containers. Non-standard
+  //     containers (#root via createRoot) must be cleaned by the tests
+  //     themselves or via afterEach in the test file. body.replaceChildren()
+  //     triggers async React effects without an act context.
+
+  // (c) Radix leak: reset the body inline style
+  doc.body.style.pointerEvents = "";
+
+  // (d) Radix-injected style tags
+  for (const el of doc.head.querySelectorAll("style")) {
+    const style = el as HTMLStyleElement;
+    if (style.id?.startsWith("radix-")) {
+      style.remove();
+    }
+  }
+
+  // (e) Reset window.location to happy-dom's initial url. replaceState
+  // instead of pushState, otherwise a history stack of 3000+ entries
+  // accumulates across all tests (memory leak, plus it breaks tests that
+  // check history.length).
+  if (typeof globalThis.history !== "undefined") {
+    globalThis.history.replaceState(null, "", "http://localhost/");
+  }
+});