@cosmicdrift/kumiko-testing 0.336.0 → 0.337.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-testing",
-  "version": "0.336.0",
+  "version": "0.337.1",
   "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>",
@@ -75,9 +75,9 @@
     "kumiko-testing": "./bin/kumiko-testing.ts"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-bundled-features": "0.336.0",
-    "@cosmicdrift/kumiko-dev-server": "0.336.0",
-    "@cosmicdrift/kumiko-framework": "0.336.0",
+    "@cosmicdrift/kumiko-bundled-features": "0.337.1",
+    "@cosmicdrift/kumiko-dev-server": "0.337.1",
+    "@cosmicdrift/kumiko-framework": "0.337.1",
     "zod": "^4.4.3"
   },
   "peerDependencies": {

package/src/bunfig.ts

@@ -102,7 +102,9 @@ function splitBunfigBlocks(content: string): readonly BunfigBlock[] {
   const blocks: { header: string; lines: string[] }[] = [];
   let current: { header: string; lines: string[] } = { header: "", lines: [] };
   for (const line of content.split("\n")) {
-    const match = /^\[([^\]]+)\]\s*$/.exec(line);
+    // An array-of-tables header keeps its inner brackets in `header`, so it
+    // never equals a generated header and is carried over as a foreign block.
+    const match = /^\[(\[[^\]]+\]|[^[\]]+)\]\s*$/.exec(line);
     if (match?.[1] !== undefined) {
       blocks.push(current);
       current = { header: match[1], lines: [] };
@@ -114,11 +116,19 @@ function splitBunfigBlocks(content: string): readonly BunfigBlock[] {
   return blocks;
 }
 
+const TOML_KEY_SEGMENT = String.raw`"[^"]+"|[A-Za-z_][\w-]*`;
+const TOML_KEY_LINE = new RegExp(
+  String.raw`^(?:"([^"]+)"|([A-Za-z_][\w-]*))(?:\s*\.\s*(?:${TOML_KEY_SEGMENT}))*\s*=`,
+);
+
+// Dotted and quoted keys resolve to their first segment, which is the key
+// the template either owns or doesn't.
 function keysIn(lines: readonly string[]): readonly string[] {
   const keys: string[] = [];
   for (const line of lines) {
-    const match = /^([A-Za-z_][\w-]*)\s*=/.exec(line.trim());
-    if (match?.[1] !== undefined) keys.push(match[1]);
+    const match = TOML_KEY_LINE.exec(line.trim());
+    const key = match?.[1] ?? match?.[2];
+    if (key !== undefined) keys.push(key);
   }
   return keys;
 }
@@ -137,9 +147,12 @@ 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"]);
+// Old app-local path -> its replacement; dropped only when the replacement is
+// generated for this variant, so an app that hasn't regenerated doesn't run
+// DOM setup twice but a variant without it keeps its own setup.
+const SUPERSEDED_PRELOADS: ReadonlyMap<string, string> = new Map([
+  ["./test-setup/dom.preload.ts", DOM_PRELOAD],
+]);
 
 // Ignore patterns the generator owns across all variants. One it omits for
 // this variant (`**/*.test.tsx` with --dom, `**/*.integration.test.ts` in the
@@ -153,9 +166,14 @@ const TEMPLATE_OWNED_IGNORE_PATTERNS = new Set<string>([
   ]),
 ]);
 
-function isKeepableExtra(key: MergedArrayKey, entry: string): boolean {
+function isKeepableExtra(
+  key: MergedArrayKey,
+  entry: string,
+  generatedValues: readonly string[],
+): boolean {
   if (key !== "preload") return !TEMPLATE_OWNED_IGNORE_PATTERNS.has(entry);
-  if (SUPERSEDED_PRELOADS.has(entry)) return false;
+  const replacement = SUPERSEDED_PRELOADS.get(entry);
+  if (replacement !== undefined) return !generatedValues.includes(replacement);
   if (entry.startsWith(PRELOAD_PREFIX)) return CURRENT_PACKAGE_PRELOADS.has(entry);
   return true;
 }
@@ -232,7 +250,7 @@ export function mergeBunfig(generated: string, existingContent: string): BunfigM
     const generatedValues = arrayField(generatedTest, key);
     const existingValues = arrayField(existingTest, key);
     const extras = existingValues.filter(
-      (item) => !generatedValues.includes(item) && isKeepableExtra(key, item),
+      (item) => !generatedValues.includes(item) && isKeepableExtra(key, item, generatedValues),
     );
     content = appendArrayExtras(content, key, extras);
   }

package/src/changes.json

@@ -1,4 +1,22 @@
 [
+  {
+    "version": "0.337.0",
+    "type": "fix",
+    "title": "bunfig merge reports dotted/quoted keys and keeps array tables, empty schema env defaults are replaced, integration dir expansion prunes node_modules, seedTenant gains unsubscribeSse",
+    "detail": "`kumiko-testing bunfig` now reports dotted and quoted keys as unknown and keeps `[[array-of-tables]]` blocks instead of folding them into `[test]`, and drops the superseded `./test-setup/dom.preload.ts` only when the DOM preload is generated. The schema-env-defaults preload treats empty values like unset ones for every key. `kumiko-testing integration <dir>` skips `node_modules`, `dist` and `e2e` while expanding a directory. `seedTenant` returns `unsubscribeSse` to detach the tenant's SSE client from `events.sse`. A real-provider scenario `waitFor` now times out after `E2E_TIMEOUT_MS.realWait` (180 s), before the 240 s test timeout."
+  },
+  {
+    "version": "0.336.1",
+    "type": "fix",
+    "title": "DOM preload bounds the printed output of SVG elements as well",
+    "detail": "The DOM preload's bounded print of nodes now covers SVG elements too. Before, printing an `<svg>` in a failed assertion dumped the whole happy-dom object graph (about 10 MB)."
+  },
+  {
+    "version": "0.336.1",
+    "type": "fix",
+    "title": "Scaffolded test:real only matches *.real.test.ts files",
+    "detail": "The scaffolded `test:real` script now filters on `.real.test.ts` instead of `real.test.ts`, so files such as `unreal.test.ts` no longer run under the real-provider environment."
+  },
   {
     "version": "0.335.0",
     "type": "fix",

package/src/e2e/screenshots.ts

@@ -216,6 +216,23 @@ async function restoreIdentitiesOnPage(
   if (mappings.length > 0) await page.evaluate(restoreIdentitiesInDocument);
 }
 
+// Order matters: beforeCapture first (it may hide/mask), identities after, so
+// the replaced text is what the screenshot sees. Exported for unit tests.
+export async function captureScenario(
+  page: Page,
+  scenario: Pick<Scenario, "beforeCapture" | "fullPage" | "captureStyle">,
+  mappings: readonly PresentIdentity[],
+  screenshotOptions: Omit<NonNullable<Parameters<Page["screenshot"]>[0]>, "fullPage" | "style">,
+): Promise<Buffer> {
+  if (scenario.beforeCapture) await scenario.beforeCapture(page);
+  await presentIdentitiesOnPage(page, mappings);
+  return page.screenshot({
+    ...screenshotOptions,
+    fullPage: scenario.fullPage ?? false,
+    ...(scenario.captureStyle !== undefined && { style: scenario.captureStyle }),
+  });
+}
+
 function collectPresentIdentities(): {
   readonly mappings: readonly PresentIdentity[];
   readonly register: (mappings: readonly PresentIdentity[]) => void;
@@ -230,6 +247,10 @@ function collectPresentIdentities(): {
   };
 }
 
+export function scenarioWaitForTimeout(realProviderRun: boolean): number {
+  return realProviderRun ? E2E_TIMEOUT_MS.realWait : E2E_TIMEOUT_MS.navigation;
+}
+
 async function openScenario(
   page: Page,
   s: Scenario,
@@ -242,8 +263,9 @@ async function openScenario(
 
   if (s.waitFor) {
     // Real-provider scenarios wait on LLM/OCR latency before the page is ready.
-    const timeout = isRealProviderRun() ? E2E_TIMEOUT_MS.real : E2E_TIMEOUT_MS.navigation;
-    await expect(page.locator(s.waitFor).first()).toBeVisible({ timeout });
+    await expect(page.locator(s.waitFor).first()).toBeVisible({
+      timeout: scenarioWaitForTimeout(isRealProviderRun()),
+    });
   }
   await waitForSettledPage(page, inFlightDataRequests);
 }
@@ -303,14 +325,8 @@ export function runScreenshots(scenarios: readonly Scenario[], opts: FlatOptions
             seedTenant,
             presentIdentities: identities.register,
           });
-          if (s.beforeCapture) await s.beforeCapture(page);
-          await presentIdentitiesOnPage(page, identities.mappings);
           const path = `${outDir}/${s.name}.png`;
-          await page.screenshot({
-            path,
-            fullPage: s.fullPage ?? false,
-            ...(s.captureStyle !== undefined && { style: s.captureStyle }),
-          });
+          await captureScenario(page, s, identities.mappings, { path });
           expect.soft(statSync(path).size).toBeGreaterThan(MIN_BYTES);
         },
       );
@@ -570,19 +586,15 @@ export function runMatrix<T extends string>(
             for (const vp of plan.viewports) {
               if (plan.mode === "desktop") await page.setViewportSize(viewportSizes[vp]);
               await waitForSettledPage(page, inFlightDataRequests);
-              if (s.beforeCapture) await s.beforeCapture(page);
-              await presentIdentitiesOnPage(page, identities.mappings);
               const dir = `${projectBaseDir}/${s.name}/${locale}/${theme}`;
               mkdirSync(dir, { recursive: true });
               const path = `${dir}/${vp}.png`;
               // animations: "disabled" jumps to end-state at the engine level — immune to CSS specificity, unlike an addStyleTag injection.
               // screenshot() returns the same bytes it writes to `path` — reuse
               // them for both checks instead of a statSync/read-back roundtrip.
-              const buffer = await page.screenshot({
+              const buffer = await captureScenario(page, s, identities.mappings, {
                 path,
-                fullPage: s.fullPage ?? false,
                 animations: "disabled",
-                ...(s.captureStyle !== undefined && { style: s.captureStyle }),
               });
               expect.soft(buffer.length).toBeGreaterThan(MIN_BYTES);
               digests.push({

package/src/e2e/timeouts.ts

@@ -10,4 +10,7 @@ export const E2E_TIMEOUT_MS = {
   poll: 15_000,
   webServer: 90_000,
   real: 240_000,
+  // Selector wait of a real-provider scenario; below `real` so the locator error
+  // (selector, scenario) fires before the generic test timeout swallows it.
+  realWait: 180_000,
 } as const;

package/src/index.ts

@@ -1,6 +1,7 @@
 export { PROVIDER_ENV_KEYS } from "./provider-env-keys";
 export {
   type BoundApi,
+  type InProcessSeededTenant,
   type PersistedTenant,
   persistTenantRows,
   type SavedRow,

package/src/integration-runner.ts

@@ -34,7 +34,7 @@ export function selectIntegrationFiles(paths: readonly string[]): string[] {
 
 function listDirectoryFiles(path: string): string[] | undefined {
   if (statSync(path, { throwIfNoEntry: false })?.isDirectory() !== true) return undefined;
-  return readdirSync(path, { recursive: true, encoding: "utf8" });
+  return listIntegrationTestFiles(path);
 }
 
 /** Resolves `kumiko-testing integration`'s positional file args against `cwd`

package/src/preload/dom.ts

@@ -49,9 +49,8 @@ if (typeof globalThis.window === "undefined") {
 // 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 { cleanup } =
+  require("@testing-library/react/pure") as typeof import("@testing-library/react/pure");
 
 const HTML_PRINT_LIMIT = 2000;
 
@@ -65,15 +64,19 @@ if (typeof globalThis.HTMLElement !== "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).
+// 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. On Element, not
+// HTMLElement: SVGElement does not inherit from HTMLElement.
+if (typeof globalThis.Element !== "undefined") {
+  const elementProto = globalThis.Element.prototype as unknown as Record<string | symbol, unknown>;
   const inspect = Symbol.for("nodejs.util.inspect.custom");
-  if (proto[inspect] === undefined) {
-    proto[inspect] = function (this: HTMLElement): string {
+  if (elementProto[inspect] === undefined) {
+    elementProto[inspect] = function (this: Element): string {
       const html = this.outerHTML;
       return html.length > HTML_PRINT_LIMIT ? `${html.slice(0, HTML_PRINT_LIMIT)}…` : html;
     };
@@ -84,15 +87,15 @@ if (typeof globalThis.HTMLElement !== "undefined") {
 // test files in one process, so without afterEach, React components from
 // file N stay mounted in file N+1's DOM.
 //
-// FIVE leak sources:
+// FIVE leak sources (b is NOT cleaned here):
 //
 //   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.
+//   b) Containers not created via testing-library/react (e.g. #root via
+//      ReactDOM.createRoot + renderShell) are not cleaned here: the test
+//      file must unmount them itself, since body.replaceChildren() would
+//      trigger React effects outside act().
 //
 //   c) Radix DismissableLayer sets body.style.pointerEvents='none' when
 //      opening a Dialog/Popover/Dropdown.

package/src/preload/schema-env-defaults.ts

@@ -6,13 +6,11 @@ import { SCHEMA_ENV_DEFAULTS } from "./schema-env-defaults-values";
 const MIN_JWT_SECRET_LENGTH = 32;
 
 function isTooShortJwtSecret(key: string, value: string | undefined): boolean {
-  return key === "JWT_SECRET" && (!value || value.length < MIN_JWT_SECRET_LENGTH);
+  return key === "JWT_SECRET" && value !== undefined && value.length < MIN_JWT_SECRET_LENGTH;
 }
 
+// An empty value counts as unset: `${{ secrets.X }}` in GitHub Actions yields "" for a missing secret.
 for (const [key, value] of Object.entries(SCHEMA_ENV_DEFAULTS)) {
-  if (isTooShortJwtSecret(key, process.env[key])) {
-    process.env[key] = value;
-    continue;
-  }
-  process.env[key] ??= value;
+  const current = process.env[key];
+  if (!current || isTooShortJwtSecret(key, current)) process.env[key] = value;
 }

package/src/scaffold.ts

@@ -194,9 +194,10 @@ export function renderTestSetup(input: RenderTestSetupInput): ScaffoldTestSetup
       // verified against bun 1.4), so it can't express "match only *.real.test.ts"
       // on its own — every *.test.ts file matches bun's default test glob too,
       // real.test.ts included. The positional filter narrows the run to files
-      // whose path contains "real.test.ts", so an unfiltered test:real never
+      // whose path contains ".real.test.ts" (a bare "real.test.ts" would also
+      // match unreal.test.ts), so an unfiltered test:real never
       // picks up the unit suite.
-      "test:real": `${REAL_PROVIDERS_ENV}=1 bun --config=${BUNFIG_FILES.real} test --timeout=${TEST_TIMEOUT_MS.real} real.test.ts`,
+      "test:real": `${REAL_PROVIDERS_ENV}=1 bun --config=${BUNFIG_FILES.real} test --timeout=${TEST_TIMEOUT_MS.real} .real.test.ts`,
       "test:bunfig": "bun kumiko-testing bunfig --hoisted",
       e2e: "bunx --bun playwright test",
       "e2e:real": `${REAL_PROVIDERS_ENV}=1 bunx --bun playwright test`,

package/src/seed-tenant.ts

@@ -169,24 +169,30 @@ function lightTenantRows(opts: SeedTenantOptions): PersistedTenant {
   return { ...identity, admin: lightCredentials(adminEmail), members };
 }
 
+export type InProcessSeededTenant = SeededTenant & {
+  // Stops this tenant's events from landing in the stack's `events.sse`.
+  readonly unsubscribeSse: () => void;
+};
+
 export async function seedTenant(
   stack: TestStack,
   opts: SeedTenantOptions = {},
-): Promise<SeededTenant> {
+): Promise<InProcessSeededTenant> {
   const write = stackSeedWriter(stack);
   const persist = opts.persist === true;
   const rows = persist ? await persistTenantRows(write, opts) : lightTenantRows(opts);
   const { id } = rows;
 
   // setupTestStack subscribes events.sse only to test tenant 1; a seeded tenant has a fresh random id.
-  stack.sseBroker.addClient(
-    tenantChannel(id),
+  const channel = tenantChannel(id);
+  const sseClientId = stack.sseBroker.addClient(
+    channel,
     (event) => stack.events.sse.push(event),
     () => {},
   );
 
   const admin = withSession(rows.admin, id, [ROLES.TenantAdmin]);
-  const tenant: SeededTenant = {
+  const tenant: InProcessSeededTenant = {
     id,
     key: rows.key,
     name: rows.name,
@@ -202,6 +208,7 @@ export async function seedTenant(
         id,
         roles,
       ),
+    unsubscribeSse: () => stack.sseBroker.removeClient(channel, sseClientId),
     api: bindApi(stack, admin.session),
     apiAs: (user) => bindApi(stack, user.session),
   };