@warlock.js/core 5.29.0 → 5.31.0

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

@@ -1,10 +1,16 @@
-//#region ../core/src/tests/start-http-development-server.d.ts
+import { TestFakesSelection } from "./fakes/test-fakes.mjs";
+
+//#region ../../packages/core/src/tests/start-http-development-server.d.ts
 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 +23,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,6 +43,10 @@ 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>;
 /**

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

@@ -1 +1 @@
-{"version":3,"file":"start-http-development-server.d.mts","names":[],"sources":["../../../../../../../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":";;;KA4BY,0BAAA;;AAAZ;;;;;;;;;EAWE,IAAA;EAqJoB;;;;;;;;AAAsE;EA1I1F,GAAA;EAqQsC;;;AAAW;AAmCnD;;;;AAAmC;;;EA3RjC,KAAA,GAAQ,kBAAkB;AAAA;;;;;;;;;;;;;iBA6HN,mBAAA,CAAoB,OAAA,GAAS,0BAAA,GAAkC,OAAO;;;;;iBA2HtE,kBAAA,IAAsB,OAAO;;;;iBAmCnC,mBAAA"}

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,10 +9,11 @@ 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";
 
-//#region ../core/src/tests/start-http-development-server.ts
+//#region ../../packages/core/src/tests/start-http-development-server.ts
 /**
 * HTTP Test Server
 *
@@ -50,14 +52,28 @@ async function startTestServerPhase(phase) {
 async function applyTestServerPort(port) {
 	if (!config.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 (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.`);
+	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, config.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":["../../../../../../../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":[],"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,CAFe,OAAO,IAAI,MAEhB,GAAG;EACf,IAAI,SAAS,QACX,MAAM,IAAI,MACR,+BAA+B,KAAK,2HACtC;EAGF,OAAO;CACT;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;CAQF,IAAI,iBAAiB,GACnB,OAAO;CAGT,IAAI,eAAe,GACjB,MAAM,IAAI,MACR,4CAA4C,aAAa,kGAC3D;CAGF,MAAM,sBAAsB,cAAc,OAAO,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,5 +1,5 @@
 import { ConnectorName } from "../connectors/types.mjs";
-//#region ../core/src/tests/test-connectors-selection.d.ts
+//#region ../../packages/core/src/tests/test-connectors-selection.d.ts
 /**
  * What a test runtime was asked to start.
  *

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

@@ -1 +1 @@
-{"version":3,"file":"test-connectors-selection.d.mts","names":[],"sources":["../../../../../../../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":";;;;;AAqBA;;;;AAA6D;KAAjD,uBAAA,aAAoC,aAAa"}

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

@@ -1,7 +1,7 @@
 import { config } from "../config/config-getter.mjs";
 import "../config/index.mjs";
 
-//#region ../core/src/tests/test-connectors-selection.ts
+//#region ../../packages/core/src/tests/test-connectors-selection.ts
 /**
 * Classify the caller's `connectors` option as explicit or deferred.
 */

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

@@ -1 +1 @@
-{"version":3,"file":"test-connectors-selection.mjs","names":[],"sources":["../../../../../../../core/src/tests/test-connectors-selection.ts"],"sourcesContent":["/**\n * Effective connector selection for the worker test lifecycle.\n *\n * Owns one decision: given what the caller passed and what the project\n * configured, which connectors does `setupTest` actually start? The precedence\n * is ratified in `contracts/2026-08-12-test-worker-lifecycle.md`:\n *\n *     explicit non-`undefined` setupTest option > tests.connectors config > true\n */\nimport type { GenericObject } from \"@mongez/reinforcements\";\nimport { config } from \"../config\";\nimport type { ConnectorName } from \"../connectors\";\n\n/**\n * What a test runtime was asked to start.\n *\n * - `false` — bootstrap the runtime, start no connectors.\n * - `true` — start the framework's default connector set.\n * - an array — start exactly those. Order is not promised; lifecycle priority\n *   decides the real boot/shutdown order.\n */\nexport type TestConnectorsSelection = boolean | ConnectorName[];\n\n/**\n * A caller's request, before the lower precedence layers are consulted.\n *\n * The distinction that matters is \"did the caller supply a value at all\", not\n * \"what value\" — `setupTest({ connectors: undefined })` must fall through to\n * project config exactly like `setupTest()` does, so an optional variable\n * holding `undefined` can never silently erase a project's configuration.\n */\nexport type RequestedTestConnectors =\n  | { readonly isExplicit: true; readonly selection: TestConnectorsSelection }\n  | { readonly isExplicit: false };\n\n/**\n * Classify the caller's `connectors` option as explicit or deferred.\n */\nexport function readRequestedConnectors(\n  selection: TestConnectorsSelection | undefined,\n): RequestedTestConnectors {\n  if (selection === undefined) {\n    return { isExplicit: false };\n  }\n\n  return { isExplicit: true, selection };\n}\n\n/**\n * Read the `tests.connectors` config layer, or `undefined` when the project has\n * not configured one.\n *\n * Only meaningful once config files are loaded — before that, every project\n * looks like a project without a `tests` config.\n */\nexport function readConfiguredConnectors(): TestConnectorsSelection | undefined {\n  // The default matters: `config.get` resolves an absent key to its default, and\n  // ITS default is `null` — not `{}`. `warlock add test` does not generate\n  // `src/config/tests.ts`, so reading `.connectors` off the result threw\n  // \"Cannot read properties of null\" on the generated default path.\n  const testsConfig = config.get<GenericObject>(\"tests\", {});\n\n  // Cast at the config boundary: `GenericObject` values are untyped, and this is\n  // the one place the untyped value becomes a typed selection.\n  return testsConfig?.connectors as TestConnectorsSelection | undefined;\n}\n\n/**\n * Apply the ratified precedence:\n *\n *     explicit non-`undefined` setupTest option > tests.connectors config > true\n *\n * ⚠ This is the reverse of 4.13, where config won over the parameter. Explicit\n * call-site intent beats a project default; a call that supplied nothing is not\n * intent, which is why \"omitted\" and \"explicitly `undefined`\" both defer.\n */\nexport function resolveEffectiveConnectors(\n  requested: RequestedTestConnectors,\n): TestConnectorsSelection {\n  if (requested.isExplicit) {\n    return requested.selection;\n  }\n\n  const configured = readConfiguredConnectors();\n\n  if (configured !== undefined) {\n    return configured;\n  }\n\n  return true;\n}\n\n/**\n * Deduplicate a connector list and put it in a stable order.\n *\n * Two callers naming the same connectors in a different order asked for the same\n * thing, so the lifecycle must not treat them as a conflict.\n */\nexport function normalizeConnectorNames(names: ConnectorName[]): ConnectorName[] {\n  return [...new Set(names)].sort();\n}\n\n/**\n * Compare two selections by normalized semantics — arrays as deduplicated sets,\n * never by caller order.\n */\nexport function isSameConnectorsSelection(\n  left: TestConnectorsSelection,\n  right: TestConnectorsSelection,\n): boolean {\n  if (Array.isArray(left) && Array.isArray(right)) {\n    const normalizedLeft = normalizeConnectorNames(left);\n    const normalizedRight = normalizeConnectorNames(right);\n\n    return (\n      normalizedLeft.length === normalizedRight.length &&\n      normalizedLeft.every((name, index) => name === normalizedRight[index])\n    );\n  }\n\n  return left === right;\n}\n\n/**\n * Render a selection for an error message a caller can act on.\n */\nexport function describeConnectorsSelection(selection: TestConnectorsSelection): string {\n  if (selection === true) {\n    return \"the default connector set (`connectors: true`)\";\n  }\n\n  if (selection === false) {\n    return \"no connectors (`connectors: false`)\";\n  }\n\n  const names = normalizeConnectorNames(selection)\n    .map((name) => `\"${name}\"`)\n    .join(\", \");\n\n  return `\\`connectors: [${names}]\\``;\n}\n"],"mappings":";;;;;;;AAsCA,SAAgB,wBACd,WACyB;CACzB,IAAI,cAAc,QAChB,OAAO,EAAE,YAAY,MAAM;CAG7B,OAAO;EAAE,YAAY;EAAM;CAAU;AACvC;;;;;;;;AASA,SAAgB,2BAAgE;CAS9E,OAJoB,OAAO,IAAmB,SAAS,CAAC,CAIvC,CAAC,EAAE;AACtB;;;;;;;;;;AAWA,SAAgB,2BACd,WACyB;CACzB,IAAI,UAAU,YACZ,OAAO,UAAU;CAGnB,MAAM,aAAa,yBAAyB;CAE5C,IAAI,eAAe,QACjB,OAAO;CAGT,OAAO;AACT;;;;;;;AAQA,SAAgB,wBAAwB,OAAyC;CAC/E,OAAO,CAAC,GAAG,IAAI,IAAI,KAAK,CAAC,CAAC,CAAC,KAAK;AAClC;;;;;AAMA,SAAgB,0BACd,MACA,OACS;CACT,IAAI,MAAM,QAAQ,IAAI,KAAK,MAAM,QAAQ,KAAK,GAAG;EAC/C,MAAM,iBAAiB,wBAAwB,IAAI;EACnD,MAAM,kBAAkB,wBAAwB,KAAK;EAErD,OACE,eAAe,WAAW,gBAAgB,UAC1C,eAAe,OAAO,MAAM,UAAU,SAAS,gBAAgB,MAAM;CAEzE;CAEA,OAAO,SAAS;AAClB;;;;AAKA,SAAgB,4BAA4B,WAA4C;CACtF,IAAI,cAAc,MAChB,OAAO;CAGT,IAAI,cAAc,OAChB,OAAO;CAOT,OAAO,kBAJO,wBAAwB,SAAS,CAAC,CAC7C,KAAK,SAAS,IAAI,KAAK,EAAE,CAAC,CAC1B,KAAK,IAEqB,EAAE;AACjC"}
+{"version":3,"file":"test-connectors-selection.mjs","names":[],"sources":["../../../../../../../../packages/core/src/tests/test-connectors-selection.ts"],"sourcesContent":["/**\n * Effective connector selection for the worker test lifecycle.\n *\n * Owns one decision: given what the caller passed and what the project\n * configured, which connectors does `setupTest` actually start? The precedence\n * is ratified in `contracts/2026-08-12-test-worker-lifecycle.md`:\n *\n *     explicit non-`undefined` setupTest option > tests.connectors config > true\n */\nimport type { GenericObject } from \"@mongez/reinforcements\";\nimport { config } from \"../config\";\nimport type { ConnectorName } from \"../connectors\";\n\n/**\n * What a test runtime was asked to start.\n *\n * - `false` — bootstrap the runtime, start no connectors.\n * - `true` — start the framework's default connector set.\n * - an array — start exactly those. Order is not promised; lifecycle priority\n *   decides the real boot/shutdown order.\n */\nexport type TestConnectorsSelection = boolean | ConnectorName[];\n\n/**\n * A caller's request, before the lower precedence layers are consulted.\n *\n * The distinction that matters is \"did the caller supply a value at all\", not\n * \"what value\" — `setupTest({ connectors: undefined })` must fall through to\n * project config exactly like `setupTest()` does, so an optional variable\n * holding `undefined` can never silently erase a project's configuration.\n */\nexport type RequestedTestConnectors =\n  | { readonly isExplicit: true; readonly selection: TestConnectorsSelection }\n  | { readonly isExplicit: false };\n\n/**\n * Classify the caller's `connectors` option as explicit or deferred.\n */\nexport function readRequestedConnectors(\n  selection: TestConnectorsSelection | undefined,\n): RequestedTestConnectors {\n  if (selection === undefined) {\n    return { isExplicit: false };\n  }\n\n  return { isExplicit: true, selection };\n}\n\n/**\n * Read the `tests.connectors` config layer, or `undefined` when the project has\n * not configured one.\n *\n * Only meaningful once config files are loaded — before that, every project\n * looks like a project without a `tests` config.\n */\nexport function readConfiguredConnectors(): TestConnectorsSelection | undefined {\n  // The default matters: `config.get` resolves an absent key to its default, and\n  // ITS default is `null` — not `{}`. `warlock add test` does not generate\n  // `src/config/tests.ts`, so reading `.connectors` off the result threw\n  // \"Cannot read properties of null\" on the generated default path.\n  const testsConfig = config.get<GenericObject>(\"tests\", {});\n\n  // Cast at the config boundary: `GenericObject` values are untyped, and this is\n  // the one place the untyped value becomes a typed selection.\n  return testsConfig?.connectors as TestConnectorsSelection | undefined;\n}\n\n/**\n * Apply the ratified precedence:\n *\n *     explicit non-`undefined` setupTest option > tests.connectors config > true\n *\n * ⚠ This is the reverse of 4.13, where config won over the parameter. Explicit\n * call-site intent beats a project default; a call that supplied nothing is not\n * intent, which is why \"omitted\" and \"explicitly `undefined`\" both defer.\n */\nexport function resolveEffectiveConnectors(\n  requested: RequestedTestConnectors,\n): TestConnectorsSelection {\n  if (requested.isExplicit) {\n    return requested.selection;\n  }\n\n  const configured = readConfiguredConnectors();\n\n  if (configured !== undefined) {\n    return configured;\n  }\n\n  return true;\n}\n\n/**\n * Deduplicate a connector list and put it in a stable order.\n *\n * Two callers naming the same connectors in a different order asked for the same\n * thing, so the lifecycle must not treat them as a conflict.\n */\nexport function normalizeConnectorNames(names: ConnectorName[]): ConnectorName[] {\n  return [...new Set(names)].sort();\n}\n\n/**\n * Compare two selections by normalized semantics — arrays as deduplicated sets,\n * never by caller order.\n */\nexport function isSameConnectorsSelection(\n  left: TestConnectorsSelection,\n  right: TestConnectorsSelection,\n): boolean {\n  if (Array.isArray(left) && Array.isArray(right)) {\n    const normalizedLeft = normalizeConnectorNames(left);\n    const normalizedRight = normalizeConnectorNames(right);\n\n    return (\n      normalizedLeft.length === normalizedRight.length &&\n      normalizedLeft.every((name, index) => name === normalizedRight[index])\n    );\n  }\n\n  return left === right;\n}\n\n/**\n * Render a selection for an error message a caller can act on.\n */\nexport function describeConnectorsSelection(selection: TestConnectorsSelection): string {\n  if (selection === true) {\n    return \"the default connector set (`connectors: true`)\";\n  }\n\n  if (selection === false) {\n    return \"no connectors (`connectors: false`)\";\n  }\n\n  const names = normalizeConnectorNames(selection)\n    .map((name) => `\"${name}\"`)\n    .join(\", \");\n\n  return `\\`connectors: [${names}]\\``;\n}\n"],"mappings":";;;;;;;AAsCA,SAAgB,wBACd,WACyB;CACzB,IAAI,cAAc,QAChB,OAAO,EAAE,YAAY,MAAM;CAG7B,OAAO;EAAE,YAAY;EAAM;CAAU;AACvC;;;;;;;;AASA,SAAgB,2BAAgE;CAS9E,OAJoB,OAAO,IAAmB,SAAS,CAAC,CAIvC,CAAC,EAAE;AACtB;;;;;;;;;;AAWA,SAAgB,2BACd,WACyB;CACzB,IAAI,UAAU,YACZ,OAAO,UAAU;CAGnB,MAAM,aAAa,yBAAyB;CAE5C,IAAI,eAAe,QACjB,OAAO;CAGT,OAAO;AACT;;;;;;;AAQA,SAAgB,wBAAwB,OAAyC;CAC/E,OAAO,CAAC,GAAG,IAAI,IAAI,KAAK,CAAC,CAAC,CAAC,KAAK;AAClC;;;;;AAMA,SAAgB,0BACd,MACA,OACS;CACT,IAAI,MAAM,QAAQ,IAAI,KAAK,MAAM,QAAQ,KAAK,GAAG;EAC/C,MAAM,iBAAiB,wBAAwB,IAAI;EACnD,MAAM,kBAAkB,wBAAwB,KAAK;EAErD,OACE,eAAe,WAAW,gBAAgB,UAC1C,eAAe,OAAO,MAAM,UAAU,SAAS,gBAAgB,MAAM;CAEzE;CAEA,OAAO,SAAS;AAClB;;;;AAKA,SAAgB,4BAA4B,WAA4C;CACtF,IAAI,cAAc,MAChB,OAAO;CAGT,IAAI,cAAc,OAChB,OAAO;CAOT,OAAO,kBAJO,wBAAwB,SAAS,CAAC,CAC7C,KAAK,SAAS,IAAI,KAAK,EAAE,CAAC,CAC1B,KAAK,IAEqB,EAAE;AACjC"}

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

@@ -1,4 +1,4 @@
-//#region ../core/src/tests/test-helpers.d.ts
+//#region ../../packages/core/src/tests/test-helpers.d.ts
 /**
  * Warlock.js Test Helpers
  *
@@ -13,6 +13,25 @@ declare function getTestServerUrl(): string;
  * Uses native fetch - lightweight, no extra dependencies
  */
 declare function testRequest(path: string, options?: RequestInit): Promise<Response>;
+/** The request helpers, bound to one server. */
+type TestRequestClient = {
+  request(path: string, options?: RequestInit): Promise<Response>;
+  get(path: string, options?: RequestInit): Promise<Response>;
+  post(path: string, body?: unknown, options?: RequestInit): Promise<Response>;
+  put(path: string, body?: unknown, options?: RequestInit): Promise<Response>;
+  patch(path: string, body?: unknown, options?: RequestInit): Promise<Response>;
+  delete(path: string, options?: RequestInit): Promise<Response>;
+};
+/**
+ * Request helpers bound to `baseUrl` (a string, or a function read on every
+ * request). `testGet()` and friends are this, bound to the shared test server;
+ * `createTestHttpServer()` returns one bound to its own port.
+ *
+ * @example
+ * const client = createTestRequestClient("http://127.0.0.1:4100");
+ * await client.post("/posts", { title: "Hello" });
+ */
+declare function createTestRequestClient(baseUrl: string | (() => string)): TestRequestClient;
 /**
  * GET request helper
  */
@@ -42,5 +61,5 @@ declare function parseJsonResponse<T>(response: Response): Promise<T>;
  */
 declare function expectJson<T>(response: Response, expectedStatus?: number): Promise<T>;
 //#endregion
-export { expectJson, getTestServerUrl, parseJsonResponse, testDelete, testGet, testPatch, testPost, testPut, testRequest };
+export { TestRequestClient, createTestRequestClient, expectJson, getTestServerUrl, parseJsonResponse, testDelete, testGet, testPatch, testPost, testPut, testRequest };
 //# sourceMappingURL=test-helpers.d.mts.map

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

@@ -1 +1 @@
-{"version":3,"file":"test-helpers.d.mts","names":[],"sources":["../../../../../../../core/src/tests/test-helpers.ts"],"mappings":";;AAaA;;;;AAAgC;AA6BhC;;AA7BgC,iBAAhB,gBAAA;;;;;iBA6BM,WAAA,CAAY,IAAA,UAAc,OAAA,GAAS,WAAA,GAAmB,OAAA,CAAQ,QAAA;;;;iBAgD9D,OAAA,CAAQ,IAAA,UAAc,OAAA,GAAS,WAAA,GAAmB,OAAA,CAAQ,QAAA;;;AAhDY;iBAuDtE,QAAA,CACpB,IAAA,UACA,IAAA,YACA,OAAA,GAAS,WAAA,GACR,OAAA,CAAQ,QAAA;;;;iBAWW,OAAA,CACpB,IAAA,UACA,IAAA,YACA,OAAA,GAAS,WAAA,GACR,OAAA,CAAQ,QAAA;;;;iBAOW,UAAA,CAAW,IAAA,UAAc,OAAA,GAAS,WAAA,GAAmB,OAAA,CAAQ,QAAA;;;;iBAO7D,SAAA,CACpB,IAAA,UACA,IAAA,YACA,OAAA,GAAS,WAAA,GACR,OAAA,CAAQ,QAAA;;AA5C6E;AAOxF;iBAgDsB,iBAAA,IAAqB,QAAA,EAAU,QAAA,GAAW,OAAA,CAAQ,CAAA;;;;iBAOlD,UAAA,IAAc,QAAA,EAAU,QAAA,EAAU,cAAA,YAAuB,OAAA,CAAQ,CAAA"}
+{"version":3,"file":"test-helpers.d.mts","names":[],"sources":["../../../../../../../../packages/core/src/tests/test-helpers.ts"],"mappings":";;AAaA;;;;AAAgC;AA6BhC;;AA7BgC,iBAAhB,gBAAA;;;;;iBA6BM,WAAA,CAAY,IAAA,UAAc,OAAA,GAAS,WAAA,GAAmB,OAAA,CAAQ,QAAA;;KA8CxE,iBAAA;EACV,OAAA,CAAQ,IAAA,UAAc,OAAA,GAAU,WAAA,GAAc,OAAA,CAAQ,QAAA;EACtD,GAAA,CAAI,IAAA,UAAc,OAAA,GAAU,WAAA,GAAc,OAAA,CAAQ,QAAA;EAClD,IAAA,CAAK,IAAA,UAAc,IAAA,YAAgB,OAAA,GAAU,WAAA,GAAc,OAAA,CAAQ,QAAA;EACnE,GAAA,CAAI,IAAA,UAAc,IAAA,YAAgB,OAAA,GAAU,WAAA,GAAc,OAAA,CAAQ,QAAA;EAClE,KAAA,CAAM,IAAA,UAAc,IAAA,YAAgB,OAAA,GAAU,WAAA,GAAc,OAAA,CAAQ,QAAA;EACpE,MAAA,CAAO,IAAA,UAAc,OAAA,GAAU,WAAA,GAAc,OAAA,CAAQ,QAAA;AAAA;;;;;;;;;;iBAYvC,uBAAA,CAAwB,OAAA,4BAAmC,iBAAiB;;;;iBAqBtE,OAAA,CAAQ,IAAA,UAAc,OAAA,GAAS,WAAA,GAAmB,OAAA,CAAQ,QAAA;;;;iBAO1D,QAAA,CACpB,IAAA,UACA,IAAA,YACA,OAAA,GAAS,WAAA,GACR,OAAA,CAAQ,QAAA;;;;iBAOW,OAAA,CACpB,IAAA,UACA,IAAA,YACA,OAAA,GAAS,WAAA,GACR,OAAA,CAAQ,QAAA;;;;iBAOW,UAAA,CAAW,IAAA,UAAc,OAAA,GAAS,WAAA,GAAmB,OAAA,CAAQ,QAAA;;;;iBAO7D,SAAA,CACpB,IAAA,UACA,IAAA,YACA,OAAA,GAAS,WAAA,GACR,OAAA,CAAQ,QAAA;;;;iBAOW,iBAAA,IAAqB,QAAA,EAAU,QAAA,GAAW,OAAA,CAAQ,CAAA;;;;iBAOlD,UAAA,IAAc,QAAA,EAAU,QAAA,EAAU,cAAA,YAAuB,OAAA,CAAQ,CAAA"}

package/esm/tests/test-helpers.mjs

@@ -3,7 +3,7 @@ import "../config/index.mjs";
 import { getHttpReadyReport } from "../http/ready-report.mjs";
 import { TEST_SERVER_PORT_ENV_KEY } from "./test-server-port-channel.mjs";
 
-//#region ../core/src/tests/test-helpers.ts
+//#region ../../packages/core/src/tests/test-helpers.ts
 /**
 * Warlock.js Test Helpers
 *
@@ -23,7 +23,7 @@ function getTestServerUrl() {
 * Uses native fetch - lightweight, no extra dependencies
 */
 async function testRequest(path, options = {}) {
-	return sendRequest(path, options, false);
+	return sendRequest(getTestServerUrl(), path, options, false);
 }
 /**
 * The single place a request is actually built.
@@ -33,8 +33,7 @@ async function testRequest(path, options = {}) {
 * a `FormData` body carries a multipart boundary the runtime generates, and
 * labelling it `application/json` produces a request no server can parse.
 */
-async function sendRequest(path, options, serializedJson) {
-	const baseUrl = getTestServerUrl();
+async function sendRequest(baseUrl, path, options, serializedJson) {
 	const url = path.startsWith("/") ? `${baseUrl}${path}` : `${baseUrl}/${path}`;
 	const headers = new Headers(options.headers);
 	if (serializedJson && !headers.has("content-type")) headers.set("content-type", "application/json");
@@ -55,52 +54,66 @@ function jsonBody(body) {
 	return body === void 0 ? void 0 : JSON.stringify(body);
 }
 /**
+* Request helpers bound to `baseUrl` (a string, or a function read on every
+* request). `testGet()` and friends are this, bound to the shared test server;
+* `createTestHttpServer()` returns one bound to its own port.
+*
+* @example
+* const client = createTestRequestClient("http://127.0.0.1:4100");
+* await client.post("/posts", { title: "Hello" });
+*/
+function createTestRequestClient(baseUrl) {
+	const base = () => typeof baseUrl === "function" ? baseUrl() : baseUrl;
+	const send = (method, path, body, options = {}) => sendRequest(base(), path, {
+		...options,
+		method,
+		body: jsonBody(body)
+	}, body !== void 0);
+	return {
+		request: (path, options = {}) => sendRequest(base(), path, options, false),
+		get: (path, options = {}) => sendRequest(base(), path, {
+			...options,
+			method: "GET"
+		}, false),
+		post: (path, body, options) => send("POST", path, body, options),
+		put: (path, body, options) => send("PUT", path, body, options),
+		patch: (path, body, options) => send("PATCH", path, body, options),
+		delete: (path, options = {}) => sendRequest(base(), path, {
+			...options,
+			method: "DELETE"
+		}, false)
+	};
+}
+const sharedServer = createTestRequestClient(getTestServerUrl);
+/**
 * GET request helper
 */
 async function testGet(path, options = {}) {
-	return testRequest(path, {
-		...options,
-		method: "GET"
-	});
+	return sharedServer.get(path, options);
 }
 /**
 * POST request helper
 */
 async function testPost(path, body, options = {}) {
-	return sendRequest(path, {
-		...options,
-		method: "POST",
-		body: jsonBody(body)
-	}, body !== void 0);
+	return sharedServer.post(path, body, options);
 }
 /**
 * PUT request helper
 */
 async function testPut(path, body, options = {}) {
-	return sendRequest(path, {
-		...options,
-		method: "PUT",
-		body: jsonBody(body)
-	}, body !== void 0);
+	return sharedServer.put(path, body, options);
 }
 /**
 * DELETE request helper
 */
 async function testDelete(path, options = {}) {
-	return testRequest(path, {
-		...options,
-		method: "DELETE"
-	});
+	return sharedServer.delete(path, options);
 }
 /**
 * PATCH request helper
 */
 async function testPatch(path, body, options = {}) {
-	return sendRequest(path, {
-		...options,
-		method: "PATCH",
-		body: jsonBody(body)
-	}, body !== void 0);
+	return sharedServer.patch(path, body, options);
 }
 /**
 * Parse JSON response with type safety
@@ -120,5 +133,5 @@ async function expectJson(response, expectedStatus = 200) {
 }
 
 //#endregion
-export { expectJson, getTestServerUrl, parseJsonResponse, testDelete, testGet, testPatch, testPost, testPut, testRequest };
+export { createTestRequestClient, expectJson, getTestServerUrl, parseJsonResponse, testDelete, testGet, testPatch, testPost, testPut, testRequest };
 //# sourceMappingURL=test-helpers.mjs.map

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

@@ -1 +1 @@
-{"version":3,"file":"test-helpers.mjs","names":[],"sources":["../../../../../../../core/src/tests/test-helpers.ts"],"sourcesContent":["/**\n * Warlock.js Test Helpers\n *\n * Utilities for testing Warlock.js applications.\n */\n\nimport { config } from \"../config\";\nimport { getHttpReadyReport } from \"../http/ready-report\";\nimport { TEST_SERVER_PORT_ENV_KEY } from \"./test-server-port-channel\";\n\n/**\n * Get the test server base URL\n */\nexport function getTestServerUrl(): string {\n  // `startHttpTestServer` publishes the port it actually bound. Test workers are\n  // separate processes whose own config resolves `http.port` from `.env`, so\n  // without this a suite started on an explicit port would send every request to\n  // the `.env` port instead of the one the server is listening on.\n  const publishedPort = process.env[TEST_SERVER_PORT_ENV_KEY];\n\n  // Same-process fallback: a test that boots the HTTP connector directly\n  // (rather than through `startHttpTestServer`'s cross-process channel) never\n  // writes `TEST_SERVER_PORT_ENV_KEY`, so without this the next fallback —\n  // `config.key(\"http.port\", 2031)` — was the only source left, and it holds\n  // the CONFIGURED port, not the bound one. For `http.port: 0` that is `0`,\n  // producing `http://host:0` even though `HttpConnector.start()` had already\n  // recorded the real bound port right here in `ready-report.ts`.\n  const boundPort = getHttpReadyReport()?.port;\n\n  // `config.key`'s default only substitutes for `undefined` — `0` is a\n  // defined configured value, not an absent one — so it cannot be trusted to\n  // paper over an unresolved port 0 either. `boundPort` is read first for\n  // that exact reason.\n  const port = publishedPort || boundPort || config.key(\"http.port\", 2031);\n  const host = config.key(\"http.host\", \"localhost\");\n  return `http://${host}:${port}`;\n}\n\n/**\n * Simple HTTP request helper for test server\n * Uses native fetch - lightweight, no extra dependencies\n */\nexport async function testRequest(path: string, options: RequestInit = {}): Promise<Response> {\n  return sendRequest(path, options, false);\n}\n\n/**\n * The single place a request is actually built.\n *\n * `serializedJson` says whether THIS module turned the caller's value into a\n * JSON string. It is the only thing that justifies setting a JSON content type:\n * a `FormData` body carries a multipart boundary the runtime generates, and\n * labelling it `application/json` produces a request no server can parse.\n */\nasync function sendRequest(\n  path: string,\n  options: RequestInit,\n  serializedJson: boolean,\n): Promise<Response> {\n  const baseUrl = getTestServerUrl();\n  const url = path.startsWith(\"/\") ? `${baseUrl}${path}` : `${baseUrl}/${path}`;\n\n  // Normalised through `Headers` rather than object-spread: `RequestInit.headers`\n  // may be a record, a `Headers` instance, or a list of `[name, value]` tuples,\n  // and spreading the last two silently produces an object with numeric keys —\n  // the header is simply lost, with no error anywhere.\n  const headers = new Headers(options.headers);\n\n  if (serializedJson && !headers.has(\"content-type\")) {\n    headers.set(\"content-type\", \"application/json\");\n  }\n\n  return fetch(url, { ...options, headers });\n}\n\n/**\n * Serialize a body for a JSON request.\n *\n * `undefined` means the caller omitted the argument; every other value —\n * including `false`, `0`, `\"\"` and `null` — is a legal JSON document and must\n * be sent. The old check was `body ? JSON.stringify(body) : undefined`, which\n * dropped all four.\n */\nfunction jsonBody(body: unknown): string | undefined {\n  return body === undefined ? undefined : JSON.stringify(body);\n}\n\n/**\n * GET request helper\n */\nexport async function testGet(path: string, options: RequestInit = {}): Promise<Response> {\n  return testRequest(path, { ...options, method: \"GET\" });\n}\n\n/**\n * POST request helper\n */\nexport async function testPost(\n  path: string,\n  body?: unknown,\n  options: RequestInit = {},\n): Promise<Response> {\n  return sendRequest(\n    path,\n    { ...options, method: \"POST\", body: jsonBody(body) },\n    body !== undefined,\n  );\n}\n\n/**\n * PUT request helper\n */\nexport async function testPut(\n  path: string,\n  body?: unknown,\n  options: RequestInit = {},\n): Promise<Response> {\n  return sendRequest(path, { ...options, method: \"PUT\", body: jsonBody(body) }, body !== undefined);\n}\n\n/**\n * DELETE request helper\n */\nexport async function testDelete(path: string, options: RequestInit = {}): Promise<Response> {\n  return testRequest(path, { ...options, method: \"DELETE\" });\n}\n\n/**\n * PATCH request helper\n */\nexport async function testPatch(\n  path: string,\n  body?: unknown,\n  options: RequestInit = {},\n): Promise<Response> {\n  return sendRequest(\n    path,\n    { ...options, method: \"PATCH\", body: jsonBody(body) },\n    body !== undefined,\n  );\n}\n\n/**\n * Parse JSON response with type safety\n */\nexport async function parseJsonResponse<T>(response: Response): Promise<T> {\n  return response.json() as Promise<T>;\n}\n\n/**\n * Assert response status and return parsed JSON\n */\nexport async function expectJson<T>(response: Response, expectedStatus = 200): Promise<T> {\n  if (response.status !== expectedStatus) {\n    const text = await response.text();\n    throw new Error(`Expected status ${expectedStatus}, got ${response.status}. Body: ${text}`);\n  }\n  return parseJsonResponse<T>(response);\n}\n"],"mappings":";;;;;;;;;;;;;;AAaA,SAAgB,mBAA2B;CAKzC,MAAM,gBAAgB,QAAQ,IAAI;CASlC,MAAM,YAAY,mBAAmB,CAAC,EAAE;CAMxC,MAAM,OAAO,iBAAiB,aAAa,OAAO,IAAI,aAAa,IAAI;CAEvE,OAAO,UADM,OAAO,IAAI,aAAa,WACjB,EAAE,GAAG;AAC3B;;;;;AAMA,eAAsB,YAAY,MAAc,UAAuB,CAAC,GAAsB;CAC5F,OAAO,YAAY,MAAM,SAAS,KAAK;AACzC;;;;;;;;;AAUA,eAAe,YACb,MACA,SACA,gBACmB;CACnB,MAAM,UAAU,iBAAiB;CACjC,MAAM,MAAM,KAAK,WAAW,GAAG,IAAI,GAAG,UAAU,SAAS,GAAG,QAAQ,GAAG;CAMvE,MAAM,UAAU,IAAI,QAAQ,QAAQ,OAAO;CAE3C,IAAI,kBAAkB,CAAC,QAAQ,IAAI,cAAc,GAC/C,QAAQ,IAAI,gBAAgB,kBAAkB;CAGhD,OAAO,MAAM,KAAK;EAAE,GAAG;EAAS;CAAQ,CAAC;AAC3C;;;;;;;;;AAUA,SAAS,SAAS,MAAmC;CACnD,OAAO,SAAS,SAAY,SAAY,KAAK,UAAU,IAAI;AAC7D;;;;AAKA,eAAsB,QAAQ,MAAc,UAAuB,CAAC,GAAsB;CACxF,OAAO,YAAY,MAAM;EAAE,GAAG;EAAS,QAAQ;CAAM,CAAC;AACxD;;;;AAKA,eAAsB,SACpB,MACA,MACA,UAAuB,CAAC,GACL;CACnB,OAAO,YACL,MACA;EAAE,GAAG;EAAS,QAAQ;EAAQ,MAAM,SAAS,IAAI;CAAE,GACnD,SAAS,MACX;AACF;;;;AAKA,eAAsB,QACpB,MACA,MACA,UAAuB,CAAC,GACL;CACnB,OAAO,YAAY,MAAM;EAAE,GAAG;EAAS,QAAQ;EAAO,MAAM,SAAS,IAAI;CAAE,GAAG,SAAS,MAAS;AAClG;;;;AAKA,eAAsB,WAAW,MAAc,UAAuB,CAAC,GAAsB;CAC3F,OAAO,YAAY,MAAM;EAAE,GAAG;EAAS,QAAQ;CAAS,CAAC;AAC3D;;;;AAKA,eAAsB,UACpB,MACA,MACA,UAAuB,CAAC,GACL;CACnB,OAAO,YACL,MACA;EAAE,GAAG;EAAS,QAAQ;EAAS,MAAM,SAAS,IAAI;CAAE,GACpD,SAAS,MACX;AACF;;;;AAKA,eAAsB,kBAAqB,UAAgC;CACzE,OAAO,SAAS,KAAK;AACvB;;;;AAKA,eAAsB,WAAc,UAAoB,iBAAiB,KAAiB;CACxF,IAAI,SAAS,WAAW,gBAAgB;EACtC,MAAM,OAAO,MAAM,SAAS,KAAK;EACjC,MAAM,IAAI,MAAM,mBAAmB,eAAe,QAAQ,SAAS,OAAO,UAAU,MAAM;CAC5F;CACA,OAAO,kBAAqB,QAAQ;AACtC"}
+{"version":3,"file":"test-helpers.mjs","names":[],"sources":["../../../../../../../../packages/core/src/tests/test-helpers.ts"],"sourcesContent":["/**\n * Warlock.js Test Helpers\n *\n * Utilities for testing Warlock.js applications.\n */\n\nimport { config } from \"../config\";\nimport { getHttpReadyReport } from \"../http/ready-report\";\nimport { TEST_SERVER_PORT_ENV_KEY } from \"./test-server-port-channel\";\n\n/**\n * Get the test server base URL\n */\nexport function getTestServerUrl(): string {\n  // `startHttpTestServer` publishes the port it actually bound. Test workers are\n  // separate processes whose own config resolves `http.port` from `.env`, so\n  // without this a suite started on an explicit port would send every request to\n  // the `.env` port instead of the one the server is listening on.\n  const publishedPort = process.env[TEST_SERVER_PORT_ENV_KEY];\n\n  // Same-process fallback: a test that boots the HTTP connector directly\n  // (rather than through `startHttpTestServer`'s cross-process channel) never\n  // writes `TEST_SERVER_PORT_ENV_KEY`, so without this the next fallback —\n  // `config.key(\"http.port\", 2031)` — was the only source left, and it holds\n  // the CONFIGURED port, not the bound one. For `http.port: 0` that is `0`,\n  // producing `http://host:0` even though `HttpConnector.start()` had already\n  // recorded the real bound port right here in `ready-report.ts`.\n  const boundPort = getHttpReadyReport()?.port;\n\n  // `config.key`'s default only substitutes for `undefined` — `0` is a\n  // defined configured value, not an absent one — so it cannot be trusted to\n  // paper over an unresolved port 0 either. `boundPort` is read first for\n  // that exact reason.\n  const port = publishedPort || boundPort || config.key(\"http.port\", 2031);\n  const host = config.key(\"http.host\", \"localhost\");\n  return `http://${host}:${port}`;\n}\n\n/**\n * Simple HTTP request helper for test server\n * Uses native fetch - lightweight, no extra dependencies\n */\nexport async function testRequest(path: string, options: RequestInit = {}): Promise<Response> {\n  return sendRequest(getTestServerUrl(), path, options, false);\n}\n\n/**\n * The single place a request is actually built.\n *\n * `serializedJson` says whether THIS module turned the caller's value into a\n * JSON string. It is the only thing that justifies setting a JSON content type:\n * a `FormData` body carries a multipart boundary the runtime generates, and\n * labelling it `application/json` produces a request no server can parse.\n */\nasync function sendRequest(\n  baseUrl: string,\n  path: string,\n  options: RequestInit,\n  serializedJson: boolean,\n): Promise<Response> {\n  const url = path.startsWith(\"/\") ? `${baseUrl}${path}` : `${baseUrl}/${path}`;\n\n  // Normalised through `Headers` rather than object-spread: `RequestInit.headers`\n  // may be a record, a `Headers` instance, or a list of `[name, value]` tuples,\n  // and spreading the last two silently produces an object with numeric keys —\n  // the header is simply lost, with no error anywhere.\n  const headers = new Headers(options.headers);\n\n  if (serializedJson && !headers.has(\"content-type\")) {\n    headers.set(\"content-type\", \"application/json\");\n  }\n\n  return fetch(url, { ...options, headers });\n}\n\n/**\n * Serialize a body for a JSON request.\n *\n * `undefined` means the caller omitted the argument; every other value —\n * including `false`, `0`, `\"\"` and `null` — is a legal JSON document and must\n * be sent. The old check was `body ? JSON.stringify(body) : undefined`, which\n * dropped all four.\n */\nfunction jsonBody(body: unknown): string | undefined {\n  return body === undefined ? undefined : JSON.stringify(body);\n}\n\n/** The request helpers, bound to one server. */\nexport type TestRequestClient = {\n  request(path: string, options?: RequestInit): Promise<Response>;\n  get(path: string, options?: RequestInit): Promise<Response>;\n  post(path: string, body?: unknown, options?: RequestInit): Promise<Response>;\n  put(path: string, body?: unknown, options?: RequestInit): Promise<Response>;\n  patch(path: string, body?: unknown, options?: RequestInit): Promise<Response>;\n  delete(path: string, options?: RequestInit): Promise<Response>;\n};\n\n/**\n * Request helpers bound to `baseUrl` (a string, or a function read on every\n * request). `testGet()` and friends are this, bound to the shared test server;\n * `createTestHttpServer()` returns one bound to its own port.\n *\n * @example\n * const client = createTestRequestClient(\"http://127.0.0.1:4100\");\n * await client.post(\"/posts\", { title: \"Hello\" });\n */\nexport function createTestRequestClient(baseUrl: string | (() => string)): TestRequestClient {\n  const base = () => (typeof baseUrl === \"function\" ? baseUrl() : baseUrl);\n  const send = (method: string, path: string, body: unknown, options: RequestInit = {}) =>\n    sendRequest(base(), path, { ...options, method, body: jsonBody(body) }, body !== undefined);\n\n  return {\n    request: (path, options = {}) => sendRequest(base(), path, options, false),\n    get: (path, options = {}) => sendRequest(base(), path, { ...options, method: \"GET\" }, false),\n    post: (path, body, options) => send(\"POST\", path, body, options),\n    put: (path, body, options) => send(\"PUT\", path, body, options),\n    patch: (path, body, options) => send(\"PATCH\", path, body, options),\n    delete: (path, options = {}) =>\n      sendRequest(base(), path, { ...options, method: \"DELETE\" }, false),\n  };\n}\n\nconst sharedServer = createTestRequestClient(getTestServerUrl);\n\n/**\n * GET request helper\n */\nexport async function testGet(path: string, options: RequestInit = {}): Promise<Response> {\n  return sharedServer.get(path, options);\n}\n\n/**\n * POST request helper\n */\nexport async function testPost(\n  path: string,\n  body?: unknown,\n  options: RequestInit = {},\n): Promise<Response> {\n  return sharedServer.post(path, body, options);\n}\n\n/**\n * PUT request helper\n */\nexport async function testPut(\n  path: string,\n  body?: unknown,\n  options: RequestInit = {},\n): Promise<Response> {\n  return sharedServer.put(path, body, options);\n}\n\n/**\n * DELETE request helper\n */\nexport async function testDelete(path: string, options: RequestInit = {}): Promise<Response> {\n  return sharedServer.delete(path, options);\n}\n\n/**\n * PATCH request helper\n */\nexport async function testPatch(\n  path: string,\n  body?: unknown,\n  options: RequestInit = {},\n): Promise<Response> {\n  return sharedServer.patch(path, body, options);\n}\n\n/**\n * Parse JSON response with type safety\n */\nexport async function parseJsonResponse<T>(response: Response): Promise<T> {\n  return response.json() as Promise<T>;\n}\n\n/**\n * Assert response status and return parsed JSON\n */\nexport async function expectJson<T>(response: Response, expectedStatus = 200): Promise<T> {\n  if (response.status !== expectedStatus) {\n    const text = await response.text();\n    throw new Error(`Expected status ${expectedStatus}, got ${response.status}. Body: ${text}`);\n  }\n  return parseJsonResponse<T>(response);\n}\n"],"mappings":";;;;;;;;;;;;;;AAaA,SAAgB,mBAA2B;CAKzC,MAAM,gBAAgB,QAAQ,IAAI;CASlC,MAAM,YAAY,mBAAmB,CAAC,EAAE;CAMxC,MAAM,OAAO,iBAAiB,aAAa,OAAO,IAAI,aAAa,IAAI;CAEvE,OAAO,UADM,OAAO,IAAI,aAAa,WACjB,EAAE,GAAG;AAC3B;;;;;AAMA,eAAsB,YAAY,MAAc,UAAuB,CAAC,GAAsB;CAC5F,OAAO,YAAY,iBAAiB,GAAG,MAAM,SAAS,KAAK;AAC7D;;;;;;;;;AAUA,eAAe,YACb,SACA,MACA,SACA,gBACmB;CACnB,MAAM,MAAM,KAAK,WAAW,GAAG,IAAI,GAAG,UAAU,SAAS,GAAG,QAAQ,GAAG;CAMvE,MAAM,UAAU,IAAI,QAAQ,QAAQ,OAAO;CAE3C,IAAI,kBAAkB,CAAC,QAAQ,IAAI,cAAc,GAC/C,QAAQ,IAAI,gBAAgB,kBAAkB;CAGhD,OAAO,MAAM,KAAK;EAAE,GAAG;EAAS;CAAQ,CAAC;AAC3C;;;;;;;;;AAUA,SAAS,SAAS,MAAmC;CACnD,OAAO,SAAS,SAAY,SAAY,KAAK,UAAU,IAAI;AAC7D;;;;;;;;;;AAqBA,SAAgB,wBAAwB,SAAqD;CAC3F,MAAM,aAAc,OAAO,YAAY,aAAa,QAAQ,IAAI;CAChE,MAAM,QAAQ,QAAgB,MAAc,MAAe,UAAuB,CAAC,MACjF,YAAY,KAAK,GAAG,MAAM;EAAE,GAAG;EAAS;EAAQ,MAAM,SAAS,IAAI;CAAE,GAAG,SAAS,MAAS;CAE5F,OAAO;EACL,UAAU,MAAM,UAAU,CAAC,MAAM,YAAY,KAAK,GAAG,MAAM,SAAS,KAAK;EACzE,MAAM,MAAM,UAAU,CAAC,MAAM,YAAY,KAAK,GAAG,MAAM;GAAE,GAAG;GAAS,QAAQ;EAAM,GAAG,KAAK;EAC3F,OAAO,MAAM,MAAM,YAAY,KAAK,QAAQ,MAAM,MAAM,OAAO;EAC/D,MAAM,MAAM,MAAM,YAAY,KAAK,OAAO,MAAM,MAAM,OAAO;EAC7D,QAAQ,MAAM,MAAM,YAAY,KAAK,SAAS,MAAM,MAAM,OAAO;EACjE,SAAS,MAAM,UAAU,CAAC,MACxB,YAAY,KAAK,GAAG,MAAM;GAAE,GAAG;GAAS,QAAQ;EAAS,GAAG,KAAK;CACrE;AACF;AAEA,MAAM,eAAe,wBAAwB,gBAAgB;;;;AAK7D,eAAsB,QAAQ,MAAc,UAAuB,CAAC,GAAsB;CACxF,OAAO,aAAa,IAAI,MAAM,OAAO;AACvC;;;;AAKA,eAAsB,SACpB,MACA,MACA,UAAuB,CAAC,GACL;CACnB,OAAO,aAAa,KAAK,MAAM,MAAM,OAAO;AAC9C;;;;AAKA,eAAsB,QACpB,MACA,MACA,UAAuB,CAAC,GACL;CACnB,OAAO,aAAa,IAAI,MAAM,MAAM,OAAO;AAC7C;;;;AAKA,eAAsB,WAAW,MAAc,UAAuB,CAAC,GAAsB;CAC3F,OAAO,aAAa,OAAO,MAAM,OAAO;AAC1C;;;;AAKA,eAAsB,UACpB,MACA,MACA,UAAuB,CAAC,GACL;CACnB,OAAO,aAAa,MAAM,MAAM,MAAM,OAAO;AAC/C;;;;AAKA,eAAsB,kBAAqB,UAAgC;CACzE,OAAO,SAAS,KAAK;AACvB;;;;AAKA,eAAsB,WAAc,UAAoB,iBAAiB,KAAiB;CACxF,IAAI,SAAS,WAAW,gBAAgB;EACtC,MAAM,OAAO,MAAM,SAAS,KAAK;EACjC,MAAM,IAAI,MAAM,mBAAmB,eAAe,QAAQ,SAAS,OAAO,UAAU,MAAM;CAC5F;CACA,OAAO,kBAAqB,QAAQ;AACtC"}

package/esm/tests/test-http-server.d.mts

@@ -0,0 +1,62 @@
+import { FastifyInstance } from "../http/server.mjs";
+import { Router } from "../router/router.mjs";
+import { TestRequestClient } from "./test-helpers.mjs";
+import { AuthenticatedTestClient, TestAuthenticableUser } from "./authenticated-test-client.mjs";
+import { AppModuleImporter } from "../loader/app-module-importer.mjs";
+
+//#region ../../packages/core/src/tests/test-http-server.d.ts
+type CreateTestHttpServerOptions = {
+  /**
+   * Register routes for this server, exactly as a `routes.ts` would. They are
+   * tagged with a source of their own and removed again by `close()`.
+   */
+  routes?: (router: Router) => unknown;
+  /**
+   * Load the application's modules (`routes.ts`, `main.ts`, events, ...) first,
+   * so the server answers every app route. Needs `setupTest()` to have run in
+   * this worker. Modules load once per process; later servers reuse them.
+   */
+  loadAppModules?: boolean;
+  /**
+   * How app modules are imported when `loadAppModules` is set. Pass
+   * `(file) => import(file)` from the test file, as `setupTest()` takes it, so
+   * app classes are the same ones the test imports.
+   */
+  importModule?: AppModuleImporter; /** Interface to bind. Defaults to `127.0.0.1`. */
+  host?: string;
+};
+type TestHttpServer = TestRequestClient & {
+  /** `http://127.0.0.1:<port>` */readonly url: string; /** The port the OS assigned. */
+  readonly port: number; /** The Fastify instance, for `inject()` or anything else Fastify offers. */
+  readonly server: FastifyInstance; /** A client for this server, signed in as `user` with a real access token. */
+  actingAs(user: TestAuthenticableUser): Promise<AuthenticatedTestClient>; /** Stop listening and remove the routes `routes` registered. */
+  close(): Promise<void>;
+};
+/**
+ * Start an in-process HTTP server with the production plugins, on a free port.
+ *
+ * @example
+ * const app = await createTestHttpServer({
+ *   routes: (router) => router.post("/echo", ({ request, response }) =>
+ *     response.success({ body: request.all() })),
+ * });
+ *
+ * const response = await app.post("/echo", { name: "Ada" });
+ * expect(response.status).toBe(200);
+ *
+ * await app.close();
+ *
+ * @example
+ * // every app route, with the fakes seeing what the controller did
+ * const app = await createTestHttpServer({
+ *   loadAppModules: true,
+ *   importModule: (file) => import(file),
+ * });
+ *
+ * await app.post("/contact", { email: "ada@example.test", message: "Hi" });
+ * mailFake.assertSent({ to: "support@example.test" });
+ */
+declare function createTestHttpServer(options?: CreateTestHttpServerOptions): Promise<TestHttpServer>;
+//#endregion
+export { CreateTestHttpServerOptions, TestHttpServer, createTestHttpServer };
+//# sourceMappingURL=test-http-server.d.mts.map

package/esm/tests/test-http-server.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"test-http-server.d.mts","names":[],"sources":["../../../../../../../../packages/core/src/tests/test-http-server.ts"],"mappings":";;;;;;;KA+BY,2BAAA;;AAAZ;;;EAKE,MAAA,IAAU,MAAA,EAAQ,MAAA;EAAlB;;;;;EAMA,cAAA;EAQA;;AAAI;AAGN;;EALE,YAAA,GAAe,iBAAiB,EAKL;EAH3B,IAAA;AAAA;AAAA,KAGU,cAAA,GAAiB,iBAAA;EAQY,yCAN9B,GAAA,UAQO;EAAA,SANP,IAAA,UAJkB;EAAA,SAMlB,MAAA,EAAQ,eAAA,EAFR;EAIT,QAAA,CAAS,IAAA,EAAM,qBAAA,GAAwB,OAAA,CAAQ,uBAAA,GAF9B;EAIjB,KAAA,IAAS,OAAA;AAAA;;;;;;;AAAO;AAmElB;;;;;;;;;;;;;AAEyB;;;;iBAFH,oBAAA,CACpB,OAAA,GAAS,2BAAA,GACR,OAAA,CAAQ,cAAA"}