@cosmicdrift/kumiko-testing 0.334.0 → 0.336.0

package/README.md

@@ -22,7 +22,7 @@ await tenant.api.writeOk("my-feature:write:thing:create", { title: "x" });
 - `kumiko-testing bunfig [--dom] [--coverage]`: writes `bunfig.toml`,
   `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`.
+  `@testing-library/react` (which needs `@testing-library/dom`) 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.
@@ -89,10 +89,14 @@ receives the seeded-tenant fixture too:
 ```ts
 { name: "dispatch", flow: async (page, { seedTenant }) => {
     const tenant = await seedTenant({ users: 1 });
-    await tenant.loginAs(page, tenant.members[0]!);
+    const [member] = tenant.members;
+    if (!member) throw new Error("seedTenant returned no member");
+    await tenant.loginAs(page, member);
     await page.goto("/dispatch");
   },
-  beforeCapture: async (page) => page.addStyleTag({ content: ".live-clock { visibility: hidden }" }),
+  beforeCapture: async (page) => {
+    await page.addStyleTag({ content: ".live-clock { visibility: hidden }" });
+  },
 }
 ```
 

package/bin/kumiko-testing.ts

@@ -3,10 +3,10 @@
 
 import { existsSync, readFileSync, writeFileSync } from "node:fs";
 import { parseArgs } from "node:util";
-import { Glob } from "bun";
 import { BUNFIG_FILES, mergeBunfig, renderBunfigFiles } from "../src/bunfig";
 import {
   buildIntegrationTestArgs,
+  listIntegrationTestFiles,
   resolveRequestedIntegrationFiles,
   selectIntegrationFiles,
 } from "../src/integration-runner";
@@ -82,9 +82,7 @@ async function runIntegration(args: readonly string[]): Promise<number> {
       return 1;
     }
   } else {
-    files = selectIntegrationFiles(
-      await Array.fromAsync(new Glob("**/*.integration.test.ts").scan({ cwd: process.cwd() })),
-    );
+    files = selectIntegrationFiles(listIntegrationTestFiles(process.cwd()));
     if (files.length === 0) {
       console.error("no *.integration.test.ts files found");
       return 1;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-testing",
-  "version": "0.334.0",
+  "version": "0.336.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>",
@@ -75,14 +75,15 @@
     "kumiko-testing": "./bin/kumiko-testing.ts"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-bundled-features": "0.334.0",
-    "@cosmicdrift/kumiko-dev-server": "0.334.0",
-    "@cosmicdrift/kumiko-framework": "0.334.0",
+    "@cosmicdrift/kumiko-bundled-features": "0.336.0",
+    "@cosmicdrift/kumiko-dev-server": "0.336.0",
+    "@cosmicdrift/kumiko-framework": "0.336.0",
     "zod": "^4.4.3"
   },
   "peerDependencies": {
     "@happy-dom/global-registrator": "^20.11.2",
     "@playwright/test": "^1.62.1",
+    "@testing-library/dom": "^10.4.1",
     "@testing-library/react": "^16.3.2"
   },
   "peerDependenciesMeta": {
@@ -92,6 +93,9 @@
     "@playwright/test": {
       "optional": true
     },
+    "@testing-library/dom": {
+      "optional": true
+    },
     "@testing-library/react": {
       "optional": true
     }
@@ -99,6 +103,7 @@
   "devDependencies": {
     "@happy-dom/global-registrator": "^20.11.2",
     "@playwright/test": "^1.62.1",
+    "@testing-library/dom": "^10.4.1",
     "@testing-library/react": "^16.3.2"
   },
   "publishConfig": {

package/src/bunfig.ts

@@ -141,8 +141,20 @@ const CURRENT_PACKAGE_PRELOADS = new Set<string>([...Object.values(PRELOADS).fla
 // regenerated doesn't run DOM setup twice.
 const SUPERSEDED_PRELOADS = new Set<string>(["./test-setup/dom.preload.ts"]);
 
+// Ignore patterns the generator owns across all variants. One it omits for
+// this variant (`**/*.test.tsx` with --dom, `**/*.integration.test.ts` in the
+// integration variant) is never a legit app extra: keeping it would silently
+// skip the whole suite the variant exists to run.
+const TEMPLATE_OWNED_IGNORE_PATTERNS = new Set<string>([
+  ...COVERAGE_IGNORED,
+  ...(Object.keys(PRELOADS) as BunfigVariant[]).flatMap((variant) => [
+    ...ignoredPaths(variant, false),
+    ...ignoredPaths(variant, true),
+  ]),
+]);
+
 function isKeepableExtra(key: MergedArrayKey, entry: string): boolean {
-  if (key !== "preload") return true;
+  if (key !== "preload") return !TEMPLATE_OWNED_IGNORE_PATTERNS.has(entry);
   if (SUPERSEDED_PRELOADS.has(entry)) return false;
   if (entry.startsWith(PRELOAD_PREFIX)) return CURRENT_PACKAGE_PRELOADS.has(entry);
   return true;

package/src/changes.json

@@ -1,4 +1,22 @@
 [
+  {
+    "version": "0.335.0",
+    "type": "fix",
+    "title": "Screenshot runner skips empty desktop passes, keeps regional locale tags and restores presented identities",
+    "detail": "Screenshot runner fixes: a desktop project whose viewports are all covered by device projects is now skipped with a reason instead of running empty. Locales that already carry a region (`pt-BR`, `en-GB`) keep their tag instead of becoming `pt-BR-BR`. `captureScreenshot` with `presentIdentities` restores the original DOM text and field values after the capture, so later assertions and form submits in the same spec see real data."
+  },
+  {
+    "version": "0.335.0",
+    "type": "fix",
+    "title": "bunfig merge drops stale template-owned ignore patterns; @testing-library/dom declared as optional peer",
+    "detail": "`kumiko-testing bunfig` drops ignore patterns the template owns but omits for the variant (such as `**/*.test.tsx` in a DOM bunfig) instead of keeping them as app extras, which silently skipped the whole suite. `@testing-library/dom` is declared as an optional peer dependency, since `@testing-library/react` needs it for `preload/dom`; apps using `--dom` install it alongside `@testing-library/react`."
+  },
+  {
+    "version": "0.335.0",
+    "type": "fix",
+    "title": "captureScreenshot fit content ignores non-shrinking scroll containers, integration discovery skips node_modules, apiAs retries a failed login",
+    "detail": "`captureScreenshot(..., { fit: \"content\" })` ignores scroll containers whose overflow does not shrink when the viewport grows (textareas, fixed-height panes) instead of failing to converge. `kumiko-testing integration` no longer walks `node_modules` while discovering test files, and the seeded-tenant `apiAs` retries a failed login on the next call instead of replaying the cached error. The privacy-center and profile `cancel-deletion` actions declare the `x` icon instead of resolving to the destructive trash icon."
+  },
   {
     "version": "0.329.0",
     "type": "fix",

package/src/e2e/define-app-e2e-config.ts

@@ -210,7 +210,10 @@ export function defineAppE2eConfig(input: AppE2eConfigInput): PlaywrightTestConf
         // E2e clients all share ::1, so the default trustedProxyHops (0,
         // socket-only) would collapse every seeded user into one rate-limit
         // bucket. loginViaApi sends a synthetic per-user X-Forwarded-For, so
-        // trust exactly one hop to give each user its own bucket.
+        // trust exactly one hop to give each user its own bucket. An explicit
+        // `trustedProxyHops` / `auth.trustedProxyHops` in the consumer's
+        // server entrypoint wins over this env and brings the shared bucket
+        // (and 429s) back — such a server must read the value from the env.
         [TRUSTED_PROXY_HOPS_ENV]: "1",
       },
       reuseExistingServer: false,

package/src/e2e/screenshots.ts

@@ -155,24 +155,53 @@ function assertPresentableMappings(mappings: readonly PresentIdentity[]): void {
   }
 }
 
-// Runs in the browser, so it may not reference module scope.
+declare global {
+  interface Window {
+    __kumikoPresentRestore?: Array<() => void>;
+  }
+}
+
+// Runs in the browser, so it may not reference module scope. Originals are kept
+// on window so a later evaluate can put them back (captureScreenshot runs
+// mid-flow, where the spec keeps asserting and submitting forms).
 function replaceIdentitiesInDocument(mappings: readonly PresentIdentity[]): void {
+  window.__kumikoPresentRestore ??= [];
+  const restorers = window.__kumikoPresentRestore;
   const present = (text: string): string =>
     mappings.reduce((current, { from, to }) => current.replaceAll(from, to), text);
   const walker = document.createTreeWalker(document.body, NodeFilter.SHOW_TEXT);
   for (let node = walker.nextNode(); node !== null; node = walker.nextNode()) {
     const text = node.nodeValue ?? "";
     const presented = present(text);
-    if (presented !== text) node.nodeValue = presented;
+    if (presented !== text) {
+      const textNode = node;
+      textNode.nodeValue = presented;
+      restorers.push(() => {
+        textNode.nodeValue = text;
+      });
+    }
   }
   for (const field of document.querySelectorAll("input, textarea")) {
     if (field instanceof HTMLInputElement || field instanceof HTMLTextAreaElement) {
-      const presented = present(field.value);
-      if (presented !== field.value) field.value = presented;
+      const original = field.value;
+      const presented = present(original);
+      if (presented !== original) {
+        field.value = presented;
+        restorers.push(() => {
+          field.value = original;
+        });
+      }
     }
   }
 }
 
+// Reverse order: a second presentation pass records already-presented values.
+function restoreIdentitiesInDocument(): void {
+  const restorers = window.__kumikoPresentRestore ?? [];
+  for (const restore of restorers.reverse()) restore();
+  window.__kumikoPresentRestore = [];
+}
+
 async function presentIdentitiesOnPage(
   page: Page,
   mappings: readonly PresentIdentity[],
@@ -180,6 +209,13 @@ async function presentIdentitiesOnPage(
   if (mappings.length > 0) await page.evaluate(replaceIdentitiesInDocument, mappings);
 }
 
+async function restoreIdentitiesOnPage(
+  page: Page,
+  mappings: readonly PresentIdentity[],
+): Promise<void> {
+  if (mappings.length > 0) await page.evaluate(restoreIdentitiesInDocument);
+}
+
 function collectPresentIdentities(): {
   readonly mappings: readonly PresentIdentity[];
   readonly register: (mappings: readonly PresentIdentity[]) => void;
@@ -256,8 +292,8 @@ export function runScreenshots(scenarios: readonly Scenario[], opts: FlatOptions
       test(
         s.description ? `${s.name} — ${s.description}` : s.name,
         async ({ page, seedTenant }) => {
-          // reducedMotion isn't a PlaywrightTestOptions fixture (test.use can't
-          // set it), so it's applied per-page like the rest of emulateMedia.
+          // reducedMotion isn't a PlaywrightTestOptions fixture (only reachable via test.use({ contextOptions }),
+          // which this runner cannot set per scenario), so it's applied per-page like the rest of emulateMedia.
           await page.emulateMedia({ reducedMotion: opts.reducedMotion ?? DEFAULT_REDUCED_MOTION });
           if (opts.pinLocale) await pinEnglishLocale(page);
           const inFlightDataRequests = countInFlightDataRequests(page);
@@ -357,8 +393,10 @@ const DEFAULT_LOCALE_TAGS: Readonly<Record<string, string>> = { en: "en-US", de:
 // own `localeTags` instead of relying on the derived default.
 function deriveLocaleTag(locale: string): string | undefined {
   try {
-    const region = new Intl.Locale(locale).maximize().region;
-    return region === undefined ? undefined : `${locale}-${region}`;
+    const parsed = new Intl.Locale(locale);
+    if (parsed.region !== undefined) return parsed.toString();
+    const region = parsed.maximize().region;
+    return region === undefined ? undefined : `${parsed.language}-${region}`;
   } catch {
     return undefined;
   }
@@ -459,10 +497,14 @@ export function resolveMatrixViewports(
   const deviceProjectIds = new Set(
     projects.filter((p) => p.isMobile && isViewportId(p.name)).map((p) => p.name),
   );
-  return {
-    mode: "desktop",
-    viewports: allowedViewports.filter((id) => !deviceProjectIds.has(id)),
-  };
+  const viewports = allowedViewports.filter((id) => !deviceProjectIds.has(id));
+  if (viewports.length === 0) {
+    return {
+      mode: "skip",
+      reason: `no viewports left for project "${projectName}": SCREENSHOT_VIEWPORTS [${allowedViewports.join(", ")}] all covered by device projects`,
+    };
+  }
+  return { mode: "desktop", viewports };
 }
 
 export function runMatrix<T extends string>(
@@ -489,8 +531,8 @@ export function runMatrix<T extends string>(
       for (const s of scenarios) {
         if (only !== undefined && only !== s.name) continue;
         test(s.name, async ({ page, seedTenant }) => {
-          // reducedMotion isn't a PlaywrightTestOptions fixture (test.use can't set
-          // it), so it's applied per-page like the rest of emulateMedia.
+          // reducedMotion isn't a PlaywrightTestOptions fixture (only reachable via test.use({ contextOptions }),
+          // which this runner cannot set per scenario), so it's applied per-page like the rest of emulateMedia.
           await page.emulateMedia({ reducedMotion: opts.reducedMotion ?? DEFAULT_REDUCED_MOTION });
           const info = test.info();
           const plan = resolveMatrixViewports(
@@ -593,47 +635,67 @@ export interface CaptureScreenshotOptions {
 
 const CONTENT_FIT_MAX_ROUNDS = 4;
 
-// Runs in the browser: the largest vertical overflow of the document or of any
+type ScrollMeasurement = {
+  readonly documentDeficit: number;
+  // [index in document.querySelectorAll("*"), overflow px] per scrolling container.
+  readonly containers: readonly (readonly [number, number])[];
+};
+
+// Runs in the browser: the document's vertical overflow plus that of every
 // visible scrolling container. Serialized into the page, so it may not reference
 // module scope. A 1px container deficit is sub-pixel rounding, not content: an
 // `overflow-x-auto` table wrapper computes overflow-y to `auto` as well and
 // reported scrollHeight one pixel above clientHeight in solon at 1280px, so
 // growth never converged.
-function scrollDeficit(): number {
-  const containerDeficits = [...document.querySelectorAll("*")]
-    .filter((el) => {
-      const style = getComputedStyle(el);
-      return (
-        (style.overflowY === "auto" || style.overflowY === "scroll") &&
-        el.scrollHeight - el.clientHeight > 1 &&
-        el.getClientRects().length > 0 &&
-        style.visibility !== "hidden"
-      );
-    })
-    .map((el) => el.scrollHeight - el.clientHeight);
-  return Math.max(
-    0,
-    document.documentElement.scrollHeight - window.innerHeight,
-    ...containerDeficits,
-  );
+function scrollDeficit(): ScrollMeasurement {
+  const containers: [number, number][] = [];
+  [...document.querySelectorAll("*")].forEach((el, index) => {
+    const style = getComputedStyle(el);
+    if (
+      (style.overflowY === "auto" || style.overflowY === "scroll") &&
+      el.scrollHeight - el.clientHeight > 1 &&
+      el.getClientRects().length > 0 &&
+      style.visibility !== "hidden"
+    ) {
+      containers.push([index, el.scrollHeight - el.clientHeight]);
+    }
+  });
+  return {
+    documentDeficit: Math.max(0, document.documentElement.scrollHeight - window.innerHeight),
+    containers,
+  };
 }
 
 // Growing the viewport re-flows flex-1 regions under an h-svh shell, which can
-// reveal more content, hence rounds. A deficit left after the last round throws
-// instead of writing a silently cropped screenshot.
+// reveal more content, hence rounds. A container whose overflow is unchanged
+// after a growth round (a textarea, a fixed-height log pane, a max-h list) does
+// not depend on the viewport, so it is ignored from then on instead of
+// inflating the viewport until the round budget runs out; this costs one
+// wasted growth step. A deficit left after the last round throws instead of
+// writing a silently cropped screenshot.
 async function growViewportToContent(page: Page, name: string, width: number): Promise<void> {
-  for (let round = 0; round < CONTENT_FIT_MAX_ROUNDS; round++) {
-    const deficit = await page.evaluate(scrollDeficit);
-    if (deficit === 0) break;
+  const ignored = new Set<number>();
+  let previous = new Map<number, number>();
+  for (let round = 0; ; round++) {
+    const measurement = await page.evaluate(scrollDeficit);
+    for (const [index, deficit] of measurement.containers) {
+      if (previous.get(index) === deficit) ignored.add(index);
+    }
+    previous = new Map(measurement.containers);
+    const deficit = Math.max(
+      measurement.documentDeficit,
+      ...measurement.containers.filter(([index]) => !ignored.has(index)).map(([, d]) => d),
+    );
+    // skip: everything fits, no further growth needed
+    if (deficit === 0) return;
+    if (round === CONTENT_FIT_MAX_ROUNDS) {
+      throw new Error(
+        `captureScreenshot(${name}): viewport growth did not converge after ${CONTENT_FIT_MAX_ROUNDS} rounds, ${deficit}px still overflow`,
+      );
+    }
     const height = page.viewportSize()?.height ?? 0;
     await page.setViewportSize({ width, height: height + deficit });
   }
-  const remaining = await page.evaluate(scrollDeficit);
-  if (remaining > 0) {
-    throw new Error(
-      `captureScreenshot(${name}): viewport growth did not converge after ${CONTENT_FIT_MAX_ROUNDS} rounds, ${remaining}px still overflow`,
-    );
-  }
 }
 
 // Inline mid-flow screenshot for a single point in an existing e2e/real-provider
@@ -657,8 +719,12 @@ export async function captureScreenshot(
   mkdirSync(dirname(path), { recursive: true });
   // Before the content fit too: a presented value of another length can change the overflow.
   await presentIdentitiesOnPage(page, identities);
-  if (fit === "content") await captureGrownToContent(page, name, path, identities);
-  else await page.screenshot({ path, animations: "disabled", fullPage: fit === "fullPage" });
+  try {
+    if (fit === "content") await captureGrownToContent(page, name, path, identities);
+    else await page.screenshot({ path, animations: "disabled", fullPage: fit === "fullPage" });
+  } finally {
+    await restoreIdentitiesOnPage(page, identities);
+  }
 }
 
 async function captureGrownToContent(

package/src/e2e/seeded-tenant-fixture.ts

@@ -100,7 +100,11 @@ export async function provideSeedTenant(
     if (cached !== undefined) return cached;
     let opened: Promise<BoundApi> | undefined;
     const bound = (): Promise<BoundApi> => {
-      opened ??= openLoggedInApi(user);
+      // A rejected login must not stay cached, or every later call replays the same stale error.
+      opened ??= openLoggedInApi(user).catch((error: unknown) => {
+        opened = undefined;
+        throw error;
+      });
       return opened;
     };
     const api: BoundApi = {

package/src/integration-runner.ts

@@ -11,6 +11,20 @@ export type IntegrationRunOptions = {
 
 const EXCLUDED_SEGMENTS: ReadonlySet<string> = new Set(["node_modules", "dist", "e2e"]);
 
+// Walks `cwd` without descending into excluded or dot directories, so a
+// hoisted node_modules is never traversed (a glob scan would walk it in full).
+export function listIntegrationTestFiles(cwd: string, relativeDir = ""): string[] {
+  const entries = readdirSync(join(cwd, relativeDir), { withFileTypes: true });
+  return entries.flatMap((entry) => {
+    const relativePath = relativeDir === "" ? entry.name : `${relativeDir}/${entry.name}`;
+    if (entry.isDirectory()) {
+      if (EXCLUDED_SEGMENTS.has(entry.name) || entry.name.startsWith(".")) return [];
+      return listIntegrationTestFiles(cwd, relativePath);
+    }
+    return relativePath.endsWith(".integration.test.ts") ? [relativePath] : [];
+  });
+}
+
 export function selectIntegrationFiles(paths: readonly string[]): string[] {
   return paths
     .filter((path) => path.endsWith(".integration.test.ts"))