@cosmicdrift/kumiko-testing 0.371.0 → 0.372.0

package/README.md

@@ -49,6 +49,12 @@ test("member sees the note", async ({ seedTenant, page }) => {
 
 - `defineAppE2eConfig({ port, env?, locale?, projects?, serverEntry?, testDir?, testMatch? })`: parallelism, retries, timeouts and
   workers (`KUMIKO_E2E_WORKERS` overrides) are fixed by the template; projects cannot set them.
+- `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`;
+  timeouts, viewport and DPR stay with the template. The seed routes do not exist on such a target, so use
+  it for specs that only need an existing session. Trace, screenshot and video are off there, because a trace zip holds the target's session cookie and data. `csrfFetch` handles the `__Host-` prefixed csrf cookie
+  an https target sets.
 - 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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-testing",
-  "version": "0.371.0",
+  "version": "0.372.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>",
@@ -95,8 +95,8 @@
     "kumiko-testing": "./bin/kumiko-testing.ts"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-framework": "0.371.0",
-    "@cosmicdrift/kumiko-types": "0.371.0",
+    "@cosmicdrift/kumiko-framework": "0.372.0",
+    "@cosmicdrift/kumiko-types": "0.372.0",
     "zod": "^4.4.3"
   },
   "peerDependencies": {
@@ -128,8 +128,8 @@
     }
   },
   "devDependencies": {
-    "@cosmicdrift/kumiko-bundled-features": "0.371.0",
-    "@cosmicdrift/kumiko-dev-server": "0.371.0",
+    "@cosmicdrift/kumiko-bundled-features": "0.372.0",
+    "@cosmicdrift/kumiko-dev-server": "0.372.0",
     "@happy-dom/global-registrator": "^20.11.2",
     "@playwright/test": "^1.62.1",
     "@testing-library/dom": "^10.4.1",

package/src/changes.json

@@ -1,4 +1,10 @@
 [
+  {
+    "version": "0.372.0",
+    "type": "improvement",
+    "title": "defineAppE2eConfig runs against a remote instance via KUMIKO_E2E_REMOTE_BASE_URL; csrfFetch handles the __Host- csrf cookie",
+    "detail": "KUMIKO_E2E_STORAGE_STATE supplies a recorded session. Without the remote env nothing changes."
+  },
   {
     "version": "0.371.0",
     "type": "improvement",

package/src/e2e/auth-kit.ts

@@ -5,7 +5,7 @@ import type { WriteErrorInfo } from "@cosmicdrift/kumiko-framework/errors";
 import { type APIRequestContext, type APIResponse, expect, type Page } from "@playwright/test";
 import * as z from "zod";
 import type { BoundApi } from "../seed-types";
-import { CSRF_COOKIE_NAME, CSRF_HEADER_NAME } from "./constants";
+import { CSRF_COOKIE_NAMES, CSRF_HEADER_NAME } from "./constants";
 
 export type LoginCredentials = {
   readonly email: string;
@@ -37,8 +37,11 @@ const errorEnvelope = z.looseObject({ error: z.looseObject({ code: z.string() })
 export function csrfHeaderFromCookies(
   cookies: readonly { readonly name: string; readonly value: string }[],
 ): Record<string, string> {
-  const token = cookies.find((cookie) => cookie.name === CSRF_COOKIE_NAME)?.value;
-  return token === undefined ? {} : { [CSRF_HEADER_NAME]: token };
+  for (const name of CSRF_COOKIE_NAMES) {
+    const token = cookies.find((cookie) => cookie.name === name)?.value;
+    if (token !== undefined) return { [CSRF_HEADER_NAME]: token };
+  }
+  return {};
 }
 
 export async function csrfFetch(

package/src/e2e/constants.ts

@@ -1,4 +1,8 @@
-import { CSRF_COOKIE_BASE, sessionCookieName } from "@cosmicdrift/kumiko-types/session-cookies";
+import {
+  CSRF_COOKIE_BASE,
+  sessionCookieName,
+  sessionCookieNameCandidates,
+} from "@cosmicdrift/kumiko-types/session-cookies";
 
 export const KUMIKO_SECRETS_MASTER_KEY_V1 = "a3VtaWtvLXNjcmVlbnNob3QtZGV2LW1hc3Rlci0zMmI=";
 
@@ -11,6 +15,9 @@ export const PLAYWRIGHT_DEMO_ENV = {
 
 // e2e servers run on plain http, so the cookies are never Secure and keep the unprefixed names.
 export const CSRF_COOKIE_NAME = sessionCookieName(CSRF_COOKIE_BASE, { secure: false });
+// Against a remote https target the server sets the `__Host-` prefixed cookie, so reading a csrf
+// cookie has to try both names, prefixed first.
+export const CSRF_COOKIE_NAMES = sessionCookieNameCandidates(CSRF_COOKIE_BASE);
 export const CSRF_HEADER_NAME = "X-CSRF-Token";
 
 // Duplicated from kumiko-framework (SEED_MODE_ENV): the Playwright config runs under Node
@@ -19,6 +26,8 @@ export const SEED_ENABLE_ENV = "KUMIKO_TEST_SEED";
 export const SEED_TOKEN_ENV = "KUMIKO_TEST_SEED_TOKEN";
 export const SEED_TOKEN_HEADER = "x-kumiko-test-seed";
 export const E2E_WORKERS_ENV = "KUMIKO_E2E_WORKERS";
+export const E2E_REMOTE_BASE_URL_ENV = "KUMIKO_E2E_REMOTE_BASE_URL";
+export const E2E_STORAGE_STATE_ENV = "KUMIKO_E2E_STORAGE_STATE";
 
 // Same literal as kumiko-dev-server's createKumikoServer (STYLESHEET_WATCH_ENV),
 // duplicated because the Playwright config runs under Node and can't import

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

@@ -17,6 +17,8 @@ import { isRealProviderRun } from "../helpers/real-providers.ts";
 import { SERVICE_ENV_DEFAULTS } from "../preload/service-env-defaults-values";
 import {
   DESKTOP_VIEWPORT,
+  E2E_REMOTE_BASE_URL_ENV,
+  E2E_STORAGE_STATE_ENV,
   E2E_WORKERS_ENV,
   PLAYWRIGHT_DEMO_ENV,
   PROD_BUNDLES_ENV,
@@ -187,6 +189,50 @@ function seedTokenForRun(): string {
   return process.env[SEED_TOKEN_ENV];
 }
 
+type RemoteTarget = { readonly baseURL: string; readonly storageState: string | undefined };
+
+// A set KUMIKO_E2E_REMOTE_BASE_URL points the run at an already running instance (staging, prod)
+// instead of a locally started server. The session comes from a Playwright storageState file the
+// operator recorded, so no login is automated against the remote.
+function remoteTargetFromEnv(
+  env: Readonly<Record<string, string | undefined>>,
+): RemoteTarget | undefined {
+  const rawBaseUrl = env[E2E_REMOTE_BASE_URL_ENV];
+  const storageState = env[E2E_STORAGE_STATE_ENV];
+  const hasStorageState = storageState !== undefined && storageState !== "";
+  if (rawBaseUrl === undefined || rawBaseUrl === "") {
+    if (hasStorageState) {
+      throw new Error(
+        `defineAppE2eConfig: ${E2E_STORAGE_STATE_ENV} is only used together with ${E2E_REMOTE_BASE_URL_ENV}`,
+      );
+    }
+    return undefined;
+  }
+  let url: URL;
+  try {
+    url = new URL(rawBaseUrl);
+  } catch {
+    throw new Error(
+      `defineAppE2eConfig: ${E2E_REMOTE_BASE_URL_ENV} must be an http(s) URL, got "${rawBaseUrl}"`,
+    );
+  }
+  if (url.protocol !== "http:" && url.protocol !== "https:") {
+    throw new Error(
+      `defineAppE2eConfig: ${E2E_REMOTE_BASE_URL_ENV} must be an http(s) URL, got "${rawBaseUrl}"`,
+    );
+  }
+  return { baseURL: rawBaseUrl, storageState: hasStorageState ? storageState : undefined };
+}
+
+// A remote target is a real deployment: trace zips hold its session cookie and data, and a
+// failure screenshot or video shows them, so nothing is recorded there.
+function failureRecording(
+  remote: RemoteTarget | undefined,
+): Pick<NonNullable<PlaywrightTestConfig["use"]>, "trace" | "screenshot" | "video"> {
+  if (remote === undefined) return { trace: "retain-on-failure", screenshot: "only-on-failure" };
+  return { trace: "off", screenshot: "off", video: "off" };
+}
+
 export function defineAppE2eConfig(input: AppE2eConfigInput): PlaywrightTestConfig {
   const {
     port,
@@ -208,7 +254,8 @@ export function defineAppE2eConfig(input: AppE2eConfigInput): PlaywrightTestConf
   if (!isScreenshotRun() && /(?:^|\/)screenshots\/?$/.test(testDir)) {
     requireScreenshotDir();
   }
-  const baseURL = `http://localhost:${port}`;
+  const remote = remoteTargetFromEnv(process.env);
+  const baseURL = remote?.baseURL ?? `http://localhost:${port}`;
   const realRun = isRealProviderRun();
 
   return defineConfig({
@@ -227,10 +274,10 @@ export function defineAppE2eConfig(input: AppE2eConfigInput): PlaywrightTestConf
     use: {
       baseURL,
       locale,
-      trace: "retain-on-failure",
-      screenshot: "only-on-failure",
+      ...failureRecording(remote),
       actionTimeout: E2E_TIMEOUT_MS.action,
       navigationTimeout: E2E_TIMEOUT_MS.navigation,
+      ...(remote?.storageState !== undefined && { storageState: remote.storageState }),
       ...(permissions !== undefined && { permissions: [...permissions] }),
       ...(launchOptions !== undefined && { launchOptions }),
     },
@@ -245,36 +292,38 @@ export function defineAppE2eConfig(input: AppE2eConfigInput): PlaywrightTestConf
       },
       ...projects,
     ],
-    webServer: {
-      command: serverCommand,
-      url: baseURL,
-      env: {
-        ...infraEnvDefaults(),
-        ...PLAYWRIGHT_DEMO_ENV,
-        ...env,
-        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",
-        // E2E runs against prod-shaped bundles: splitting, no sourcemap,
-        // NODE_ENV=production — matches what actually ships.
-        [PROD_BUNDLES_ENV]: "1",
-        // 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. 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",
+    ...(remote === undefined && {
+      webServer: {
+        command: serverCommand,
+        url: baseURL,
+        env: {
+          ...infraEnvDefaults(),
+          ...PLAYWRIGHT_DEMO_ENV,
+          ...env,
+          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",
+          // E2E runs against prod-shaped bundles: splitting, no sourcemap,
+          // NODE_ENV=production — matches what actually ships.
+          [PROD_BUNDLES_ENV]: "1",
+          // 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. 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,
+        timeout: E2E_TIMEOUT_MS.webServer,
+        stdout: "pipe",
+        stderr: "pipe",
       },
-      reuseExistingServer: false,
-      timeout: E2E_TIMEOUT_MS.webServer,
-      stdout: "pipe",
-      stderr: "pipe",
-    },
+    }),
   });
 }

package/src/helpers/observability-recorder.ts

@@ -15,7 +15,7 @@ import {
 export type RecordingProvider = ObservabilityProvider & {
   readonly spans: readonly RecordedSpan[];
   readonly metricEvents: readonly MetricEvent[];
-  // Returns spans filtered by name — handy for `.find(s => s.name === "http.request")`.
+  // Returns spans filtered by name — handy for `.find(s => s.name === "POST /api/write")`.
   spansByName(name: string): readonly RecordedSpan[];
   // All spans sharing a trace id — use this to reconstruct a single request's tree.
   spansByTraceId(traceId: string): readonly RecordedSpan[];

package/src/helpers/seed.ts

@@ -44,6 +44,6 @@ export function updateRows<TRow = unknown>(
   return updateMany<TRow>(db, table as EntityTableMeta, set, where);
 }
 
-export function deleteRows(db: AnyDb, table: SeedTable, where: WhereObject): Promise<void> {
+export function deleteRows(db: AnyDb, table: SeedTable, where: WhereObject): Promise<number> {
   return deleteMany(db, table as EntityTableMeta, where);
 }

package/src/stack/request-helper.ts

@@ -1,6 +1,6 @@
 // @runtime dev
 import type { JwtHelper, SessionCreator } from "@cosmicdrift/kumiko-framework/api";
-import type { SessionUser } from "@cosmicdrift/kumiko-framework/engine";
+import { type SessionUser, SYSTEM_ROLE } from "@cosmicdrift/kumiko-framework/engine";
 import type { Hono } from "hono";
 
 export type BatchCommand = { type: string; payload: unknown };
@@ -132,6 +132,11 @@ export function createRequestHelper(
   const sidByUserKey = new Map<string, Promise<string>>();
 
   async function authHeader(user: SessionUser): Promise<Record<string, string>> {
+    if (user.roles.includes(SYSTEM_ROLE)) {
+      throw new Error(
+        "system identity is in-process only: JWT verify strips the system role; use stack.dispatcher.write/query",
+      );
+    }
     let forJwt = user;
     if (options.sessionCreator && !user.sid) {
       const key = `${user.id}:${user.tenantId}`;

package/src/stack/test-stack.ts

@@ -368,8 +368,10 @@ export async function setupTestStack(options: TestStackOptions): Promise<TestSta
     // exist before the first upload. Skipped when no provider — the table
     // stays off tenant test DBs that never touch files.
     if (options.files) {
-      const { fileRefsTable } = await import("@cosmicdrift/kumiko-framework/files");
-      await unsafePushTables(testDb.db, { fileRefsTable });
+      const { fileRefsTable, fileUploadLedgerTable } = await import(
+        "@cosmicdrift/kumiko-framework/files"
+      );
+      await unsafePushTables(testDb.db, { fileRefsTable, fileUploadLedgerTable });
     }
 
     // Same table list as `kumiko schema generate` (collectTableMetas) — divergence
@@ -444,7 +446,8 @@ export async function setupTestStack(options: TestStackOptions): Promise<TestSta
     | undefined;
   if (options.files) {
     const provider = options.files.storageProvider;
-    fileProviderResolver = () => Promise.resolve(provider);
+    const { withUploadLedger } = await import("@cosmicdrift/kumiko-framework/files");
+    fileProviderResolver = withUploadLedger(() => Promise.resolve(provider), testDb.db);
   }
 
   const observability = options.observability ?? createNoopProvider();