@cosmicdrift/kumiko-testing 0.295.0

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

@@ -0,0 +1,152 @@
+import { randomUUID } from "node:crypto";
+import { cpus } from "node:os";
+import {
+  defineConfig,
+  devices,
+  type PlaywrightTestConfig,
+  type PlaywrightTestOptions,
+  type PlaywrightWorkerOptions,
+  type Project,
+} from "@playwright/test";
+import {
+  E2E_WORKERS_ENV,
+  PLAYWRIGHT_DEMO_ENV,
+  REAL_PROVIDERS_ENV,
+  SEED_ENABLE_ENV,
+  SEED_TOKEN_ENV,
+} from "./constants";
+import { screenshotSpecsIgnore } from "./screenshot-dir";
+import { E2E_TIMEOUT_MS } from "./timeouts";
+
+const TEMPLATE_OWNED_PROJECT_KEYS = [
+  "fullyParallel",
+  "retries",
+  "timeout",
+  "workers",
+  "expect",
+] as const;
+const TEMPLATE_OWNED_USE_KEYS = ["actionTimeout", "navigationTimeout"] as const;
+const REAL_SPEC_GLOB = "**/*.real.spec.ts";
+const RESERVED_ENV_KEYS = ["PORT", SEED_ENABLE_ENV, SEED_TOKEN_ENV] as const;
+
+type ProjectUse = Partial<PlaywrightTestOptions & PlaywrightWorkerOptions>;
+
+export type E2eProject = Omit<Project, (typeof TEMPLATE_OWNED_PROJECT_KEYS)[number] | "use"> & {
+  readonly use?: Omit<ProjectUse, (typeof TEMPLATE_OWNED_USE_KEYS)[number]>;
+};
+
+export type AppE2eConfigInput = {
+  readonly port: number;
+  readonly env?: Readonly<Record<string, string>>;
+  readonly locale?: string;
+  readonly projects?: readonly E2eProject[];
+  readonly serverEntry?: string;
+  readonly testDir?: string;
+  readonly testMatch?: string | RegExp | readonly (string | RegExp)[];
+};
+
+function mutableTestMatch(
+  match: NonNullable<AppE2eConfigInput["testMatch"]>,
+): string | RegExp | (string | RegExp)[] {
+  return typeof match === "string" || match instanceof RegExp ? match : [...match];
+}
+
+export function resolveE2eWorkers(
+  env: Readonly<Record<string, string | undefined>> = process.env,
+  cpuCount: number = cpus().length,
+): number {
+  const override = env[E2E_WORKERS_ENV];
+  if (override === undefined || override === "") {
+    return Math.max(2, Math.min(4, Math.floor(cpuCount / 2)));
+  }
+  const workers = Number(override);
+  if (!Number.isInteger(workers) || workers < 1) {
+    throw new Error(`${E2E_WORKERS_ENV} must be a positive integer, got "${override}"`);
+  }
+  return workers;
+}
+
+function assertTemplateOwnedKeysUnset(project: E2eProject): void {
+  const name = project.name ?? "(unnamed)";
+  const setKeys: readonly string[] = Object.keys(project);
+  const useKeys: readonly string[] = Object.keys(project.use ?? {});
+  const offending = [
+    ...TEMPLATE_OWNED_PROJECT_KEYS.filter((key) => setKeys.includes(key)),
+    ...TEMPLATE_OWNED_USE_KEYS.filter((key) => useKeys.includes(key)).map((key) => `use.${key}`),
+  ];
+  if (offending.length > 0) {
+    throw new Error(
+      `defineAppE2eConfig: project "${name}" sets ${offending.join(", ")}; timeouts, retries and workers belong to the template. Diagnose per docs/guides/test-failures.md instead of raising them.`,
+    );
+  }
+}
+
+function assertNoReservedEnv(env: Readonly<Record<string, string>>): void {
+  const reserved = RESERVED_ENV_KEYS.filter((key) => key in env);
+  if (reserved.length > 0) {
+    throw new Error(
+      `defineAppE2eConfig: env must not set ${reserved.join(", ")}; the template owns them.`,
+    );
+  }
+}
+
+// Workers re-evaluate this config but inherit the runner's env, so ??= keeps one token per run.
+function seedTokenForRun(): string {
+  process.env[SEED_TOKEN_ENV] ??= randomUUID();
+  return process.env[SEED_TOKEN_ENV];
+}
+
+export function defineAppE2eConfig(input: AppE2eConfigInput): PlaywrightTestConfig {
+  const {
+    port,
+    env = {},
+    locale = "en",
+    projects = [],
+    serverEntry = "e2e/server.ts",
+    testDir = "./e2e",
+    testMatch,
+  } = input;
+  assertNoReservedEnv(env);
+  for (const project of projects) assertTemplateOwnedKeysUnset(project);
+  const baseURL = `http://localhost:${port}`;
+  const realRun = process.env[REAL_PROVIDERS_ENV] === "1";
+
+  return defineConfig({
+    testDir,
+    ...(realRun
+      ? { testMatch: REAL_SPEC_GLOB }
+      : testMatch !== undefined && { testMatch: mutableTestMatch(testMatch) }),
+    testIgnore: [...screenshotSpecsIgnore(), ...(realRun ? [] : [REAL_SPEC_GLOB])],
+    fullyParallel: true,
+    forbidOnly: !!process.env["CI"],
+    retries: 0,
+    workers: resolveE2eWorkers(),
+    reporter: [["list"]],
+    timeout: E2E_TIMEOUT_MS.test,
+    expect: { timeout: E2E_TIMEOUT_MS.expect },
+    use: {
+      baseURL,
+      locale,
+      trace: "retain-on-failure",
+      screenshot: "only-on-failure",
+      actionTimeout: E2E_TIMEOUT_MS.action,
+      navigationTimeout: E2E_TIMEOUT_MS.navigation,
+    },
+    projects: [{ name: "chromium", use: { ...devices["Desktop Chrome"] } }, ...projects],
+    webServer: {
+      command: `bun run ${serverEntry}`,
+      url: baseURL,
+      env: {
+        ...PLAYWRIGHT_DEMO_ENV,
+        ...env,
+        PORT: String(port),
+        [SEED_ENABLE_ENV]: "1",
+        [SEED_TOKEN_ENV]: seedTokenForRun(),
+      },
+      reuseExistingServer: false,
+      timeout: E2E_TIMEOUT_MS.webServer,
+      stdout: "pipe",
+      stderr: "pipe",
+    },
+  });
+}

package/src/e2e/index.ts

@@ -0,0 +1,56 @@
+export { expect } from "@playwright/test";
+export {
+  apiCommand,
+  apiQuery,
+  apiWrite,
+  createHttpApi,
+  csrfFetch,
+  csrfHeaderFromCookies,
+  type LoginCredentials,
+  loginViaApi,
+  loginViaUi,
+  totpCode,
+} from "./auth-kit";
+export {
+  CSRF_COOKIE_NAME,
+  CSRF_HEADER_NAME,
+  E2E_WORKERS_ENV,
+  KUMIKO_SECRETS_MASTER_KEY_V1,
+  PLAYWRIGHT_DEMO_ENV,
+  SEED_ENABLE_ENV,
+  SEED_TOKEN_ENV,
+} from "./constants";
+export {
+  type AppE2eConfigInput,
+  defineAppE2eConfig,
+  type E2eProject,
+  resolveE2eWorkers,
+} from "./define-app-e2e-config";
+export { mailCapture } from "./mail-capture";
+export { pinEnglishLocale } from "./pin-english-locale";
+export { pollForRow, waitForProjection } from "./poll";
+export {
+  requireScreenshotDir,
+  SCREENSHOT_DIR_ENV,
+  screenshotSpecsIgnore,
+} from "./screenshot-dir";
+export {
+  applyDefaultTheme,
+  DEFAULT_THEMES,
+  type DefaultThemeId,
+  type FlatOptions,
+  findIdenticalThemeScreenshots,
+  type MatrixOptions,
+  runMatrix,
+  runScreenshots,
+  type Scenario,
+  type ThemeScreenshotDigest,
+  validateScenarios,
+} from "./screenshots";
+export type { CapturedMail } from "./seed-contract";
+export {
+  type E2eSeededTenant,
+  type E2eSeedTenantOptions,
+  test,
+} from "./seeded-tenant-fixture";
+export { E2E_TIMEOUT_MS } from "./timeouts";

package/src/e2e/mail-capture.ts

@@ -0,0 +1,43 @@
+import type { APIRequestContext } from "@playwright/test";
+import { SEED_ROUTES, SEED_TOKEN_ENV, SEED_TOKEN_HEADER } from "./constants";
+import { waitForProjection } from "./poll";
+import { type CapturedMail, inboxResponseSchema } from "./seed-contract";
+
+export function seedRouteHeaders(): Record<string, string> {
+  const token = process.env[SEED_TOKEN_ENV];
+  if (token === undefined || token === "") {
+    throw new Error(
+      `${SEED_TOKEN_ENV} is not set; build the Playwright config with defineAppE2eConfig`,
+    );
+  }
+  return { [SEED_TOKEN_HEADER]: token };
+}
+
+async function readInbox(
+  request: APIRequestContext,
+  tenantId: string,
+  to: string,
+): Promise<readonly CapturedMail[]> {
+  const response = await request.get(SEED_ROUTES.inbox, {
+    headers: seedRouteHeaders(),
+    params: { tenantId, to },
+  });
+  if (!response.ok()) {
+    throw new Error(
+      `mailCapture: GET ${SEED_ROUTES.inbox} -> ${response.status()} ${await response.text()}`,
+    );
+  }
+  return inboxResponseSchema.parse(await response.json()).messages;
+}
+
+export function mailCapture(
+  request: APIRequestContext,
+  tenantId: string,
+  to: string,
+): Promise<readonly CapturedMail[]> {
+  return waitForProjection(
+    () => readInbox(request, tenantId, to),
+    (messages) => messages.length > 0,
+    `mailCapture: no mail arrived for ${to} in tenant ${tenantId}`,
+  );
+}

package/src/e2e/pin-english-locale.ts

@@ -0,0 +1,14 @@
+import type { Page } from "@playwright/test";
+
+const STORAGE_KEY = "kumiko:locale";
+
+/** Docs screenshots are EN-only — call before the first navigation. */
+export async function pinEnglishLocale(page: Page): Promise<void> {
+  await page.addInitScript((key: string) => {
+    try {
+      localStorage.setItem(key, "en");
+    } catch {
+      // Safari private mode etc. — Playwright locale still applies.
+    }
+  }, STORAGE_KEY);
+}

package/src/e2e/poll.ts

@@ -0,0 +1,39 @@
+import { expect } from "@playwright/test";
+import type { BoundApi } from "../seed-types";
+import { E2E_TIMEOUT_MS } from "./timeouts";
+
+export async function waitForProjection<T>(
+  read: () => Promise<T>,
+  isReady: (value: T) => boolean,
+  message = "waitForProjection: condition never became true",
+): Promise<T> {
+  let ready: { readonly value: T } | undefined;
+  await expect
+    .poll(
+      async () => {
+        const value = await read();
+        if (isReady(value)) ready = { value };
+        return ready !== undefined;
+      },
+      { message, timeout: E2E_TIMEOUT_MS.poll },
+    )
+    .toBe(true);
+  if (ready === undefined) throw new Error(message);
+  return ready.value;
+}
+
+export async function pollForRow<TRow extends { readonly id: string } = { readonly id: string }>(
+  api: Pick<BoundApi, "queryOk">,
+  queryType: string,
+  predicate: (row: TRow) => boolean,
+  payload: unknown = {},
+): Promise<TRow> {
+  const rows = await waitForProjection(
+    async () => (await api.queryOk<{ readonly rows: readonly TRow[] }>(queryType, payload)).rows,
+    (candidates) => candidates.some(predicate),
+    `pollForRow: no row of "${queryType}" matched the predicate`,
+  );
+  const row = rows.find(predicate);
+  if (row === undefined) throw new Error(`pollForRow: no row of "${queryType}" matched`);
+  return row;
+}

package/src/e2e/screenshot-dir.ts

@@ -0,0 +1,28 @@
+export const SCREENSHOT_DIR_ENV = "SCREENSHOT_DIR";
+
+const NORMAL_RUN_IGNORE: readonly string[] = [
+  "**/screenshots.spec.ts",
+  "**/*.screenshots.spec.ts",
+  "**/screenshots/**",
+];
+
+type Env = Readonly<Record<string, string | undefined>>;
+
+function isScreenshotRun(env: Env): boolean {
+  const dir = env[SCREENSHOT_DIR_ENV];
+  return dir !== undefined && dir !== "";
+}
+
+export function requireScreenshotDir(env: Env = process.env): string {
+  const dir = env[SCREENSHOT_DIR_ENV];
+  if (dir === undefined || dir === "") {
+    throw new Error(
+      `${SCREENSHOT_DIR_ENV} is required for screenshot runs: set it to the directory the PNGs are written to (e.g. ${SCREENSHOT_DIR_ENV}=$(mktemp -d)). There is deliberately no default, because a default path would overwrite the committed docs images on every run.`,
+    );
+  }
+  return dir;
+}
+
+export function screenshotSpecsIgnore(env: Env = process.env): string[] {
+  return isScreenshotRun(env) ? [] : [...NORMAL_RUN_IGNORE];
+}

package/src/e2e/screenshots.ts

@@ -0,0 +1,312 @@
+import { createHash } from "node:crypto";
+import { mkdirSync, statSync } from "node:fs";
+import { expect, type Page, type Request, test } from "@playwright/test";
+import { pinEnglishLocale } from "./pin-english-locale";
+import { requireScreenshotDir } from "./screenshot-dir";
+
+// runScreenshots: one image per scenario → $SCREENSHOT_DIR/<name>.png.
+// runMatrix: every scenario × locale × theme × viewport in ONE run →
+//   $SCREENSHOT_DIR/<name>/<locale>/<theme>/<viewport>.png (feeds the preview switcher).
+//
+// Both are registrars: call at the spec's module top, do NOT await — otherwise
+// they register test() only after Playwright's collection pass (0 tests).
+// SCREENSHOT_DIR is read when a registrar runs, never at import time.
+
+const MIN_BYTES = 5 * 1024;
+
+// The two themes every sample app renders out of the box: renderer-web's
+// light default and its `.dark` variant. Apps with extra themes (styleguide's
+// brand-token override) pass their own pair to runMatrix.
+export const DEFAULT_THEMES = ["default-light", "default-dark"] as const;
+export type DefaultThemeId = (typeof DEFAULT_THEMES)[number];
+
+export async function applyDefaultTheme(page: Page, theme: DefaultThemeId): Promise<void> {
+  await page.evaluate((t) => {
+    document.documentElement.classList.toggle("dark", t === "default-dark");
+  }, theme);
+}
+
+export interface Scenario {
+  readonly name: string;
+  readonly description?: string;
+  readonly url?: string;
+  readonly flow?: (page: Page) => Promise<void>;
+  readonly waitFor?: string;
+  readonly fullPage?: boolean;
+  readonly viewport?: { readonly width: number; readonly height: number };
+  // runMatrix only: opt out of the identical-theme-screenshot check for
+  // scenarios that legitimately render the same pixels across themes — e.g.
+  // a plain server-rendered content page with no client-side theme wiring.
+  readonly themeInvariant?: boolean;
+}
+
+// EventSource (hot-reload, live events) has its own resource type, so a
+// never-ending stream does not count as an in-flight data request.
+const DATA_REQUEST_TYPES: ReadonlySet<string> = new Set(["fetch", "xhr"]);
+const STABLE_POLLS = 2;
+
+function countInFlightDataRequests(page: Page): () => number {
+  const inFlight = new Set<Request>();
+  const settle = (request: Request): void => {
+    inFlight.delete(request);
+  };
+  page.on("request", (request) => {
+    if (DATA_REQUEST_TYPES.has(request.resourceType())) inFlight.add(request);
+  });
+  page.on("requestfinished", settle);
+  page.on("requestfailed", settle);
+  return () => inFlight.size;
+}
+
+function pageFingerprint(): string {
+  return [
+    document.fonts.status,
+    document.documentElement.scrollWidth,
+    document.documentElement.scrollHeight,
+    document.body.getElementsByTagName("*").length,
+    document.getAnimations().filter((animation) => animation.playState === "running").length,
+  ].join(":");
+}
+
+// Replaces fixed sleeps: settled = no data request in flight and an unchanged
+// DOM/scroll-size/animation fingerprint over STABLE_POLLS consecutive polls.
+async function waitForSettledPage(page: Page, inFlightDataRequests: () => number): Promise<void> {
+  let previous: string | undefined;
+  let stablePolls = 0;
+  await expect
+    .poll(
+      async () => {
+        const current = await page.evaluate(pageFingerprint);
+        stablePolls = current === previous && inFlightDataRequests() === 0 ? stablePolls + 1 : 0;
+        previous = current;
+        return stablePolls;
+      },
+      {
+        message: "page never settled (data requests in flight or DOM still changing)",
+        intervals: [100],
+      },
+    )
+    .toBeGreaterThanOrEqual(STABLE_POLLS);
+}
+
+async function openScenario(
+  page: Page,
+  s: Scenario,
+  inFlightDataRequests: () => number,
+): Promise<void> {
+  if (s.flow) await s.flow(page);
+  else if (s.url) await page.goto(s.url);
+  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 });
+  }
+  await waitForSettledPage(page, inFlightDataRequests);
+}
+
+export interface FlatOptions {
+  readonly pinLocale?: boolean;
+}
+
+// Fail at registration time, not mid-run: a url-only scenario with no
+// waitFor races the page's own render (screenshot fires before content
+// settles); a scenario with neither url nor flow throws inside openScenario
+// anyway, but only once Playwright actually runs that test — catching it
+// here surfaces every broken scenario in one pass instead of one per run.
+export function validateScenarios(scenarios: readonly Scenario[]): void {
+  for (const s of scenarios) {
+    if (s.flow === undefined && s.url === undefined) {
+      throw new Error(`Scenario "${s.name}" needs either url or flow`);
+    }
+    if (s.flow === undefined && s.waitFor === undefined) {
+      throw new Error(
+        `Scenario "${s.name}" uses url without waitFor — the screenshot would race the page's ` +
+          `own render. Set waitFor to a selector that's only present once the page is ready.`,
+      );
+    }
+  }
+}
+
+export function runScreenshots(scenarios: readonly Scenario[], opts: FlatOptions = {}): void {
+  validateScenarios(scenarios);
+  const outDir = requireScreenshotDir();
+  mkdirSync(outDir, { recursive: true });
+  // Scoped in its own describe so `test.use` below can't leak the pinned
+  // locale into sibling test.describe blocks in the same spec file.
+  test.describe(() => {
+    // Browser-context locale for JS-side Intl/navigator.language (e.g. money-input's
+    // resolvedLocale) — pinEnglishLocale() only seeds the app's own kumiko:locale.
+    // ponytail: native <input type="number"> still formats per the host OS region,
+    // unreachable from Playwright (context.locale and --lang both no-op there). #1851
+    if (opts.pinLocale) test.use({ locale: "en-US" });
+    for (const s of scenarios) {
+      test(s.description ? `${s.name} — ${s.description}` : s.name, async ({ page }) => {
+        if (opts.pinLocale) await pinEnglishLocale(page);
+        const inFlightDataRequests = countInFlightDataRequests(page);
+        if (s.viewport) await page.setViewportSize(s.viewport);
+        await openScenario(page, s, inFlightDataRequests);
+        const path = `${outDir}/${s.name}.png`;
+        await page.screenshot({ path, fullPage: s.fullPage ?? false });
+        expect.soft(statSync(path).size).toBeGreaterThan(MIN_BYTES);
+      });
+    }
+  });
+}
+
+const VIEWPORT_IDS = ["desktop", "tablet", "mobile"] as const;
+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 },
+  // Landscape: portrait tablet shots collapsed two-column layouts into the mobile stack.
+  tablet: { width: 1112, height: 834 },
+  mobile: { width: 390, height: 844 },
+};
+
+// Narrow the axis from env (CSV) or take the default. Filters instead of
+// casting: a typo in the env var (e.g. SCREENSHOT_VIEWPORTS=typo) would
+// otherwise either crash at runtime (page.setViewportSize(undefined)) or,
+// worse, silently produce wrong screenshots (applyTheme with an unknown
+// theme value just toggles nothing).
+function axis<T extends string>(env: string | undefined, all: readonly T[]): readonly T[] {
+  const picked = env
+    ?.split(",")
+    .map((s) => s.trim())
+    .filter(Boolean);
+  if (!picked || picked.length === 0) return all;
+  // ponytail: filter-instead-of-cast — unknown values are silently ignored
+  const known = new Set<string>(all);
+  const matched = picked.filter((p): p is T => known.has(p));
+  if (matched.length === 0) {
+    throw new Error(
+      `axis(): env filter "${env}" matched none of [${all.join(", ")}] — 0 registered tests.`,
+    );
+  }
+  return matched;
+}
+
+export interface MatrixOptions<T extends string> {
+  readonly themes: readonly T[];
+  readonly applyTheme: (page: Page, theme: T) => Promise<void>;
+  readonly locales?: readonly string[];
+}
+
+// App locale codes ("en"/"de") -> BCP47 tags for Playwright's browser-context
+// `locale` option, pinning JS-side Intl/navigator.language regardless of the
+// host's own locale — without it, a screenshot regen on a non-en-US host bakes
+// in the host's Intl-driven formatting regardless of SCREENSHOT_LOCALES.
+const LOCALE_TAGS: Readonly<Record<string, string>> = { en: "en-US", de: "de-DE" };
+
+export interface ThemeScreenshotDigest<T extends string> {
+  readonly viewport: string;
+  readonly theme: T;
+  readonly hash: string;
+}
+
+// Catches a renamed CSS class or an overridden theme provider that leaves every
+// theme rendering identically — MIN_BYTES alone can't (a valid PNG is a valid
+// PNG regardless of which theme produced it). Keyed by viewport so a failure
+// names the exact viewport and colliding theme pair, not just the scenario.
+export function findIdenticalThemeScreenshots<T extends string>(
+  digests: readonly ThemeScreenshotDigest<T>[],
+): string[] {
+  const seenByViewport = new Map<string, Map<string, T>>();
+  const violations: string[] = [];
+  for (const { viewport, theme, hash } of digests) {
+    let seenHashes = seenByViewport.get(viewport);
+    if (seenHashes === undefined) {
+      seenHashes = new Map();
+      seenByViewport.set(viewport, seenHashes);
+    }
+    const collidingTheme = seenHashes.get(hash);
+    if (collidingTheme !== undefined) {
+      violations.push(
+        `viewport "${viewport}": themes "${collidingTheme}" and "${theme}" produced byte-identical screenshots`,
+      );
+    } else {
+      seenHashes.set(hash, theme);
+    }
+  }
+  return violations;
+}
+
+export function runMatrix<T extends string>(
+  scenarios: readonly Scenario[],
+  opts: MatrixOptions<T>,
+): void {
+  validateScenarios(scenarios);
+
+  const baseDir = requireScreenshotDir();
+  const locales = axis(process.env["SCREENSHOT_LOCALES"], opts.locales ?? ["en", "de"]);
+  const themes = axis(process.env["SCREENSHOT_THEMES"], opts.themes);
+  const viewports = axis(process.env["SCREENSHOT_VIEWPORTS"], VIEWPORT_IDS);
+  const only = process.env["SCREENSHOT_ONLY"];
+
+  for (const locale of locales) {
+    test.describe(locale, () => {
+      // Browser-context locale for JS-side Intl/navigator.language — the
+      // kumiko:locale seed below only drives the app's own i18n strings.
+      // ponytail: see the runScreenshots() locale comment above / #1851
+      const tag = LOCALE_TAGS[locale];
+      if (tag === undefined) {
+        throw new Error(
+          `runMatrix(): no BCP47 tag mapped for locale "${locale}" — extend LOCALE_TAGS`,
+        );
+      }
+      test.use({ locale: tag });
+
+      for (const s of scenarios) {
+        if (only !== undefined && only !== s.name) continue;
+        test(s.name, async ({ page }) => {
+          // kumiko:locale drives the boot-time language (before goto); kumiko:theme
+          // is cleared so the mode is decided solely by applyTheme.
+          await page.addInitScript((lng) => {
+            localStorage.setItem("kumiko:locale", lng);
+            localStorage.removeItem("kumiko:theme");
+          }, locale);
+          const inFlightDataRequests = countInFlightDataRequests(page);
+          await openScenario(page, s, inFlightDataRequests);
+
+          const digests: ThemeScreenshotDigest<T>[] = [];
+
+          for (const theme of themes) {
+            await opts.applyTheme(page, theme);
+            for (const vp of viewports) {
+              await page.setViewportSize(VIEWPORTS[vp]);
+              await waitForSettledPage(page, inFlightDataRequests);
+              const dir = `${baseDir}/${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({
+                path,
+                fullPage: s.fullPage ?? false,
+                animations: "disabled",
+              });
+              expect.soft(buffer.length).toBeGreaterThan(MIN_BYTES);
+              digests.push({
+                viewport: vp,
+                theme,
+                hash: createHash("sha256").update(buffer).digest("hex"),
+              });
+            }
+          }
+
+          if (!s.themeInvariant) {
+            expect
+              .soft(
+                findIdenticalThemeScreenshots(digests),
+                `scenario "${s.name}" (${locale}): theme switch produced no visual difference`,
+              )
+              .toEqual([]);
+          }
+        });
+      }
+    });
+  }
+}