@cosmicdrift/kumiko-testing 0.386.0 → 0.388.0

package/LICENSE

@@ -1,57 +1,21 @@
-Business Source License 1.1
-
-Parameters
-
-Licensor:             Marc Frost
-
-Licensed Work:        @cosmicdrift/kumiko-testing
-                      The Licensed Work is © 2026 Marc Frost.
-
-Additional Use Grant: 
-You may use the Licensed Work in production for any purpose, including 
-commercially, EXCEPT for the Restricted Use. 
-
-"Restricted Use" is defined as using the Licensed Work to provide a platform 
-or service to third parties that allows them to host, deploy, or run their 
-own applications built with the Licensed Work. This includes, but is not 
-limited to: managed hosting services, software-as-a-service (SaaS) platforms, 
-platform-as-a-service (PaaS), developer platforms, or any multi-tenant 
-managed offering of the Licensed Work.
-
-This restriction does not apply to the Licensor, any entity controlled by, 
-controlling, or under common control with the Licensor ("Affiliates"), or 
-contractors acting on their behalf. The Licensor remains free to use the 
-Licensed Work for any purpose, including for the operation of kumiko.rocks.
-
-Change Date:          2030-05-05
-Change License:       Apache License, Version 2.0
-
-
-Terms
-
-The Licensor hereby grants you the right to copy, modify, create derivative works, 
-redistribute, and make non-production use of the Licensed Work. The Licensor may 
-make an Additional Use Grant, above, permitting limited production use.
-
-Effective on the Change Date, or the fourth anniversary of the first publicly 
-available distribution of the Licensed Work under this License, whichever comes 
-first, this License will convert to the Change License.
-
-This Business Source License governs use of the Licensed Work in all cases, except 
-as to any use that is explicitly granted in the Additional Use Grant above or 
-under the Change License after the Change Date.
-
-If your use of the Licensed Work does not comply with the requirements of this 
-License, you must cease use of the Licensed Work immediately.
-
-All copies of the Licensed Work, and all derivative works thereof, must include 
-this License.
-
-This License does not grant you any right, title, or interest in any trademark, 
-logo, or branding of the Licensor, except as required to comply with this License.
-
-TO THE EXTENT PERMITTED BY APPLICABLE LAW, THE LICENSED WORK IS PROVIDED ON AN 
-“AS IS” BASIS. LICENSOR DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING 
-WITHOUT LIMITATION WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, 
-TITLE, AND NON-INFRINGEMENT. IN NO EVENT WILL LICENSOR BE LIABLE FOR ANY DAMAGES 
-ARISING OUT OF OR RELATED TO THIS LICENSE OR THE USE OF THE LICENSED WORK.
+MIT License
+
+Copyright (c) 2026 Marc Frost
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@cosmicdrift/kumiko-testing",
-  "version": "0.386.0",
+  "version": "0.388.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",
+  "license": "MIT",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
   "repository": {
     "type": "git",
@@ -99,9 +99,9 @@
     "kumiko-testing": "./bin/kumiko-testing.ts"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-framework": "0.386.0",
-    "@cosmicdrift/kumiko-guards": "0.386.0",
-    "@cosmicdrift/kumiko-types": "0.386.0",
+    "@cosmicdrift/kumiko-framework": "0.388.0",
+    "@cosmicdrift/kumiko-guards": "0.388.0",
+    "@cosmicdrift/kumiko-types": "0.388.0",
     "zod": "^4.4.3"
   },
   "peerDependencies": {
@@ -125,8 +125,8 @@
     }
   },
   "devDependencies": {
-    "@cosmicdrift/kumiko-bundled-features": "0.386.0",
-    "@cosmicdrift/kumiko-dev-server": "0.386.0",
+    "@cosmicdrift/kumiko-bundled-features": "0.388.0",
+    "@cosmicdrift/kumiko-dev-server": "0.388.0",
     "@happy-dom/global-registrator": "^20.11.2",
     "@playwright/test": "^1.62.1",
     "@testing-library/dom": "^10.4.1",

package/src/bunfig.ts

@@ -102,7 +102,7 @@ type BunfigBlock = { readonly header: string; readonly lines: readonly string[]
 // contain "[" are never alone on their own line. Anything before the first
 // header (top-level keys like `preload`/`telemetry`/`smol`/`logLevel`, plus
 // the header comments) is its own block under the synthetic header "" —
-// dropping it silently lost those keys (kumiko-framework#3120).
+// dropping it silently lost those keys.
 function splitBunfigBlocks(content: string): readonly BunfigBlock[] {
   const blocks: { header: string; lines: string[] }[] = [];
   let current: { header: string; lines: string[] } = { header: "", lines: [] };
@@ -224,7 +224,7 @@ function appendArrayExtras(
  * verbatim, appended after the generated content — so a section the
  * template doesn't own this run is never silently dropped. A key inside a
  * section the template DOES emit that isn't in this run's own version of
- * that section (e.g. `concurrency`, `timeout`, kumiko-framework#3120) fails
+ * that section (e.g. `concurrency`, `timeout`) fails
  * the merge instead of silently disappearing. Within an array key the
  * template does emit on both sides (`preload`, `pathIgnorePatterns`,
  * `coveragePathIgnorePatterns`), entries the app appended on top of the

package/src/changes.json

@@ -1,4 +1,22 @@
 [
+  {
+    "version": "0.388.0",
+    "type": "improvement",
+    "title": "setupTestStack split into setup phases",
+    "detail": "setupTestStack() keeps its signature and behavior. Feature validation, storage provisioning with its DDL cleanup, cache sync, services, the job runner and the server start are separate phases in stack/test-stack-setup.ts. The cleanup on a failed setup still stops the job runner, closes cache sync and drops the test database and Redis in that order."
+  },
+  {
+    "version": "0.388.0",
+    "type": "fix",
+    "title": "Barrier, SSE reader, boundary guard and Redis helper fixes",
+    "detail": "createBarrier rejects late arrivals after a timeout instead of hanging. readSseFrames accepts CRLF and CR line endings. The error-boundary guard observes every page of the context and no longer fails on closed pages. createTestRedis disconnects the client when the initial connect fails. createE2eSeedRoutes of the e2e/seed-route subpath is also available as createE2eSeedRoutesWith, the old name stays as a deprecated alias."
+  },
+  {
+    "version": "0.388.0",
+    "type": "fix",
+    "title": "consoleCallsMentioning helper for console spies",
+    "detail": "`@cosmicdrift/kumiko-testing/helpers` exports `consoleCallsMentioning(spy, fragment)` and `ConsoleSpyLike`, replacing the per-file filters tests used to ignore console output of other test files."
+  },
   {
     "version": "0.386.0",
     "type": "fix",

package/src/e2e/boundary-guard.ts

@@ -3,7 +3,40 @@ import {
   ROOT_ERROR_FALLBACK_TEST_ID,
   SCREEN_ERROR_FALLBACK_TEST_ID,
 } from "@cosmicdrift/kumiko-types/error-boundary";
-import { test as base, expect } from "@playwright/test";
+import { type BrowserContext, test as base, expect } from "@playwright/test";
+
+export type BoundaryFindings = {
+  readonly boundaryLogs: readonly string[];
+  readonly visibleFallbacks: number;
+};
+
+const FALLBACK_SELECTOR = `[data-testid="${SCREEN_ERROR_FALLBACK_TEST_ID}"], [data-testid="${ROOT_ERROR_FALLBACK_TEST_ID}"]`;
+
+// Listens on the context so pages opened later (popups, context.newPage()) are covered too.
+export function observeErrorBoundaries(context: BrowserContext): {
+  readonly findings: () => Promise<BoundaryFindings>;
+} {
+  const boundaryLogs: string[] = [];
+  context.on("console", (msg) => {
+    if (msg.type() === "error" && msg.text().includes(ERROR_BOUNDARY_LOG_MARKER)) {
+      boundaryLogs.push(msg.text());
+    }
+  });
+  return {
+    async findings() {
+      let visibleFallbacks = 0;
+      for (const page of context.pages()) {
+        // A spec may close its page or a page may crash; counting then would throw and mask the test result.
+        if (page.isClosed()) continue;
+        visibleFallbacks += await page
+          .locator(FALLBACK_SELECTOR)
+          .count()
+          .catch(() => 0);
+      }
+      return { boundaryLogs: [...boundaryLogs], visibleFallbacks };
+    },
+  };
+}
 
 // An error boundary keeps the page alive, which also hides the failure from `pageerror`.
 // Every spec using `test` from this package fails when a boundary caught something.
@@ -13,21 +46,12 @@ export const boundaryGuardedTest = base.extend<{
 }>({
   expectErrorBoundary: [false, { option: true }],
   failOnErrorBoundary: [
-    async ({ page, expectErrorBoundary }, use) => {
-      const boundaryLogs: string[] = [];
-      page.on("console", (msg) => {
-        if (msg.type() === "error" && msg.text().includes(ERROR_BOUNDARY_LOG_MARKER)) {
-          boundaryLogs.push(msg.text());
-        }
-      });
+    async ({ context, expectErrorBoundary }, use) => {
+      const observer = observeErrorBoundaries(context);
       await use(undefined);
       // skip: the spec provokes a boundary on purpose and asserts the fallback itself
       if (expectErrorBoundary) return;
-      const visibleFallbacks = await page
-        .locator(
-          `[data-testid="${SCREEN_ERROR_FALLBACK_TEST_ID}"], [data-testid="${ROOT_ERROR_FALLBACK_TEST_ID}"]`,
-        )
-        .count();
+      const { boundaryLogs, visibleFallbacks } = await observer.findings();
       expect(
         { boundaryLogs, visibleFallbacks },
         "an error boundary caught a render/effect error",

package/src/e2e/index.ts

@@ -22,7 +22,11 @@ export {
   syntheticClientIpFor,
   totpCode,
 } from "./auth-kit";
-export { boundaryGuardedTest } from "./boundary-guard";
+export {
+  type BoundaryFindings,
+  boundaryGuardedTest,
+  observeErrorBoundaries,
+} from "./boundary-guard";
 export {
   CSRF_COOKIE_NAME,
   CSRF_HEADER_NAME,

package/src/e2e/screenshots.ts

@@ -324,7 +324,7 @@ export function runScreenshots(scenarios: readonly Scenario[], opts: FlatOptions
     // 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
+    // unreachable from Playwright (context.locale and --lang both no-op there).
     if (opts.pinLocale) test.use({ locale: "en-US" });
     for (const s of scenarios) {
       test(
@@ -556,7 +556,7 @@ export function runMatrix<T extends string>(
     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
+      // ponytail: see the runScreenshots() locale comment above.
       const tag = resolveLocaleTag(locale, opts.localeTags);
       test.use({ locale: tag });
 

package/src/e2e/seed-route.ts

@@ -51,7 +51,7 @@ function parseJsonBody<S extends z.ZodType>(schema: S, raw: string): ParsedBody<
 }
 
 // Shared by every verify() below — a failed parse becomes a 400 the same way
-// the pre-#3050 handler-level parseJsonBody/parseWith checks did.
+// the handler-level parseJsonBody/parseWith checks did.
 function parseOrReject<T>(value: ParsedBody<T>): T {
   if (value.success) return value.data;
   throw new ExtraRouteRejection(400, { error: value.error });
@@ -153,10 +153,10 @@ function toCapturedMail(message: InboxMessage): CapturedMail {
 // still throw in every environment) — the *mounting* decision is the
 // caller's: use isE2eSeedingEnabled() to keep prod from ever registering
 // these route objects at all, e.g. `...(isE2eSeedingEnabled() ?
-// createE2eSeedRoutes() : [])` in a server entry that also runs in prod
-// (kumiko-framework#3120). Each route's own assertGateOpen() 404s outside
-// the seed condition regardless — this is belt-and-suspenders, not the only gate.
-export function createE2eSeedRoutes(
+// createE2eSeedRoutes() : [])` in a server entry that also runs in prod.
+// Each route's own assertGateOpen() 404s outside the seed condition regardless
+// — this is belt-and-suspenders, not the only gate.
+export function createE2eSeedRoutesWith(
   options: E2eSeedRoutesOptions,
   bundled: SeedRouteBundledApi,
 ): readonly ExtraRouteDefinition[] {
@@ -327,3 +327,6 @@ export function createE2eSeedRoutes(
 
   return [seedTenantRoute, seedUserRoute, inboxRoute, extraSeedRoute];
 }
+
+/** @deprecated Use `createE2eSeedRoutesWith`; the old name collides with the bound `createE2eSeedRoutes` of dev-server/testing. */
+export const createE2eSeedRoutes = createE2eSeedRoutesWith;

package/src/helpers/barrier.ts

@@ -19,6 +19,8 @@ export function createBarrier(options: {
   let arrived = 0;
   let skipped = 0;
   let timer: ReturnType<typeof setTimeout> | undefined;
+  // Late arrivals after a timeout must fail loudly too instead of hanging until the test timeout.
+  let timedOutError: Error | undefined;
   const waiting: { resolve: () => void; reject: (error: Error) => void }[] = [];
 
   function openIfComplete(): void {
@@ -30,15 +32,17 @@ export function createBarrier(options: {
 
   return {
     arrive() {
+      if (timedOutError !== undefined) return Promise.reject(timedOutError);
       arrived++;
       const pending = new Promise<void>((resolve, reject) => {
         waiting.push({ resolve, reject });
       });
-      if (arrived === 1 && arrived + skipped < expected) {
+      if (timer === undefined && arrived + skipped < expected) {
         timer = setTimeout(() => {
           const error = new Error(
             `barrier timed out: ${arrived} of ${expected} arrived, ${skipped} skipped`,
           );
+          timedOutError = error;
           for (const waiter of waiting.splice(0)) waiter.reject(error);
         }, timeoutMs);
       }

package/src/helpers/boot-validator-fixture.ts

@@ -68,7 +68,7 @@ function ensureEntityListRowNavigation(
       // No `params` here: this same-entity target always resolves to
       // UPDATE mode (the renderer auto-fills entityId from row["id"]),
       // and entityEdit-update never reads search-params as initial
-      // values — the boot-validator now rejects that combination (#1680).
+      // values — the boot-validator now rejects that combination.
       {
         kind: "navigate",
         id: "edit",

package/src/helpers/console-calls.ts

@@ -0,0 +1,12 @@
+export type ConsoleSpyLike = {
+  readonly mock: { readonly calls: ReadonlyArray<ReadonlyArray<unknown>> };
+};
+
+// Other test files in the same bun process emit async console output while a console spy is
+// active, so assertions only count the calls that mention the message under test.
+export function consoleCallsMentioning(
+  spy: ConsoleSpyLike,
+  fragment: string,
+): ReadonlyArray<ReadonlyArray<unknown>> {
+  return spy.mock.calls.filter((args) => args.some((arg) => String(arg).includes(fragment)));
+}

package/src/helpers/e2e-generator.ts

@@ -309,7 +309,7 @@ function buildEditFillOps(
           ops.push({ kind: "fill", field, value: String(v) });
           break;
         // embedded/money/timestamp/locatedTimestamp/file/image/files/images:
-        // no generic interaction. Since #369 timestamp renders two inputs
+        // no generic interaction. Since timestamp renders two inputs
         // (date + time) that a single .fill() cannot drive; the test author
         // supplies a hand override or skips it.
         default:
@@ -489,7 +489,7 @@ function fieldToFixture(name: string, field: FieldDefinition): unknown {
     case "images":
       // File-upload fixtures are not generic yet: Playwright would have to supply
       // file contents, and the write API already expects uploaded fileRef UUIDs.
-      // Can be added once a sample settles the paths (M4).
+      // Can be added once a sample settles the paths.
       return undefined;
     default:
       return undefined;

package/src/helpers/index.ts

@@ -4,9 +4,9 @@
 
 // The four cache/injection resets stay in their own modules (they close over
 // module-private state) and are only re-exported here — they are out of /crypto
-// and /db as of #1631. A production call to resetPiiSubjectKmsForTests() silently
-// switches the PII layer off, and subject-annotated fields are written in
-// plaintext from then on: no error, no log.
+// and /db. A production call to resetPiiSubjectKmsForTests() silently switches
+// the PII layer off, and subject-annotated fields are written in plaintext from
+// then on: no error, no log.
 export {
   resetBlindIndexKeyForTests,
   resetEntityFieldEncryptionCacheForTests,
@@ -23,6 +23,7 @@ export {
   terminateBackendsByApplicationName,
   testDatabaseUrl,
 } from "./closed-connection-error.ts";
+export { type ConsoleSpyLike, consoleCallsMentioning } from "./console-calls.ts";
 export { type ClearableTable, clearTables, resetTestTables } from "./db-cleanup.ts";
 export {
   type E2EGeneratorOptions,

package/src/helpers/sse-frames.ts

@@ -25,6 +25,8 @@ export async function readSseFrames(
   const decoder = new TextDecoder();
   const frames: SseFrame[] = [];
   let buffer = "";
+  // A "\r" at a chunk end may be the first half of "\r\n", so it is held back until the next chunk.
+  let heldCarriageReturn: boolean = false;
   let timer: ReturnType<typeof setTimeout> | undefined;
   const timedOut = new Promise<never>((_, reject) => {
     timer = setTimeout(
@@ -40,7 +42,10 @@ export async function readSseFrames(
       if (chunk.done) {
         throw new Error(`sse stream ended before condition: ${frames.length} frames read`);
       }
-      buffer += decoder.decode(chunk.value, { stream: true });
+      const decodedText = decoder.decode(chunk.value, { stream: true });
+      const decoded: string = (heldCarriageReturn ? "\r" : "") + decodedText;
+      heldCarriageReturn = decoded.endsWith("\r");
+      buffer += (heldCarriageReturn ? decoded.slice(0, -1) : decoded).replace(/\r\n?/g, "\n");
       let separator = buffer.indexOf("\n\n");
       while (separator !== -1) {
         const rawFrame = buffer.slice(0, separator);

package/src/helpers/without-ambient-temporal.ts

@@ -1,6 +1,6 @@
 /**
  * Run `fn` with `globalThis.Temporal` deleted, then restore.
- * Used by ambient-independence regression tests (kumiko-framework#1525/#1550).
+ * Used by ambient-independence regression tests.
  */
 export async function withoutAmbientTemporal<T>(fn: () => T | Promise<T>): Promise<T> {
   const savedGlobal: unknown = Reflect.get(globalThis, "Temporal");

package/src/seed-types.ts

@@ -28,7 +28,7 @@ export type SeededUser = SeededCredentials & {
 export type SeedPart = (ctx: { readonly tenant: SeededTenant }) => Promise<void>;
 
 // email may contain the literal "{tenantId}" placeholder, substituted with the
-// seeded tenant's id — user:create's email uniqueness is global (fw#2134/#2593),
+// seeded tenant's id — user:create's email uniqueness is global,
 // so a fixed literal email collides across per-scenario tenants.
 export type SeedAdminIdentity = {
   readonly displayName?: string;

package/src/stack/db.ts

@@ -54,7 +54,7 @@ export function testDbTemplatePrefix(runId: string): string {
   return `kumiko_test_tpl_${runId}_`;
 }
 
-function adminUrlOf(url: string): string {
+export function adminUrlOf(url: string): string {
   return url.replace(/\/[^/]+$/, "/postgres");
 }
 
@@ -132,7 +132,7 @@ export function ensureTestDbTemplate(
   return pending;
 }
 
-async function buildTestDbTemplate(
+export async function buildTestDbTemplate(
   templateDbName: string,
   buildSchema: (db: DbConnection) => Promise<void>,
 ): Promise<void> {

package/src/stack/redis.ts

@@ -7,9 +7,8 @@ export type TestRedis = {
   // The exact REDIS_URL used to build `redis` above — for a second, unrelated
   // connection (e.g. the test-stack's JobRunner) that needs its own client
   // rather than sharing this one's keyPrefix. Reconstructing a URL from
-  // `redis.options` loses password/username/tls/path (pr-review
-  // kumiko-framework #1036/2) — callers needing a fresh connection should use
-  // this raw string, not rebuild one from parsed options.
+  // `redis.options` loses password/username/tls/path — callers needing a fresh
+  // connection should use this raw string, not rebuild one from parsed options.
   redisUrl: string;
   /** The per-test `keyPrefix` on `redis`, e.g. `kt:1a2b3c4d:`. */
   keyPrefix: string;
@@ -41,7 +40,13 @@ export async function createTestRedis(opts: CreateTestRedisOptions = {}): Promis
   const prefix = opts.borrowKeyPrefix ?? `kt:${generateId().slice(-8)}:`;
   // Callers that check redis.status (rate-limit resolver) must not see "connect" on their first call.
   const redis = new Redis(redisUrl, { keyPrefix: prefix, lazyConnect: true });
-  await redis.connect();
+  try {
+    await redis.connect();
+  } catch (error) {
+    // Without this the client keeps retrying in the background and holds the process open.
+    redis.disconnect();
+    throw error;
+  }
 
   async function deleteKeysMatching(pattern: string): Promise<void> {
     // Open a prefix-less client for the scan — ioredis' keyPrefix is applied

package/src/stack/request-helper.ts

@@ -109,7 +109,7 @@ export type RequestHelper = {
 export type RequestHelperOptions = {
   // When sessionChecker is wired (sessions feature), JWTs without jti are
   // rejected as no_sid. Seed/test helpers that only jwt.sign(user) need a
-  // live sid — create one via the same sessionCreator login uses (#1372).
+  // live sid — create one via the same sessionCreator login uses.
   readonly sessionCreator?: SessionCreator;
 };