@cosmicdrift/kumiko-testing 0.369.0 → 0.371.0

package/package.json

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

package/src/bunfig.ts

@@ -1,5 +1,8 @@
+// @runtime tooling
+// Pure TOML rendering with no test-stack imports: dev-server's managed-files
+// sync renders and merges app bunfigs with it outside of any test run.
 import { isPlainObject } from "@cosmicdrift/kumiko-types/type-guards";
-import { E2E_TIMEOUT_MS } from "./e2e-timeouts";
+import { E2E_TIMEOUT_MS } from "./e2e-timeouts.ts";
 
 export const TEST_TIMEOUT_MS = {
   unit: 5000,

package/src/changes.json

@@ -1,4 +1,28 @@
 [
+  {
+    "version": "0.371.0",
+    "type": "improvement",
+    "title": "Scaffold test:dom passes without test files",
+    "detail": "The scaffold sets test:dom to pass without test files and adds the devDependencies @testing-library/react, @testing-library/dom and @happy-dom/global-registrator."
+  },
+  {
+    "version": "0.370.0",
+    "type": "improvement",
+    "title": "setupTestStack binds the MFA token secrets",
+    "detail": "setupTestStack binds the auth-mfa token secrets from the stack's JWT secret, independent of the host env, so tests that mount auth-mfa without explicit secrets keep working."
+  },
+  {
+    "version": "0.370.0",
+    "type": "improvement",
+    "title": "renderTestSetup writes the standard test scripts, bunfig.dom.toml and the helper homes",
+    "detail": "The scaffolded test setup now adds test:unit, test:integration:ci, test:dom and screenshots, writes bunfig.dom.toml (with @happy-dom/global-registrator as devDependency), e2e/_helpers/index.ts and src/__tests__/_setup.ts."
+  },
+  {
+    "version": "0.370.0",
+    "type": "improvement",
+    "title": "createTestStoredEvent builds a StoredEvent fixture",
+    "detail": "createTestStoredEvent(overrides) from @cosmicdrift/kumiko-testing/helpers returns a complete StoredEvent with stable defaults, for hook tests that construct SaveContext or DeleteContext directly."
+  },
   {
     "version": "0.365.0",
     "type": "fix",

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

@@ -13,7 +13,7 @@ import {
   type Project,
 } from "@playwright/test";
 import { E2E_TIMEOUT_MS } from "../e2e-timeouts";
-import { isRealProviderRun } from "../helpers/real-providers.js";
+import { isRealProviderRun } from "../helpers/real-providers.ts";
 import { SERVICE_ENV_DEFAULTS } from "../preload/service-env-defaults-values";
 import {
   DESKTOP_VIEWPORT,

package/src/e2e/index.ts

@@ -4,7 +4,7 @@ export {
   isRealProviderRun,
   REAL_PROVIDERS_ENV,
   requireRealProviders,
-} from "../helpers/real-providers.js";
+} from "../helpers/real-providers.ts";
 export {
   apiCommand,
   apiQuery,

package/src/e2e/screenshots.ts

@@ -3,7 +3,7 @@ import { mkdirSync, statSync } from "node:fs";
 import { dirname } from "node:path";
 import { expect, type Page, errors as playwrightErrors, type Request } from "@playwright/test";
 import { E2E_TIMEOUT_MS } from "../e2e-timeouts";
-import { isRealProviderRun } from "../helpers/real-providers.js";
+import { isRealProviderRun } from "../helpers/real-providers.ts";
 import { DESKTOP_VIEWPORT } from "./constants";
 import { pinEnglishLocale } from "./pin-english-locale";
 import { requireScreenshotDir, SCREENSHOT_DIR_ENV } from "./screenshot-dir";

package/src/helpers/closed-connection-error.ts

@@ -3,7 +3,7 @@
 
 import { isClosedConnectionError } from "@cosmicdrift/kumiko-framework/internal/stack-support";
 import postgres from "postgres";
-import { requireEnv } from "../stack/db.js";
+import { requireEnv } from "../stack/db.ts";
 
 export function testDatabaseUrl(): string {
   return requireEnv("TEST_DATABASE_URL");

package/src/helpers/index.ts

@@ -14,45 +14,45 @@ export {
   resetPiiSubjectKmsForTests,
 } from "@cosmicdrift/kumiko-framework/internal/testing";
 
-export { rolesOf } from "./access-assertions.js";
-export { expectError, expectSuccess } from "./assertions.js";
-export { withBootValidatorFixture } from "./boot-validator-fixture.js";
+export { rolesOf } from "./access-assertions.ts";
+export { expectError, expectSuccess } from "./assertions.ts";
+export { withBootValidatorFixture } from "./boot-validator-fixture.ts";
 export {
   captureClosedConnectionError,
   terminateBackendsByApplicationName,
   testDatabaseUrl,
-} from "./closed-connection-error.js";
-export { type ClearableTable, clearTables, resetTestTables } from "./db-cleanup.js";
+} from "./closed-connection-error.ts";
+export { type ClearableTable, clearTables, resetTestTables } from "./db-cleanup.ts";
 export {
   type E2EGeneratorOptions,
   type E2ETestSpec,
   type EditFillOp,
   generateE2ESpec,
   generateZodFixture,
-} from "./e2e-generator.js";
-export { expectErrorIncludes } from "./expect-error.js";
-export { describeFileProviderContract } from "./file-provider-contract.js";
+} from "./e2e-generator.ts";
+export { expectErrorIncludes } from "./expect-error.ts";
+export { describeFileProviderContract } from "./file-provider-contract.ts";
 export {
   getSetCookieRaw,
   getSetCookies,
   getSetCookieValue,
   type ParsedSetCookie,
-} from "./http-cookies.js";
-export { createLateBoundHolder, type LateBoundHolder } from "./late-bound.js";
-export { createManualClock, type ManualClock } from "./manual-clock.js";
-export { buildMultipartBody, patchFileInstanceofForBunTest } from "./multipart-helper.js";
+} from "./http-cookies.ts";
+export { createLateBoundHolder, type LateBoundHolder } from "./late-bound.ts";
+export { createManualClock, type ManualClock } from "./manual-clock.ts";
+export { buildMultipartBody, patchFileInstanceofForBunTest } from "./multipart-helper.ts";
 export {
   createMutableMasterKeyProvider,
   createTestEnvelopeCipher,
   createTestMasterKeyProvider,
   type MutableMasterKeyProvider,
-} from "./mutable-master-key-provider.js";
+} from "./mutable-master-key-provider.ts";
 export {
   createRecordingProvider,
   type RecordingProvider,
-} from "./observability-recorder.js";
-export { isRealProviderRun, REAL_PROVIDERS_ENV, requireRealProviders } from "./real-providers.js";
-export { deleteRows, seedRow, seedRows, updateRows } from "./seed.js";
+} from "./observability-recorder.ts";
+export { isRealProviderRun, REAL_PROVIDERS_ENV, requireRealProviders } from "./real-providers.ts";
+export { deleteRows, seedRow, seedRows, updateRows } from "./seed.ts";
 export {
   sharedItemEntity,
   sharedItemTable,
@@ -60,8 +60,9 @@ export {
   sharedUserTable,
   sharedWidgetEntity,
   sharedWidgetTable,
-} from "./shared-entities.js";
-export { sleep } from "./utils.js";
-export { waitFor } from "./wait-for.js";
-export { withoutAmbientTemporal } from "./without-ambient-temporal.js";
-export { zipWithEntries } from "./zip-fixture.js";
+} from "./shared-entities.ts";
+export { createTestStoredEvent } from "./stored-event-fixture.ts";
+export { sleep } from "./utils.ts";
+export { waitFor } from "./wait-for.ts";
+export { withoutAmbientTemporal } from "./without-ambient-temporal.ts";
+export { zipWithEntries } from "./zip-fixture.ts";

package/src/helpers/stored-event-fixture.ts

@@ -0,0 +1,20 @@
+import type { StoredEvent } from "@cosmicdrift/kumiko-types/event-store-types";
+
+// SaveContext and DeleteContext always carry the event that produced them, so a
+// hand-built context in a hook test needs one too.
+export function createTestStoredEvent(overrides: Partial<StoredEvent> = {}): StoredEvent {
+  return {
+    id: "test-event-1",
+    aggregateId: "test-aggregate-1",
+    aggregateType: "test-aggregate",
+    tenantId: "test-tenant-1",
+    version: 1,
+    type: "test:event:saved",
+    eventVersion: 1,
+    payload: {},
+    metadata: { userId: "test-user-1" },
+    createdAt: Temporal.Instant.from("2026-01-01T00:00:00Z"),
+    createdBy: "test-user-1",
+    ...overrides,
+  };
+}

package/src/preload/real.ts

@@ -1,4 +1,4 @@
-import { requireRealProviders } from "../helpers/real-providers.js";
+import { requireRealProviders } from "../helpers/real-providers.ts";
 import "./schema-env-defaults";
 import "./service-env-defaults";
 

package/src/scaffold.ts

@@ -1,6 +1,6 @@
 // @runtime tooling
 import { BUNFIG_FILES, renderBunfigFiles, TEST_TIMEOUT_MS } from "./bunfig";
-import { REAL_PROVIDERS_ENV } from "./helpers/real-providers.js";
+import { REAL_PROVIDERS_ENV } from "./helpers/real-providers";
 
 export type ScaffoldTestSetup = {
   readonly files: Readonly<Record<string, string>>;
@@ -21,6 +21,10 @@ export const SCAFFOLD_E2E_PORT = 4174;
 export const SCAFFOLD_INTEGRATION_PARALLEL = 4;
 
 const PLAYWRIGHT_VERSION = "^1.62.1";
+// bunfig.dom.toml preloads kumiko-testing's dom preload, which registers happy-dom.
+const HAPPY_DOM_VERSION = "^20.11.2";
+const TESTING_LIBRARY_REACT_VERSION = "^16.3.2";
+const TESTING_LIBRARY_DOM_VERSION = "^10.4.1";
 
 const TEST_RUNTIME_DIRECTIVE = "// @runtime test";
 
@@ -81,22 +85,8 @@ function renderE2eServer(appName: string): string {
 function renderE2eSmokeSpec(): string {
   return [
     TEST_RUNTIME_DIRECTIVE,
-    'import type { SeedPart } from "@cosmicdrift/kumiko-testing";',
     'import { expect, test } from "@cosmicdrift/kumiko-testing/e2e";',
-    'import type { Page } from "@playwright/test";',
-    "",
-    `const TASK_CREATE = ${JSON.stringify(TASK_CREATE)};`,
-    "",
-    "function withTask(title: string): SeedPart {",
-    "  return async ({ tenant }) => {",
-    '    await tenant.api.writeOk(TASK_CREATE, { title, status: "todo", priority: 1 });',
-    "  };",
-    "}",
-    "",
-    "async function openTasks(page: Page): Promise<void> {",
-    '  await page.goto("/");',
-    '  await page.getByRole("link", { name: "Tasks" }).first().click();',
-    "}",
+    'import { openTasks, withTask } from "./_helpers";',
     "",
     'test("a seeded task shows up on the tasks screen", async ({ seedTenant, page }) => {',
     '  const tenant = await seedTenant({ with: [withTask("Water the plants")] });',
@@ -117,6 +107,41 @@ function renderE2eSmokeSpec(): string {
   ].join("\n");
 }
 
+function renderE2eHelpers(): string {
+  return [
+    TEST_RUNTIME_DIRECTIVE,
+    'import type { SeedPart } from "@cosmicdrift/kumiko-testing";',
+    'import type { Page } from "@playwright/test";',
+    "",
+    `const TASK_CREATE = ${JSON.stringify(TASK_CREATE)};`,
+    "",
+    "export function withTask(title: string): SeedPart {",
+    "  return async ({ tenant }) => {",
+    '    await tenant.api.writeOk(TASK_CREATE, { title, status: "todo", priority: 1 });',
+    "  };",
+    "}",
+    "",
+    "export async function openTasks(page: Page): Promise<void> {",
+    '  await page.goto("/");',
+    '  await page.getByRole("link", { name: "Tasks" }).first().click();',
+    "}",
+    "",
+  ].join("\n");
+}
+
+function renderIntegrationSetup(): string {
+  return [
+    'import { setupAppTestStack } from "@cosmicdrift/kumiko-testing";',
+    'import type { TestStack } from "@cosmicdrift/kumiko-testing/stack";',
+    'import { tasksFeature } from "../features/tasks";',
+    "",
+    "export function setupTasksStack(): Promise<TestStack> {",
+    "  return setupAppTestStack([tasksFeature]);",
+    "}",
+    "",
+  ].join("\n");
+}
+
 function renderUnitTest(): string {
   return [
     'import { describe, expect, test } from "bun:test";',
@@ -140,9 +165,9 @@ function renderUnitTest(): string {
 function renderIntegrationTest(): string {
   return [
     'import { afterAll, beforeAll, describe, expect, test } from "bun:test";',
-    'import { seedTenant, setupAppTestStack } from "@cosmicdrift/kumiko-testing";',
+    'import { seedTenant } from "@cosmicdrift/kumiko-testing";',
     'import type { TestStack } from "@cosmicdrift/kumiko-testing/stack";',
-    'import { tasksFeature } from "../features/tasks";',
+    'import { setupTasksStack } from "./_setup";',
     "",
     `const TASK_CREATE = ${JSON.stringify(TASK_CREATE)};`,
     `const TASK_LIST = ${JSON.stringify(TASK_LIST)};`,
@@ -152,7 +177,7 @@ function renderIntegrationTest(): string {
     "let stack: TestStack;",
     "",
     "beforeAll(async () => {",
-    "  stack = await setupAppTestStack([tasksFeature]);",
+    "  stack = await setupTasksStack();",
     "});",
     "",
     "afterAll(async () => {",
@@ -178,18 +203,25 @@ function renderIntegrationTest(): string {
 
 export function renderTestSetup(input: RenderTestSetupInput): ScaffoldTestSetup {
   const { appName, frameworkVersion, port = SCAFFOLD_E2E_PORT } = input;
+  const unitTestScript = `bun --config=${BUNFIG_FILES.unit} test --timeout=${TEST_TIMEOUT_MS.unit} --dots`;
+  const integrationTestScript = `bun kumiko-testing integration --parallel ${SCAFFOLD_INTEGRATION_PARALLEL}`;
   return {
     files: {
-      ...renderBunfigFiles({ install: { linker: "hoisted" } }),
+      ...renderBunfigFiles({ install: { linker: "hoisted" }, dom: true }),
       "playwright.config.ts": renderPlaywrightConfig(port),
+      "e2e/_helpers/index.ts": renderE2eHelpers(),
       "e2e/server.ts": renderE2eServer(appName),
       "e2e/smoke.spec.ts": renderE2eSmokeSpec(),
+      "src/__tests__/_setup.ts": renderIntegrationSetup(),
       "src/__tests__/run-config.test.ts": renderUnitTest(),
       "src/__tests__/tasks.integration.test.ts": renderIntegrationTest(),
     },
     scripts: {
-      test: `bun --config=${BUNFIG_FILES.unit} test --timeout=${TEST_TIMEOUT_MS.unit} --dots`,
-      "test:integration": `bun kumiko-testing integration --parallel ${SCAFFOLD_INTEGRATION_PARALLEL}`,
+      test: unitTestScript,
+      "test:unit": unitTestScript,
+      "test:integration": integrationTestScript,
+      "test:integration:ci": integrationTestScript,
+      "test:dom": `bun --config=${BUNFIG_FILES.dom} test --timeout=${TEST_TIMEOUT_MS.unit} --dots --pass-with-no-tests .test.tsx`,
       // bunfig.real.toml's pathIgnorePatterns can only blacklist (no "!" negation,
       // verified against bun 1.4), so it can't express "match only *.real.test.ts"
       // on its own — every *.test.ts file matches bun's default test glob too,
@@ -201,10 +233,14 @@ export function renderTestSetup(input: RenderTestSetupInput): ScaffoldTestSetup
       "test:bunfig": "bun kumiko-testing bunfig --hoisted",
       e2e: "bunx --bun playwright test",
       "e2e:real": `${REAL_PROVIDERS_ENV}=1 bunx --bun playwright test`,
+      screenshots: "SCREENSHOT_DIR=docs/screenshots bunx --bun playwright test",
     },
     devDependencies: {
       "@cosmicdrift/kumiko-testing": frameworkVersion,
+      "@happy-dom/global-registrator": HAPPY_DOM_VERSION,
       "@playwright/test": PLAYWRIGHT_VERSION,
+      "@testing-library/dom": TESTING_LIBRARY_DOM_VERSION,
+      "@testing-library/react": TESTING_LIBRARY_REACT_VERSION,
     },
     rulesMarkdown: RULES_MARKDOWN,
   };

package/src/seed-tenant.ts

@@ -20,7 +20,7 @@ import {
   splitSeedRoles,
   withSession,
 } from "./seed-types";
-import type { TestStack } from "./stack/index.js";
+import type { TestStack } from "./stack/index.ts";
 
 export type {
   BoundApi,

package/src/setup-app-test-stack.ts

@@ -3,7 +3,7 @@ import {
   setupTestStackFromFeatures,
 } from "@cosmicdrift/kumiko-dev-server/setup-test-stack-from-features";
 import type { FeatureDefinition } from "@cosmicdrift/kumiko-framework/engine";
-import { pushEntityProjectionTables, type TestStack } from "./stack/index.js";
+import { pushEntityProjectionTables, type TestStack } from "./stack/index.ts";
 
 export type SetupAppTestStackOptions = SetupTestStackFromFeaturesOptions & {
   readonly registryTables?: boolean;

package/src/stack/drain-event-consumers.ts

@@ -5,7 +5,7 @@ import {
   type ConsumerRecoveryState,
   getConsumerState,
 } from "@cosmicdrift/kumiko-framework/pipeline";
-import type { TestStack } from "./test-stack.js";
+import type { TestStack } from "./test-stack.ts";
 
 const DEFAULT_MAX_PASSES = 25;
 

package/src/stack/index.ts

@@ -18,11 +18,11 @@ export {
   type CreateTestDbOptions,
   createTestDb,
   type TestDb,
-} from "./db.js";
-export { drainEventConsumers } from "./drain-event-consumers.js";
-export { createEventCollector, type EventCollector } from "./event-collector.js";
-export { pushEntityProjectionTables } from "./push-entity-projection-tables.js";
-export { createTestRedis, type TestRedis } from "./redis.js";
-export { createRequestHelper, type RequestHelper } from "./request-helper.js";
-export { resetEventStore } from "./table-helpers.js";
-export { setupTestStack, type TestStack, type TestStackOptions } from "./test-stack.js";
+} from "./db.ts";
+export { drainEventConsumers } from "./drain-event-consumers.ts";
+export { createEventCollector, type EventCollector } from "./event-collector.ts";
+export { pushEntityProjectionTables } from "./push-entity-projection-tables.ts";
+export { createTestRedis, type TestRedis } from "./redis.ts";
+export { createRequestHelper, type RequestHelper } from "./request-helper.ts";
+export { resetEventStore } from "./table-helpers.ts";
+export { setupTestStack, type TestStack, type TestStackOptions } from "./test-stack.ts";

package/src/stack/redis.ts

@@ -1,6 +1,6 @@
 // @runtime dev
 import { generateId } from "@cosmicdrift/kumiko-framework/utils";
-import { requireEnv } from "./db.js";
+import { requireEnv } from "./db.ts";
 
 export type TestRedis = {
   redis: import("ioredis").Redis;

package/src/stack/test-stack.ts

@@ -50,11 +50,11 @@ import type { SearchAdapter } from "@cosmicdrift/kumiko-framework/search";
 import { createInMemorySearchAdapter } from "@cosmicdrift/kumiko-framework/search";
 import { propertyOf } from "@cosmicdrift/kumiko-types/type-guards";
 import type { Hono } from "hono";
-import { createTestDb } from "./db.js";
-import { createJobFailureTracker, drainJobs } from "./drain-jobs.js";
-import { createEventCollector, type EventCollector } from "./event-collector.js";
-import { createTestRedis, queueNamePrefixForTestRedis, type TestRedis } from "./redis.js";
-import { createRequestHelper, type RequestHelper } from "./request-helper.js";
+import { createTestDb } from "./db.ts";
+import { createJobFailureTracker, drainJobs } from "./drain-jobs.ts";
+import { createEventCollector, type EventCollector } from "./event-collector.ts";
+import { createTestRedis, queueNamePrefixForTestRedis, type TestRedis } from "./redis.ts";
+import { createRequestHelper, type RequestHelper } from "./request-helper.ts";
 
 export type TestStack = {
   app: Hono;
@@ -279,6 +279,29 @@ export type TestStackOptions = {
 
 const DEFAULT_JWT_SECRET = "test-stack-secret-minimum-32-characters!!";
 
+type MfaTokenSecretBinder = (
+  masterSecret: string,
+  env: Readonly<Record<string, string | undefined>>,
+) => void;
+
+// Mirrors bindMfaTokenSecretsFromFeature from bundled-features/auth-mfa,
+// which this package cannot import: bundled-features is an optional peer.
+function isMfaTokenSecretBinder(value: unknown): value is MfaTokenSecretBinder {
+  return typeof value === "function";
+}
+
+// The env is empty on purpose: test secrets derive from jwtSecret,
+// independent of the host env.
+function bindMfaTokenSecrets(features: readonly FeatureDefinition[], jwtSecret: string): void {
+  for (const { exports } of features) {
+    if (typeof exports !== "object" || exports === null || !("bindTokenSecrets" in exports)) {
+      continue;
+    }
+    const { bindTokenSecrets } = exports;
+    if (isMfaTokenSecretBinder(bindTokenSecrets)) bindTokenSecrets(jwtSecret, {});
+  }
+}
+
 export async function setupTestStack(options: TestStackOptions): Promise<TestStack> {
   const jwtSecret = options.jwtSecret ?? DEFAULT_JWT_SECRET;
   const enabledHooks = options.systemHooks ?? ["sse", "search"];
@@ -298,6 +321,7 @@ export async function setupTestStack(options: TestStackOptions): Promise<TestSta
   // Nav/workspace refs fail the prod boot too; the subset check tolerates refs into unmounted features.
   validateNavBootSubset(options.features);
   if (options.validateBoot === "full") validateBoot(options.features);
+  bindMfaTokenSecrets(options.features, jwtSecret);
 
   // Forward db-name/persistent-flag through to createTestDb. The
   // defaults (undefined dbName, persistent:false) keep the legacy