@warlock.js/core 5.30.0 → 5.32.0

package/esm/tests/fakes/storage-fake.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"storage-fake.mjs","names":[],"sources":["../../../../../../../../../packages/core/src/tests/fakes/storage-fake.ts"],"sourcesContent":["import { existsSync, mkdirSync, mkdtempSync, readdirSync, rmSync } from \"node:fs\";\nimport os from \"node:os\";\nimport path from \"node:path\";\nimport { storage } from \"../../storage\";\nimport { storageConfigurations } from \"../../storage/config\";\nimport type { StorageDriverName } from \"../../storage/types\";\nimport { FakeAssertionError } from \"./fake-assertion-error\";\n\n/**\n * The env var that carries the fake storage root from the process that\n * created it (the HTTP test server, in `globalSetup`) to the test workers it\n * spawns, so both sides read and write the same files. Like\n * `WARLOCK_TEST_SERVER_PORT`, it is plumbing between the kit's own processes.\n */\nexport const TEST_STORAGE_ROOT_ENV_KEY = \"WARLOCK_TEST_STORAGE_ROOT\";\n\nlet root: string | undefined;\nlet ownsRoot = false;\nlet installed = false;\nlet wasInitialized = false;\n\nfunction currentRoot(): string {\n  if (!root) {\n    throw new FakeAssertionError(\n      \"storageFake is not installed. It installs by default in the test environment; check `tests.fakes` in src/config/tests.ts, or call storageFake.install().\",\n    );\n  }\n\n  return root;\n}\n\nfunction listFiles(directory: string, base: string): string[] {\n  if (!existsSync(directory)) return [];\n\n  return readdirSync(directory, { withFileTypes: true }).flatMap((entry) => {\n    const absolute = path.join(directory, entry.name);\n\n    return entry.isDirectory()\n      ? listFiles(absolute, base)\n      : [path.relative(base, absolute).split(path.sep).join(\"/\")];\n  });\n}\n\n/**\n * Points every configured storage driver — local, S3, R2, Spaces — at a\n * local temporary directory.\n *\n * Installed by default in the test environment: uploads and `storage.put()`\n * calls land on disk under one temp root (a folder per driver name), never in\n * a bucket and never in the app's real `storage/` folder. The root is shared\n * with the HTTP test server, so a file an HTTP request stored is visible to\n * the test that sent it. The process that created the root deletes it on\n * restore.\n *\n * @example\n * await uploadAvatar(user, file);\n *\n * await storageFake.assertExists(`avatars/${user.id}.png`);\n */\nexport const storageFake = {\n  /** Re-register every driver as a local one under the temp root. */\n  async install(): Promise<void> {\n    if (!installed) {\n      wasInitialized = storage.isInitialized;\n      installed = true;\n    }\n\n    if (!root) {\n      const shared = process.env[TEST_STORAGE_ROOT_ENV_KEY];\n\n      if (shared) {\n        root = shared;\n        ownsRoot = false;\n      } else {\n        root = mkdtempSync(path.join(os.tmpdir(), \"warlock-test-storage-\"));\n        ownsRoot = true;\n        process.env[TEST_STORAGE_ROOT_ENV_KEY] = root;\n      }\n    }\n\n    await storage.init();\n\n    const fakeRoot = root;\n\n    for (const name of storage.driverNames()) {\n      const driverRoot = path.join(fakeRoot, name);\n\n      mkdirSync(driverRoot, { recursive: true });\n      storage.register(\n        name,\n        storageConfigurations.local({ root: driverRoot, urlPrefix: `/test-storage/${name}` }),\n      );\n    }\n\n    const defaultName = storage.getDefaultName();\n\n    if (defaultName) storage.setDefault(defaultName);\n  },\n\n  /** Drop the fake drivers; the real configuration is read again on next use. */\n  async restore(): Promise<void> {\n    if (!installed) return;\n\n    installed = false;\n    storage.reset();\n\n    if (wasInitialized) await storage.init();\n\n    if (root && ownsRoot) {\n      rmSync(root, { recursive: true, force: true });\n\n      if (process.env[TEST_STORAGE_ROOT_ENV_KEY] === root) {\n        delete process.env[TEST_STORAGE_ROOT_ENV_KEY];\n      }\n    }\n\n    root = undefined;\n    ownsRoot = false;\n  },\n\n  isInstalled(): boolean {\n    return installed;\n  },\n\n  /** The temp directory every fake driver lives under. */\n  root(): string {\n    return currentRoot();\n  },\n\n  /** Every stored file, as `<driver>/<path>`, sorted. */\n  files(driver?: StorageDriverName): string[] {\n    const base = currentRoot();\n    const directory = driver ? path.join(base, driver) : base;\n\n    return listFiles(directory, directory).sort();\n  },\n\n  /** Assert a file exists, on the default driver unless `driver` is given. */\n  async assertExists(location: string, driver?: StorageDriverName): Promise<void> {\n    currentRoot();\n\n    const target = driver ? storage.use(driver) : storage;\n\n    if (!(await target.exists(location))) {\n      throw new FakeAssertionError(\n        `Expected ${JSON.stringify(location)} to be stored${driver ? ` on \"${driver}\"` : \"\"}. Stored files: ${JSON.stringify(storageFake.files())}.`,\n      );\n    }\n  },\n\n  /** Assert a file does not exist, on the default driver unless `driver` is given. */\n  async assertMissing(location: string, driver?: StorageDriverName): Promise<void> {\n    currentRoot();\n\n    const target = driver ? storage.use(driver) : storage;\n\n    if (await target.exists(location)) {\n      throw new FakeAssertionError(\n        `Expected ${JSON.stringify(location)} not to be stored${driver ? ` on \"${driver}\"` : \"\"}, but it is.`,\n      );\n    }\n  },\n};\n"],"mappings":";;;;;;;;;;;;;;;AAcA,MAAa,4BAA4B;AAEzC,IAAI;AACJ,IAAI,WAAW;AACf,IAAI,YAAY;AAChB,IAAI,iBAAiB;AAErB,SAAS,cAAsB;CAC7B,IAAI,CAAC,MACH,MAAM,IAAI,mBACR,0JACF;CAGF,OAAO;AACT;AAEA,SAAS,UAAU,WAAmB,MAAwB;CAC5D,IAAI,CAAC,WAAW,SAAS,GAAG,OAAO,CAAC;CAEpC,OAAO,YAAY,WAAW,EAAE,eAAe,KAAK,CAAC,CAAC,CAAC,SAAS,UAAU;EACxE,MAAM,WAAW,KAAK,KAAK,WAAW,MAAM,IAAI;EAEhD,OAAO,MAAM,YAAY,IACrB,UAAU,UAAU,IAAI,IACxB,CAAC,KAAK,SAAS,MAAM,QAAQ,CAAC,CAAC,MAAM,KAAK,GAAG,CAAC,CAAC,KAAK,GAAG,CAAC;CAC9D,CAAC;AACH;;;;;;;;;;;;;;;;;AAkBA,MAAa,cAAc;;CAEzB,MAAM,UAAyB;EAC7B,IAAI,CAAC,WAAW;GACd,iBAAiB,QAAQ;GACzB,YAAY;EACd;EAEA,IAAI,CAAC,MAAM;GACT,MAAM,SAAS,QAAQ,IAAI;GAE3B,IAAI,QAAQ;IACV,OAAO;IACP,WAAW;GACb,OAAO;IACL,OAAO,YAAY,KAAK,KAAK,GAAG,OAAO,GAAG,uBAAuB,CAAC;IAClE,WAAW;IACX,QAAQ,IAAI,6BAA6B;GAC3C;EACF;EAEA,MAAM,QAAQ,KAAK;EAEnB,MAAM,WAAW;EAEjB,KAAK,MAAM,QAAQ,QAAQ,YAAY,GAAG;GACxC,MAAM,aAAa,KAAK,KAAK,UAAU,IAAI;GAE3C,UAAU,YAAY,EAAE,WAAW,KAAK,CAAC;GACzC,QAAQ,SACN,MACA,sBAAsB,MAAM;IAAE,MAAM;IAAY,WAAW,iBAAiB;GAAO,CAAC,CACtF;EACF;EAEA,MAAM,cAAc,QAAQ,eAAe;EAE3C,IAAI,aAAa,QAAQ,WAAW,WAAW;CACjD;;CAGA,MAAM,UAAyB;EAC7B,IAAI,CAAC,WAAW;EAEhB,YAAY;EACZ,QAAQ,MAAM;EAEd,IAAI,gBAAgB,MAAM,QAAQ,KAAK;EAEvC,IAAI,QAAQ,UAAU;GACpB,OAAO,MAAM;IAAE,WAAW;IAAM,OAAO;GAAK,CAAC;GAE7C,IAAI,QAAQ,qCAAmC,MAC7C,OAAO,QAAQ,IAAI;EAEvB;EAEA,OAAO;EACP,WAAW;CACb;CAEA,cAAuB;EACrB,OAAO;CACT;;CAGA,OAAe;EACb,OAAO,YAAY;CACrB;;CAGA,MAAM,QAAsC;EAC1C,MAAM,OAAO,YAAY;EACzB,MAAM,YAAY,SAAS,KAAK,KAAK,MAAM,MAAM,IAAI;EAErD,OAAO,UAAU,WAAW,SAAS,CAAC,CAAC,KAAK;CAC9C;;CAGA,MAAM,aAAa,UAAkB,QAA2C;EAC9E,YAAY;EAIZ,IAAI,CAAE,OAFS,SAAS,QAAQ,IAAI,MAAM,IAAI,QAE5B,CAAC,OAAO,QAAQ,GAChC,MAAM,IAAI,mBACR,YAAY,KAAK,UAAU,QAAQ,EAAE,eAAe,SAAS,QAAQ,OAAO,KAAK,GAAG,kBAAkB,KAAK,UAAU,YAAY,MAAM,CAAC,EAAE,EAC5I;CAEJ;;CAGA,MAAM,cAAc,UAAkB,QAA2C;EAC/E,YAAY;EAIZ,IAAI,OAFW,SAAS,QAAQ,IAAI,MAAM,IAAI,QAE9B,CAAC,OAAO,QAAQ,GAC9B,MAAM,IAAI,mBACR,YAAY,KAAK,UAAU,QAAQ,EAAE,mBAAmB,SAAS,QAAQ,OAAO,KAAK,GAAG,aAC1F;CAEJ;AACF"}

package/esm/tests/fakes/test-fakes.d.mts

@@ -0,0 +1,38 @@
+//#region ../../packages/core/src/tests/fakes/test-fakes.d.ts
+/** The fakes the test kit installs. */
+export declare const TEST_FAKE_NAMES: readonly ["mail", "queue", "cache", "storage", "clock", "ids"];
+export type TestFakeName = (typeof TEST_FAKE_NAMES)[number];
+/**
+ * Which fakes to install.
+ *
+ * - `true` (the default) — all of them.
+ * - `false` — none: real drivers, real clock, real ids.
+ * - an object — all of them except the ones set to `false`, e.g.
+ *   `{ cache: false }` keeps the configured cache driver.
+ */
+export type TestFakesSelection = boolean | Partial<Record<TestFakeName, boolean>>;
+/** Read `tests.fakes` from `src/config/tests.ts`, or `undefined` when unset. */
+export declare function readConfiguredFakes(): TestFakesSelection | undefined;
+/**
+ * The fakes to install. Precedence: an explicit selection (the `fakes`
+ * option of `setupTest()` / `startHttpTestServer()`) > `tests.fakes` in
+ * `src/config/tests.ts` > all on.
+ */
+export declare function resolveTestFakes(explicit?: TestFakesSelection): TestFakeName[];
+/**
+ * Install the selected fakes. Called by `setupTest()` and
+ * `startHttpTestServer()` once their connectors are up; call it yourself only
+ * when you bootstrap the framework without them.
+ *
+ * @returns the fakes that are now installed.
+ */
+export declare function installTestFakes(explicit?: TestFakesSelection): Promise<TestFakeName[]>;
+/**
+ * Restore every installed fake, in reverse order. Every fake is restored even
+ * when one fails; the failures are rethrown together afterwards.
+ */
+export declare function restoreTestFakes(): Promise<void>;
+/** The fakes installed right now. */
+export declare function installedTestFakes(): TestFakeName[];
+//#endregion
+//# sourceMappingURL=test-fakes.d.mts.map

package/esm/tests/fakes/test-fakes.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"test-fakes.d.mts","names":[],"sources":["../../../../../../../../../packages/core/src/tests/fakes/test-fakes.ts"],"mappings":";;qBAUa;YAED,uBAAuB;;;;;;;;;YAUvB,+BAA+B,QAAQ,OAAO;;wBAiB1C,uBAAuB;;;;;;wBA0CvB,iBAAiB,WAAW,qBAAqB;;;;;;;;wBAiB3C,iBAAiB,WAAW,qBAAqB,QAAQ;;;;;wBAgBzD,oBAAoB;;wBAiB1B,sBAAsB"}

package/esm/tests/fakes/test-fakes.mjs

@@ -0,0 +1,90 @@
+import { config } from "../../config/config-getter.mjs";
+import "../../config/index.mjs";
+import { cacheFake } from "./cache-fake.mjs";
+import { clockFake } from "./clock-fake.mjs";
+import { idsFake } from "./ids-fake.mjs";
+import { mailFake } from "./mail-fake.mjs";
+import { queueFake } from "./queue-fake.mjs";
+import { storageFake } from "./storage-fake.mjs";
+
+//#region ../../packages/core/src/tests/fakes/test-fakes.ts
+/** The fakes the test kit installs. */
+const TEST_FAKE_NAMES = [
+	"mail",
+	"queue",
+	"cache",
+	"storage",
+	"clock",
+	"ids"
+];
+const fakes = {
+	mail: mailFake,
+	queue: queueFake,
+	cache: cacheFake,
+	storage: storageFake,
+	clock: clockFake,
+	ids: idsFake
+};
+let active = [];
+/** Read `tests.fakes` from `src/config/tests.ts`, or `undefined` when unset. */
+function readConfiguredFakes() {
+	return validateSelection((config.get("tests", {}) ?? {}).fakes, "tests.fakes");
+}
+function validateSelection(value, source) {
+	if (value === void 0 || typeof value === "boolean") return value;
+	if (typeof value !== "object" || value === null || Array.isArray(value)) throw new Error(`${source} must be true, false, or an object such as { cache: false }; got ${JSON.stringify(value)}.`);
+	const selection = {};
+	for (const [key, flag] of Object.entries(value)) {
+		const name = TEST_FAKE_NAMES.find((candidate) => candidate === key);
+		if (!name) throw new Error(`${source} has an unknown fake "${key}". Known fakes: ${TEST_FAKE_NAMES.join(", ")}.`);
+		if (typeof flag !== "boolean") throw new Error(`${source}.${key} must be true or false; got ${JSON.stringify(flag)}.`);
+		selection[name] = flag;
+	}
+	return selection;
+}
+/**
+* The fakes to install. Precedence: an explicit selection (the `fakes`
+* option of `setupTest()` / `startHttpTestServer()`) > `tests.fakes` in
+* `src/config/tests.ts` > all on.
+*/
+function resolveTestFakes(explicit) {
+	const selection = explicit !== void 0 ? validateSelection(explicit, "fakes") : readConfiguredFakes();
+	if (selection === void 0 || selection === true) return [...TEST_FAKE_NAMES];
+	if (selection === false) return [];
+	return TEST_FAKE_NAMES.filter((name) => selection[name] !== false);
+}
+/**
+* Install the selected fakes. Called by `setupTest()` and
+* `startHttpTestServer()` once their connectors are up; call it yourself only
+* when you bootstrap the framework without them.
+*
+* @returns the fakes that are now installed.
+*/
+async function installTestFakes(explicit) {
+	const selected = resolveTestFakes(explicit);
+	for (const name of selected) await fakes[name].install();
+	active = [.../* @__PURE__ */ new Set([...active, ...selected])];
+	return selected;
+}
+/**
+* Restore every installed fake, in reverse order. Every fake is restored even
+* when one fails; the failures are rethrown together afterwards.
+*/
+async function restoreTestFakes() {
+	const errors = [];
+	for (const name of [...active].reverse()) try {
+		await fakes[name].restore();
+	} catch (error) {
+		errors.push(error);
+	}
+	active = [];
+	if (errors.length > 0) throw new AggregateError(errors, "Restoring the test fakes failed.");
+}
+/** The fakes installed right now. */
+function installedTestFakes() {
+	return [...active];
+}
+
+//#endregion
+export { TEST_FAKE_NAMES, installTestFakes, installedTestFakes, readConfiguredFakes, resolveTestFakes, restoreTestFakes };
+//# sourceMappingURL=test-fakes.mjs.map

package/esm/tests/fakes/test-fakes.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"test-fakes.mjs","names":[],"sources":["../../../../../../../../../packages/core/src/tests/fakes/test-fakes.ts"],"sourcesContent":["import type { GenericObject } from \"@mongez/reinforcements\";\nimport { config } from \"../../config\";\nimport { cacheFake } from \"./cache-fake\";\nimport { clockFake } from \"./clock-fake\";\nimport { idsFake } from \"./ids-fake\";\nimport { mailFake } from \"./mail-fake\";\nimport { queueFake } from \"./queue-fake\";\nimport { storageFake } from \"./storage-fake\";\n\n/** The fakes the test kit installs. */\nexport const TEST_FAKE_NAMES = [\"mail\", \"queue\", \"cache\", \"storage\", \"clock\", \"ids\"] as const;\n\nexport type TestFakeName = (typeof TEST_FAKE_NAMES)[number];\n\n/**\n * Which fakes to install.\n *\n * - `true` (the default) — all of them.\n * - `false` — none: real drivers, real clock, real ids.\n * - an object — all of them except the ones set to `false`, e.g.\n *   `{ cache: false }` keeps the configured cache driver.\n */\nexport type TestFakesSelection = boolean | Partial<Record<TestFakeName, boolean>>;\n\nconst fakes: Record<\n  TestFakeName,\n  { install(): void | Promise<void>; restore(): void | Promise<void> }\n> = {\n  mail: mailFake,\n  queue: queueFake,\n  cache: cacheFake,\n  storage: storageFake,\n  clock: clockFake,\n  ids: idsFake,\n};\n\nlet active: TestFakeName[] = [];\n\n/** Read `tests.fakes` from `src/config/tests.ts`, or `undefined` when unset. */\nexport function readConfiguredFakes(): TestFakesSelection | undefined {\n  // `config.get` resolves an absent key to `null`, not to its default's shape.\n  const testsConfig = config.get<GenericObject>(\"tests\", {}) ?? {};\n\n  return validateSelection(testsConfig.fakes as unknown, \"tests.fakes\");\n}\n\nfunction validateSelection(value: unknown, source: string): TestFakesSelection | undefined {\n  if (value === undefined || typeof value === \"boolean\") return value;\n\n  if (typeof value !== \"object\" || value === null || Array.isArray(value)) {\n    throw new Error(\n      `${source} must be true, false, or an object such as { cache: false }; got ${JSON.stringify(value)}.`,\n    );\n  }\n\n  const selection: Partial<Record<TestFakeName, boolean>> = {};\n\n  for (const [key, flag] of Object.entries(value)) {\n    const name = TEST_FAKE_NAMES.find((candidate) => candidate === key);\n\n    if (!name) {\n      throw new Error(\n        `${source} has an unknown fake \"${key}\". Known fakes: ${TEST_FAKE_NAMES.join(\", \")}.`,\n      );\n    }\n\n    if (typeof flag !== \"boolean\") {\n      throw new Error(`${source}.${key} must be true or false; got ${JSON.stringify(flag)}.`);\n    }\n\n    selection[name] = flag;\n  }\n\n  return selection;\n}\n\n/**\n * The fakes to install. Precedence: an explicit selection (the `fakes`\n * option of `setupTest()` / `startHttpTestServer()`) > `tests.fakes` in\n * `src/config/tests.ts` > all on.\n */\nexport function resolveTestFakes(explicit?: TestFakesSelection): TestFakeName[] {\n  const selection =\n    explicit !== undefined ? validateSelection(explicit, \"fakes\") : readConfiguredFakes();\n\n  if (selection === undefined || selection === true) return [...TEST_FAKE_NAMES];\n  if (selection === false) return [];\n\n  return TEST_FAKE_NAMES.filter((name) => selection[name] !== false);\n}\n\n/**\n * Install the selected fakes. Called by `setupTest()` and\n * `startHttpTestServer()` once their connectors are up; call it yourself only\n * when you bootstrap the framework without them.\n *\n * @returns the fakes that are now installed.\n */\nexport async function installTestFakes(explicit?: TestFakesSelection): Promise<TestFakeName[]> {\n  const selected = resolveTestFakes(explicit);\n\n  for (const name of selected) {\n    await fakes[name].install();\n  }\n\n  active = [...new Set([...active, ...selected])];\n\n  return selected;\n}\n\n/**\n * Restore every installed fake, in reverse order. Every fake is restored even\n * when one fails; the failures are rethrown together afterwards.\n */\nexport async function restoreTestFakes(): Promise<void> {\n  const errors: unknown[] = [];\n\n  for (const name of [...active].reverse()) {\n    try {\n      await fakes[name].restore();\n    } catch (error) {\n      errors.push(error);\n    }\n  }\n\n  active = [];\n\n  if (errors.length > 0) throw new AggregateError(errors, \"Restoring the test fakes failed.\");\n}\n\n/** The fakes installed right now. */\nexport function installedTestFakes(): TestFakeName[] {\n  return [...active];\n}\n"],"mappings":";;;;;;;;;;;AAUA,MAAa,kBAAkB;CAAC;CAAQ;CAAS;CAAS;CAAW;CAAS;AAAK;AAcnF,MAAM,QAGF;CACF,MAAM;CACN,OAAO;CACP,OAAO;CACP,SAAS;CACT,OAAO;CACP,KAAK;AACP;AAEA,IAAI,SAAyB,CAAC;;AAG9B,SAAgB,sBAAsD;CAIpE,OAAO,mBAFa,OAAO,IAAmB,SAAS,CAAC,CAAC,KAAK,CAAC,EAE3B,CAAC,OAAkB,aAAa;AACtE;AAEA,SAAS,kBAAkB,OAAgB,QAAgD;CACzF,IAAI,UAAU,UAAa,OAAO,UAAU,WAAW,OAAO;CAE9D,IAAI,OAAO,UAAU,YAAY,UAAU,QAAQ,MAAM,QAAQ,KAAK,GACpE,MAAM,IAAI,MACR,GAAG,OAAO,mEAAmE,KAAK,UAAU,KAAK,EAAE,EACrG;CAGF,MAAM,YAAoD,CAAC;CAE3D,KAAK,MAAM,CAAC,KAAK,SAAS,OAAO,QAAQ,KAAK,GAAG;EAC/C,MAAM,OAAO,gBAAgB,MAAM,cAAc,cAAc,GAAG;EAElE,IAAI,CAAC,MACH,MAAM,IAAI,MACR,GAAG,OAAO,wBAAwB,IAAI,kBAAkB,gBAAgB,KAAK,IAAI,EAAE,EACrF;EAGF,IAAI,OAAO,SAAS,WAClB,MAAM,IAAI,MAAM,GAAG,OAAO,GAAG,IAAI,8BAA8B,KAAK,UAAU,IAAI,EAAE,EAAE;EAGxF,UAAU,QAAQ;CACpB;CAEA,OAAO;AACT;;;;;;AAOA,SAAgB,iBAAiB,UAA+C;CAC9E,MAAM,YACJ,aAAa,SAAY,kBAAkB,UAAU,OAAO,IAAI,oBAAoB;CAEtF,IAAI,cAAc,UAAa,cAAc,MAAM,OAAO,CAAC,GAAG,eAAe;CAC7E,IAAI,cAAc,OAAO,OAAO,CAAC;CAEjC,OAAO,gBAAgB,QAAQ,SAAS,UAAU,UAAU,KAAK;AACnE;;;;;;;;AASA,eAAsB,iBAAiB,UAAwD;CAC7F,MAAM,WAAW,iBAAiB,QAAQ;CAE1C,KAAK,MAAM,QAAQ,UACjB,MAAM,MAAM,KAAK,CAAC,QAAQ;CAG5B,SAAS,CAAC,mBAAG,IAAI,IAAI,CAAC,GAAG,QAAQ,GAAG,QAAQ,CAAC,CAAC;CAE9C,OAAO;AACT;;;;;AAMA,eAAsB,mBAAkC;CACtD,MAAM,SAAoB,CAAC;CAE3B,KAAK,MAAM,QAAQ,CAAC,GAAG,MAAM,CAAC,CAAC,QAAQ,GACrC,IAAI;EACF,MAAM,MAAM,KAAK,CAAC,QAAQ;CAC5B,SAAS,OAAO;EACd,OAAO,KAAK,KAAK;CACnB;CAGF,SAAS,CAAC;CAEV,IAAI,OAAO,SAAS,GAAG,MAAM,IAAI,eAAe,QAAQ,kCAAkC;AAC5F;;AAGA,SAAgB,qBAAqC;CACnD,OAAO,CAAC,GAAG,MAAM;AACnB"}

package/esm/tests/index.d.mts

@@ -1,6 +1,19 @@
 import { assertPortIsAvailable, isPortAvailable } from "../http/port-preflight.mjs";
+import { TEST_FAKE_NAMES, TestFakeName, TestFakesSelection, installTestFakes, installedTestFakes, readConfiguredFakes, resolveTestFakes, restoreTestFakes } from "./fakes/test-fakes.mjs";
 import { StartHttpTestServerOptions, isTestServerRunning, startHttpTestServer, stopHttpTestServer } from "./start-http-development-server.mjs";
-import { expectJson, getTestServerUrl, parseJsonResponse, testDelete, testGet, testPatch, testPost, testPut, testRequest } from "./test-helpers.mjs";
+import { TestRequestClient, createTestRequestClient, expectJson, getTestServerUrl, parseJsonResponse, testDelete, testGet, testPatch, testPost, testPut, testRequest } from "./test-helpers.mjs";
+import { AuthenticatedTestClient, TestAuthenticableUser, actingAs } from "./authenticated-test-client.mjs";
 import { TestConnectorsSelection } from "./test-connectors-selection.mjs";
 import { TestLifecycleError, TestSetupOptions, setupTest, teardownTest, warnMissingImportModule } from "./vitest-setup.mjs";
-export { StartHttpTestServerOptions, type TestConnectorsSelection, TestLifecycleError, TestSetupOptions, assertPortIsAvailable, expectJson, getTestServerUrl, isPortAvailable, isTestServerRunning, parseJsonResponse, setupTest, startHttpTestServer, stopHttpTestServer, teardownTest, testDelete, testGet, testPatch, testPost, testPut, testRequest, warnMissingImportModule };
+import { cacheFake } from "./fakes/cache-fake.mjs";
+import { DEFAULT_FAKE_NOW, clockFake } from "./fakes/clock-fake.mjs";
+import { FakeAssertionError, describeRecorded } from "./fakes/fake-assertion-error.mjs";
+import { idsFake } from "./fakes/ids-fake.mjs";
+import { MailMatcher, mailFake } from "./fakes/mail-fake.mjs";
+import { JobReference, PushedJob, PushedJobMatcher, queueFake } from "./fakes/queue-fake.mjs";
+import { storageFake } from "./fakes/storage-fake.mjs";
+import "./fakes/index.mjs";
+import { Factory, FactoryAttributes, FactoryOverrides, FactorySeed, FactoryState, defineFactory, resetFactorySequences } from "./factories.mjs";
+import { CreateTestHttpServerOptions, TestHttpServer, createTestHttpServer } from "./test-http-server.mjs";
+import { REDACTED, ResponseSnapshot, SnapshotResponseOptions, snapshotResponse } from "./snapshot-response.mjs";
+export { AuthenticatedTestClient, CreateTestHttpServerOptions, DEFAULT_FAKE_NOW, Factory, FactoryAttributes, FactoryOverrides, FactorySeed, FactoryState, FakeAssertionError, JobReference, MailMatcher, PushedJob, PushedJobMatcher, REDACTED, ResponseSnapshot, SnapshotResponseOptions, StartHttpTestServerOptions, TEST_FAKE_NAMES, TestAuthenticableUser, type TestConnectorsSelection, TestFakeName, TestFakesSelection, TestHttpServer, TestLifecycleError, TestRequestClient, TestSetupOptions, actingAs, assertPortIsAvailable, cacheFake, clockFake, createTestHttpServer, createTestRequestClient, defineFactory, describeRecorded, expectJson, getTestServerUrl, idsFake, installTestFakes, installedTestFakes, isPortAvailable, isTestServerRunning, mailFake, parseJsonResponse, queueFake, readConfiguredFakes, resetFactorySequences, resolveTestFakes, restoreTestFakes, setupTest, snapshotResponse, startHttpTestServer, stopHttpTestServer, storageFake, teardownTest, testDelete, testGet, testPatch, testPost, testPut, testRequest, warnMissingImportModule };

package/esm/tests/index.mjs

@@ -1,6 +1,19 @@
 import { assertPortIsAvailable, isPortAvailable } from "../http/port-preflight.mjs";
+import { FakeAssertionError, describeRecorded } from "./fakes/fake-assertion-error.mjs";
+import { cacheFake } from "./fakes/cache-fake.mjs";
+import { DEFAULT_FAKE_NOW, clockFake } from "./fakes/clock-fake.mjs";
+import { idsFake } from "./fakes/ids-fake.mjs";
+import { mailFake } from "./fakes/mail-fake.mjs";
+import { queueFake } from "./fakes/queue-fake.mjs";
+import { storageFake } from "./fakes/storage-fake.mjs";
+import { TEST_FAKE_NAMES, installTestFakes, installedTestFakes, readConfiguredFakes, resolveTestFakes, restoreTestFakes } from "./fakes/test-fakes.mjs";
 import { isTestServerRunning, startHttpTestServer, stopHttpTestServer } from "./start-http-development-server.mjs";
-import { expectJson, getTestServerUrl, parseJsonResponse, testDelete, testGet, testPatch, testPost, testPut, testRequest } from "./test-helpers.mjs";
+import { createTestRequestClient, expectJson, getTestServerUrl, parseJsonResponse, testDelete, testGet, testPatch, testPost, testPut, testRequest } from "./test-helpers.mjs";
+import { actingAs } from "./authenticated-test-client.mjs";
 import { TestLifecycleError, setupTest, teardownTest, warnMissingImportModule } from "./vitest-setup.mjs";
+import "./fakes/index.mjs";
+import { defineFactory, resetFactorySequences } from "./factories.mjs";
+import { createTestHttpServer } from "./test-http-server.mjs";
+import { REDACTED, snapshotResponse } from "./snapshot-response.mjs";
 
-export { TestLifecycleError, assertPortIsAvailable, expectJson, getTestServerUrl, isPortAvailable, isTestServerRunning, parseJsonResponse, setupTest, startHttpTestServer, stopHttpTestServer, teardownTest, testDelete, testGet, testPatch, testPost, testPut, testRequest, warnMissingImportModule };
+export { DEFAULT_FAKE_NOW, FakeAssertionError, REDACTED, TEST_FAKE_NAMES, TestLifecycleError, actingAs, assertPortIsAvailable, cacheFake, clockFake, createTestHttpServer, createTestRequestClient, defineFactory, describeRecorded, expectJson, getTestServerUrl, idsFake, installTestFakes, installedTestFakes, isPortAvailable, isTestServerRunning, mailFake, parseJsonResponse, queueFake, readConfiguredFakes, resetFactorySequences, resolveTestFakes, restoreTestFakes, setupTest, snapshotResponse, startHttpTestServer, stopHttpTestServer, storageFake, teardownTest, testDelete, testGet, testPatch, testPost, testPut, testRequest, warnMissingImportModule };

package/esm/tests/snapshot-response.d.mts

@@ -0,0 +1,33 @@
+//#region ../../packages/core/src/tests/snapshot-response.d.ts
+/**
+ * A response reduced to what a snapshot should pin: the status, the content
+ * type and the body — with the values that differ on every run (ids, tokens,
+ * timestamps) replaced, so the snapshot fails only when the shape or a stable
+ * value changes.
+ */
+export type ResponseSnapshot = {
+  status: number;
+  contentType: string | null;
+  body: unknown;
+};
+export type SnapshotResponseOptions = {
+  /**
+   * Dot paths whose values are replaced by `"[redacted]"`. `*` matches any
+   * key or array index: `"post.id"`, `"posts.*.createdAt"`, `"*.token"`.
+   */
+  redact?: string[];
+};
+export declare const REDACTED = "[redacted]";
+/**
+ * Read a response into a {@link ResponseSnapshot} for `toMatchSnapshot()`.
+ * Consumes the body: call it instead of `response.json()`, not after.
+ *
+ * @example
+ * const response = await testPost("/posts", { title: "Hello" });
+ *
+ * expect(await snapshotResponse(response, { redact: ["post.id", "post.createdAt"] }))
+ *   .toMatchSnapshot();
+ */
+export declare function snapshotResponse(response: Response, options?: SnapshotResponseOptions): Promise<ResponseSnapshot>;
+//#endregion
+//# sourceMappingURL=snapshot-response.d.mts.map

package/esm/tests/snapshot-response.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"snapshot-response.d.mts","names":[],"sources":["../../../../../../../../packages/core/src/tests/snapshot-response.ts"],"mappings":";;;;;;;YAMY;EACV;EACA;EACA;;YAGU;;;;;EAKV;;qBAGW;;;;;;;;;;;wBAkCS,iBACpB,UAAU,UACV,UAAS,0BACR,QAAQ"}

package/esm/tests/snapshot-response.mjs

@@ -0,0 +1,42 @@
+//#region ../../packages/core/src/tests/snapshot-response.ts
+const REDACTED = "[redacted]";
+function redactPath(value, segments) {
+	if (segments.length === 0) return REDACTED;
+	if (typeof value !== "object" || value === null) return value;
+	const [head, ...rest] = segments;
+	if (Array.isArray(value)) return value.map((item, index) => head === "*" || head === String(index) ? redactPath(item, rest) : item);
+	const record = value;
+	const copy = { ...record };
+	for (const key of Object.keys(record)) if (head === "*" || head === key) copy[key] = redactPath(record[key], rest);
+	return copy;
+}
+/**
+* Read a response into a {@link ResponseSnapshot} for `toMatchSnapshot()`.
+* Consumes the body: call it instead of `response.json()`, not after.
+*
+* @example
+* const response = await testPost("/posts", { title: "Hello" });
+*
+* expect(await snapshotResponse(response, { redact: ["post.id", "post.createdAt"] }))
+*   .toMatchSnapshot();
+*/
+async function snapshotResponse(response, options = {}) {
+	const contentType = response.headers.get("content-type");
+	const text = await response.text();
+	let body = text;
+	if (contentType?.includes("json") && text !== "") try {
+		body = JSON.parse(text);
+	} catch {
+		body = text;
+	}
+	for (const path of options.redact ?? []) body = redactPath(body, path.split("."));
+	return {
+		status: response.status,
+		contentType,
+		body
+	};
+}
+
+//#endregion
+export { REDACTED, snapshotResponse };
+//# sourceMappingURL=snapshot-response.mjs.map

package/esm/tests/snapshot-response.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"snapshot-response.mjs","names":[],"sources":["../../../../../../../../packages/core/src/tests/snapshot-response.ts"],"sourcesContent":["/**\n * A response reduced to what a snapshot should pin: the status, the content\n * type and the body — with the values that differ on every run (ids, tokens,\n * timestamps) replaced, so the snapshot fails only when the shape or a stable\n * value changes.\n */\nexport type ResponseSnapshot = {\n  status: number;\n  contentType: string | null;\n  body: unknown;\n};\n\nexport type SnapshotResponseOptions = {\n  /**\n   * Dot paths whose values are replaced by `\"[redacted]\"`. `*` matches any\n   * key or array index: `\"post.id\"`, `\"posts.*.createdAt\"`, `\"*.token\"`.\n   */\n  redact?: string[];\n};\n\nexport const REDACTED = \"[redacted]\";\n\nfunction redactPath(value: unknown, segments: readonly string[]): unknown {\n  if (segments.length === 0) return REDACTED;\n  if (typeof value !== \"object\" || value === null) return value;\n\n  const [head, ...rest] = segments;\n\n  if (Array.isArray(value)) {\n    return value.map((item, index) =>\n      head === \"*\" || head === String(index) ? redactPath(item, rest) : item,\n    );\n  }\n\n  const record = value as Record<string, unknown>;\n  const copy: Record<string, unknown> = { ...record };\n\n  for (const key of Object.keys(record)) {\n    if (head === \"*\" || head === key) copy[key] = redactPath(record[key], rest);\n  }\n\n  return copy;\n}\n\n/**\n * Read a response into a {@link ResponseSnapshot} for `toMatchSnapshot()`.\n * Consumes the body: call it instead of `response.json()`, not after.\n *\n * @example\n * const response = await testPost(\"/posts\", { title: \"Hello\" });\n *\n * expect(await snapshotResponse(response, { redact: [\"post.id\", \"post.createdAt\"] }))\n *   .toMatchSnapshot();\n */\nexport async function snapshotResponse(\n  response: Response,\n  options: SnapshotResponseOptions = {},\n): Promise<ResponseSnapshot> {\n  const contentType = response.headers.get(\"content-type\");\n  const text = await response.text();\n  let body: unknown = text;\n\n  if (contentType?.includes(\"json\") && text !== \"\") {\n    try {\n      body = JSON.parse(text) as unknown;\n    } catch {\n      body = text;\n    }\n  }\n\n  for (const path of options.redact ?? []) {\n    body = redactPath(body, path.split(\".\"));\n  }\n\n  return { status: response.status, contentType, body };\n}\n"],"mappings":";AAoBA,MAAa,WAAW;AAExB,SAAS,WAAW,OAAgB,UAAsC;CACxE,IAAI,SAAS,WAAW,GAAG,OAAO;CAClC,IAAI,OAAO,UAAU,YAAY,UAAU,MAAM,OAAO;CAExD,MAAM,CAAC,MAAM,GAAG,QAAQ;CAExB,IAAI,MAAM,QAAQ,KAAK,GACrB,OAAO,MAAM,KAAK,MAAM,UACtB,SAAS,OAAO,SAAS,OAAO,KAAK,IAAI,WAAW,MAAM,IAAI,IAAI,IACpE;CAGF,MAAM,SAAS;CACf,MAAM,OAAgC,EAAE,GAAG,OAAO;CAElD,KAAK,MAAM,OAAO,OAAO,KAAK,MAAM,GAClC,IAAI,SAAS,OAAO,SAAS,KAAK,KAAK,OAAO,WAAW,OAAO,MAAM,IAAI;CAG5E,OAAO;AACT;;;;;;;;;;;AAYA,eAAsB,iBACpB,UACA,UAAmC,CAAC,GACT;CAC3B,MAAM,cAAc,SAAS,QAAQ,IAAI,cAAc;CACvD,MAAM,OAAO,MAAM,SAAS,KAAK;CACjC,IAAI,OAAgB;CAEpB,IAAI,aAAa,SAAS,MAAM,KAAK,SAAS,IAC5C,IAAI;EACF,OAAO,KAAK,MAAM,IAAI;CACxB,QAAQ;EACN,OAAO;CACT;CAGF,KAAK,MAAM,QAAQ,QAAQ,UAAU,CAAC,GACpC,OAAO,WAAW,MAAM,KAAK,MAAM,GAAG,CAAC;CAGzC,OAAO;EAAE,QAAQ,SAAS;EAAQ;EAAa;CAAK;AACtD"}

package/esm/tests/start-http-development-server.d.mts

@@ -1,10 +1,15 @@
+import { TestFakesSelection } from "./fakes/test-fakes.mjs";
 //#region ../../packages/core/src/tests/start-http-development-server.d.ts
-type StartHttpTestServerOptions = {
+export type StartHttpTestServerOptions = {
   /**
    * Port the test server binds to, overriding `http.port`.
    *
    * Needed because the server cannot be moved from outside: this function
    * bootstraps the app itself, and that bootstrap re-reads `.env`.
+   *
+   * `0` asks the OS for a free port. The port actually bound is published to
+   * the test workers, so `testGet()`, `actingAs()` and friends follow it, and
+   * a suite never collides with `warlock dev` or another suite.
    */
   port?: number;
   /**
@@ -17,6 +22,18 @@ type StartHttpTestServerOptions = {
    * @default true
    */
   web?: boolean;
+  /**
+   * Which test fakes the server process installs (mail, queue, cache,
+   * storage, clock, ids). Same values and precedence as `setupTest({ fakes })`:
+   * this option > `tests.fakes` config > all on.
+   *
+   * A fake records what happens in ITS process: mail sent while this server
+   * handles a request is captured here, not in the test worker that sent the
+   * request. To assert on what an HTTP request did, serve it in the worker
+   * with `createTestHttpServer()`. The storage fake is the exception: its
+   * temp root is shared with the workers.
+   */
+  fakes?: TestFakesSelection;
 };
 /**
  * Start the HTTP test server (minimal - no file watching)
@@ -25,17 +42,20 @@ type StartHttpTestServerOptions = {
  * @example
  * // run this suite on its own port, whatever `.env` says
  * await startHttpTestServer({ port: 3999 });
+ *
+ * @example
+ * // let the OS pick a free port; the request helpers follow it
+ * await startHttpTestServer({ port: 0 });
  */
-declare function startHttpTestServer(options?: StartHttpTestServerOptions): Promise<void>;
+export declare function startHttpTestServer(options?: StartHttpTestServerOptions): Promise<void>;
 /**
  * Stop the HTTP test server
  * Call this in Vitest's globalTeardown
  */
-declare function stopHttpTestServer(): Promise<void>;
+export declare function stopHttpTestServer(): Promise<void>;
 /**
  * Check if test server is running
  */
-declare function isTestServerRunning(): boolean;
+export declare function isTestServerRunning(): boolean;
 //#endregion
-export { StartHttpTestServerOptions, isTestServerRunning, startHttpTestServer, stopHttpTestServer };
 //# sourceMappingURL=start-http-development-server.d.mts.map

package/esm/tests/start-http-development-server.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"start-http-development-server.d.mts","names":[],"sources":["../../../../../../../../packages/core/src/tests/start-http-development-server.ts"],"mappings":";KAyBY,0BAAA;EAAA;;;;AAkBP;AAkGL;EA7GE,IAAA;;;;;;;AA6G0F;AA0G5F;;EA5ME,GAAG;AAAA;AA4M8C;AA6BnD;;;;AAAmC;;;AA7BgB,iBA1G7B,mBAAA,CAAoB,OAAA,GAAS,0BAAA,GAAkC,OAAO;;;;;iBA0GtE,kBAAA,IAAsB,OAAO;;;;iBA6BnC,mBAAA"}
+{"version":3,"file":"start-http-development-server.d.mts","names":[],"sources":["../../../../../../../../packages/core/src/tests/start-http-development-server.ts"],"mappings":";;YA4BY;;;;;;;;;;;EAWV;;;;;;;;;;EAWA;;;;;;;;;;;;EAaA,QAAQ;;;;;;;;;;;;;;wBA6HY,oBAAoB,UAAS,6BAAkC;;;;;wBA2H/D,sBAAsB;;;;wBAmC5B"}

package/esm/tests/start-http-development-server.mjs

@@ -1,6 +1,7 @@
 import { Application } from "../application/application.mjs";
 import "../application/index.mjs";
 import { assertPortIsAvailable } from "../http/port-preflight.mjs";
+import { getHttpReadyReport } from "../http/ready-report.mjs";
 import { loadEnvironmentFiles } from "../utils/load-environment.mjs";
 import { bootstrap } from "../bootstrap.mjs";
 import { ConnectorLifecyclePhase } from "../connectors/types.mjs";
@@ -8,8 +9,9 @@ import { connectorsManager } from "../connectors/connectors-manager.mjs";
 import { warlockConfigManager } from "../warlock-config/warlock-config.manager.mjs";
 import { filesOrchestrator } from "../dev-server/files-orchestrator.mjs";
 import { loadConfigFiles } from "../config/load-config-files.mjs";
+import { installTestFakes, restoreTestFakes } from "./fakes/test-fakes.mjs";
 import { publishTestServerPort, withdrawTestServerPort } from "./test-server-port-channel.mjs";
-import config from "@mongez/config";
+import baseConfig from "@mongez/config";
 
 //#region ../../packages/core/src/tests/start-http-development-server.ts
 /**
@@ -48,16 +50,30 @@ async function startTestServerPhase(phase) {
 * and never falls back to `process.env`.
 */
 async function applyTestServerPort(port) {
-	if (!config.get("http")) {
+	if (!baseConfig.get("http")) {
 		if (port !== void 0) throw new Error(`startHttpTestServer({ port: ${port} }) was given a port, but this app has no \`http\` config, so no HTTP server is started. Add \`src/config/http.ts\` first.`);
-		return;
+		return "none";
 	}
-	if (port !== void 0) config.set("http.port", port);
-	const resolvedPort = config.get("http.port");
+	if (port !== void 0) baseConfig.set("http.port", port);
+	const resolvedPort = baseConfig.get("http.port");
 	if (typeof resolvedPort !== "number") throw new Error(`startHttpTestServer() cannot use \`http.port\` value ${JSON.stringify(resolvedPort)} — it did not round-trip through Number() (env() only coerces a value when \`String(Number(v)) === v\`, so "03999", "+3999", "1e3", and values with stray whitespace stay strings). Fix \`HTTP_PORT\` in .env, or pass an explicit numeric port: startHttpTestServer({ port: 3999 }).`);
-	if (resolvedPort <= 0) throw new Error(`startHttpTestServer() cannot run on port ${resolvedPort}. Pass an explicit port — e.g. startHttpTestServer({ port: 3999 }) — or set \`http.port\` in your config. Test workers are separate processes that resolve the server's URL from the port published at startup, and an OS-assigned port is not knowable to them.`);
-	await assertPortIsAvailable(resolvedPort, config.get("http.host") || "localhost");
+	if (resolvedPort === 0) return "ephemeral";
+	if (resolvedPort < 0) throw new Error(`startHttpTestServer() cannot run on port ${resolvedPort}. Pass a port number, or 0 to let the OS pick a free one — e.g. startHttpTestServer({ port: 0 }).`);
+	await assertPortIsAvailable(resolvedPort, baseConfig.get("http.host") || "localhost");
 	publishTestServerPort(resolvedPort);
+	return "published";
+}
+/**
+* Publish the port an ephemeral (`port: 0`) bind actually took.
+*
+* `before` is the ready report from before the late phase: the report is a
+* module-level record, so an unchanged one means THIS boot bound nothing and an
+* older report must not be mistaken for it.
+*/
+function publishEphemeralPort(before) {
+	const report = getHttpReadyReport();
+	if (!report || report === before || report.port <= 0) throw new Error("startHttpTestServer({ port: 0 }) booted, but the HTTP connector did not bind a port, so there is no address to give the test workers. Check that `src/config/http.ts` exists and that this process serves HTTP (its role is not worker-only).");
+	publishTestServerPort(report.port);
 }
 /**
 * Start the HTTP test server (minimal - no file watching)
@@ -66,6 +82,10 @@ async function applyTestServerPort(port) {
 * @example
 * // run this suite on its own port, whatever `.env` says
 * await startHttpTestServer({ port: 3999 });
+*
+* @example
+* // let the OS pick a free port; the request helpers follow it
+* await startHttpTestServer({ port: 0 });
 */
 async function startHttpTestServer(options = {}) {
 	const nodeEnvironment = process.env.NODE_ENV;
@@ -87,11 +107,14 @@ async function startHttpTestServer(options = {}) {
 		await loadConfigFiles(true);
 		if (options.web === false) await startTestServerPhase("early");
 		else await connectorsManager.startPhase("early");
+		await installTestFakes(options.fakes);
 		await filesOrchestrator.moduleLoader.loadAll();
-		await applyTestServerPort(options.port);
+		const portMode = await applyTestServerPort(options.port);
+		const readyReportBefore = getHttpReadyReport();
 		await Application.runStartupValidators();
 		if (options.web === false) await startTestServerPhase("late");
 		else await connectorsManager.startPhase("late");
+		if (portMode === "ephemeral") publishEphemeralPort(readyReportBefore);
 		isServerRunning = true;
 	} catch (error) {
 		await unwindPartialStartup();
@@ -106,6 +129,11 @@ async function startHttpTestServer(options = {}) {
 * already in flight, and the caller is about to rethrow it.
 */
 async function unwindPartialStartup() {
+	try {
+		await restoreTestFakes();
+	} catch (fakesError) {
+		console.error("[test-server] Restoring the test fakes after a failed start did not complete:", fakesError);
+	}
 	try {
 		await connectorsManager.shutdown();
 	} catch (shutdownError) {
@@ -124,6 +152,11 @@ async function stopHttpTestServer() {
 		return;
 	}
 	try {
+		try {
+			await restoreTestFakes();
+		} catch (fakesError) {
+			console.error("[test-server] Restoring the test fakes did not complete:", fakesError);
+		}
 		await connectorsManager.shutdown();
 		console.log("[test-server] HTTP test server stopped");
 	} catch (error) {

package/esm/tests/start-http-development-server.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"start-http-development-server.mjs","names":[],"sources":["../../../../../../../../packages/core/src/tests/start-http-development-server.ts"],"sourcesContent":["/**\n * HTTP Test Server\n *\n * Starts a minimal HTTP server for testing.\n * Unlike the full DevelopmentServer, this:\n * - Does NOT watch files\n * - Does NOT do HMR\n * - Only starts connectors needed for HTTP requests\n *\n * Used in Vitest's globalSetup to start server once for all test workers.\n */\nimport config from \"@mongez/config\";\nimport { Application } from \"../application\";\nimport { bootstrap } from \"../bootstrap\";\nimport { loadConfigFiles } from \"../config/load-config-files\";\nimport { connectorsManager } from \"../connectors/connectors-manager\";\nimport { ConnectorLifecyclePhase } from \"../connectors/types\";\nimport { filesOrchestrator } from \"../dev-server/files-orchestrator\";\nimport { assertPortIsAvailable } from \"../http/port-preflight\";\nimport { loadEnvironmentFiles } from \"../utils/load-environment\";\nimport { warlockConfigManager } from \"../warlock-config/warlock-config.manager\";\nimport { publishTestServerPort, withdrawTestServerPort } from \"./test-server-port-channel\";\n\nlet isServerRunning = false;\n\nexport type StartHttpTestServerOptions = {\n  /**\n   * Port the test server binds to, overriding `http.port`.\n   *\n   * Needed because the server cannot be moved from outside: this function\n   * bootstraps the app itself, and that bootstrap re-reads `.env`.\n   */\n  port?: number;\n\n  /**\n   * Whether to boot the optional web connector.\n   *\n   * Defaults to `true` to preserve the full-stack test server. Pass `false`\n   * for API-only suites: the web connector's lazy delegate is skipped before\n   * `boot()`, so it never constructs its Vite-backed implementation.\n   *\n   * @default true\n   */\n  web?: boolean;\n};\n\n/**\n * Start one lifecycle phase while omitting the web connector.\n *\n * Kept here rather than changing the manager's public API: this is a\n * test-server-only selection, and retaining the manager's boot-all / start-all\n * ordering is essential for HTTP and socket connector wiring.\n */\nasync function startTestServerPhase(phase: ConnectorLifecyclePhase): Promise<void> {\n  const connectors = connectorsManager\n    .list()\n    .filter((connector) => connector.lifecyclePhase === phase)\n    .filter((connector) => connector.name !== \"web\");\n\n  for (const connector of connectors) {\n    await connector.boot();\n  }\n\n  for (const connector of connectors) {\n    await connector.start();\n  }\n}\n\n/**\n * Apply the caller's port and preflight the bind.\n *\n * Called at the last moment before the HTTP connector binds, and that timing is\n * the fix: `bootstrap()` re-reads `.env` through `loadEnv()` (dotenv overrides\n * by default), and `src/config/http.ts` then resolves its port from that store,\n * so anything the caller set earlier is gone by the time the port is read.\n * Writing into `config` here is also the only channel that works — assigning\n * `process.env.HTTP_PORT` has no effect, since `env()` reads dotenv's own store\n * and never falls back to `process.env`.\n */\nasync function applyTestServerPort(port?: number): Promise<void> {\n  const httpConfig = config.get(\"http\");\n\n  if (!httpConfig) {\n    if (port !== undefined) {\n      throw new Error(\n        `startHttpTestServer({ port: ${port} }) was given a port, but this app has no \\`http\\` config, so no HTTP server is started. Add \\`src/config/http.ts\\` first.`,\n      );\n    }\n\n    return;\n  }\n\n  if (port !== undefined) {\n    config.set(\"http.port\", port);\n  }\n\n  const resolvedPort = config.get(\"http.port\");\n\n  // No configured port at all is fine: Fastify falls back to its own default and\n  // the workers resolve the same one from their own config, so both ends agree\n  // without the channel.\n  //\n  // A non-numeric port is NOT fine, and must fail loudly rather than skip the\n  // preflight silently. `env()` coerces a value only when it round-trips exactly\n  // (`String(Number(v)) === v`), so `HTTP_PORT=3999` and `HTTP_PORT=0` arrive as\n  // numbers, but `03999`, `+3999`, `1e3` and anything with stray whitespace stay\n  // strings. Letting those through used to reach `HttpConnector.start()`'s\n  // `listen({ port })` unchanged — no preflight, no published port, and every\n  // test worker resolving a URL from a channel nothing ever wrote to.\n  if (typeof resolvedPort !== \"number\") {\n    throw new Error(\n      `startHttpTestServer() cannot use \\`http.port\\` value ${JSON.stringify(resolvedPort)} — it did not round-trip through Number() (env() only coerces a value when \\`String(Number(v)) === v\\`, so \"03999\", \"+3999\", \"1e3\", and values with stray whitespace stay strings). Fix \\`HTTP_PORT\\` in .env, or pass an explicit numeric port: startHttpTestServer({ port: 3999 }).`,\n    );\n  }\n\n  // `0` is the OS's \"pick a free one for me\" idiom, and the test server cannot\n  // support it. Preflighting 0 would bind some unrelated ephemeral port and pass\n  // without proving anything, and there is nothing meaningful to publish: the\n  // port Fastify ends up binding is never recorded — `HttpConnector.start()`\n  // stores the port it ASKED for, not the one it got. Accepting 0 silently is\n  // what left `getTestServerUrl()` resolving to `http://host:0` through its own\n  // config fallback, so every worker request went to a port nothing listens on.\n  if (resolvedPort <= 0) {\n    throw new Error(\n      `startHttpTestServer() cannot run on port ${resolvedPort}. Pass an explicit port — e.g. startHttpTestServer({ port: 3999 }) — or set \\`http.port\\` in your config. Test workers are separate processes that resolve the server's URL from the port published at startup, and an OS-assigned port is not knowable to them.`,\n    );\n  }\n\n  await assertPortIsAvailable(resolvedPort, config.get(\"http.host\") || \"localhost\");\n\n  publishTestServerPort(resolvedPort);\n}\n\n/**\n * Start the HTTP test server (minimal - no file watching)\n * Call this in Vitest's globalSetup\n *\n * @example\n * // run this suite on its own port, whatever `.env` says\n * await startHttpTestServer({ port: 3999 });\n */\nexport async function startHttpTestServer(options: StartHttpTestServerOptions = {}): Promise<void> {\n  const nodeEnvironment = process.env.NODE_ENV;\n\n  if (nodeEnvironment === undefined) {\n    process.env.NODE_ENV = \"test\";\n  } else if (nodeEnvironment !== \"test\") {\n    throw new Error(\n      `startHttpTestServer() requires NODE_ENV=\"test\", but received NODE_ENV=${JSON.stringify(nodeEnvironment)}. Set NODE_ENV=test before starting the test server.`,\n    );\n  }\n\n  if (isServerRunning) {\n    console.log(\"[test-server] Server already running, skipping start\");\n    return;\n  }\n\n  console.log(\"[test-server] Starting HTTP test server...\");\n\n  try {\n    // `globalSetup` runs in Vitest's main process, where Vitest's worker env\n    // setup has not run. Load `.env.test` here, before any config is read.\n    await loadEnvironmentFiles();\n\n    // Set environment\n    Application.setRuntimeStrategy(\"development\");\n    Application.setEnvironment(\"test\");\n\n    // Bootstrap (env, etc.)\n    await warlockConfigManager.load();\n    await bootstrap();\n\n    // Initialize file orchestrator (but don't watch)\n    await filesOrchestrator.init();\n    await filesOrchestrator.initializeAll();\n\n    // Load config files\n    await loadConfigFiles(true);\n\n    // Early-phase connectors (database, cache, logger, storage, mailer,\n    // herald) must start BEFORE app modules load: a module's `main.ts` boot\n    // side-effect can query the DB at import time, so the data source has to\n    // be registered first. This mirrors the dev/prod boot order (see\n    // `cli-commands.manager`, `production-builder`, and `DevelopmentServer`).\n    if (options.web === false) {\n      await startTestServerPhase(ConnectorLifecyclePhase.Early);\n    } else {\n      await connectorsManager.startPhase(ConnectorLifecyclePhase.Early);\n    }\n\n    // Load application modules (their boot side-effects now see a live DB).\n    await filesOrchestrator.moduleLoader.loadAll();\n\n    await applyTestServerPort(options.port);\n\n    // A rejecting validator (Application.onValidateBoot) must abort boot\n    // before late-phase connectors bind a port — same slot as\n    // `DevelopmentServer.start()` and the generated production `app.ts`.\n    await Application.runStartupValidators();\n\n    // Late-phase connectors (http, socket) bind after app code has\n    // registered its routes and listeners.\n    if (options.web === false) {\n      await startTestServerPhase(ConnectorLifecyclePhase.Late);\n    } else {\n      await connectorsManager.startPhase(ConnectorLifecyclePhase.Late);\n    }\n\n    isServerRunning = true;\n  } catch (error) {\n    // This function owns the connectors it starts, so a failure part-way\n    // through has to leave nothing behind. Without this, `isServerRunning` was\n    // still `false` — it is only set on the last line — so `globalTeardown`'s\n    // `stopHttpTestServer()` reported \"No server to stop\" and walked away from\n    // live early-phase connectors and a published port that outlived them.\n    await unwindPartialStartup();\n\n    // Rethrown unchanged: the startup failure is the one the caller needs to\n    // read. A cleanup failure that replaced it would hide the actual cause.\n    throw error;\n  }\n}\n\n/**\n * Best-effort teardown of whatever a failed {@link startHttpTestServer} managed\n * to start.\n *\n * Every step is independent and none may throw: this runs while an error is\n * already in flight, and the caller is about to rethrow it.\n */\nasync function unwindPartialStartup(): Promise<void> {\n  try {\n    await connectorsManager.shutdown();\n  } catch (shutdownError) {\n    // Reported, not thrown — it is secondary to the startup error being\n    // rethrown, and losing that one to this would be the worse outcome.\n    console.error(\"[test-server] Cleanup after a failed start did not complete:\", shutdownError);\n  }\n\n  withdrawTestServerPort();\n  isServerRunning = false;\n}\n\n/**\n * Stop the HTTP test server\n * Call this in Vitest's globalTeardown\n */\nexport async function stopHttpTestServer(): Promise<void> {\n  if (!isServerRunning) {\n    console.log(\"[test-server] No server to stop\");\n    return;\n  }\n\n  try {\n    await connectorsManager.shutdown();\n\n    console.log(\"[test-server] HTTP test server stopped\");\n  } catch (error) {\n    // Surfaced, never swallowed — cleaning up is not the same as the shutdown\n    // having succeeded, and a suite whose teardown failed should say so.\n    console.error(\"[test-server] Error stopping HTTP server:\", error);\n\n    throw error;\n  } finally {\n    // In a `finally` rather than after the `await`: when `shutdown()` threw,\n    // the published port survived the server it pointed at, so the next run in\n    // the same process inherited a stale one and sent every request to it.\n    withdrawTestServerPort();\n\n    isServerRunning = false;\n  }\n}\n\n/**\n * Check if test server is running\n */\nexport function isTestServerRunning(): boolean {\n  return isServerRunning;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;AAuBA,IAAI,kBAAkB;;;;;;;;AA8BtB,eAAe,qBAAqB,OAA+C;CACjF,MAAM,aAAa,kBAChB,KAAK,CAAC,CACN,QAAQ,cAAc,UAAU,mBAAmB,KAAK,CAAC,CACzD,QAAQ,cAAc,UAAU,SAAS,KAAK;CAEjD,KAAK,MAAM,aAAa,YACtB,MAAM,UAAU,KAAK;CAGvB,KAAK,MAAM,aAAa,YACtB,MAAM,UAAU,MAAM;AAE1B;;;;;;;;;;;;AAaA,eAAe,oBAAoB,MAA8B;CAG/D,IAAI,CAFe,OAAO,IAAI,MAEhB,GAAG;EACf,IAAI,SAAS,QACX,MAAM,IAAI,MACR,+BAA+B,KAAK,2HACtC;EAGF;CACF;CAEA,IAAI,SAAS,QACX,OAAO,IAAI,aAAa,IAAI;CAG9B,MAAM,eAAe,OAAO,IAAI,WAAW;CAa3C,IAAI,OAAO,iBAAiB,UAC1B,MAAM,IAAI,MACR,wDAAwD,KAAK,UAAU,YAAY,EAAE,sRACvF;CAUF,IAAI,gBAAgB,GAClB,MAAM,IAAI,MACR,4CAA4C,aAAa,iQAC3D;CAGF,MAAM,sBAAsB,cAAc,OAAO,IAAI,WAAW,KAAK,WAAW;CAEhF,sBAAsB,YAAY;AACpC;;;;;;;;;AAUA,eAAsB,oBAAoB,UAAsC,CAAC,GAAkB;CACjG,MAAM,kBAAkB,QAAQ,IAAI;CAEpC,IAAI,oBAAoB,QACtB,QAAQ,IAAI,WAAW;MAClB,IAAI,oBAAoB,QAC7B,MAAM,IAAI,MACR,yEAAyE,KAAK,UAAU,eAAe,EAAE,qDAC3G;CAGF,IAAI,iBAAiB;EACnB,QAAQ,IAAI,sDAAsD;EAClE;CACF;CAEA,QAAQ,IAAI,4CAA4C;CAExD,IAAI;EAGF,MAAM,qBAAqB;EAG3B,YAAY,mBAAmB,aAAa;EAC5C,YAAY,eAAe,MAAM;EAGjC,MAAM,qBAAqB,KAAK;EAChC,MAAM,UAAU;EAGhB,MAAM,kBAAkB,KAAK;EAC7B,MAAM,kBAAkB,cAAc;EAGtC,MAAM,gBAAgB,IAAI;EAO1B,IAAI,QAAQ,QAAQ,OAClB,MAAM,4BAAkD;OAExD,MAAM,kBAAkB,kBAAwC;EAIlE,MAAM,kBAAkB,aAAa,QAAQ;EAE7C,MAAM,oBAAoB,QAAQ,IAAI;EAKtC,MAAM,YAAY,qBAAqB;EAIvC,IAAI,QAAQ,QAAQ,OAClB,MAAM,2BAAiD;OAEvD,MAAM,kBAAkB,iBAAuC;EAGjE,kBAAkB;CACpB,SAAS,OAAO;EAMd,MAAM,qBAAqB;EAI3B,MAAM;CACR;AACF;;;;;;;;AASA,eAAe,uBAAsC;CACnD,IAAI;EACF,MAAM,kBAAkB,SAAS;CACnC,SAAS,eAAe;EAGtB,QAAQ,MAAM,gEAAgE,aAAa;CAC7F;CAEA,uBAAuB;CACvB,kBAAkB;AACpB;;;;;AAMA,eAAsB,qBAAoC;CACxD,IAAI,CAAC,iBAAiB;EACpB,QAAQ,IAAI,iCAAiC;EAC7C;CACF;CAEA,IAAI;EACF,MAAM,kBAAkB,SAAS;EAEjC,QAAQ,IAAI,wCAAwC;CACtD,SAAS,OAAO;EAGd,QAAQ,MAAM,6CAA6C,KAAK;EAEhE,MAAM;CACR,UAAU;EAIR,uBAAuB;EAEvB,kBAAkB;CACpB;AACF;;;;AAKA,SAAgB,sBAA+B;CAC7C,OAAO;AACT"}
+{"version":3,"file":"start-http-development-server.mjs","names":["config"],"sources":["../../../../../../../../packages/core/src/tests/start-http-development-server.ts"],"sourcesContent":["/**\n * HTTP Test Server\n *\n * Starts a minimal HTTP server for testing.\n * Unlike the full DevelopmentServer, this:\n * - Does NOT watch files\n * - Does NOT do HMR\n * - Only starts connectors needed for HTTP requests\n *\n * Used in Vitest's globalSetup to start server once for all test workers.\n */\nimport config from \"@mongez/config\";\nimport { Application } from \"../application\";\nimport { bootstrap } from \"../bootstrap\";\nimport { loadConfigFiles } from \"../config/load-config-files\";\nimport { connectorsManager } from \"../connectors/connectors-manager\";\nimport { ConnectorLifecyclePhase } from \"../connectors/types\";\nimport { filesOrchestrator } from \"../dev-server/files-orchestrator\";\nimport { assertPortIsAvailable } from \"../http/port-preflight\";\nimport { getHttpReadyReport } from \"../http/ready-report\";\nimport { loadEnvironmentFiles } from \"../utils/load-environment\";\nimport { warlockConfigManager } from \"../warlock-config/warlock-config.manager\";\nimport { installTestFakes, restoreTestFakes } from \"./fakes/test-fakes\";\nimport type { TestFakesSelection } from \"./fakes/test-fakes\";\nimport { publishTestServerPort, withdrawTestServerPort } from \"./test-server-port-channel\";\n\nlet isServerRunning = false;\n\nexport type StartHttpTestServerOptions = {\n  /**\n   * Port the test server binds to, overriding `http.port`.\n   *\n   * Needed because the server cannot be moved from outside: this function\n   * bootstraps the app itself, and that bootstrap re-reads `.env`.\n   *\n   * `0` asks the OS for a free port. The port actually bound is published to\n   * the test workers, so `testGet()`, `actingAs()` and friends follow it, and\n   * a suite never collides with `warlock dev` or another suite.\n   */\n  port?: number;\n\n  /**\n   * Whether to boot the optional web connector.\n   *\n   * Defaults to `true` to preserve the full-stack test server. Pass `false`\n   * for API-only suites: the web connector's lazy delegate is skipped before\n   * `boot()`, so it never constructs its Vite-backed implementation.\n   *\n   * @default true\n   */\n  web?: boolean;\n\n  /**\n   * Which test fakes the server process installs (mail, queue, cache,\n   * storage, clock, ids). Same values and precedence as `setupTest({ fakes })`:\n   * this option > `tests.fakes` config > all on.\n   *\n   * A fake records what happens in ITS process: mail sent while this server\n   * handles a request is captured here, not in the test worker that sent the\n   * request. To assert on what an HTTP request did, serve it in the worker\n   * with `createTestHttpServer()`. The storage fake is the exception: its\n   * temp root is shared with the workers.\n   */\n  fakes?: TestFakesSelection;\n};\n\n/**\n * Start one lifecycle phase while omitting the web connector.\n *\n * Kept here rather than changing the manager's public API: this is a\n * test-server-only selection, and retaining the manager's boot-all / start-all\n * ordering is essential for HTTP and socket connector wiring.\n */\nasync function startTestServerPhase(phase: ConnectorLifecyclePhase): Promise<void> {\n  const connectors = connectorsManager\n    .list()\n    .filter((connector) => connector.lifecyclePhase === phase)\n    .filter((connector) => connector.name !== \"web\");\n\n  for (const connector of connectors) {\n    await connector.boot();\n  }\n\n  for (const connector of connectors) {\n    await connector.start();\n  }\n}\n\n/**\n * Apply the caller's port and preflight the bind.\n *\n * Called at the last moment before the HTTP connector binds, and that timing is\n * the fix: `bootstrap()` re-reads `.env` through `loadEnv()` (dotenv overrides\n * by default), and `src/config/http.ts` then resolves its port from that store,\n * so anything the caller set earlier is gone by the time the port is read.\n * Writing into `config` here is also the only channel that works — assigning\n * `process.env.HTTP_PORT` has no effect, since `env()` reads dotenv's own store\n * and never falls back to `process.env`.\n */\nasync function applyTestServerPort(port?: number): Promise<\"published\" | \"ephemeral\" | \"none\"> {\n  const httpConfig = config.get(\"http\");\n\n  if (!httpConfig) {\n    if (port !== undefined) {\n      throw new Error(\n        `startHttpTestServer({ port: ${port} }) was given a port, but this app has no \\`http\\` config, so no HTTP server is started. Add \\`src/config/http.ts\\` first.`,\n      );\n    }\n\n    return \"none\";\n  }\n\n  if (port !== undefined) {\n    config.set(\"http.port\", port);\n  }\n\n  const resolvedPort = config.get(\"http.port\");\n\n  // No configured port at all is fine: Fastify falls back to its own default and\n  // the workers resolve the same one from their own config, so both ends agree\n  // without the channel.\n  //\n  // A non-numeric port is NOT fine, and must fail loudly rather than skip the\n  // preflight silently. `env()` coerces a value only when it round-trips exactly\n  // (`String(Number(v)) === v`), so `HTTP_PORT=3999` and `HTTP_PORT=0` arrive as\n  // numbers, but `03999`, `+3999`, `1e3` and anything with stray whitespace stay\n  // strings. Letting those through used to reach `HttpConnector.start()`'s\n  // `listen({ port })` unchanged — no preflight, no published port, and every\n  // test worker resolving a URL from a channel nothing ever wrote to.\n  if (typeof resolvedPort !== \"number\") {\n    throw new Error(\n      `startHttpTestServer() cannot use \\`http.port\\` value ${JSON.stringify(resolvedPort)} — it did not round-trip through Number() (env() only coerces a value when \\`String(Number(v)) === v\\`, so \"03999\", \"+3999\", \"1e3\", and values with stray whitespace stay strings). Fix \\`HTTP_PORT\\` in .env, or pass an explicit numeric port: startHttpTestServer({ port: 3999 }).`,\n    );\n  }\n\n  // `0` is the OS's \"pick a free one for me\". There is nothing to preflight —\n  // probing 0 would bind some unrelated port and prove nothing — and nothing to\n  // publish yet: the port is only known once the HTTP connector has bound, and\n  // `HttpConnector.start()` records the port `listen()` actually returned (see\n  // `ready-report.ts`). It is published right after the late phase instead.\n  if (resolvedPort === 0) {\n    return \"ephemeral\";\n  }\n\n  if (resolvedPort < 0) {\n    throw new Error(\n      `startHttpTestServer() cannot run on port ${resolvedPort}. Pass a port number, or 0 to let the OS pick a free one — e.g. startHttpTestServer({ port: 0 }).`,\n    );\n  }\n\n  await assertPortIsAvailable(resolvedPort, config.get(\"http.host\") || \"localhost\");\n\n  publishTestServerPort(resolvedPort);\n\n  return \"published\";\n}\n\n/**\n * Publish the port an ephemeral (`port: 0`) bind actually took.\n *\n * `before` is the ready report from before the late phase: the report is a\n * module-level record, so an unchanged one means THIS boot bound nothing and an\n * older report must not be mistaken for it.\n */\nfunction publishEphemeralPort(before: ReturnType<typeof getHttpReadyReport>): void {\n  const report = getHttpReadyReport();\n\n  if (!report || report === before || report.port <= 0) {\n    throw new Error(\n      \"startHttpTestServer({ port: 0 }) booted, but the HTTP connector did not bind a port, so there is no address to give the test workers. Check that `src/config/http.ts` exists and that this process serves HTTP (its role is not worker-only).\",\n    );\n  }\n\n  publishTestServerPort(report.port);\n}\n\n/**\n * Start the HTTP test server (minimal - no file watching)\n * Call this in Vitest's globalSetup\n *\n * @example\n * // run this suite on its own port, whatever `.env` says\n * await startHttpTestServer({ port: 3999 });\n *\n * @example\n * // let the OS pick a free port; the request helpers follow it\n * await startHttpTestServer({ port: 0 });\n */\nexport async function startHttpTestServer(options: StartHttpTestServerOptions = {}): Promise<void> {\n  const nodeEnvironment = process.env.NODE_ENV;\n\n  if (nodeEnvironment === undefined) {\n    process.env.NODE_ENV = \"test\";\n  } else if (nodeEnvironment !== \"test\") {\n    throw new Error(\n      `startHttpTestServer() requires NODE_ENV=\"test\", but received NODE_ENV=${JSON.stringify(nodeEnvironment)}. Set NODE_ENV=test before starting the test server.`,\n    );\n  }\n\n  if (isServerRunning) {\n    console.log(\"[test-server] Server already running, skipping start\");\n    return;\n  }\n\n  console.log(\"[test-server] Starting HTTP test server...\");\n\n  try {\n    // `globalSetup` runs in Vitest's main process, where Vitest's worker env\n    // setup has not run. Load `.env.test` here, before any config is read.\n    await loadEnvironmentFiles();\n\n    // Set environment\n    Application.setRuntimeStrategy(\"development\");\n    Application.setEnvironment(\"test\");\n\n    // Bootstrap (env, etc.)\n    await warlockConfigManager.load();\n    await bootstrap();\n\n    // Initialize file orchestrator (but don't watch)\n    await filesOrchestrator.init();\n    await filesOrchestrator.initializeAll();\n\n    // Load config files\n    await loadConfigFiles(true);\n\n    // Early-phase connectors (database, cache, logger, storage, mailer,\n    // herald) must start BEFORE app modules load: a module's `main.ts` boot\n    // side-effect can query the DB at import time, so the data source has to\n    // be registered first. This mirrors the dev/prod boot order (see\n    // `cli-commands.manager`, `production-builder`, and `DevelopmentServer`).\n    if (options.web === false) {\n      await startTestServerPhase(ConnectorLifecyclePhase.Early);\n    } else {\n      await connectorsManager.startPhase(ConnectorLifecyclePhase.Early);\n    }\n\n    // Fakes before app modules load, so module boot code already sees them.\n    await installTestFakes(options.fakes);\n\n    // Load application modules (their boot side-effects now see a live DB).\n    await filesOrchestrator.moduleLoader.loadAll();\n\n    const portMode = await applyTestServerPort(options.port);\n    const readyReportBefore = getHttpReadyReport();\n\n    // A rejecting validator (Application.onValidateBoot) must abort boot\n    // before late-phase connectors bind a port — same slot as\n    // `DevelopmentServer.start()` and the generated production `app.ts`.\n    await Application.runStartupValidators();\n\n    // Late-phase connectors (http, socket) bind after app code has\n    // registered its routes and listeners.\n    if (options.web === false) {\n      await startTestServerPhase(ConnectorLifecyclePhase.Late);\n    } else {\n      await connectorsManager.startPhase(ConnectorLifecyclePhase.Late);\n    }\n\n    if (portMode === \"ephemeral\") {\n      publishEphemeralPort(readyReportBefore);\n    }\n\n    isServerRunning = true;\n  } catch (error) {\n    // This function owns the connectors it starts, so a failure part-way\n    // through has to leave nothing behind. Without this, `isServerRunning` was\n    // still `false` — it is only set on the last line — so `globalTeardown`'s\n    // `stopHttpTestServer()` reported \"No server to stop\" and walked away from\n    // live early-phase connectors and a published port that outlived them.\n    await unwindPartialStartup();\n\n    // Rethrown unchanged: the startup failure is the one the caller needs to\n    // read. A cleanup failure that replaced it would hide the actual cause.\n    throw error;\n  }\n}\n\n/**\n * Best-effort teardown of whatever a failed {@link startHttpTestServer} managed\n * to start.\n *\n * Every step is independent and none may throw: this runs while an error is\n * already in flight, and the caller is about to rethrow it.\n */\nasync function unwindPartialStartup(): Promise<void> {\n  try {\n    await restoreTestFakes();\n  } catch (fakesError) {\n    console.error(\n      \"[test-server] Restoring the test fakes after a failed start did not complete:\",\n      fakesError,\n    );\n  }\n\n  try {\n    await connectorsManager.shutdown();\n  } catch (shutdownError) {\n    // Reported, not thrown — it is secondary to the startup error being\n    // rethrown, and losing that one to this would be the worse outcome.\n    console.error(\"[test-server] Cleanup after a failed start did not complete:\", shutdownError);\n  }\n\n  withdrawTestServerPort();\n  isServerRunning = false;\n}\n\n/**\n * Stop the HTTP test server\n * Call this in Vitest's globalTeardown\n */\nexport async function stopHttpTestServer(): Promise<void> {\n  if (!isServerRunning) {\n    console.log(\"[test-server] No server to stop\");\n    return;\n  }\n\n  try {\n    try {\n      await restoreTestFakes();\n    } catch (fakesError) {\n      console.error(\"[test-server] Restoring the test fakes did not complete:\", fakesError);\n    }\n\n    await connectorsManager.shutdown();\n\n    console.log(\"[test-server] HTTP test server stopped\");\n  } catch (error) {\n    // Surfaced, never swallowed — cleaning up is not the same as the shutdown\n    // having succeeded, and a suite whose teardown failed should say so.\n    console.error(\"[test-server] Error stopping HTTP server:\", error);\n\n    throw error;\n  } finally {\n    // In a `finally` rather than after the `await`: when `shutdown()` threw,\n    // the published port survived the server it pointed at, so the next run in\n    // the same process inherited a stale one and sent every request to it.\n    withdrawTestServerPort();\n\n    isServerRunning = false;\n  }\n}\n\n/**\n * Check if test server is running\n */\nexport function isTestServerRunning(): boolean {\n  return isServerRunning;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;AA0BA,IAAI,kBAAkB;;;;;;;;AA+CtB,eAAe,qBAAqB,OAA+C;CACjF,MAAM,aAAa,kBAChB,KAAK,CAAC,CACN,QAAQ,cAAc,UAAU,mBAAmB,KAAK,CAAC,CACzD,QAAQ,cAAc,UAAU,SAAS,KAAK;CAEjD,KAAK,MAAM,aAAa,YACtB,MAAM,UAAU,KAAK;CAGvB,KAAK,MAAM,aAAa,YACtB,MAAM,UAAU,MAAM;AAE1B;;;;;;;;;;;;AAaA,eAAe,oBAAoB,MAA4D;CAG7F,IAAI,CAFeA,WAAO,IAAI,MAEhB,GAAG;EACf,IAAI,SAAS,QACX,MAAM,IAAI,MACR,+BAA+B,KAAK,2HACtC;EAGF,OAAO;CACT;CAEA,IAAI,SAAS,QACX,WAAO,IAAI,aAAa,IAAI;CAG9B,MAAM,eAAeA,WAAO,IAAI,WAAW;CAa3C,IAAI,OAAO,iBAAiB,UAC1B,MAAM,IAAI,MACR,wDAAwD,KAAK,UAAU,YAAY,EAAE,sRACvF;CAQF,IAAI,iBAAiB,GACnB,OAAO;CAGT,IAAI,eAAe,GACjB,MAAM,IAAI,MACR,4CAA4C,aAAa,kGAC3D;CAGF,MAAM,sBAAsB,cAAcA,WAAO,IAAI,WAAW,KAAK,WAAW;CAEhF,sBAAsB,YAAY;CAElC,OAAO;AACT;;;;;;;;AASA,SAAS,qBAAqB,QAAqD;CACjF,MAAM,SAAS,mBAAmB;CAElC,IAAI,CAAC,UAAU,WAAW,UAAU,OAAO,QAAQ,GACjD,MAAM,IAAI,MACR,+OACF;CAGF,sBAAsB,OAAO,IAAI;AACnC;;;;;;;;;;;;;AAcA,eAAsB,oBAAoB,UAAsC,CAAC,GAAkB;CACjG,MAAM,kBAAkB,QAAQ,IAAI;CAEpC,IAAI,oBAAoB,QACtB,QAAQ,IAAI,WAAW;MAClB,IAAI,oBAAoB,QAC7B,MAAM,IAAI,MACR,yEAAyE,KAAK,UAAU,eAAe,EAAE,qDAC3G;CAGF,IAAI,iBAAiB;EACnB,QAAQ,IAAI,sDAAsD;EAClE;CACF;CAEA,QAAQ,IAAI,4CAA4C;CAExD,IAAI;EAGF,MAAM,qBAAqB;EAG3B,YAAY,mBAAmB,aAAa;EAC5C,YAAY,eAAe,MAAM;EAGjC,MAAM,qBAAqB,KAAK;EAChC,MAAM,UAAU;EAGhB,MAAM,kBAAkB,KAAK;EAC7B,MAAM,kBAAkB,cAAc;EAGtC,MAAM,gBAAgB,IAAI;EAO1B,IAAI,QAAQ,QAAQ,OAClB,MAAM,4BAAkD;OAExD,MAAM,kBAAkB,kBAAwC;EAIlE,MAAM,iBAAiB,QAAQ,KAAK;EAGpC,MAAM,kBAAkB,aAAa,QAAQ;EAE7C,MAAM,WAAW,MAAM,oBAAoB,QAAQ,IAAI;EACvD,MAAM,oBAAoB,mBAAmB;EAK7C,MAAM,YAAY,qBAAqB;EAIvC,IAAI,QAAQ,QAAQ,OAClB,MAAM,2BAAiD;OAEvD,MAAM,kBAAkB,iBAAuC;EAGjE,IAAI,aAAa,aACf,qBAAqB,iBAAiB;EAGxC,kBAAkB;CACpB,SAAS,OAAO;EAMd,MAAM,qBAAqB;EAI3B,MAAM;CACR;AACF;;;;;;;;AASA,eAAe,uBAAsC;CACnD,IAAI;EACF,MAAM,iBAAiB;CACzB,SAAS,YAAY;EACnB,QAAQ,MACN,iFACA,UACF;CACF;CAEA,IAAI;EACF,MAAM,kBAAkB,SAAS;CACnC,SAAS,eAAe;EAGtB,QAAQ,MAAM,gEAAgE,aAAa;CAC7F;CAEA,uBAAuB;CACvB,kBAAkB;AACpB;;;;;AAMA,eAAsB,qBAAoC;CACxD,IAAI,CAAC,iBAAiB;EACpB,QAAQ,IAAI,iCAAiC;EAC7C;CACF;CAEA,IAAI;EACF,IAAI;GACF,MAAM,iBAAiB;EACzB,SAAS,YAAY;GACnB,QAAQ,MAAM,4DAA4D,UAAU;EACtF;EAEA,MAAM,kBAAkB,SAAS;EAEjC,QAAQ,IAAI,wCAAwC;CACtD,SAAS,OAAO;EAGd,QAAQ,MAAM,6CAA6C,KAAK;EAEhE,MAAM;CACR,UAAU;EAIR,uBAAuB;EAEvB,kBAAkB;CACpB;AACF;;;;AAKA,SAAgB,sBAA+B;CAC7C,OAAO;AACT"}

package/esm/tests/test-connectors-selection.d.mts

@@ -1,4 +1,5 @@
 import { ConnectorName } from "../connectors/types.mjs";
+import "../connectors/index.mjs";
 //#region ../../packages/core/src/tests/test-connectors-selection.d.ts
 /**
  * What a test runtime was asked to start.
@@ -8,7 +9,6 @@ import { ConnectorName } from "../connectors/types.mjs";
  * - an array — start exactly those. Order is not promised; lifecycle priority
  *   decides the real boot/shutdown order.
  */
-type TestConnectorsSelection = boolean | ConnectorName[];
+export type TestConnectorsSelection = boolean | ConnectorName[];
 //#endregion
-export { TestConnectorsSelection };
 //# sourceMappingURL=test-connectors-selection.d.mts.map

package/esm/tests/test-connectors-selection.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"test-connectors-selection.d.mts","names":[],"sources":["../../../../../../../../packages/core/src/tests/test-connectors-selection.ts"],"mappings":";;;;;AAqBA;;;;AAA6D;KAAjD,uBAAA,aAAoC,aAAa"}
+{"version":3,"file":"test-connectors-selection.d.mts","names":[],"sources":["../../../../../../../../packages/core/src/tests/test-connectors-selection.ts"],"mappings":";;;;;;;;;;;YAqBY,oCAAoC"}

package/esm/tests/test-connectors-selection.mjs

@@ -68,5 +68,5 @@ function describeConnectorsSelection(selection) {
 }
 
 //#endregion
-export { describeConnectorsSelection, isSameConnectorsSelection, normalizeConnectorNames, readRequestedConnectors, resolveEffectiveConnectors };
+export { describeConnectorsSelection, isSameConnectorsSelection, normalizeConnectorNames, readConfiguredConnectors, readRequestedConnectors, resolveEffectiveConnectors };
 //# sourceMappingURL=test-connectors-selection.mjs.map