@cosmicdrift/kumiko-testing 0.413.0 → 0.414.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -50,7 +50,8 @@ test("member sees the note", async ({ seedTenant, page }) => {
50
50
  - `defineAppE2eConfig({ port, env?, locale?, projects?, serverEntry?, testDir?, testMatch?, isolatedSpecs? })`: parallelism, retries, timeouts and
51
51
  workers (`KUMIKO_E2E_WORKERS` overrides) are fixed by the template; projects cannot set them.
52
52
  - `isolatedSpecs: ["**/composer.spec.ts"]` moves specs that change app-wide state (catalog entries, global
53
- settings) into the `chromium-isolated` project, which runs after all parallel projects on one worker. It cannot
53
+ settings) into an isolated twin of each project (`chromium-isolated`, `<name>-isolated`), which runs after all parallel
54
+ projects on one worker with the project's own `use`. A project with its own `testMatch` is rejected. It cannot
54
55
  be combined with `--shard`; details in `docs/guides/testing-standard.md`.
55
56
  - `KUMIKO_E2E_REMOTE_BASE_URL=https://staging.example.com` runs the same specs against an already running
56
57
  instance: no web server is started and `baseURL` is that URL (http or https only). Add
@@ -7,7 +7,7 @@ import {
7
7
  buildIntegrationTestArgs,
8
8
  listIntegrationTestFiles,
9
9
  resolveRequestedIntegrationFiles,
10
- runWithTestDbTemplates,
10
+ runWithTestRun,
11
11
  selectIntegrationFiles,
12
12
  } from "../src/integration-runner";
13
13
 
@@ -112,9 +112,9 @@ async function runIntegration(args: readonly string[], io: CliIo): Promise<numbe
112
112
  ...(values.timings !== undefined && { timings: values.timings }),
113
113
  ...(values["update-timings"] === true && { updateTimings: true }),
114
114
  });
115
- return runWithTestDbTemplates(
115
+ return runWithTestRun(
116
116
  // Bun.spawn defaults to the env from process start; pass the live one so the
117
- // template run id set by runWithTestDbTemplates reaches the test process.
117
+ // run id set by runWithTestRun reaches the test process.
118
118
  () =>
119
119
  Bun.spawn(["bun", ...testArgs], {
120
120
  cwd: io.cwd,
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@cosmicdrift/kumiko-testing",
3
- "version": "0.413.0",
3
+ "version": "0.414.0",
4
4
  "description": "Test template for Kumiko apps: per-flow seedTenant, app test stack, canonical test preloads, bunfig generator and integration runner.",
5
5
  "license": "MIT",
6
6
  "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -107,9 +107,9 @@
107
107
  "kumiko-testing": "./bin/kumiko-testing.ts"
108
108
  },
109
109
  "dependencies": {
110
- "@cosmicdrift/kumiko-framework": "0.413.0",
111
- "@cosmicdrift/kumiko-guards": "0.413.0",
112
- "@cosmicdrift/kumiko-types": "0.413.0",
110
+ "@cosmicdrift/kumiko-framework": "0.414.0",
111
+ "@cosmicdrift/kumiko-guards": "0.414.0",
112
+ "@cosmicdrift/kumiko-types": "0.414.0",
113
113
  "zod": "^4.6.7"
114
114
  },
115
115
  "peerDependencies": {
@@ -133,8 +133,8 @@
133
133
  }
134
134
  },
135
135
  "devDependencies": {
136
- "@cosmicdrift/kumiko-bundled-features": "0.413.0",
137
- "@cosmicdrift/kumiko-dev-server": "0.413.0",
136
+ "@cosmicdrift/kumiko-bundled-features": "0.414.0",
137
+ "@cosmicdrift/kumiko-dev-server": "0.414.0",
138
138
  "@happy-dom/global-registrator": "^21.0.4",
139
139
  "@playwright/test": "^1.64.1",
140
140
  "@testing-library/dom": "^10.4.2",
@@ -10,9 +10,12 @@ export const EXAMPLE_REQUEST_ID = "11111111-1111-4111-8111-111111111111";
10
10
  export const EXAMPLE_CURSOR = "CURSOR";
11
11
  export const EXAMPLE_TOKEN = "kpat_EXAMPLE";
12
12
  export const EXAMPLE_SECRET = "REDACTED";
13
+ export const EXAMPLE_JWT = "eyJEXAMPLE.EXAMPLE.EXAMPLE";
13
14
 
14
15
  // Recordings are committed and published, so credentials sent in a payload never reach the file.
15
- const SECRET_KEY = /password|secret|mfaCode/i;
16
+ // Only string values are replaced, so counters such as `tokenCount` stay readable.
17
+ const SECRET_KEY = /password|secret|mfa|token|apikey|api_key|authorization|credential/i;
18
+ const JWT = /eyJ[\w-]+\.[\w-]+\.[\w-]+/g;
16
19
 
17
20
  const UUID = /[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}/gi;
18
21
  const ISO_TIMESTAMP = /\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:Z|[+-]\d{2}:\d{2})/g;
@@ -31,6 +34,7 @@ function createExampleWalker(): (value: unknown) => unknown {
31
34
  const uuids = new Map<string, string>();
32
35
  const normalizeString = (text: string): string =>
33
36
  text
37
+ .replace(JWT, EXAMPLE_JWT)
34
38
  .replace(PAT_TOKEN, EXAMPLE_TOKEN)
35
39
  .replace(UUID, (found) => {
36
40
  const key = found.toLowerCase();
package/src/changes.json CHANGED
@@ -1,4 +1,61 @@
1
1
  [
2
+ {
3
+ "version": "0.414.0",
4
+ "type": "improvement",
5
+ "title": "seedRowsViaEventStore seeds several rows through the event store",
6
+ "detail": "`@cosmicdrift/kumiko-testing/helpers` exports `seedRowsViaEventStore(db, table, rows)`, the event store counterpart of `seedRows`. Each row becomes its own event stream."
7
+ },
8
+ {
9
+ "version": "0.414.0",
10
+ "type": "fix",
11
+ "title": "stricter and clearer test helpers",
12
+ "detail": "`loginViaUi` throws with the MFA verify status and body, or names the missing post-login redirect. `defineAppE2eConfig` merges the default ignores into app projects that set `testIgnore` even without `isolatedSpecs`. `seedRowViaEventStore` throws for system columns such as `isDeleted`; use `deleteRowViaEventStore` or the real command. The unused `end` member of `RawDbClient` is gone.",
13
+ "migration": "Replace seeds with system columns by the real event, for example `softDeleteUserViaEventStore` instead of `isDeleted: true`."
14
+ },
15
+ {
16
+ "version": "0.414.0",
17
+ "type": "fix",
18
+ "title": "setupTestStack cleans up when a factory throws",
19
+ "detail": "The cleanup region of `setupTestStack` starts right after the storage is provisioned, so a throwing `extraContext` factory, `runLogger` factory or job runner creation no longer leaves the test database, Redis namespace and cache-sync connection open. The cleanup only closes what already exists."
20
+ },
21
+ {
22
+ "version": "0.414.0",
23
+ "type": "fix",
24
+ "title": "test stack setup split, drain-jobs regression bound to the batch size",
25
+ "detail": "The test stack setup moved from one 694-line file into test-stack-storage.ts, test-stack-services.ts and test-stack-server.ts without behaviour change. The drain-jobs row-level-security regression derives its backlog from `DEFAULT_EVENT_DISPATCHER_BATCH_SIZE` (newly exported from `@cosmicdrift/kumiko-framework/pipeline`) instead of a fixed 450, so it keeps covering \"more than two batches\" when the batch size changes. The seeded-tenant fixture documents that the per-test client IP header forces a CORS preflight on cross-origin requests. The use-all-bundled admin session file is cleared by a Playwright globalSetup, so a reused runner pid never serves expired cookies."
26
+ },
27
+ {
28
+ "version": "0.414.0",
29
+ "type": "fix",
30
+ "title": "api example recordings redact tokens, api keys and JWTs",
31
+ "detail": "The recording normalizer only masked values under keys matching `password|secret|mfaCode`, so an `accessToken`, `refreshToken`, `apiKey` or `authorization` value was committed and published verbatim. The key rule is now `password|secret|mfa|token|apikey|api_key|authorization|credential` (string values only; numeric fields such as `tokenCount` are untouched) and any JWT-shaped string in a value is replaced by a fixed placeholder. A recorded `token` field is now `REDACTED` instead of the `kpat_EXAMPLE` placeholder. The committed samples/recipes recordings contain no matching keys and are unchanged."
32
+ },
33
+ {
34
+ "version": "0.414.0",
35
+ "type": "improvement",
36
+ "title": "e2e fixture client ip header also overrides a per-fetch x-forwarded-for",
37
+ "detail": "The per-test client ip goes through `context.setExtraHTTPHeaders`, so an `x-forwarded-for` set in a single `fetch(..., { headers })` is replaced by it; only `page.setExtraHTTPHeaders` or a separate `browser.newContext()` with its own header changes the IP. This is now covered by `e2e/client-ip.spec.ts`.",
38
+ "migration": "Specs that simulate other client IPs per request (rate limit, audit IP, geo) must set the header with `page.setExtraHTTPHeaders` or on their own `browser.newContext()`; a per-fetch `x-forwarded-for` is overwritten. A cross-origin `fetch`/XHR from the page now carries `x-forwarded-for` and therefore forces a CORS preflight; route third-party endpoints that send no `Access-Control-Allow-Headers` through a same-origin proxy or mock them with `page.route`."
39
+ },
40
+ {
41
+ "version": "0.414.0",
42
+ "type": "fix",
43
+ "title": "event-store write helpers fail on ambiguous row filters",
44
+ "detail": "`updateRowViaEventStore` and `deleteRowViaEventStore` now throw when the filter matches more than one row instead of writing to whichever row came first. `updateInvitationViaEventStore` also filters on the inviting tenant, so the same email invited in two tenants no longer hits the wrong row."
45
+ },
46
+ {
47
+ "version": "0.414.0",
48
+ "type": "fix",
49
+ "title": "Test stack attaches the job dispatcher before the runner starts",
50
+ "detail": "With jobs.consumerLane set, setupTestStack started the runner (worker plus runOnBoot enqueue) before attachDispatcher. Under load a boot job such as a perTenant sync reached ctx.dispatch.write in that window, failed, and drainJobs reported it later as a job failure in an unrelated test. The order now matches the prod entrypoint."
51
+ },
52
+ {
53
+ "version": "0.414.0",
54
+ "type": "breaking",
55
+ "title": "Test-stack cleanup removes only its own queues; one sweep per integration run",
56
+ "detail": "`stack.cleanup()` scanned the whole Redis for its namespace and queue keys, so every teardown got slower as the local Redis filled up. It now obliterates the stack's two job queues by name (new `obliterateJobQueues` in `@cosmicdrift/kumiko-framework/jobs`) and leaves the namespace to the run sweep. The integration runner gives every run an id, keeps it alive in Redis, puts it into Redis prefixes and database names, and after the run removes its own keys and databases plus those of runs whose alive key has expired. Databases still in use and keys of live runs (including a single `bun test` outside the runner) are kept.",
57
+ "migration": "Rename imports of `runWithTestDbTemplates` from `@cosmicdrift/kumiko-testing/integration-runner` to `runWithTestRun`. A test that builds its own JobRunner (`jobs.queueNamePrefix` on setupTestStack, `createJobRunner`) should take its prefix from `testRunQueueNamePrefix(\"<label>\")` in `@cosmicdrift/kumiko-testing/stack`; the run sweep then removes its BullMQ keys, which a hand-made prefix such as `my-test-${Date.now()}` leaves behind. `stack.cleanup()` no longer flushes the Redis namespace; call `flushNamespace()` between tests where a test needs an empty namespace."
58
+ },
2
59
  {
3
60
  "version": "0.412.0",
4
61
  "type": "improvement",
@@ -272,7 +272,14 @@ export async function loginViaUi(page: Page, credentials: LoginCredentials): Pro
272
272
  }
273
273
  // The form disappears before the app navigates to its landing page; a goto issued in
274
274
  // between is interrupted by that navigation.
275
- await page.waitForURL((url) => !url.pathname.startsWith("/login"));
275
+ await page
276
+ .waitForURL((url) => !url.pathname.startsWith("/login"))
277
+ .catch((error: unknown) => {
278
+ throw new Error(
279
+ "loginViaUi: the app stayed on /login after the login went through; configure auth.postAuthLanding or redirect authenticated users away from /login",
280
+ { cause: error },
281
+ );
282
+ });
276
283
  }
277
284
 
278
285
  async function completeMfaStep(page: Page, mfaTotpSecret: string): Promise<void> {
@@ -282,12 +289,16 @@ async function completeMfaStep(page: Page, mfaTotpSecret: string): Promise<void>
282
289
  await expect(codeField).toBeVisible();
283
290
  const code = await unburnedTotpCode(mfaTotpSecret);
284
291
  // The sixth digit submits on its own and disables the field; an Enter press would race that.
285
- await Promise.all([
292
+ const [verifyResponse] = await Promise.all([
286
293
  page.waitForResponse(
287
- (response) => response.url().includes("/api/auth/mfa/verify") && response.ok(),
294
+ (response) =>
295
+ response.url().includes("/api/auth/mfa/verify") && response.request().method() === "POST",
288
296
  ),
289
297
  codeField.fill(code),
290
298
  ]);
299
+ if (!verifyResponse.ok()) {
300
+ throw new Error(`MFA verify failed: ${verifyResponse.status()} ${await verifyResponse.text()}`);
301
+ }
291
302
  await expect(codeField).toHaveCount(0);
292
303
  }
293
304
 
@@ -262,6 +262,12 @@ function assertIsolatedSpecsUsable(appProjects: readonly E2eProject[]): void {
262
262
  "defineAppE2eConfig: isolatedSpecs needs named projects, because the isolated project waits for them via dependencies",
263
263
  );
264
264
  }
265
+ const withOwnTestMatch = appProjects.find((project) => project.testMatch !== undefined);
266
+ if (withOwnTestMatch !== undefined) {
267
+ throw new Error(
268
+ `defineAppE2eConfig: isolatedSpecs cannot be combined with testMatch on project "${withOwnTestMatch.name}"; the isolated twin of a project would run specs outside its match`,
269
+ );
270
+ }
265
271
  if (isShardedRun()) {
266
272
  throw new Error(
267
273
  "defineAppE2eConfig: isolatedSpecs cannot be combined with --shard; Playwright does not shard dependency projects, so one shard would run every spec.",
@@ -271,28 +277,45 @@ function assertIsolatedSpecsUsable(appProjects: readonly E2eProject[]): void {
271
277
 
272
278
  function buildE2eProjects(input: ProjectsInput): Project[] {
273
279
  const { chromiumUse, appProjects, isolated, baseIgnore, realRun } = input;
274
- const baseProjects: Project[] = [{ name: "chromium", use: chromiumUse }, ...appProjects];
280
+ // A project-level testIgnore replaces the top-level one instead of merging with it.
281
+ const mergedAppProjects = appProjects.map((project) =>
282
+ project.testIgnore === undefined
283
+ ? project
284
+ : { ...project, testIgnore: [...baseIgnore, ...patternList(project.testIgnore)] },
285
+ );
286
+ const baseProjects: Project[] = [{ name: "chromium", use: chromiumUse }, ...mergedAppProjects];
275
287
  if (isolated.length === 0) return baseProjects;
276
288
  assertIsolatedSpecsUsable(appProjects);
277
- // A project-level testIgnore replaces the top-level one instead of merging with it.
278
289
  const parallelProjects = baseProjects.map((project) => ({
279
290
  ...project,
280
- testIgnore: [...baseIgnore, ...patternList(project.testIgnore), ...isolated],
291
+ testIgnore: [...new Set([...baseIgnore, ...patternList(project.testIgnore), ...isolated])],
281
292
  }));
282
- return [
283
- ...parallelProjects,
284
- {
285
- name: ISOLATED_E2E_PROJECT_NAME,
293
+ const parallelNames = parallelProjects.flatMap((project) =>
294
+ project.name === undefined ? [] : [project.name],
295
+ );
296
+ // Each base project gets its own serial twin so an isolated spec still runs under every
297
+ // project's `use` (viewport, storageState, locale) instead of only under Desktop Chrome.
298
+ const isolatedProjects: Project[] = [];
299
+ for (const project of baseProjects) {
300
+ const isChromium = project === baseProjects[0];
301
+ const { name, testIgnore: ownIgnore, ...rest } = project;
302
+ isolatedProjects.push({
303
+ ...rest,
304
+ name: isChromium ? ISOLATED_E2E_PROJECT_NAME : `${name}-isolated`,
286
305
  testMatch: [...isolated],
287
- testIgnore: [...baseIgnore, ...(realRun ? [NON_REAL_SPEC_PATTERN] : [])],
288
- dependencies: parallelProjects.flatMap((project) =>
289
- project.name === undefined ? [] : [project.name],
290
- ),
306
+ testIgnore: [
307
+ ...new Set([
308
+ ...baseIgnore,
309
+ ...patternList(ownIgnore),
310
+ ...(realRun ? [NON_REAL_SPEC_PATTERN] : []),
311
+ ]),
312
+ ],
313
+ dependencies: [...parallelNames, ...isolatedProjects.flatMap((prev) => prev.name ?? [])],
291
314
  fullyParallel: false,
292
315
  workers: 1,
293
- use: chromiumUse,
294
- },
295
- ];
316
+ });
317
+ }
318
+ return [...parallelProjects, ...isolatedProjects];
296
319
  }
297
320
 
298
321
  export function defineAppE2eConfig(input: AppE2eConfigInput): PlaywrightTestConfig {
@@ -236,7 +236,9 @@ export function perTestClientIpKey(
236
236
  }
237
237
 
238
238
  // Chromium turns its HTTP cache off for a context as soon as it has a route,
239
- // so the header goes through setExtraHTTPHeaders and the cache stays on.
239
+ // so the header goes through setExtraHTTPHeaders and the cache stays on. It also rides on
240
+ // cross-origin requests, where it forces a CORS preflight: mock or proxy third-party endpoints
241
+ // that don't allow x-forwarded-for.
240
242
  export async function providePerTestClientIpContext(
241
243
  {
242
244
  context,
@@ -6,7 +6,6 @@ import {
6
6
  createEventStoreExecutor,
7
7
  createTenantDb,
8
8
  type DbConnection,
9
- fetchOne,
10
9
  selectMany,
11
10
  type WhereObject,
12
11
  } from "@cosmicdrift/kumiko-framework/db";
@@ -44,10 +43,16 @@ async function loadTarget(
44
43
  where: WhereObject,
45
44
  verb: string,
46
45
  ): Promise<{ id: EntityId; version: number }> {
47
- const row = await fetchOne<Record<string, unknown>>(db, target.table, where);
46
+ const rows = await selectMany<Record<string, unknown>>(db, target.table, where);
47
+ const [row] = rows;
48
48
  if (!row) {
49
49
  throw new Error(`${verb} ${target.entityName}: no row matches ${JSON.stringify(where)}`);
50
50
  }
51
+ if (rows.length > 1) {
52
+ throw new Error(
53
+ `${verb} ${target.entityName}: ${rows.length} rows match ${JSON.stringify(where)}, expected exactly 1`,
54
+ );
55
+ }
51
56
  const { id, version } = row;
52
57
  if (!isEntityId(id)) throw new Error(`${verb} ${target.entityName}: row has no id`);
53
58
  if (typeof version !== "number") {
@@ -96,6 +101,14 @@ export async function seedRowViaEventStore(
96
101
  }
97
102
  const { entity, entityName } = source;
98
103
  const { tenantId, ...payload } = values;
104
+ const unknownKeys = Object.keys(payload).filter(
105
+ (key) => key !== "id" && entity.fields[key] === undefined,
106
+ );
107
+ if (unknownKeys.length > 0) {
108
+ throw new Error(
109
+ `seed ${entityName}: ${unknownKeys.join(", ")} not entity fields; system columns come from events, use deleteRowViaEventStore or the real command`,
110
+ );
111
+ }
99
112
  if (payload["id"] !== undefined && typeof payload["id"] !== "string") {
100
113
  throw new Error(
101
114
  `seed ${entityName}: id must be a string, the event store would mint a new one`,
@@ -110,6 +123,15 @@ export async function seedRowViaEventStore(
110
123
  if (!result.isSuccess) throw failedWrite("seed", entityName, result.error);
111
124
  }
112
125
 
126
+ // Same arguments as seedRows. Seeds one after the other: each row is its own event stream.
127
+ export async function seedRowsViaEventStore(
128
+ db: DbConnection,
129
+ table: EventStoreWriteTarget["table"],
130
+ rows: ReadonlyArray<Readonly<Record<string, unknown>>>,
131
+ ): Promise<void> {
132
+ for (const values of rows) await seedRowViaEventStore(db, table, values);
133
+ }
134
+
113
135
  export async function updateRowViaEventStore(
114
136
  db: DbConnection,
115
137
  target: EventStoreWriteTarget,
@@ -47,6 +47,7 @@ export {
47
47
  deleteRowViaEventStore,
48
48
  type EventStoreWriteScope,
49
49
  type EventStoreWriteTarget,
50
+ seedRowsViaEventStore,
50
51
  seedRowViaEventStore,
51
52
  updateRowViaEventStore,
52
53
  } from "./event-store-writes.ts";
@@ -1,3 +1,4 @@
1
+ // @runtime dev
1
2
  import type { Temporal } from "@cosmicdrift/kumiko-types/temporal";
2
3
  import type { Clock } from "@cosmicdrift/kumiko-types/tz-context";
3
4
 
@@ -15,15 +15,39 @@ import {
15
15
  type WhereObject,
16
16
  } from "@cosmicdrift/kumiko-framework/db";
17
17
  import type { AnyDb } from "@cosmicdrift/kumiko-framework/internal/stack-support";
18
- import { withExecutorManagedWritesForTests } from "@cosmicdrift/kumiko-framework/internal/testing";
18
+ import {
19
+ executorManagedEntitySourceOf,
20
+ withExecutorManagedWritesForTests,
21
+ } from "@cosmicdrift/kumiko-framework/internal/testing";
19
22
 
20
23
  type SeedTable = EntityTable | EntityTableMeta;
21
24
 
25
+ export type SeedOptions = {
26
+ // Plants a projection row of an event-sourced entity without its event, on purpose (legacy,
27
+ // drift or corrupt-row scenarios). The reason names the scenario.
28
+ readonly projectionOnly?: string;
29
+ };
30
+
31
+ // A row seeded on an event-sourced entity table has no event, so a rebuild erases it. The
32
+ // entity-source registry sees tables the guard's file-local scan cannot (imported ones).
33
+ function assertSeedable(table: SeedTable, options: SeedOptions | undefined): void {
34
+ const isEventSourced = executorManagedEntitySourceOf(table) !== undefined;
35
+ const hasProjectionOnlyReason =
36
+ options?.projectionOnly !== undefined && options.projectionOnly.trim() !== "";
37
+ if (isEventSourced && !hasProjectionOnlyReason) {
38
+ throw new Error(
39
+ "seedRow on an event-sourced entity table writes the projection without its event: use seedRowViaEventStore, or pass { projectionOnly: reason } for a deliberate event-less row",
40
+ );
41
+ }
42
+ }
43
+
22
44
  export function seedRow<TRow = unknown>(
23
45
  db: AnyDb,
24
46
  table: SeedTable,
25
47
  values: Record<string, unknown>,
48
+ options?: SeedOptions,
26
49
  ): Promise<TRow | undefined> {
50
+ assertSeedable(table, options);
27
51
  return insertOne<TRow>(withExecutorManagedWritesForTests(db), table, values);
28
52
  }
29
53
 
@@ -31,7 +55,9 @@ export function seedRows<TRow = unknown>(
31
55
  db: AnyDb,
32
56
  table: SeedTable,
33
57
  rows: ReadonlyArray<Record<string, unknown>>,
58
+ options?: SeedOptions,
34
59
  ): Promise<readonly TRow[]> {
60
+ assertSeedable(table, options);
35
61
  return insertMany<TRow>(withExecutorManagedWritesForTests(db), table, rows);
36
62
  }
37
63
 
@@ -1,4 +1,3 @@
1
- import { randomBytes } from "node:crypto";
2
1
  import { existsSync, readdirSync, statSync } from "node:fs";
3
2
  import { join, resolve } from "node:path";
4
3
  import { BUNFIG_FILES, TEST_TIMEOUT_MS } from "./bunfig";
@@ -89,20 +88,32 @@ export function buildIntegrationTestArgs(opts: IntegrationRunOptions): string[]
89
88
  ];
90
89
  }
91
90
 
92
- // Test stacks of this run clone migrated template databases instead of repeating
93
- // the DDL per stack; the templates live exactly as long as the run.
94
- export async function runWithTestDbTemplates(run: () => Promise<number>): Promise<number> {
95
- const { TEST_DB_TEMPLATE_RUN_ENV, dropTestDbTemplates } = await import("./stack/db.ts");
96
- const runId = randomBytes(4).toString("hex");
91
+ // One run id for every process of the run: test stacks clone the run's migrated template
92
+ // databases, and the run's Redis keys and databases are swept once when it ends, together with
93
+ // those of runs that died without a sweep.
94
+ export async function runWithTestRun(run: () => Promise<number>): Promise<number> {
95
+ const { TEST_DB_TEMPLATE_RUN_ENV, adminUrlOf } = await import("./stack/db.ts");
96
+ const { TEST_RUN_ID_ENV, createTestRunId, keepTestRunAlive, sweepFinishedTestRuns } =
97
+ await import("./stack/test-run.ts");
98
+ const runId = createTestRunId();
99
+ const redisUrl = process.env["REDIS_URL"] ?? SERVICE_ENV_DEFAULTS.REDIS_URL;
100
+ const databaseUrl = process.env["TEST_DATABASE_URL"] ?? SERVICE_ENV_DEFAULTS.TEST_DATABASE_URL;
101
+ let alive: { readonly stop: () => void } | undefined;
97
102
  try {
98
- return await withEnv({ [TEST_DB_TEMPLATE_RUN_ENV]: runId }, run);
103
+ alive = await keepTestRunAlive(redisUrl, runId);
104
+ } catch (error) {
105
+ // biome-ignore lint/suspicious/noConsole: runner output is the interface
106
+ console.warn(`kumiko-testing: could not mark test run ${runId} alive:`, error);
107
+ }
108
+ try {
109
+ return await withEnv({ [TEST_DB_TEMPLATE_RUN_ENV]: runId, [TEST_RUN_ID_ENV]: runId }, run);
99
110
  } finally {
100
- const baseUrl = process.env["TEST_DATABASE_URL"] ?? SERVICE_ENV_DEFAULTS.TEST_DATABASE_URL;
111
+ alive?.stop();
101
112
  try {
102
- await dropTestDbTemplates(baseUrl, runId);
113
+ await sweepFinishedTestRuns({ runId, redisUrl, adminDatabaseUrl: adminUrlOf(databaseUrl) });
103
114
  } catch (error) {
104
115
  // biome-ignore lint/suspicious/noConsole: runner output is the interface
105
- console.warn(`kumiko-testing: could not drop the test DB templates of run ${runId}:`, error);
116
+ console.warn(`kumiko-testing: could not sweep the leftovers of test run ${runId}:`, error);
106
117
  }
107
118
  }
108
119
  }
package/src/stack/db.ts CHANGED
@@ -2,6 +2,7 @@
2
2
  // Test-DB Factory: CREATE DATABASE → connect → createEventsTable.
3
3
 
4
4
  import { DEFAULT_OUTSIDE_TRANSACTION_POOL_MAX } from "@cosmicdrift/kumiko-framework/db";
5
+ import { requiredEnvFor } from "@cosmicdrift/kumiko-framework/env";
5
6
  import {
6
7
  acquireSessionAdvisoryLock,
7
8
  createApplicationRole,
@@ -15,18 +16,14 @@ import {
15
16
  transferPublicSchemaOwnership,
16
17
  } from "@cosmicdrift/kumiko-framework/internal/stack-support";
17
18
  import { ensureTemporalPolyfill } from "@cosmicdrift/kumiko-framework/time";
18
- import { generateId } from "@cosmicdrift/kumiko-framework/utils";
19
19
  import type { DbConnection, PgListenClient } from "@cosmicdrift/kumiko-types/db-connection";
20
+ import { testDatabaseName } from "./test-run.ts";
20
21
 
21
- function requireEnv(name: string): string {
22
- const value = process.env[name];
23
- if (!value) {
24
- throw new Error(
25
- `Missing required env var: ${name}. Copy .env.example to .env and fill in values. Tests also need the test services (Postgres, Redis) running, e.g. "docker compose up -d".`,
26
- );
27
- }
28
- return value;
29
- }
22
+ const requireEnv = requiredEnvFor(
23
+ "test stack",
24
+ process.env,
25
+ 'Copy .env.example to .env and fill in values. Tests also need the test services (Postgres, Redis) running, e.g. "docker compose up -d".',
26
+ );
30
27
 
31
28
  export const DEFAULT_TEST_DB_POOL_MAX = 10;
32
29
 
@@ -66,7 +63,7 @@ export function adminUrlOf(url: string): string {
66
63
  return url.replace(/\/[^/]+$/, "/postgres");
67
64
  }
68
65
 
69
- function databaseUrlOf(url: string, dbName: string): string {
66
+ export function databaseUrlOf(url: string, dbName: string): string {
70
67
  return url.replace(/\/[^/]+$/, `/${dbName}`);
71
68
  }
72
69
 
@@ -135,7 +132,7 @@ export async function createTestDb(arg?: string | CreateTestDbOptions): Promise<
135
132
  await ensureTemporalPolyfill();
136
133
  const opts: CreateTestDbOptions = typeof arg === "string" ? { baseUrl: arg } : (arg ?? {});
137
134
  const url = opts.baseUrl ?? requireEnv("TEST_DATABASE_URL");
138
- const dbName = opts.dbName ?? `kumiko_test_${generateId().slice(-8)}`;
135
+ const dbName = opts.dbName ?? testDatabaseName();
139
136
  const adminUrl = adminUrlOf(url);
140
137
 
141
138
  const applicationRole = opts.applicationRole === true;
@@ -200,7 +197,7 @@ export function ensureTestDbTemplate(
200
197
  options: { readonly applicationRole?: boolean } = {},
201
198
  ): Promise<void> {
202
199
  const known = testDbTemplates.get(templateDbName);
203
- if (known) return known;
200
+ if (known !== undefined) return known;
204
201
  const pending = buildTestDbTemplate(templateDbName, buildSchema, options);
205
202
  testDbTemplates.set(templateDbName, pending);
206
203
  pending.catch(() => testDbTemplates.delete(templateDbName));
@@ -29,4 +29,5 @@ export { pushEntityProjectionTables } from "./push-entity-projection-tables.ts";
29
29
  export { createTestRedis, type TestRedis } from "./redis.ts";
30
30
  export { createRequestHelper, type RequestHelper } from "./request-helper.ts";
31
31
  export { resetEventStore } from "./table-helpers.ts";
32
+ export { testRunQueueNamePrefix } from "./test-run.ts";
32
33
  export { setupTestStack, type TestStack, type TestStackOptions } from "./test-stack.ts";
@@ -1,6 +1,8 @@
1
1
  // @runtime dev
2
+ import { obliterateJobQueues } from "@cosmicdrift/kumiko-framework/jobs";
2
3
  import { generateId } from "@cosmicdrift/kumiko-framework/utils";
3
4
  import { requireEnv } from "./db.ts";
5
+ import { ensureCurrentTestRunAlive } from "./test-run.ts";
4
6
 
5
7
  export type TestRedis = {
6
8
  redis: import("ioredis").Redis;
@@ -12,8 +14,8 @@ export type TestRedis = {
12
14
  redisUrl: string;
13
15
  /** The per-test `keyPrefix` on `redis`, e.g. `kt:1a2b3c4d:`. */
14
16
  keyPrefix: string;
15
- /** Delete every key this test created (prefix-scoped). Replaces the old
16
- * `redis.flushdb()` — that wiped other parallel tests' BullMQ state. */
17
+ /** Delete every key this test created (prefix-scoped). Scans the whole Redis, so call it
18
+ * between tests that need a clean namespace, not as teardown — the run sweep does that. */
17
19
  flushNamespace: () => Promise<void>;
18
20
  cleanup: () => Promise<void>;
19
21
  };
@@ -27,17 +29,18 @@ export function queueNamePrefixForTestRedis(keyPrefix: string): string {
27
29
 
28
30
  export type CreateTestRedisOptions = {
29
31
  /** Reuse another stack's keyPrefix on a fresh connection. cleanup() then only
30
- * disconnects — the owning stack flushes the namespace and its queues. */
32
+ * disconnects — the owning stack removes the shared queues. */
31
33
  readonly borrowKeyPrefix?: string;
32
34
  };
33
35
 
34
36
  export async function createTestRedis(opts: CreateTestRedisOptions = {}): Promise<TestRedis> {
35
37
  const Redis = (await import("ioredis")).Redis;
36
38
  const redisUrl = requireEnv("REDIS_URL");
37
- // Every test gets a per-file key prefix on a shared DB (no DB-pool-of-15
38
- // round-robin). Collisions at birthday-paradox rates are gone — the
39
- // prefix space is unbounded. See Track B.3 in docs/plans/tests-refactor.
40
- const prefix = opts.borrowKeyPrefix ?? `kt:${generateId().slice(-8)}:`;
39
+ // Per-stack prefix inside the test run's namespace on a shared DB: the run sweep removes the
40
+ // namespace once per run instead of every cleanup scanning the whole Redis for it.
41
+ const prefix =
42
+ opts.borrowKeyPrefix ??
43
+ `kt:${await ensureCurrentTestRunAlive(redisUrl)}:${generateId().slice(-8)}:`;
41
44
  // Callers that check redis.status (rate-limit resolver) must not see "connect" on their first call.
42
45
  const redis = new Redis(redisUrl, { keyPrefix: prefix, lazyConnect: true });
43
46
  try {
@@ -73,12 +76,12 @@ export async function createTestRedis(opts: CreateTestRedisOptions = {}): Promis
73
76
  cleanup: async () => {
74
77
  if (opts.borrowKeyPrefix !== undefined) {
75
78
  redis.disconnect();
76
- // skip: the owning stack flushes the shared namespace and its queues
79
+ // skip: the owning stack removes the shared queues
77
80
  return;
78
81
  }
79
- await flushNamespace();
80
- // The derived per-stack JobRunner queues sit outside the keyPrefix.
81
- await deleteKeysMatching(`bull:${queueNamePrefixForTestRedis(prefix)}-*`);
82
+ // The namespace itself stays for the run sweep; only the derived JobRunner queues, which
83
+ // sit outside the keyPrefix, go now, by name.
84
+ await obliterateJobQueues({ redisUrl, queueNamePrefix: queueNamePrefixForTestRedis(prefix) });
82
85
  redis.disconnect();
83
86
  },
84
87
  };