@cosmicdrift/kumiko-testing 0.299.0 → 0.305.0

package/README.md

@@ -44,6 +44,9 @@ test("member sees the note", async ({ seedTenant, page }) => {
   workers (`KUMIKO_E2E_WORKERS` overrides) are fixed by the template; projects cannot set them.
 - The seed routes answer only with `KUMIKO_TEST_SEED=1`, outside `NODE_ENV=production`, and with the
   per-run `KUMIKO_TEST_SEED_TOKEN` in the `x-kumiko-test-seed` header. `defineAppE2eConfig` sets all three.
+- The template also sets `KUMIKO_DEV_STYLESHEET_WATCH=0`, so the dev-server builds the app's CSS once and
+  never starts a Tailwind `--watch` process — that watcher would otherwise treat every Playwright artifact
+  write under `test-results/` as a rebuild trigger.
 - App roles: `createE2eSeedRoutes({ extraRoles: ["TenantMember"] })` lets `tenant.addUser(["TenantMember"])` seed them;
   `SystemAdmin` is never seedable and makes the route builder throw.
 - A `SeedPart` receives `{ tenant }` and works against the in-process `seedTenant` and the HTTP tenant alike.
@@ -52,6 +55,26 @@ test("member sees the note", async ({ seedTenant, page }) => {
   when the seed condition holds: `...(isE2eSeedingEnabled() ? createE2eSeedRoutes() : [])` in its own
   `extraRoutes` — prod then never registers the routes at all, not just a per-request 404.
   `isE2eSeedingEnabled` is exported from `@cosmicdrift/kumiko-testing/e2e/seed-route`.
-- App-wide defaults after tenant creation (e.g. a completed onboarding) belong in a `postSave` hook on
-  the `"tenant"` entity (`r.hook("postSave", { allOf: "tenant" }, ...)`), fired via
-  `seedTenant(db, options, { registry, context })` — not in `seedTenant()` itself, which stays a blank tenant.
+- App-wide defaults for tests (e.g. a completed onboarding) belong in a `SeedPart` passed to
+  `seedTenant({ with: [defaults] })` — never in a `postSave` hook on the `"tenant"` entity, since that
+  hook also fires on every real signup in prod.
+
+## Screenshots (`./e2e`)
+
+`runScreenshots`/`runMatrix` register their tests on the same `test` as above, so a scenario's `flow`
+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]!);
+    await page.goto("/dispatch");
+  },
+  beforeCapture: async (page) => page.addStyleTag({ content: ".live-clock { visibility: hidden }" }),
+}
+```
+
+`beforeCapture?: (page) => Promise<void>` runs after the viewport is set and the page has settled,
+right before the screenshot. `runMatrix` calls it once per theme × viewport for the same scenario, so
+it must be idempotent — hide or mask an element rather than a one-shot action like clicking a button,
+which would only succeed on the first capture and time out on every one after.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-testing",
-  "version": "0.299.0",
+  "version": "0.305.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.299.0",
-    "@cosmicdrift/kumiko-dev-server": "0.299.0",
-    "@cosmicdrift/kumiko-framework": "0.299.0",
+    "@cosmicdrift/kumiko-bundled-features": "0.305.0",
+    "@cosmicdrift/kumiko-dev-server": "0.305.0",
+    "@cosmicdrift/kumiko-framework": "0.305.0",
     "zod": "^4.4.3"
   },
   "peerDependencies": {

package/src/changes.json

@@ -1,4 +1,16 @@
 [
+  {
+    "version": "0.305.0",
+    "type": "fix",
+    "title": "defineAppE2eConfig starts the E2E web server without a Tailwind --watch process, so Playwright artifact writes no longer trigger hundreds of CSS rebuilds",
+    "detail": "`defineAppE2eConfig` sets `KUMIKO_DEV_STYLESHEET_WATCH=0`, so the dev-server it boots builds CSS once and stops instead of keeping a Tailwind `--watch` process alive. Tailwind v4's watcher subscribes to the whole app cwd recursively with no gitignore filter, so every Playwright artifact write under `test-results/` previously counted as a rebuild trigger."
+  },
+  {
+    "version": "0.304.0",
+    "type": "improvement",
+    "title": "Screenshot scenarios get { seedTenant } in flow and a beforeCapture hook; the README no longer recommends a postSave hook on tenant for test defaults",
+    "detail": "`runScreenshots`/`runMatrix` register their tests on the same `test` as `@cosmicdrift/kumiko-testing/e2e`'s seeded-tenant fixture, so `Scenario.flow` now receives `(page, { seedTenant })` — existing single-parameter `flow(page)` scenarios keep working unchanged. `Scenario.beforeCapture?: (page) => Promise<void>` runs after the viewport is set and the page has settled, right before each screenshot. `seedTenant()`'s \"no baseURL\" error now only fires when a scenario actually calls it, not for every screenshot spec's fixture setup."
+  },
   {
     "version": "0.299.0",
     "type": "fix",

package/src/e2e/constants.ts

@@ -18,6 +18,11 @@ export const E2E_WORKERS_ENV = "KUMIKO_E2E_WORKERS";
 // Same literal as the framework's requireRealProviders(), which does not export it.
 export const REAL_PROVIDERS_ENV = "KUMIKO_REAL_PROVIDERS";
 
+// Same literal as kumiko-dev-server's createKumikoServer (STYLESHEET_WATCH_ENV),
+// duplicated because the Playwright config runs under Node and can't import
+// that Bun-toolchain-adjacent module.
+export const STYLESHEET_WATCH_ENV = "KUMIKO_DEV_STYLESHEET_WATCH";
+
 export const SEED_ROUTE_PREFIX = "/__test";
 
 export const SEED_ROUTES = {

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

@@ -14,6 +14,7 @@ import {
   REAL_PROVIDERS_ENV,
   SEED_ENABLE_ENV,
   SEED_TOKEN_ENV,
+  STYLESHEET_WATCH_ENV,
 } from "./constants";
 import { screenshotSpecsIgnore } from "./screenshot-dir";
 import { E2E_TIMEOUT_MS } from "./timeouts";
@@ -27,7 +28,7 @@ const TEMPLATE_OWNED_PROJECT_KEYS = [
 ] 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;
+const RESERVED_ENV_KEYS = ["PORT", SEED_ENABLE_ENV, SEED_TOKEN_ENV, STYLESHEET_WATCH_ENV] as const;
 
 type ProjectUse = Partial<PlaywrightTestOptions & PlaywrightWorkerOptions>;
 
@@ -142,6 +143,10 @@ export function defineAppE2eConfig(input: AppE2eConfigInput): PlaywrightTestConf
         PORT: String(port),
         [SEED_ENABLE_ENV]: "1",
         [SEED_TOKEN_ENV]: seedTokenForRun(),
+        // A Tailwind --watch process subscribes to the whole app cwd
+        // recursively (Tailwind v4, no gitignore filter); every Playwright
+        // artifact write under test-results/ would then count as a rebuild.
+        [STYLESHEET_WATCH_ENV]: "0",
       },
       reuseExistingServer: false,
       timeout: E2E_TIMEOUT_MS.webServer,

package/src/e2e/index.ts

@@ -51,6 +51,7 @@ export type { CapturedMail } from "./seed-contract";
 export {
   type E2eSeededTenant,
   type E2eSeedTenantOptions,
+  type SeedTenantFixture,
   test,
 } from "./seeded-tenant-fixture";
 export { E2E_TIMEOUT_MS } from "./timeouts";

package/src/e2e/screenshots.ts

@@ -1,8 +1,9 @@
 import { createHash } from "node:crypto";
 import { mkdirSync, statSync } from "node:fs";
-import { expect, type Page, type Request, test } from "@playwright/test";
+import { expect, type Page, type Request } from "@playwright/test";
 import { pinEnglishLocale } from "./pin-english-locale";
 import { requireScreenshotDir } from "./screenshot-dir";
+import { type SeedTenantFixture, test } from "./seeded-tenant-fixture";
 
 // runScreenshots: one image per scenario → $SCREENSHOT_DIR/<name>.png.
 // runMatrix: every scenario × locale × theme × viewport in ONE run →
@@ -30,10 +31,16 @@ export interface Scenario {
   readonly name: string;
   readonly description?: string;
   readonly url?: string;
-  readonly flow?: (page: Page) => Promise<void>;
+  readonly flow?: (page: Page, fixtures: { seedTenant: SeedTenantFixture }) => Promise<void>;
   readonly waitFor?: string;
   readonly fullPage?: boolean;
   readonly viewport?: { readonly width: number; readonly height: number };
+  // Runs after the viewport is set and the page has settled, right before the
+  // screenshot. runMatrix calls this once per theme × viewport combination for
+  // the scenario — it must be idempotent (e.g. hide/mask an element) rather
+  // than a one-shot action like clicking a dismiss button, which would only
+  // succeed on the first capture and time out on every one after.
+  readonly beforeCapture?: (page: Page) => Promise<void>;
   // 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.
@@ -93,8 +100,9 @@ async function openScenario(
   page: Page,
   s: Scenario,
   inFlightDataRequests: () => number,
+  fixtures: { seedTenant: SeedTenantFixture },
 ): Promise<void> {
-  if (s.flow) await s.flow(page);
+  if (s.flow) await s.flow(page, fixtures);
   else if (s.url) await page.goto(s.url);
   else throw new Error(`Scenario "${s.name}" needs either url or flow`);
 
@@ -140,15 +148,19 @@ export function runScreenshots(scenarios: readonly Scenario[], opts: FlatOptions
     // 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);
-      });
+      test(
+        s.description ? `${s.name} — ${s.description}` : s.name,
+        async ({ page, seedTenant }) => {
+          if (opts.pinLocale) await pinEnglishLocale(page);
+          const inFlightDataRequests = countInFlightDataRequests(page);
+          if (s.viewport) await page.setViewportSize(s.viewport);
+          await openScenario(page, s, inFlightDataRequests, { seedTenant });
+          if (s.beforeCapture) await s.beforeCapture(page);
+          const path = `${outDir}/${s.name}.png`;
+          await page.screenshot({ path, fullPage: s.fullPage ?? false });
+          expect.soft(statSync(path).size).toBeGreaterThan(MIN_BYTES);
+        },
+      );
     }
   });
 }
@@ -260,7 +272,7 @@ export function runMatrix<T extends string>(
 
       for (const s of scenarios) {
         if (only !== undefined && only !== s.name) continue;
-        test(s.name, async ({ page }) => {
+        test(s.name, async ({ page, seedTenant }) => {
           // 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) => {
@@ -268,7 +280,7 @@ export function runMatrix<T extends string>(
             localStorage.removeItem("kumiko:theme");
           }, locale);
           const inFlightDataRequests = countInFlightDataRequests(page);
-          await openScenario(page, s, inFlightDataRequests);
+          await openScenario(page, s, inFlightDataRequests, { seedTenant });
 
           const digests: ThemeScreenshotDigest<T>[] = [];
 
@@ -277,6 +289,7 @@ export function runMatrix<T extends string>(
             for (const vp of viewports) {
               await page.setViewportSize(VIEWPORTS[vp]);
               await waitForSettledPage(page, inFlightDataRequests);
+              if (s.beforeCapture) await s.beforeCapture(page);
               const dir = `${baseDir}/${s.name}/${locale}/${theme}`;
               mkdirSync(dir, { recursive: true });
               const path = `${dir}/${vp}.png`;

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

@@ -1,5 +1,12 @@
 import { ROLES } from "@cosmicdrift/kumiko-framework/auth";
-import { type APIRequestContext, test as base, type Page } from "@playwright/test";
+import {
+  type APIRequestContext,
+  test as base,
+  type Page,
+  type PlaywrightTestArgs,
+  type PlaywrightTestOptions,
+  type PlaywrightWorkerArgs,
+} from "@playwright/test";
 import type { z } from "zod";
 import {
   type BoundApi,
@@ -24,10 +31,20 @@ export type E2eSeededTenant = SeededTenant & {
   readonly loginAs: (page: Page, user: SeededUser) => Promise<void>;
 };
 
+export type SeedTenantFixture = (opts?: E2eSeedTenantOptions) => Promise<E2eSeededTenant>;
+
 type E2eFixtures = {
-  seedTenant: (opts?: E2eSeedTenantOptions) => Promise<E2eSeededTenant>;
+  seedTenant: SeedTenantFixture;
 };
 
+// Narrowed to the four fixtures the body below actually reads, so a unit
+// test can drive it with plain stubs instead of a full Playwright run.
+export type ProvideSeedTenantDeps = Pick<
+  PlaywrightTestArgs & PlaywrightWorkerArgs,
+  "request" | "context" | "playwright"
+> &
+  Pick<PlaywrightTestOptions, "baseURL">;
+
 async function postSeedRoute<S extends z.ZodType>(
   request: APIRequestContext,
   path: string,
@@ -41,83 +58,90 @@ async function postSeedRoute<S extends z.ZodType>(
   return schema.parse(await response.json());
 }
 
-export const test = base.extend<E2eFixtures>({
-  seedTenant: async ({ request, context, playwright, baseURL }, use) => {
-    if (baseURL === undefined) throw new Error("seedTenant: the Playwright config has no baseURL");
-    const openedContexts: APIRequestContext[] = [];
-    const apiByUserId = new Map<string, BoundApi>();
-
-    // One cookie jar per user: two tenants (or admin + member) in one test must not clobber each other's session.
-    const openLoggedInApi = async (user: SeededUser): Promise<BoundApi> => {
-      const ctx = await playwright.request.newContext({ baseURL });
-      openedContexts.push(ctx);
-      await loginViaApi(ctx, user);
-      return createHttpApi(ctx);
-    };
+export async function provideSeedTenant(
+  { request, context, playwright, baseURL }: ProvideSeedTenantDeps,
+  use: (fixture: SeedTenantFixture) => Promise<void>,
+): Promise<void> {
+  const openedContexts: APIRequestContext[] = [];
+  const apiByUserId = new Map<string, BoundApi>();
 
-    const httpApiFor = (user: SeededUser): BoundApi => {
-      const cached = apiByUserId.get(user.id);
-      if (cached !== undefined) return cached;
-      let opened: Promise<BoundApi> | undefined;
-      const bound = (): Promise<BoundApi> => {
-        opened ??= openLoggedInApi(user);
-        return opened;
-      };
-      const api: BoundApi = {
-        writeOk: async (type, payload, requestId) =>
-          (await bound()).writeOk(type, payload, requestId),
-        writeErr: async (type, payload) => (await bound()).writeErr(type, payload),
-        queryOk: async (type, payload) => (await bound()).queryOk(type, payload),
-        queryErr: async (type, payload) => (await bound()).queryErr(type, payload),
-      };
-      apiByUserId.set(user.id, api);
-      return api;
-    };
+  // One cookie jar per user: two tenants (or admin + member) in one test must not clobber each other's session.
+  const openLoggedInApi = async (user: SeededUser): Promise<BoundApi> => {
+    const ctx = await playwright.request.newContext({ baseURL });
+    openedContexts.push(ctx);
+    await loginViaApi(ctx, user);
+    return createHttpApi(ctx);
+  };
 
-    const loginAs = async (page: Page, user: SeededUser): Promise<void> => {
-      await page.context().clearCookies();
-      await loginViaApi(page.context().request, user);
+  const httpApiFor = (user: SeededUser): BoundApi => {
+    const cached = apiByUserId.get(user.id);
+    if (cached !== undefined) return cached;
+    let opened: Promise<BoundApi> | undefined;
+    const bound = (): Promise<BoundApi> => {
+      opened ??= openLoggedInApi(user);
+      return opened;
+    };
+    const api: BoundApi = {
+      writeOk: async (type, payload, requestId) =>
+        (await bound()).writeOk(type, payload, requestId),
+      writeErr: async (type, payload) => (await bound()).writeErr(type, payload),
+      queryOk: async (type, payload) => (await bound()).queryOk(type, payload),
+      queryErr: async (type, payload) => (await bound()).queryErr(type, payload),
     };
+    apiByUserId.set(user.id, api);
+    return api;
+  };
 
-    await use(async (opts = {}) => {
-      const seeded = await postSeedRoute(
-        request,
-        SEED_ROUTES.seedTenant,
-        { name: opts.name, members: opts.users },
-        seedTenantResponseSchema,
-      );
-      const tenantId = seeded.id;
-      const toUser = (credentials: SeededCredentials, roles: readonly string[]): SeededUser =>
-        withSession(credentials, tenantId, roles);
-
-      const admin = toUser(seeded.admin, [ROLES.TenantAdmin]);
-      await loginViaApi(context.request, admin);
-
-      const tenant: E2eSeededTenant = {
-        id: tenantId,
-        key: seeded.key,
-        name: seeded.name,
-        admin,
-        members: seeded.members.map((member) => toUser(member, [ROLES.Member])),
-        addUser: async (roles = [ROLES.Member]) =>
-          toUser(
-            await postSeedRoute(
-              request,
-              SEED_ROUTES.seedUser,
-              { tenantId, roles: [...roles] } satisfies SeedUserRequest,
-              seedUserResponseSchema,
-            ),
-            roles,
+  const loginAs = async (page: Page, user: SeededUser): Promise<void> => {
+    await page.context().clearCookies();
+    await loginViaApi(page.context().request, user);
+  };
+
+  await use(async (opts = {}) => {
+    if (baseURL === undefined) {
+      throw new Error("seedTenant: the Playwright config has no baseURL");
+    }
+    const seeded = await postSeedRoute(
+      request,
+      SEED_ROUTES.seedTenant,
+      { name: opts.name, members: opts.users },
+      seedTenantResponseSchema,
+    );
+    const tenantId = seeded.id;
+    const toUser = (credentials: SeededCredentials, roles: readonly string[]): SeededUser =>
+      withSession(credentials, tenantId, roles);
+
+    const admin = toUser(seeded.admin, [ROLES.TenantAdmin]);
+    await loginViaApi(context.request, admin);
+
+    const tenant: E2eSeededTenant = {
+      id: tenantId,
+      key: seeded.key,
+      name: seeded.name,
+      admin,
+      members: seeded.members.map((member) => toUser(member, [ROLES.Member])),
+      addUser: async (roles = [ROLES.Member]) =>
+        toUser(
+          await postSeedRoute(
+            request,
+            SEED_ROUTES.seedUser,
+            { tenantId, roles: [...roles] } satisfies SeedUserRequest,
+            seedUserResponseSchema,
           ),
-        api: httpApiFor(admin),
-        apiAs: httpApiFor,
-        loginAs,
-      };
+          roles,
+        ),
+      api: httpApiFor(admin),
+      apiAs: httpApiFor,
+      loginAs,
+    };
 
-      for (const part of opts.with ?? []) await part({ tenant });
-      return tenant;
-    });
+    for (const part of opts.with ?? []) await part({ tenant });
+    return tenant;
+  });
 
-    await Promise.all(openedContexts.map((ctx) => ctx.dispose()));
-  },
+  await Promise.all(openedContexts.map((ctx) => ctx.dispose()));
+}
+
+export const test = base.extend<E2eFixtures>({
+  seedTenant: provideSeedTenant,
 });

package/src/preload/ci-log.ts

@@ -1,2 +1,2 @@
 // biome-ignore-all lint/suspicious/noConsole: the preload exists to print this line.
-console.log("[kumiko-test] CI profile active — config=bunfig.ci.toml concurrency=1");
+console.log("[kumiko-test] CI profile active — config=bunfig.ci.toml");