@cosmicdrift/kumiko-testing 0.309.0 → 0.311.0

package/package.json

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

package/src/changes.json

@@ -1,4 +1,36 @@
 [
+  {
+    "version": "0.311.0",
+    "type": "breaking",
+    "title": "defineAppE2eConfig's chromium project renders screenshot runs at deviceScaleFactor 2",
+    "detail": "With SCREENSHOT_DIR set, the chromium project renders at 2x so runMatrix and\ncaptureScreenshot images stay sharp on HiDPI displays (desktop files are\n3840×2160). Plain e2e runs stay at 1x. Device projects keep their own scale.",
+    "migration": "Drop app-level deviceScaleFactor overrides (test.use or project use).\nCommitted screenshots taken in the chromium project regenerate at 2x."
+  },
+  {
+    "version": "0.310.0",
+    "type": "improvement",
+    "title": "captureScreenshot accepts fit viewport, fullPage or content",
+    "detail": "`fit: \"viewport\"` (default) keeps the previous behaviour. `fit: \"fullPage\"`\ncaptures the whole document, so offlot's inline mid-flow shots\n(channel-request, channel-prompts, vehicle-channel-texts) can move to\ncaptureScreenshot. `fit: \"content\"` grows the viewport until neither the\ndocument nor a visible overflow-auto/scroll container (WorkspaceShell's\ninner scroll area) overflows, captures, and restores the viewport; it\nthrows instead of writing a cropped image when growth does not converge\nwithin 4 rounds. A 1px container overflow counts as sub-pixel rounding\n(overflow-x-auto table wrappers), not content. This replaces solon's own `e2e/_helpers/shot.ts`; its\nimages pick up the `reducedMotion: \"reduce\"` default on the switch, so a\none-time pixel drift in the handbook PNGs is expected."
+  },
+  {
+    "version": "0.310.0",
+    "type": "breaking",
+    "title": "defineAppE2eConfig's chromium project runs at 1920×1080 instead of Desktop Chrome's 1280×720",
+    "detail": "The template took Playwright's \"Desktop Chrome\" device unchanged, so every\ne2e run and every inline captureScreenshot rendered at 1280×720 while\nrunMatrix's desktop screenshots used 1920×1080. Both now share\nDESKTOP_VIEWPORT (1920×1080). A root `use.viewport` override in an app's\nplaywright config never reached the chromium project anyway (project `use`\nwins), so solon's 1920 override was silently ineffective.",
+    "migration": "Drop app-level desktop viewport overrides. Specs asserting a layout that\nonly exists below 1920px (collapsed sidebar, stacked panes) set their own\nviewport via test.use({ viewport }). Committed inline screenshots taken\nin the chromium project regenerate at 1920 width."
+  },
+  {
+    "version": "0.310.0",
+    "type": "fix",
+    "title": "defineAppE2eConfig's webServer env no longer defaults MEILI_URL and MEILI_MASTER_KEY",
+    "detail": "Since the infra env defaults landed, every e2e webServer got\nMEILI_URL=http://localhost:17700. Apps that choose Meilisearch over\ntheir in-memory search adapter when MEILI_URL is set then pointed at an\nunreachable host in CI without a Meili service. Meili is opt-in again:\nthe two vars reach the webServer only when the environment sets them or\nthe app passes them via `env`. All other infra defaults are unchanged.\nMigration: an app whose e2e needs Meilisearch sets MEILI_URL (and\nMEILI_MASTER_KEY) in `defineAppE2eConfig({ env })` or in the CI env; an\napp that worked around it with `MEILI_URL: \"\"` can drop that override."
+  },
+  {
+    "version": "0.310.0",
+    "type": "fix",
+    "title": "Screenshot scenario waitFor uses the template timeout budget instead of a fixed 10s",
+    "detail": "runScreenshots/runMatrix wait for a scenario's `waitFor` selector with\n`E2E_TIMEOUT_MS.navigation`, or `E2E_TIMEOUT_MS.real` under\nKUMIKO_REAL_PROVIDERS=1, so real-provider screenshot scenarios no longer\ntime out on LLM/OCR latency and apps don't need their own wait timeouts."
+  },
   {
     "version": "0.309.0",
     "type": "breaking",

package/src/e2e/constants.ts

@@ -43,3 +43,12 @@ export const SEED_ROUTES = {
   seedUser: `${SEED_ROUTE_PREFIX}/seed-user`,
   inbox: `${SEED_ROUTE_PREFIX}/inbox`,
 } as const;
+
+// Desktop default for e2e runs and screenshots alike. Playwright's "Desktop
+// Chrome" device ships 1280×720: handbook and doc shots at 1280 visibly soften
+// on a HiDPI display, and a list next to a reading pane looks cramped.
+export const DESKTOP_VIEWPORT = { width: 1920, height: 1080 } as const;
+
+// Screenshot runs (SCREENSHOT_DIR set) render at 2x so doc images stay sharp
+// on HiDPI displays; plain e2e runs keep 1x. Device projects keep their own.
+export const SCREENSHOT_DEVICE_SCALE_FACTOR = 2;

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

@@ -10,23 +10,39 @@ import {
 } from "@playwright/test";
 import { SERVICE_ENV_DEFAULTS } from "../preload/service-env-defaults-values";
 import {
+  DESKTOP_VIEWPORT,
   E2E_WORKERS_ENV,
   isRealProviderRun,
   PLAYWRIGHT_DEMO_ENV,
   PROD_BUNDLES_ENV,
+  SCREENSHOT_DEVICE_SCALE_FACTOR,
   SEED_ENABLE_ENV,
   SEED_TOKEN_ENV,
   STYLESHEET_WATCH_ENV,
 } from "./constants";
-import { screenshotSpecsIgnore } from "./screenshot-dir";
+import { isScreenshotRun, screenshotSpecsIgnore } from "./screenshot-dir";
 import { E2E_TIMEOUT_MS } from "./timeouts";
 
+// Apps pick Meilisearch over their in-memory search adapter just because
+// MEILI_URL is set, so a default here would point every consumer without a
+// Meili service at an unreachable host. Meili stays opt-in: environment or `env`.
+const OPT_IN_SERVICE_ENV_KEYS: readonly string[] = [
+  "MEILI_URL",
+  "MEILI_MASTER_KEY",
+] satisfies readonly (keyof typeof SERVICE_ENV_DEFAULTS)[];
+
 // A `??` merge per key, not a raw process.env spread — CI or the shell
 // environment wins over the local-dev default without leaking unrelated
 // host env vars into the webServer process.
 function infraEnvDefaults(): Record<string, string> {
   return Object.fromEntries(
-    Object.entries(SERVICE_ENV_DEFAULTS).map(([key, value]) => [key, process.env[key] ?? value]),
+    Object.entries(SERVICE_ENV_DEFAULTS).flatMap(([key, value]) => {
+      const fromEnvironment = process.env[key];
+      if (OPT_IN_SERVICE_ENV_KEYS.includes(key)) {
+        return fromEnvironment === undefined ? [] : [[key, fromEnvironment]];
+      }
+      return [[key, fromEnvironment ?? value]];
+    }),
   );
 }
 
@@ -154,7 +170,17 @@ export function defineAppE2eConfig(input: AppE2eConfigInput): PlaywrightTestConf
       actionTimeout: E2E_TIMEOUT_MS.action,
       navigationTimeout: E2E_TIMEOUT_MS.navigation,
     },
-    projects: [{ name: "chromium", use: { ...devices["Desktop Chrome"] } }, ...projects],
+    projects: [
+      {
+        name: "chromium",
+        use: {
+          ...devices["Desktop Chrome"],
+          viewport: DESKTOP_VIEWPORT,
+          deviceScaleFactor: isScreenshotRun() ? SCREENSHOT_DEVICE_SCALE_FACTOR : 1,
+        },
+      },
+      ...projects,
+    ],
     webServer: {
       command: `bun run ${serverEntry}`,
       url: baseURL,

package/src/e2e/index.ts

@@ -39,6 +39,8 @@ export {
 } from "./screenshot-dir";
 export {
   applyDefaultTheme,
+  type CaptureFit,
+  type CaptureScreenshotOptions,
   captureScreenshot,
   DEFAULT_THEMES,
   type DefaultThemeId,

package/src/e2e/screenshot-dir.ts

@@ -8,7 +8,7 @@ const NORMAL_RUN_IGNORE: readonly string[] = [
 
 type Env = Readonly<Record<string, string | undefined>>;
 
-function isScreenshotRun(env: Env): boolean {
+export function isScreenshotRun(env: Env = process.env): boolean {
   const dir = env[SCREENSHOT_DIR_ENV];
   return dir !== undefined && dir !== "";
 }

package/src/e2e/screenshots.ts

@@ -2,9 +2,11 @@ import { createHash } from "node:crypto";
 import { mkdirSync, statSync } from "node:fs";
 import { dirname } from "node:path";
 import { expect, type Page, type Request } from "@playwright/test";
+import { DESKTOP_VIEWPORT, isRealProviderRun } from "./constants";
 import { pinEnglishLocale } from "./pin-english-locale";
 import { requireScreenshotDir, SCREENSHOT_DIR_ENV } from "./screenshot-dir";
 import { type SeedTenantFixture, test } from "./seeded-tenant-fixture";
+import { E2E_TIMEOUT_MS } from "./timeouts";
 
 export const DEFAULT_REDUCED_MOTION = "reduce" as const;
 
@@ -121,7 +123,9 @@ async function openScenario(
   else throw new Error(`Scenario "${s.name}" needs either url or flow`);
 
   if (s.waitFor) {
-    await expect(page.locator(s.waitFor).first()).toBeVisible({ timeout: 10_000 });
+    // 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 waitForSettledPage(page, inFlightDataRequests);
 }
@@ -194,11 +198,7 @@ export function runScreenshots(scenarios: readonly Scenario[], opts: FlatOptions
 const VIEWPORT_IDS = ["desktop", "tablet", "mobile"] as const;
 export type ViewportId = (typeof VIEWPORT_IDS)[number];
 const VIEWPORTS: Record<ViewportId, { readonly width: number; readonly height: number }> = {
-  // 1920×1080 instead of the earlier 1280×900: these shots land in the
-  // handbook and doc pages, where a 1280 image visibly softens on a HiDPI
-  // display. Wider also shows what a two-column layout actually does — at
-  // 1280 any list next to a reading pane looks cramped.
-  desktop: { width: 1920, height: 1080 },
+  desktop: DESKTOP_VIEWPORT,
   // Landscape: portrait tablet shots collapsed two-column layouts into the mobile stack.
   tablet: { width: 1112, height: 834 },
   mobile: { width: 390, height: 844 },
@@ -461,6 +461,62 @@ function inFlightTrackerFor(page: Page): () => number {
   return tracker;
 }
 
+// "viewport": what the window shows. "fullPage": Playwright's document-height
+// capture, which renders a sticky sidebar floating mid-page. "content": grows the
+// viewport until nothing overflows, including WorkspaceShell's internally
+// scrolling `overflow-auto` containers that document.scrollHeight never sees.
+export type CaptureFit = "viewport" | "fullPage" | "content";
+
+export interface CaptureScreenshotOptions {
+  readonly reducedMotion?: ReducedMotionOption;
+  readonly fit?: CaptureFit;
+}
+
+const CONTENT_FIT_MAX_ROUNDS = 4;
+
+// Runs in the browser: the largest vertical overflow of the document or of any
+// 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,
+  );
+}
+
+// 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.
+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 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
 // spec (solon's `shot(page, id)`, offlot's inline docs/screenshots/e2e/* writes) —
 // reuses the runner's settle logic and reduced-motion default, and is a no-op
@@ -468,14 +524,30 @@ function inFlightTrackerFor(page: Page): () => number {
 export async function captureScreenshot(
   page: Page,
   name: string,
-  opts: { readonly reducedMotion?: ReducedMotionOption } = {},
+  opts: CaptureScreenshotOptions = {},
 ): Promise<void> {
   const dir = process.env[SCREENSHOT_DIR_ENV];
   // skip: a plain e2e run without SCREENSHOT_DIR must not write screenshots.
   if (dir === undefined || dir === "") return;
+  const fit = opts.fit ?? "viewport";
   await page.emulateMedia({ reducedMotion: opts.reducedMotion ?? DEFAULT_REDUCED_MOTION });
   await waitForSettledPage(page, inFlightTrackerFor(page));
   const path = `${dir}/${name}.png`;
   mkdirSync(dirname(path), { recursive: true });
-  await page.screenshot({ path, animations: "disabled" });
+  if (fit === "content") await captureGrownToContent(page, name, path);
+  else await page.screenshot({ path, animations: "disabled", fullPage: fit === "fullPage" });
+}
+
+async function captureGrownToContent(page: Page, name: string, path: string): Promise<void> {
+  const viewport = page.viewportSize();
+  if (viewport === null) {
+    throw new Error(`captureScreenshot(${name}): fit "content" needs a page with a viewport`);
+  }
+  try {
+    await growViewportToContent(page, name, viewport.width);
+    await page.screenshot({ path, animations: "disabled" });
+  } finally {
+    // Later assertions in the same test must run against the original window.
+    await page.setViewportSize(viewport);
+  }
 }

package/src/scaffold.ts

@@ -36,6 +36,7 @@ const RULES_MARKDOWN = [
   "- Tests run in parallel by default. Timeouts, retries and workers live in the scripts, the bunfig files and `playwright.config.ts`; never raise them inside a test. The only exception carries a marker: `// @timeout-exception: #<issue> <reason>`.",
   "- Every flow seeds its own tenant: `seedTenant(stack)` in integration tests, the `seedTenant` fixture in e2e. No shared tenant, no widened seed helper.",
   "- Red or flaky? Diagnose the cause first (https://github.com/CosmicDriftGameStudio/kumiko-framework/blob/main/docs/guides/test-failures.md). A longer timeout, a retry or `serial` is not a fix.",
+  "- Why the setup looks this way, and the old-pattern → new-pattern table: https://github.com/CosmicDriftGameStudio/kumiko-framework/blob/main/docs/guides/testing-standard.md.",
   "- Run Playwright as `bunx --bun playwright`, as the scripts do.",
   `- Playwright configs and e2e files start with \`${TEST_RUNTIME_DIRECTIVE}\`; without it the runtime-isolation guard flags their import of the test package.`,
   "",