@luckystack/test-runner 0.7.3 → 0.7.4

package/CHANGELOG.md

@@ -7,6 +7,30 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.7.4] - 2026-07-22
+
+### Added
+
+- `resolveTestEnvironment({ loadProjectConfig? })` and `RunAllTestsInput.loadProjectConfig`
+  give the test process the same env prefix as server/ORM boot: load env files,
+  lazily read consumer config, then dynamically run optional secret-manager
+  resolution before any layer or Layer-5 test-module import.
+- `resolveTestBaseUrl({ cwd?, fallbackUrl? })` centralizes live-test target
+  resolution: explicit `TEST_BASE_URL`, then the backend's actually-bound dev
+  port advertisement (only while its owner PID is alive), then the caller's
+  config-derived fallback.
+
+### Fixed
+
+- Layer-5 tests that directly use Prisma/Redis no longer receive unresolved
+  values such as `DATABASE_URL_V1` merely because only the separate live-server
+  process ran secret-manager bootstrap. A configured resolver that cannot load
+  now fails before test execution with an actionable error.
+- Direct `runCustomTests(...)` calls now have the same lazy config/env bootstrap
+  as `runAllTests`; both public orchestrators require the loader and fail closed
+  when an untyped caller omits it. The internal prepared entrypoint prevents a
+  second env load from replacing resolved secrets with pointers.
+
 ## [0.5.0] - 2026-07-11
 
 ### Changed

package/CLAUDE.md

@@ -27,7 +27,7 @@ Generated-type-driven test layers voor LuckyStack APIs. Walkt elke endpoint uit
 | Function / Export | 1-regel | Deep doc |
 |---|---|---|
 | `runAllTests({ apiMethodMap, apiMetaMap, apiInputSchemas, baseUrl, ... })` | Orchestrator: draait contract + auth + rate-limit + fuzz + custom (Layer 5) in volgorde, levert een `RunAllTestsSummary`. | → docs/contract-tests.md |
-| `runCustomTests(input)` | Layer 5: draait per-route `<name>_v<N>.tests.ts` files naast de `_api/` / `_sync/` sources, levert een `RunCustomTestsSummary`. | → docs/contract-tests.md |
+| `runCustomTests(input)` | Layer 5: draait per-route tests. Direct callers moeten lazy `loadProjectConfig` meegeven; env/secrets resolven vóór test-module imports. `runAllTests` gebruikt een interne already-prepared entrypoint om pointer-reload te voorkomen. | → docs/contract-tests.md |
 | `discoverCustomTestFiles(srcDir?)` | Walker die elke `<name>_v<N>.tests.ts` onder de configured src dir yields. | → docs/contract-tests.md |
 | `logRunAllSummary(summary)` | Pretty-print één `RunAllTestsSummary`. | → docs/extension-hooks.md |
 | `walkEndpoints(apiMethodMap)` | Genereert `EndpointDescriptor[]` uit de generated map | → docs/contract-tests.md |
@@ -40,6 +40,8 @@ Generated-type-driven test layers voor LuckyStack APIs. Walkt elke endpoint uit
 | `runFuzzCheck({ endpoint, baseUrl, headers? })` | Single-endpoint crash-resistance fuzz | → docs/fuzz-tests.md |
 | `runFuzzTests({ apiMethodMap, baseUrl, skip?, headers?, onResult? })` | Sweep fuzz layer (nightly CI) | → docs/fuzz-tests.md |
 | `resetServerState({ baseUrl, token? })` | POST naar `/_test/reset` om DB+Redis schoon te maken | → docs/rate-limit-tests.md |
+| `resolveTestBaseUrl({ cwd?, fallbackUrl? })` | Resolves `TEST_BASE_URL` → actually-bound dev port advertisement → caller fallback, so an auto-hop does not create false connection failures. | → docs/contract-tests.md |
+| `resolveTestEnvironment({ loadProjectConfig? })` | Laadt `.env`-lagen en resolveert optionele secret-manager-pointers in het testproces vóór DB/Redis-backed Layer-5 modules importeren. | → docs/contract-tests.md |
 | `sampleSchemaInput(schema, options?)` | Genereert Zod-valid sample payload uit een schema. `options.stringPrefix` tagt UNCONSTRAINED strings (finding #98) — format/checked strings blijven ongeprefixt zodat ze valid blijven. | → docs/contract-tests.md |
 | `createTestDataMarker()` / `TEST_DATA_PREFIX` | Run-unique `lstest_<uuid>_` marker (+ vaste `lstest_` prefix-constant) waarmee `runAllTests` gegenereerde test-strings identificeerbaar maakt. | → docs/contract-tests.md |
 | `logContractResult(result)` | Pretty-print één `ContractCheckResult` | → docs/extension-hooks.md |
@@ -76,6 +78,8 @@ Generated-type-driven test layers voor LuckyStack APIs. Walkt elke endpoint uit
 
 ## Config keys (env vars + register* slots)
 
+- `TEST_BASE_URL` (env, test process) — explicit target override consumed first by `resolveTestBaseUrl`; otherwise it reads `node_modules/.luckystack/dev-server.json` and then uses the supplied config-derived fallback.
+- `RunAllTestsInput.loadProjectConfig` / `RunCustomTestsInput.loadProjectConfig` — verplichte lazy loader voor de default export van consumer `config.ts`. De runner laadt eerst `.env`/`.env.local`, leest daarna deze config en draait bij een niet-lege `secretManager.url` `initSecretManager({...config, source:'remote'})` vóór custom test imports. `runAllTests` doet dit één keer voor alle lagen; directe Layer-5-calls doen het zelf. Een ontbrekende loader of geconfigureerd-maar-ontbrekende secret-manager is een harde fout.
 - `NODE_ENV` (env, server-side) — `/_test/reset` is automatisch beschikbaar wanneer NIET `production`.
 - `TEST_RESET_TOKEN` (env, optional, server-side) — wanneer gezet moet `resetServerState({ token })` deze meesturen als `X-Test-Reset-Token`. Verplicht voor staging/preview deploys die het endpoint over het netwerk exposen.
 - `RunRateLimitTestsInput.maxRateLimitToTest` (default `50`) — endpoints met hogere `rateLimit` worden geskipt om duizenden requests in CI te vermijden.
@@ -90,7 +94,7 @@ Generated-type-driven test layers voor LuckyStack APIs. Walkt elke endpoint uit
 - **Required**: `zod@^4.0.0` (peer), `socket.io-client@^4.8.0` (peer — `streamWatcher.ts` opent een tweede socket voor `ctx.watchStream`), `@luckystack/core@^0.1.0` (dependency — levert de helpers die de runner consumeert: `tryCatch`/`tryCatchSync`, `getProjectConfig`/`getCsrfConfig`, `getSrcDir` (default src-dir voor custom-test discovery in `customTests.ts`), `getPrismaClient` (Layer-5 `ctx.prisma`) en `clearAllRateLimits`. De `apiMethodMap` zelf wordt door de consumer als argument doorgegeven, niet uit een pad gelezen).
 - **Required server-side**: `@luckystack/server` met `/_test/reset` endpoint gemount (default ingebouwd, gated op `NODE_ENV !== 'production'`).
 - **Required generated artefact**: `apiMethodMap.generated.ts` (en `apiMetaMap.generated.ts` voor de auth/rate-limit layers), geproduceerd door `@luckystack/devkit`.
-- **Optional**: geen — fixtures, reporters en custom layers zijn pure-JS opt-in.
+- **Optional**: `@luckystack/secret-manager@^0.7.3` (optional peer) — alleen dynamisch geladen wanneer `loadProjectConfig` een niet-lege `config.secretManager.url` teruggeeft. Zonder secret-managerconfig blijft de runner een gewone lokale-env flow.
 
 ## Related
 

package/README.md

@@ -14,29 +14,31 @@ Run all four layers against a running server:
 
 ```ts
 import {
-  runContractTests,
-  runAuthEnforcementTests,
-  runRateLimitTests,
-  runFuzzTests,
-  resetServerState,
-  logContractSummary,
+  runAllTests,
+  resolveTestBaseUrl,
+  logRunAllSummary,
 } from '@luckystack/test-runner';
-import { apiMethodMap } from './src/_sockets/apiMethodMap.generated';
-import { apiMetaMap } from './src/_sockets/apiMetaMap.generated';
-
-const baseUrl = process.env.TEST_BASE_URL ?? 'http://127.0.0.1:80';
-const contract = await runContractTests({ apiMethodMap, baseUrl });
-logContractSummary(contract);
-
-const auth = await runAuthEnforcementTests({ apiMethodMap, apiMetaMap, baseUrl });
-const rate = await runRateLimitTests({ apiMethodMap, apiMetaMap, baseUrl });
-const fuzz = await runFuzzTests({ apiMethodMap, baseUrl });
-
-await resetServerState({ baseUrl });
+import { apiInputSchemas } from './src/_sockets/apiInputSchemas.generated';
+import { apiMetaMap, apiMethodMap } from './src/_sockets/apiTypes.generated';
+import { ports } from './config.ports';
+
+const baseUrl = resolveTestBaseUrl({ fallbackUrl: `http://localhost:${ports.backend}` });
+const summary = await runAllTests({
+  apiMethodMap,
+  apiMetaMap,
+  apiInputSchemas,
+  baseUrl,
+  // Loaded only after .env/.env.local. If config.secretManager.url is set,
+  // pointers are resolved in THIS process before Layer-5 tests touch Prisma.
+  loadProjectConfig: async () => (await import('./config')).default,
+});
+logRunAllSummary(summary);
 ```
 
 Each layer is independently runnable — you can skip the ones that don't apply or rearrange them.
 
+`runAllTests` always loads the normal env-file layers and requires `loadProjectConfig` as above, even in projects that currently use only local env values. A configured resolver is loaded dynamically and runs in fail-fast remote mode before custom test modules are imported. Direct `runCustomTests` callers must pass the same callback. Both public paths reject a missing loader so a later secret-manager rollout cannot silently expose pointer values. This matters because the live server resolving its own `DATABASE_URL` does not mutate the separate test process.
+
 ## Layers
 
 | Layer | What it asserts |
@@ -63,6 +65,7 @@ The fuzz layer is intentionally exhaustive and slow — wire it into nightly CI
 | `runRateLimitCheck(input)` / `runRateLimitTests(input)` | Rate-limit layer. |
 | `runFuzzCheck(input)` / `runFuzzTests(input)` | Fuzz layer. |
 | `resetServerState(input)` | POST to `/_test/reset`. |
+| `resolveTestEnvironment({ loadProjectConfig? })` | Load env layers and optional secret-manager pointers for the test process; `runAllTests` calls it automatically. |
 | `sampleSchemaInput(schema)` | Generate a Zod-valid sample payload. |
 | `logContractResult` / `logContractSummary` | Pretty-printers. |
 
@@ -75,8 +78,8 @@ Types: `EndpointDescriptor`, `HttpMethod`, `ContractCheckResult`, `RunContractSu
 
 ## Dependencies
 
-- Peer (canonical ranges, standardized 2026-05-07):
-  - `zod@^3.25.0`
+- Required peers: `zod@^4.0.0`, `socket.io-client@^4.8.0`.
+- Optional peers: `@luckystack/login`, `@luckystack/secret-manager` (loaded only for their corresponding features).
 
 ## License
 

package/dist/index.d.ts

@@ -199,6 +199,30 @@ interface ResetServerStateInput {
 }
 declare const resetServerState: ({ baseUrl, token, requestTimeoutMs }: ResetServerStateInput) => Promise<boolean>;
 
+interface ResolveTestBaseUrlOptions {
+    /** Project root containing node_modules/.luckystack/dev-server.json. */
+    cwd?: string;
+    /** Used when no explicit override or valid live advertisement exists. */
+    fallbackUrl?: string;
+}
+declare const resolveTestBaseUrl: (options?: ResolveTestBaseUrlOptions) => string;
+
+type MaybePromise<T> = T | Promise<T>;
+interface ResolveTestEnvironmentInput {
+    /**
+     * Loads the consumer's default-exported `config.ts` object after `.env` files
+     * are available. Keeping this as a callback avoids hardcoding a consumer path
+     * inside the package and keeps `@luckystack/secret-manager` optional.
+     */
+    loadProjectConfig?: () => MaybePromise<unknown>;
+}
+/**
+ * Load the project's env files and resolve optional secret-manager pointers for
+ * the TEST process. Call before importing integration-test modules that touch a
+ * database, Redis, or another env-backed SDK.
+ */
+declare const resolveTestEnvironment: (input?: ResolveTestEnvironmentInput) => Promise<void>;
+
 interface SampleSchemaOptions {
     /**
      * Marker prefix applied to generated UNCONSTRAINED string values so any rows
@@ -298,6 +322,12 @@ interface RunCustomTestsInput {
      * HTTP method (e.g. logout is DELETE). Falls back to POST when absent.
      */
     apiMethodMap?: ApiMethodMap$1;
+    /**
+     * Lazy consumer config for direct Layer-5 runs. Required so the public path
+     * cannot silently skip a configured secret manager; `runAllTests` prepares
+     * the environment separately before using the internal Layer-5 entrypoint.
+     */
+    loadProjectConfig: NonNullable<ResolveTestEnvironmentInput['loadProjectConfig']>;
     onResult?: (result: CustomTestResult) => void;
 }
 interface DiscoveredTestFile {
@@ -358,6 +388,12 @@ declare const runCustomTests: (input: RunCustomTestsInput) => Promise<RunCustomT
 type ApiInputSchemas = Partial<Record<string, Partial<Record<string, Partial<Record<string, ZodType | undefined>>>>>>;
 interface RunAllTestsInput {
     apiMethodMap: ApiMethodMap$1;
+    /**
+     * Lazy loader for the consumer's default `config.ts` export. Required so
+     * runAllTests cannot silently skip a configured secret manager; resolution
+     * happens in THIS process before any layer or env-backed client is touched.
+     */
+    loadProjectConfig: NonNullable<ResolveTestEnvironmentInput['loadProjectConfig']>;
     apiMetaMap: ApiMetaMap;
     apiInputSchemas: ApiInputSchemas;
     baseUrl: string;
@@ -510,4 +546,4 @@ declare const LAYER_KEYS: {
     readonly custom: "custom";
 };
 
-export { type ApiMetaEntry, type ApiMetaMap, type ApiMethodMap$1 as ApiMethodMap, type AuthEnforcementCheckInput, type ContractCheckInput, type ContractCheckResult, type CsrfEnforcementCheckInput, type CustomTestCase, type CustomTestResult, type EndpointDescriptor, type FuzzCheckInput, type HttpMethod, LAYER_KEYS, type OpenStreamWatcherInput, type RateLimitCheckInput, type ResetServerStateInput, type RunAllTestsInput, type RunAllTestsSummary, type RunAuthEnforcementTestsInput, type RunContractSummary, type RunContractTestsInput, type RunCsrfEnforcementTestsInput, type RunCustomTestsInput, type RunCustomTestsSummary, type RunFuzzTestsInput, type RunRateLimitTestsInput, type RunRegisteredLayersInput, type SampleSchemaOptions, type StreamChunkFrame, type StreamWatcher, type SyncMethodMap, TEST_DATA_PREFIX, type TestContext, type TestExpect, type TestFixture, type TestLayer, type TestLayerInput, type TestLayerResult, type TestReporter, type TestResult, type TestSummary, createTestDataMarker, discoverCustomTestFiles, getTestFixture, getTestReporter, listTestLayers, logContractResult, logContractSummary, logRunAllSummary, openStreamWatcher, registerTestFixture, registerTestLayer, registerTestReporter, resetServerState, resetTestExtensionsForTests, runAllTests, runAuthEnforcementCheck, runAuthEnforcementTests, runContractCheck, runContractTests, runCsrfEnforcementCheck, runCsrfEnforcementTests, runCustomTests, runFuzzCheck, runFuzzTests, runRateLimitCheck, runRateLimitTests, runRegisteredLayers, sampleSchemaInput, walkEndpoints, walkSyncEndpoints };
+export { type ApiMetaEntry, type ApiMetaMap, type ApiMethodMap$1 as ApiMethodMap, type AuthEnforcementCheckInput, type ContractCheckInput, type ContractCheckResult, type CsrfEnforcementCheckInput, type CustomTestCase, type CustomTestResult, type EndpointDescriptor, type FuzzCheckInput, type HttpMethod, LAYER_KEYS, type OpenStreamWatcherInput, type RateLimitCheckInput, type ResetServerStateInput, type ResolveTestBaseUrlOptions, type ResolveTestEnvironmentInput, type RunAllTestsInput, type RunAllTestsSummary, type RunAuthEnforcementTestsInput, type RunContractSummary, type RunContractTestsInput, type RunCsrfEnforcementTestsInput, type RunCustomTestsInput, type RunCustomTestsSummary, type RunFuzzTestsInput, type RunRateLimitTestsInput, type RunRegisteredLayersInput, type SampleSchemaOptions, type StreamChunkFrame, type StreamWatcher, type SyncMethodMap, TEST_DATA_PREFIX, type TestContext, type TestExpect, type TestFixture, type TestLayer, type TestLayerInput, type TestLayerResult, type TestReporter, type TestResult, type TestSummary, createTestDataMarker, discoverCustomTestFiles, getTestFixture, getTestReporter, listTestLayers, logContractResult, logContractSummary, logRunAllSummary, openStreamWatcher, registerTestFixture, registerTestLayer, registerTestReporter, resetServerState, resetTestExtensionsForTests, resolveTestBaseUrl, resolveTestEnvironment, runAllTests, runAuthEnforcementCheck, runAuthEnforcementTests, runContractCheck, runContractTests, runCsrfEnforcementCheck, runCsrfEnforcementTests, runCustomTests, runFuzzCheck, runFuzzTests, runRateLimitCheck, runRateLimitTests, runRegisteredLayers, sampleSchemaInput, walkEndpoints, walkSyncEndpoints };

package/dist/index.js

@@ -694,6 +694,83 @@ var runFuzzTests = async (input) => {
   return calculateSummary(results);
 };
 
+// src/resolveTestBaseUrl.ts
+import fs from "fs";
+import path from "path";
+var isProcessRunning = (pid) => {
+  if (typeof pid !== "number" || !Number.isInteger(pid) || pid <= 0) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    return error instanceof Error && "code" in error && error.code === "EPERM";
+  }
+};
+var resolveTestBaseUrl = (options = {}) => {
+  const explicit = process.env.TEST_BASE_URL;
+  if (explicit) return explicit;
+  try {
+    const raw = fs.readFileSync(
+      path.join(options.cwd ?? process.cwd(), "node_modules", ".luckystack", "dev-server.json"),
+      "utf8"
+    );
+    const info = JSON.parse(raw);
+    if (typeof info.port === "number" && Number.isInteger(info.port) && info.port > 0 && info.port <= 65535 && isProcessRunning(info.pid)) {
+      return `http://localhost:${String(info.port)}`;
+    }
+  } catch {
+  }
+  return options.fallbackUrl ?? "http://localhost:80";
+};
+
+// src/resolveTestEnvironment.ts
+import { loadEnvFiles, tryCatch as tryCatch3 } from "@luckystack/core";
+var assertProjectConfigLoader = (input, caller) => {
+  if (typeof input !== "object" || input === null || !("loadProjectConfig" in input) || typeof input.loadProjectConfig !== "function") {
+    throw new TypeError(`[test-runner] ${caller} requires a lazy loadProjectConfig callback`);
+  }
+};
+var isRecord = (value) => typeof value === "object" && value !== null;
+var isToken = (value) => typeof value === "string" || isRecord(value) && typeof value.fromFile === "string";
+var readSecretManagerConfig = (projectConfig) => {
+  if (!isRecord(projectConfig)) return null;
+  const candidate = projectConfig.secretManager;
+  if (!isRecord(candidate)) return null;
+  const url = candidate.url;
+  if (url === void 0 || url === "") return null;
+  if (typeof url !== "string") {
+    throw new TypeError("[test-runner] config.secretManager.url must be a string.");
+  }
+  if (!isToken(candidate.token)) {
+    throw new TypeError(
+      "[test-runner] config.secretManager.token must be a string or { fromFile: string }."
+    );
+  }
+  return { ...candidate, url, token: candidate.token };
+};
+var resolveTestEnvironment = async (input = {}) => {
+  loadEnvFiles();
+  if (!input.loadProjectConfig) return;
+  const projectConfig = await input.loadProjectConfig();
+  const secretManagerConfig = readSecretManagerConfig(projectConfig);
+  if (!secretManagerConfig) return;
+  const [importError, secretManager] = await tryCatch3(
+    () => import("@luckystack/secret-manager")
+  );
+  if (importError || !secretManager) {
+    throw new Error(
+      "[test-runner] config.secretManager.url is set, but @luckystack/secret-manager could not be loaded. Install the package or remove the secret-manager config; tests will not continue with unresolved env pointers.",
+      { cause: importError ?? void 0 }
+    );
+  }
+  await secretManager.initSecretManager({
+    ...secretManagerConfig,
+    //? Match the normal server/ORM bootstrap: configured remote resolution is
+    //? fail-fast. A raw DATABASE_URL_V<n> must never leak into Prisma.
+    source: "remote"
+  });
+};
+
 // src/schemaSampleInput.ts
 var innerDef = (node) => node ? node.def ?? node._def : void 0;
 var sampleForDef = (def, options) => {
@@ -859,17 +936,17 @@ var logContractSummary = (summary) => {
 
 // src/customTests.ts
 import crypto from "crypto";
-import fs from "fs";
-import path from "path";
+import fs2 from "fs";
+import path2 from "path";
 import { pathToFileURL } from "url";
-import { getCsrfConfig, getPrismaClient, getProjectConfig as getProjectConfig3, getSrcDir, tryCatch as tryCatch4, tryCatchSync } from "@luckystack/core";
+import { getCsrfConfig, getPrismaClient, getProjectConfig as getProjectConfig3, getSrcDir, tryCatch as tryCatch5, tryCatchSync } from "@luckystack/core";
 
 // src/streamWatcher.ts
 import { io as createSocketIoClient } from "socket.io-client";
 import {
   buildJoinRoomResponseEventName,
   socketEventNames,
-  tryCatch as tryCatch3,
+  tryCatch as tryCatch4,
   getProjectConfig as getProjectConfig2
 } from "@luckystack/core";
 var DEFAULT_TIMEOUT_MS = 5e3;
@@ -956,7 +1033,7 @@ var openStreamWatcher = async (input) => {
     }
   };
   socket.on(socketEventNames.sync, handleChunk);
-  const [connectError] = await tryCatch3(() => waitForConnect(socket));
+  const [connectError] = await tryCatch4(() => waitForConnect(socket));
   if (connectError) {
     socket.off(socketEventNames.sync, handleChunk);
     socket.disconnect();
@@ -967,7 +1044,7 @@ var openStreamWatcher = async (input) => {
     group: input.roomCode,
     responseIndex
   });
-  const [joinError] = await tryCatch3(() => waitForJoinAck(socket, responseIndex));
+  const [joinError] = await tryCatch4(() => waitForJoinAck(socket, responseIndex));
   if (joinError) {
     socket.off(socketEventNames.sync, handleChunk);
     socket.disconnect();
@@ -1024,36 +1101,36 @@ var API_TEST_FILE_PATTERN = /_v(\d+)\.tests\.ts$/;
 var SYNC_SERVER_TEST_FILE_PATTERN = /_server_v(\d+)\.tests\.ts$/;
 var DEFAULT_CALL_TIMEOUT_MS = 1e4;
 var discoverCustomTestFiles = (srcDir = getSrcDir()) => {
-  if (!fs.existsSync(srcDir)) return [];
+  if (!fs2.existsSync(srcDir)) return [];
   const found = [];
   const stack = [srcDir];
   const visited = /* @__PURE__ */ new Set();
   while (stack.length > 0) {
     const current = stack.pop();
     if (current === void 0) break;
-    const [realError, realPath] = tryCatchSync(() => fs.realpathSync(current));
+    const [realError, realPath] = tryCatchSync(() => fs2.realpathSync(current));
     const canonical = realError || realPath === null ? current : realPath;
     if (visited.has(canonical)) continue;
     visited.add(canonical);
-    const [readError, entries] = tryCatchSync(() => fs.readdirSync(current, { withFileTypes: true }));
+    const [readError, entries] = tryCatchSync(() => fs2.readdirSync(current, { withFileTypes: true }));
     if (readError || entries === null) continue;
     for (const entry of entries) {
-      const fullPath = path.join(current, entry.name);
+      const fullPath = path2.join(current, entry.name);
       if (entry.isSymbolicLink()) continue;
       if (entry.isDirectory()) {
         stack.push(fullPath);
         continue;
       }
       if (!entry.isFile() || !entry.name.endsWith(".tests.ts")) continue;
-      const parentDir = path.basename(current);
+      const parentDir = path2.basename(current);
       if (parentDir !== "_api" && parentDir !== "_sync") continue;
       const pattern = parentDir === "_api" ? API_TEST_FILE_PATTERN : SYNC_SERVER_TEST_FILE_PATTERN;
       const versionMatch = pattern.exec(entry.name);
       if (!versionMatch) continue;
       const version = `v${versionMatch[1]}`;
       const namePart = entry.name.replace(parentDir === "_api" ? /_v\d+\.tests\.ts$/ : /_server_v\d+\.tests\.ts$/, "");
-      const pageDir = path.dirname(current);
-      const relativePage = path.relative(srcDir, pageDir).replaceAll("\\", "/") || "system";
+      const pageDir = path2.dirname(current);
+      const relativePage = path2.relative(srcDir, pageDir).replaceAll("\\", "/") || "system";
       found.push({
         filePath: fullPath,
         kind: parentDir === "_api" ? "api" : "sync",
@@ -1081,7 +1158,7 @@ var buildExpect = () => ({
     if (!value) throw new AssertionError(message ?? `expected truthy value, got ${JSON.stringify(value)}`);
   },
   throws: async (fn, message) => {
-    const [err] = await tryCatch4(fn);
+    const [err] = await tryCatch5(fn);
     if (!err) throw new AssertionError(message ?? "expected fn to throw, but it did not");
     return err;
   },
@@ -1133,7 +1210,7 @@ var buildSessionHelpers = (state) => {
   };
 };
 var parseResponse = async (response, state) => {
-  const [textError, text] = await tryCatch4(() => response.text());
+  const [textError, text] = await tryCatch5(() => response.text());
   if (textError || text === null) {
     state.lastResponse = null;
     throw new Error(`failed to read response body (HTTP ${response.status}): ${textError?.message ?? "unknown"}`);
@@ -1159,7 +1236,7 @@ var buildCallApi = (baseUrl, routePath, state, cookieName, method) => {
     }, DEFAULT_CALL_TIMEOUT_MS);
     const init = { method, headers, signal: controller.signal };
     if (method !== "GET" && method !== "HEAD") init.body = JSON.stringify(input ?? {});
-    const [fetchError, response] = await tryCatch4(() => fetch(url, init));
+    const [fetchError, response] = await tryCatch5(() => fetch(url, init));
     clearTimeout(timeoutHandle);
     if (fetchError || !response) {
       state.lastResponse = null;
@@ -1179,7 +1256,7 @@ var buildCallSync = (baseUrl, routePath, state, cookieName) => {
     const timeoutHandle = setTimeout(() => {
       controller.abort();
     }, DEFAULT_CALL_TIMEOUT_MS);
-    const [fetchError, response] = await tryCatch4(() => fetch(url, {
+    const [fetchError, response] = await tryCatch5(() => fetch(url, {
       method: "POST",
       headers,
       body: JSON.stringify(body),
@@ -1214,7 +1291,7 @@ var buildContext = (discovery, input) => {
     while (watchers.length > 0) {
       const watcher = watchers.pop();
       if (!watcher) continue;
-      const [closeError] = await tryCatch4(() => watcher.close());
+      const [closeError] = await tryCatch5(() => watcher.close());
       if (closeError) {
       }
     }
@@ -1234,17 +1311,17 @@ var buildContext = (discovery, input) => {
   };
   return { ctx, closeAllWatchers, state };
 };
-var runCustomTests = async (input) => {
+var runCustomTestsAfterEnvironmentPrepared = async (input) => {
   const srcDir = getSrcDir();
   const files = discoverCustomTestFiles(srcDir);
   const results = [];
   for (const discovery of files) {
     const routePath = `${discovery.route.page}/${discovery.route.name}/${discovery.route.version}`;
     if (input.filter && !routePath.includes(input.filter)) continue;
-    const [realPathErr, realFilePath] = tryCatchSync(() => fs.realpathSync(discovery.filePath));
+    const [realPathErr, realFilePath] = tryCatchSync(() => fs2.realpathSync(discovery.filePath));
     const resolvedPath = realPathErr ? discovery.filePath : realFilePath ?? discovery.filePath;
-    const relToSrc = path.relative(srcDir, resolvedPath);
-    if (relToSrc.startsWith("..") || path.isAbsolute(relToSrc)) {
+    const relToSrc = path2.relative(srcDir, resolvedPath);
+    if (relToSrc.startsWith("..") || path2.isAbsolute(relToSrc)) {
       const r = {
         routePath,
         caseName: "(import)",
@@ -1256,7 +1333,7 @@ var runCustomTests = async (input) => {
       input.onResult?.(r);
       continue;
     }
-    const [importError, mod] = await tryCatch4(
+    const [importError, mod] = await tryCatch5(
       () => import(pathToFileURL(resolvedPath).href)
     );
     if (importError || !mod) {
@@ -1281,11 +1358,11 @@ var runCustomTests = async (input) => {
       const expectedToFail = typeof c.expectedToFail === "string" ? c.expectedToFail : void 0;
       const built = buildContext(discovery, input);
       const started = Date.now();
-      const [runError] = await tryCatch4(async () => c.run(built.ctx));
-      await tryCatch4(() => built.closeAllWatchers());
+      const [runError] = await tryCatch5(async () => c.run(built.ctx));
+      await tryCatch5(() => built.closeAllWatchers());
       const residualToken = built.state.token;
       if (residualToken) {
-        await tryCatch4(async () => {
+        await tryCatch5(async () => {
           const { deleteSession } = await import("@luckystack/login");
           await deleteSession(residualToken);
         });
@@ -1319,6 +1396,11 @@ var runCustomTests = async (input) => {
     results
   };
 };
+var runCustomTests = async (input) => {
+  assertProjectConfigLoader(input, "runCustomTests");
+  await resolveTestEnvironment({ loadProjectConfig: input.loadProjectConfig });
+  return runCustomTestsAfterEnvironmentPrepared(input);
+};
 
 // src/runAllTests.ts
 import { clearAllRateLimits, getCsrfConfig as getCsrfConfig2, getProjectConfig as getProjectConfig4 } from "@luckystack/core";
@@ -1436,7 +1518,7 @@ var runCustomLayer = async (input, summary) => {
     await clearAllRateLimits();
   } catch {
   }
-  const custom = await runCustomTests({
+  const custom = await runCustomTestsAfterEnvironmentPrepared({
     baseUrl: input.baseUrl,
     sessionCookieName: input.sessionCookieName,
     filter: input.filter,
@@ -1472,6 +1554,8 @@ var computeTotals = (summary) => {
   summary.totalFailed = failed + (summary.custom?.failed ?? 0);
 };
 var runAllTests = async (input) => {
+  assertProjectConfigLoader(input, "runAllTests");
+  await resolveTestEnvironment({ loadProjectConfig: input.loadProjectConfig });
   const summary = { totalPassed: 0, totalFailed: 0 };
   if (!input.noSweep) {
     const hasRoutes = Object.keys(input.apiMethodMap).length > 0;
@@ -1607,7 +1691,7 @@ var resetTestExtensionsForTests = () => {
 };
 
 // src/runRegisteredLayers.ts
-import { tryCatch as tryCatch5, tryCatchSync as tryCatchSync2 } from "@luckystack/core";
+import { tryCatch as tryCatch6, tryCatchSync as tryCatchSync2 } from "@luckystack/core";
 var isLoopbackHost = (host) => host === "localhost" || host === "::1" || host === "[::1]" || /^127\.\d+\.\d+\.\d+$/.test(host);
 var postWebhook = async (summary) => {
   const reporter2 = getTestReporter();
@@ -1625,7 +1709,7 @@ var postWebhook = async (summary) => {
   const timeoutHandle = setTimeout(() => {
     controller.abort();
   }, 1e4);
-  await tryCatch5(() => fetch(webhookUrl, {
+  await tryCatch6(() => fetch(webhookUrl, {
     method: "POST",
     headers,
     body: JSON.stringify(summary),
@@ -1643,7 +1727,7 @@ var runRegisteredLayers = async (input) => {
     for (const endpoint of endpoints) {
       if (shouldSkip(endpoint, skip)) continue;
       const started = Date.now();
-      const [runError, layerResult] = await tryCatch5(async () => layer.run({ endpoint: endpoint.fullPath, method: endpoint.method, authToken: input.authToken }));
+      const [runError, layerResult] = await tryCatch6(async () => layer.run({ endpoint: endpoint.fullPath, method: endpoint.method, authToken: input.authToken }));
       const durationMs = Date.now() - started;
       const result = runError || !layerResult ? {
         layer: layer.name,
@@ -1660,7 +1744,7 @@ var runRegisteredLayers = async (input) => {
         metadata: layerResult.metadata
       };
       results.push(result);
-      await tryCatch5(async () => reporter2?.onResult?.(result));
+      await tryCatch6(async () => reporter2?.onResult?.(result));
     }
   }
   const summary = {
@@ -1670,7 +1754,7 @@ var runRegisteredLayers = async (input) => {
     failed: results.filter((r) => !r.passed).length,
     results
   };
-  await tryCatch5(async () => reporter2?.onSummary?.(summary));
+  await tryCatch6(async () => reporter2?.onSummary?.(summary));
   await postWebhook(summary);
   return summary;
 };
@@ -1691,6 +1775,8 @@ export {
   registerTestReporter,
   resetServerState,
   resetTestExtensionsForTests,
+  resolveTestBaseUrl,
+  resolveTestEnvironment,
   runAllTests,
   runAuthEnforcementCheck,
   runAuthEnforcementTests,