@cosmicdrift/kumiko-testing 0.388.0 → 0.390.0

package/README.md

@@ -47,8 +47,11 @@ test("member sees the note", async ({ seedTenant, page }) => {
 });
 ```
 
-- `defineAppE2eConfig({ port, env?, locale?, projects?, serverEntry?, testDir?, testMatch? })`: parallelism, retries, timeouts and
+- `defineAppE2eConfig({ port, env?, locale?, projects?, serverEntry?, testDir?, testMatch?, isolatedSpecs? })`: parallelism, retries, timeouts and
   workers (`KUMIKO_E2E_WORKERS` overrides) are fixed by the template; projects cannot set them.
+- `isolatedSpecs: ["**/composer.spec.ts"]` moves specs that change app-wide state (catalog entries, global
+  settings) into the `chromium-isolated` project, which runs after all parallel projects on one worker. It cannot
+  be combined with `--shard`; details in `docs/guides/testing-standard.md`.
 - `KUMIKO_E2E_REMOTE_BASE_URL=https://staging.example.com` runs the same specs against an already running
   instance: no web server is started and `baseURL` is that URL (http or https only). Add
   `KUMIKO_E2E_STORAGE_STATE=<file>` for a session recorded with `playwright codegen --save-storage`;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-testing",
-  "version": "0.388.0",
+  "version": "0.390.0",
   "description": "Test template for Kumiko apps: per-flow seedTenant, app test stack, canonical test preloads, bunfig generator and integration runner.",
   "license": "MIT",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -34,6 +34,10 @@
       "types": "./src/helpers/index.ts",
       "default": "./src/helpers/index.ts"
     },
+    "./helpers/mock-module": {
+      "types": "./src/helpers/mock-module.ts",
+      "default": "./src/helpers/mock-module.ts"
+    },
     "./helpers/real-providers": {
       "types": "./src/helpers/real-providers.ts",
       "default": "./src/helpers/real-providers.ts"
@@ -99,13 +103,13 @@
     "kumiko-testing": "./bin/kumiko-testing.ts"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-framework": "0.388.0",
-    "@cosmicdrift/kumiko-guards": "0.388.0",
-    "@cosmicdrift/kumiko-types": "0.388.0",
+    "@cosmicdrift/kumiko-framework": "0.390.0",
+    "@cosmicdrift/kumiko-guards": "0.390.0",
+    "@cosmicdrift/kumiko-types": "0.390.0",
     "zod": "^4.4.3"
   },
   "peerDependencies": {
-    "@happy-dom/global-registrator": "^20.11.2",
+    "@happy-dom/global-registrator": "^21.0.4",
     "@playwright/test": "^1.62.1",
     "@testing-library/dom": "^10.4.1",
     "@testing-library/react": "^16.3.2"
@@ -125,9 +129,9 @@
     }
   },
   "devDependencies": {
-    "@cosmicdrift/kumiko-bundled-features": "0.388.0",
-    "@cosmicdrift/kumiko-dev-server": "0.388.0",
-    "@happy-dom/global-registrator": "^20.11.2",
+    "@cosmicdrift/kumiko-bundled-features": "0.390.0",
+    "@cosmicdrift/kumiko-dev-server": "0.390.0",
+    "@happy-dom/global-registrator": "^21.0.4",
     "@playwright/test": "^1.62.1",
     "@testing-library/dom": "^10.4.1",
     "@testing-library/react": "^16.3.2",

package/src/changes.json

@@ -1,4 +1,105 @@
 [
+  {
+    "version": "0.390.0",
+    "type": "breaking",
+    "title": "happy-dom and undici updated for security advisories",
+    "detail": "The happy-dom range for the global registrator and the DOM test setup moves to ^21.0.4 (fixes GHSA-834V-8H66-3H79, incomplete fix for an unsanitized import alias leading to host code execution), undici is pinned to 7.30.1 (fixes GHSA-XJJ6-F33Q-929C, denial of service through an unhandled error on excessive content-encodings).",
+    "migration": "Bump @happy-dom/global-registrator (and happy-dom, if listed) to ^21.0.4 in the app's devDependencies; the kumiko-testing peer range is now ^21.0.4. happy-dom 21 is a major release: run the app's DOM test suite after the bump."
+  },
+  {
+    "version": "0.390.0",
+    "type": "improvement",
+    "title": "Run e2e specs that change global app state in an isolated project",
+    "detail": "defineAppE2eConfig takes an isolatedSpecs option with the same pattern form as testMatch. Matching specs are removed from chromium and from every app project and run in a separate chromium-isolated project with one worker, only after all other projects have finished. Apps use it for specs that change state shared across the app, such as creating catalog channels. With isolatedSpecs set, every app project needs a name, and a run with --shard throws because Playwright does not shard dependency projects. Without the option the generated config is unchanged."
+  },
+  {
+    "version": "0.390.0",
+    "type": "improvement",
+    "title": "The e2e suites run in two parallel CI shards",
+    "detail": "The framework CI splits the Playwright e2e suites across two runners instead of running them one after another on a single runner. The required e2e check passes only when both shards succeed. Nothing changes for apps; the package is only republished."
+  },
+  {
+    "version": "0.390.0",
+    "type": "improvement",
+    "title": "The puppeteer render tests, including the egress guard, run in CI",
+    "detail": "The integration job installs Chrome through the trusted puppeteer postinstall and caches it between runs, so the real render tests no longer skip in CI. Nothing changes for apps; the package is only republished."
+  },
+  {
+    "version": "0.390.0",
+    "type": "breaking",
+    "title": "extraContext factories get the raw db in the test stack and dev",
+    "detail": "The test stack and dev now pass the enforcing pool to extraContext factories, as runProdApp does, so request-time services keep the ambient request scope and a tenant leak shows up in tests instead of only in production.",
+    "migration": "Services built in extraContext that read across tenants at request time, or that a test calls directly, must scope themselves: createTenantDb({ db, tenantId, mode: \"system\", reason: \"<why>\" }). Test code reads through stack.db."
+  },
+  {
+    "version": "0.390.0",
+    "type": "improvement",
+    "title": "Export applicationRoleUrlOf from kumiko-testing/stack",
+    "detail": "Use it to boot runProdApp in tests against the app role. It returns the URL of a database as the non-bypass application role with the password of TEST_DATABASE_URL; pair it with createTestDb({ applicationRole: true })."
+  },
+  {
+    "version": "0.390.0",
+    "type": "improvement",
+    "title": "The test application role is realigned to the configured password",
+    "detail": "createApplicationRole used to return early when the role existed, so a kumiko_app role with another password made every integration test fail with 28P01. It now runs ALTER ROLE with the configured password and the NOSUPERUSER NOBYPASSRLS attributes."
+  },
+  {
+    "version": "0.390.0",
+    "type": "breaking",
+    "title": "The test stack runs with row level security on as role kumiko_app",
+    "detail": "setupTestStack creates the role kumiko_app (LOGIN NOSUPERUSER NOBYPASSRLS, password taken from TEST_DATABASE_URL) once, makes it owner of the test database and opens every pool as that role with rowLevelSecurity \"on\"; template databases are built the same way. stack.db runs in system scope and sees every tenant's rows as before. The new stack.unscopedDb is the enforced pool the services use, on which a statement without a scope sees no tenant rows. rowLevelSecurity: \"off\" in the stack options restores the superuser stack without policies. createTestDb takes applicationRole: true for the same setup.",
+    "migration": "App code that reads or writes tenant tables through a raw connection outside a request, a job or a TenantDb now sees no rows in integration tests. Test code that calls such a path directly runs it inside runInSystemRowLevelSecurityScope or runInRowLevelSecurityScope(tenantRowLevelSecurityScope(tenantId), ...) from @cosmicdrift/kumiko-testing/helpers. Production code works through a TenantDb for the tenant, a job, a system-scoped handler or a granted unsafeRaw. Tests that need superuser rights on stack.db, such as CREATE EXTENSION, CREATE ROLE or event triggers, open their own connection from TEST_DATABASE_URL or use createTestDb(). Manual migration, there is no codemod."
+  },
+  {
+    "version": "0.390.0",
+    "type": "improvement",
+    "title": "Test helpers for event-store writes",
+    "detail": "The testing helpers gain updateRowViaEventStore, deleteRowViaEventStore and deleteRowsViaEventStore. They update or delete rows of an event-sourced table through the event-store executor, so the event log and the projection stay in step, instead of writing the projection table directly."
+  },
+  {
+    "version": "0.390.0",
+    "type": "improvement",
+    "title": "Seed event-sourced rows through the event store",
+    "detail": "The testing helpers gain seedRowViaEventStore(db, table, values). It takes the same arguments as seedRow, appends a created event through the event-store executor and projects the row, so a rebuild keeps the seeded row. The row's tenantId selects the acting tenant; global entities such as user are seeded without a tenantId, because the executor rejects one on them. It throws for tables that are not event-sourced entity tables, for a non-string id and when the executor rejects the row. To support this, buildEntityTable and r.entity now remember which entity a managed table belongs to; nothing changes for apps."
+  },
+  {
+    "version": "0.389.0",
+    "type": "breaking",
+    "title": "captureClosedConnectionError returns a Bun.SQL error",
+    "detail": "The helper opens Bun.SQL pools, so the captured error has the code ERR_POSTGRES_CONNECTION_CLOSED instead of the postgres-js CONNECTION_CLOSED. The client of createTestDb is the connection handle's listenClient, the same Bun.SQL pool as before.",
+    "migration": "Tests that compared the captured error's code with CONNECTION_CLOSED compare with ERR_POSTGRES_CONNECTION_CLOSED or call isClosedConnectionError. Manual migration, there is no codemod."
+  },
+  {
+    "version": "0.389.0",
+    "type": "breaking",
+    "title": "e2e tests fail after more than 8 app boots; the per-test client IP no longer disables the HTTP cache",
+    "detail": "The test fixture sent the per-test X-Forwarded-For through context.route, which turns Chromium's HTTP cache off for the whole context, so every page.goto re-downloaded all assets and GET /api/schema. It now uses setExtraHTTPHeaders and the cache stays on. The fixture also counts GET /api/schema per test and fails a passing test that boots the app more than 8 times (default of the new maxAppBootsPerTest fixture option), and closes pages left open (window.open tabs) before the context closes.",
+    "migration": "Seed through tenant.api, tenant.seed and tenant.addUser instead of calling page.goto(APP_BASE_PATH) before every seed; each page.goto reloads the app. runMatrix and runScreenshots boot the app once per test themselves, so they need no change; only your own scenario flows or specs that navigate on purpose raise the budget with test.use({ maxAppBootsPerTest: <n> }). Manual migration, there is no codemod. The X-Forwarded-For header is now sent on every request of the context, including cross-origin ones."
+  },
+  {
+    "version": "0.389.0",
+    "type": "fix",
+    "title": "loginViaUi no longer races the MFA auto-submit",
+    "detail": "The MFA code field submits itself on the sixth digit since 0.388. loginViaUi now fills the code while waiting for the verify response and no longer presses Enter on a field that may already be disabled."
+  },
+  {
+    "version": "0.389.0",
+    "type": "improvement",
+    "title": "consoleCallsFromNamespace test helper for silent-log assertions",
+    "detail": "Filters a console spy by logger namespace prefix, so a new or reworded warning from the module under test fails a silent test. The boot-validator, client-ip and settings-hub silent tests use it."
+  },
+  {
+    "version": "0.389.0",
+    "type": "improvement",
+    "title": "mockModuleForFile restores module mocks automatically",
+    "detail": "bun's mock.module is process-global, so tests had to copy the real module and restore it by hand in afterAll. The helper does both and can point re-exporting modules back at the real export."
+  },
+  {
+    "version": "0.389.0",
+    "type": "improvement",
+    "title": "E2E specs can present stable identities around their own screenshots",
+    "detail": "withPresentedIdentities replaces generated identities in page text and form values, runs the callback and restores the originals in a finally block. The lower-level present and restore functions are exported too."
+  },
   {
     "version": "0.388.0",
     "type": "improvement",

package/src/e2e/app-boot-budget.ts

@@ -0,0 +1,22 @@
+import type { BrowserContext } from "@playwright/test";
+
+// Duplicated from kumiko-renderer (APP_SCHEMA_API_PATH): kumiko-testing does not depend on the renderer.
+export const APP_SCHEMA_API_PATH = "/api/schema";
+
+export const DEFAULT_MAX_APP_BOOTS_PER_TEST = 8;
+
+// Every app boot fetches the schema once, so the request count is the number of page loads.
+export function observeAppBoots(context: Pick<BrowserContext, "on">): {
+  readonly count: () => number;
+} {
+  let bootCount = 0;
+  context.on("request", (request) => {
+    if (new URL(request.url()).pathname === APP_SCHEMA_API_PATH) bootCount += 1;
+  });
+  return { count: () => bootCount };
+}
+
+export function appBootBudgetViolation(bootCount: number, maxBoots: number): string | undefined {
+  if (bootCount <= maxBoots) return undefined;
+  return `This test booted the app ${bootCount} times (GET ${APP_SCHEMA_API_PATH}), budget is ${maxBoots}. Seed through tenant.api instead of page.goto per seed; each page.goto reloads the app. Specs that navigate on purpose (screenshot scenarios) raise the budget with test.use({ maxAppBootsPerTest }).`;
+}

package/src/e2e/auth-kit.ts

@@ -273,8 +273,14 @@ export async function loginViaUi(page: Page, credentials: LoginCredentials): Pro
   // avoids racing the transition from the password form.
   const codeField = page.locator("#mfa-verify-code");
   await expect(codeField).toBeVisible();
-  await codeField.fill(await unburnedTotpCode(credentials.mfaTotpSecret));
-  await codeField.press("Enter");
+  const code = await unburnedTotpCode(credentials.mfaTotpSecret);
+  // The sixth digit submits on its own and disables the field; an Enter press would race that.
+  await Promise.all([
+    page.waitForResponse(
+      (response) => response.url().includes("/api/auth/mfa/verify") && response.ok(),
+    ),
+    codeField.fill(code),
+  ]);
   await expect(codeField).toHaveCount(0);
 }
 

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

@@ -77,6 +77,8 @@ const TEMPLATE_OWNED_PROJECT_KEYS = [
 ] as const;
 const TEMPLATE_OWNED_USE_KEYS = ["actionTimeout", "navigationTimeout"] as const;
 const REAL_SPEC_GLOB = "**/*.real.spec.ts";
+export const ISOLATED_E2E_PROJECT_NAME = "chromium-isolated";
+export const NON_REAL_SPEC_PATTERN = /(?<!\.real)\.spec\.ts$/;
 const RESERVED_ENV_KEYS = [
   "PORT",
   SEED_ENABLE_ENV,
@@ -111,6 +113,7 @@ export type AppE2eConfigInput = {
   readonly projects?: readonly E2eProject[];
   readonly testDir?: string;
   readonly testMatch?: string | RegExp | readonly (string | RegExp)[];
+  readonly isolatedSpecs?: string | RegExp | readonly (string | RegExp)[];
   readonly permissions?: readonly string[];
   readonly launchOptions?: LaunchOptions;
 } & ServerStart;
@@ -140,6 +143,13 @@ function mutableTestMatch(
   return typeof match === "string" || match instanceof RegExp ? match : [...match];
 }
 
+function patternList(
+  patterns: NonNullable<AppE2eConfigInput["testMatch"]> | undefined,
+): (string | RegExp)[] {
+  if (patterns === undefined) return [];
+  return typeof patterns === "string" || patterns instanceof RegExp ? [patterns] : [...patterns];
+}
+
 export function resolveE2eWorkers(
   env: Readonly<Record<string, string | undefined>> = process.env,
   // cpus() reports every host core inside a CPU-limited container (1.5 CPU CI
@@ -233,6 +243,58 @@ function failureRecording(
   return { trace: "off", screenshot: "off", video: "off" };
 }
 
+// Worker processes do not carry --shard in argv, so only the runner trips this.
+function isShardedRun(argv: readonly string[] = process.argv): boolean {
+  return argv.some((arg) => arg === "--shard" || arg.startsWith("--shard="));
+}
+
+type ProjectsInput = {
+  readonly chromiumUse: Project["use"];
+  readonly appProjects: readonly E2eProject[];
+  readonly isolated: readonly (string | RegExp)[];
+  readonly baseIgnore: readonly string[];
+  readonly realRun: boolean;
+};
+
+function assertIsolatedSpecsUsable(appProjects: readonly E2eProject[]): void {
+  if (appProjects.some((project) => project.name === undefined)) {
+    throw new Error(
+      "defineAppE2eConfig: isolatedSpecs needs named projects, because the isolated project waits for them via dependencies",
+    );
+  }
+  if (isShardedRun()) {
+    throw new Error(
+      "defineAppE2eConfig: isolatedSpecs cannot be combined with --shard; Playwright does not shard dependency projects, so one shard would run every spec.",
+    );
+  }
+}
+
+function buildE2eProjects(input: ProjectsInput): Project[] {
+  const { chromiumUse, appProjects, isolated, baseIgnore, realRun } = input;
+  const baseProjects: Project[] = [{ name: "chromium", use: chromiumUse }, ...appProjects];
+  if (isolated.length === 0) return baseProjects;
+  assertIsolatedSpecsUsable(appProjects);
+  // A project-level testIgnore replaces the top-level one instead of merging with it.
+  const parallelProjects = baseProjects.map((project) => ({
+    ...project,
+    testIgnore: [...baseIgnore, ...patternList(project.testIgnore), ...isolated],
+  }));
+  return [
+    ...parallelProjects,
+    {
+      name: ISOLATED_E2E_PROJECT_NAME,
+      testMatch: [...isolated],
+      testIgnore: [...baseIgnore, ...(realRun ? [NON_REAL_SPEC_PATTERN] : [])],
+      dependencies: parallelProjects.flatMap((project) =>
+        project.name === undefined ? [] : [project.name],
+      ),
+      fullyParallel: false,
+      workers: 1,
+      use: chromiumUse,
+    },
+  ];
+}
+
 export function defineAppE2eConfig(input: AppE2eConfigInput): PlaywrightTestConfig {
   const {
     port,
@@ -241,6 +303,7 @@ export function defineAppE2eConfig(input: AppE2eConfigInput): PlaywrightTestConf
     projects = [],
     testDir = "./e2e",
     testMatch,
+    isolatedSpecs,
     permissions,
     launchOptions,
   } = input;
@@ -257,13 +320,27 @@ export function defineAppE2eConfig(input: AppE2eConfigInput): PlaywrightTestConf
   const remote = remoteTargetFromEnv(process.env);
   const baseURL = remote?.baseURL ?? `http://localhost:${port}`;
   const realRun = isRealProviderRun();
+  const baseIgnore = [...screenshotSpecsIgnore(), ...(realRun ? [] : [REAL_SPEC_GLOB])];
+  const isolated = patternList(isolatedSpecs);
+  const chromiumUse = {
+    ...devices["Desktop Chrome"],
+    viewport: DESKTOP_VIEWPORT,
+    deviceScaleFactor: isScreenshotRun() ? SCREENSHOT_DEVICE_SCALE_FACTOR : 1,
+  };
+  const e2eProjects = buildE2eProjects({
+    chromiumUse,
+    appProjects: projects,
+    isolated,
+    baseIgnore,
+    realRun,
+  });
 
   return defineConfig({
     testDir,
     ...(realRun
       ? { testMatch: REAL_SPEC_GLOB }
       : testMatch !== undefined && { testMatch: mutableTestMatch(testMatch) }),
-    testIgnore: [...screenshotSpecsIgnore(), ...(realRun ? [] : [REAL_SPEC_GLOB])],
+    testIgnore: baseIgnore,
     fullyParallel: true,
     forbidOnly: !!process.env["CI"],
     retries: 0,
@@ -281,17 +358,7 @@ export function defineAppE2eConfig(input: AppE2eConfigInput): PlaywrightTestConf
       ...(permissions !== undefined && { permissions: [...permissions] }),
       ...(launchOptions !== undefined && { launchOptions }),
     },
-    projects: [
-      {
-        name: "chromium",
-        use: {
-          ...devices["Desktop Chrome"],
-          viewport: DESKTOP_VIEWPORT,
-          deviceScaleFactor: isScreenshotRun() ? SCREENSHOT_DEVICE_SCALE_FACTOR : 1,
-        },
-      },
-      ...projects,
-    ],
+    projects: e2eProjects,
     ...(remote === undefined && {
       webServer: {
         command: serverCommand,

package/src/e2e/index.ts

@@ -40,6 +40,7 @@ export {
   type AppE2eConfigInput,
   defineAppE2eConfig,
   type E2eProject,
+  ISOLATED_E2E_PROJECT_NAME,
   resolveE2eWorkers,
 } from "./define-app-e2e-config";
 export { type MailCaptureOptions, mailCapture } from "./mail-capture";
@@ -51,6 +52,12 @@ export {
 } from "./mail-links";
 export { pinEnglishLocale } from "./pin-english-locale";
 export { pollForRow, waitForProjection } from "./poll";
+export {
+  type PresentIdentity,
+  presentIdentitiesOnPage,
+  restoreIdentitiesOnPage,
+  withPresentedIdentities,
+} from "./present-identities";
 export {
   requireScreenshotDir,
   SCREENSHOT_DIR_ENV,
@@ -66,7 +73,6 @@ export {
   type FlatOptions,
   findIdenticalThemeScreenshots,
   type MatrixOptions,
-  type PresentIdentity,
   runMatrix,
   runScreenshots,
   type Scenario,

package/src/e2e/present-identities.ts

@@ -0,0 +1,90 @@
+import type { Page } from "@playwright/test";
+
+// Seeded identities are unique per run (admin-<tenantId>@…), so a screenshot
+// would show a different address every time. Replaced in the page's text and
+// form values right before each capture; the seeded data stays untouched.
+export interface PresentIdentity {
+  readonly from: string;
+  readonly to: string;
+}
+
+export function assertPresentableMappings(mappings: readonly PresentIdentity[]): void {
+  for (const { from } of mappings) {
+    if (from === "") throw new Error("presentIdentities: `from` must not be empty");
+  }
+}
+
+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) {
+      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 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 = [];
+}
+
+export async function presentIdentitiesOnPage(
+  page: Page,
+  mappings: readonly PresentIdentity[],
+): Promise<void> {
+  if (mappings.length > 0) await page.evaluate(replaceIdentitiesInDocument, mappings);
+}
+
+export async function restoreIdentitiesOnPage(
+  page: Page,
+  mappings: readonly PresentIdentity[],
+): Promise<void> {
+  if (mappings.length > 0) await page.evaluate(restoreIdentitiesInDocument);
+}
+
+export async function withPresentedIdentities<T>(
+  page: Page,
+  mappings: readonly PresentIdentity[],
+  fn: () => Promise<T>,
+): Promise<T> {
+  assertPresentableMappings(mappings);
+  await presentIdentitiesOnPage(page, mappings);
+  try {
+    return await fn();
+  } finally {
+    await restoreIdentitiesOnPage(page, mappings);
+  }
+}

package/src/e2e/screenshots.ts

@@ -6,6 +6,12 @@ import { E2E_TIMEOUT_MS } from "../e2e-timeouts";
 import { isRealProviderRun } from "../helpers/real-providers.ts";
 import { DESKTOP_VIEWPORT } from "./constants";
 import { pinEnglishLocale } from "./pin-english-locale";
+import {
+  assertPresentableMappings,
+  type PresentIdentity,
+  presentIdentitiesOnPage,
+  restoreIdentitiesOnPage,
+} from "./present-identities";
 import { requireScreenshotDir, SCREENSHOT_DIR_ENV } from "./screenshot-dir";
 import { type SeedTenantFixture, test } from "./seeded-tenant-fixture";
 
@@ -33,14 +39,6 @@ export async function applyDefaultTheme(page: Page, theme: DefaultThemeId): Prom
   }, theme);
 }
 
-// Seeded identities are unique per run (admin-<tenantId>@…), so a screenshot
-// would show a different address every time. Replaced in the page's text and
-// form values right before each capture; the seeded data stays untouched.
-export interface PresentIdentity {
-  readonly from: string;
-  readonly to: string;
-}
-
 export interface ScenarioFixtures {
   readonly seedTenant: SeedTenantFixture;
   // runMatrix's current locale, for apps whose routes carry the locale in the
@@ -165,73 +163,6 @@ async function waitForSettledPage(page: Page, inFlightDataRequests: () => number
     .toBeGreaterThanOrEqual(STABLE_POLLS);
 }
 
-function assertPresentableMappings(mappings: readonly PresentIdentity[]): void {
-  for (const { from } of mappings) {
-    if (from === "") throw new Error("presentIdentities: `from` must not be empty");
-  }
-}
-
-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) {
-      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 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[],
-): Promise<void> {
-  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);
-}
-
 // 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(

package/src/e2e/seed-route.ts

@@ -107,6 +107,12 @@ function assertSeededTenant(tenantId: string, seededTenantIds: ReadonlySet<strin
 export type E2eSeederContext = {
   readonly write: (handlerQn: string, payload: unknown) => Promise<unknown>;
   readonly query: (handlerQn: string, payload: unknown) => Promise<unknown>;
+  // System user with "system" plus exactly these roles, no SystemAdmin.
+  readonly writeAs: (
+    roles: readonly string[],
+    handlerQn: string,
+    payload: unknown,
+  ) => Promise<unknown>;
 };
 
 // `body` is whatever the client sent; validate it with a zod schema's parse(),
@@ -311,6 +317,11 @@ export function createE2eSeedRoutesWith(
             handlerQn,
             await deps.dispatchSystemWrite({ handlerQn, payload, tenantId }),
           ),
+        writeAs: async (roles, handlerQn, payload) =>
+          unwrapWriteData(
+            handlerQn,
+            await deps.dispatchWriteAs({ handlerQn, payload, tenantId, roles }),
+          ),
         query: (handlerQn, payload) => deps.dispatchSystemQuery({ handlerQn, payload, tenantId }),
       };
       try {