@elench/testkit 0.1.39 → 0.1.40

package/README.md

@@ -24,6 +24,9 @@ npx @elench/testkit --type pw
 # Shared local stack with parallel workers
 npx @elench/testkit --workers 8 --stack-mode shared
 
+# One file-level wall clock budget for every suite file
+npx @elench/testkit --file-timeout-seconds 60
+
 # Two reusable local stacks for browser-heavy suites
 npx @elench/testkit --workers 6 --stack-mode pooled --stack-count 2
 
@@ -66,6 +69,7 @@ import {
 export default defineTestkitSetup({
   execution: {
     workers: 8,
+    fileTimeoutSeconds: 60,
     stackMode: "shared",
     stackCount: 1,
   },
@@ -118,6 +122,7 @@ export default defineTestkitSetup({
 for:
 
 - worker and stack topology
+- per-file wall clock timeout budget
 - multi-service graphs
 - local DB configuration
 - migrate / seed commands
@@ -168,7 +173,20 @@ export default suite;
 Low-level runtime primitives remain available:
 
 ```ts
-import { check, group, http } from "@elench/testkit/runtime";
+import { check, group, http, waitFor } from "@elench/testkit/runtime";
+```
+
+`waitFor()` consumes the file budget configured by `execution.fileTimeoutSeconds`.
+Consumers should not set local timeout values in test files.
+
+```ts
+import { waitFor } from "@elench/testkit/runtime";
+
+const response = waitFor(
+  () => req("GET", "/api/v1/jobs/123", setupData),
+  (res) => JSON.parse(res.body).data?.status === "completed",
+  { description: "job 123 to complete" }
+);
 ```
 
 ## Discovery

package/lib/cli/args.mjs

@@ -1,6 +1,7 @@
 import path from "path";
 import { normalizeTypeValues, parseSuiteSelectors } from "../runner/suite-selection.mjs";
 import {
+  parseFileTimeoutOption,
   parseStackCountOption,
   parseStackModeOption,
   parseWorkersOption,
@@ -45,7 +46,12 @@ export function parseSuiteOption(values) {
   return parseSuiteSelectors(input);
 }
 
-export { parseWorkersOption, parseStackModeOption, parseStackCountOption };
+export {
+  parseFileTimeoutOption,
+  parseWorkersOption,
+  parseStackModeOption,
+  parseStackCountOption,
+};
 
 export function parseShardOption(value) {
   if (!value) return null;

package/lib/cli/args.test.mjs

@@ -1,5 +1,6 @@
 import { describe, expect, it } from "vitest";
 import {
+  parseFileTimeoutOption,
   parseShardOption,
   parseStackCountOption,
   parseStackModeOption,
@@ -59,9 +60,13 @@ describe("cli-args", () => {
 
   it("parses and validates execution options", () => {
     expect(parseWorkersOption("3")).toBe(3);
+    expect(parseFileTimeoutOption("45")).toBe(45);
     expect(parseStackCountOption("2")).toBe(2);
     expect(parseStackModeOption("pooled")).toBe("pooled");
     expect(() => parseWorkersOption("0")).toThrow("Invalid --workers value");
+    expect(() => parseFileTimeoutOption("0")).toThrow(
+      "Invalid --file-timeout-seconds value"
+    );
     expect(() => parseStackModeOption("legacy")).toThrow("Invalid --stack-mode value");
   });
 

package/lib/cli/index.mjs

@@ -1,6 +1,7 @@
 import { cac } from "cac";
 import { loadConfigs } from "../config/index.mjs";
 import {
+  parseFileTimeoutOption,
   parseShardOption,
   parseStackCountOption,
   parseStackModeOption,
@@ -24,12 +25,9 @@ export function run() {
     .option("-s, --suite <name>", "Run specific suite(s)", { default: [] })
     .option("-f, --file <path>", "Run specific file(s)", { default: [] })
     .option("--dir <path>", "Explicit product directory")
-    .option("--workers <n>", "Number of test executors for the whole run", {
-      default: "1",
-    })
-    .option("--stack-mode <mode>", "Stack topology: shared, pooled, or isolated", {
-      default: "isolated",
-    })
+    .option("--workers <n>", "Number of test executors for the whole run")
+    .option("--file-timeout-seconds <n>", "Per-file wall-clock timeout in seconds")
+    .option("--stack-mode <mode>", "Stack topology: shared, pooled, or isolated")
     .option("--stack-count <n>", "Number of prepared stacks when stack-mode=pooled")
     .option("--shard <i/n>", "Run only shard i of n at suite granularity")
     .option("--write-status", "Write a deterministic testkit.status.json snapshot")
@@ -68,8 +66,12 @@ export function run() {
         return;
       }
 
-      const workers = parseWorkersOption(options.workers);
-      const stackMode = parseStackModeOption(options.stackMode);
+      const workers = options.workers == null ? null : parseWorkersOption(options.workers);
+      const fileTimeoutSeconds =
+        options.fileTimeoutSeconds == null
+          ? null
+          : parseFileTimeoutOption(options.fileTimeoutSeconds);
+      const stackMode = options.stackMode == null ? null : parseStackModeOption(options.stackMode);
       const stackCount =
         options.stackCount == null ? null : parseStackCountOption(options.stackCount);
       const shard = parseShardOption(options.shard);
@@ -87,6 +89,7 @@ export function run() {
           typeValues,
           fileNames,
           workers,
+          fileTimeoutSeconds,
           stackMode,
           stackCount,
           shard,

package/lib/config/index.mjs

@@ -8,7 +8,11 @@ import {
   parseSuiteSelectors,
   suiteSelectionType,
 } from "../runner/suite-selection.mjs";
-import { normalizeExecutionConfig, normalizeStackModeValue } from "../runner/execution-config.mjs";
+import {
+  DEFAULT_FILE_TIMEOUT_SECONDS,
+  normalizeExecutionConfig,
+  normalizeStackModeValue,
+} from "../runner/execution-config.mjs";
 
 const TESTKIT_K6_BIN = "TESTKIT_K6_BIN";
 const DEFAULT_LOCAL_IMAGE = "pgvector/pgvector:pg16";
@@ -587,6 +591,7 @@ function normalizeRepoExecution(execution) {
   if (!execution) {
     return normalizeExecutionConfig({
       workers: 1,
+      fileTimeoutSeconds: DEFAULT_FILE_TIMEOUT_SECONDS,
       stackMode: "isolated",
       stackCount: 1,
     });

package/lib/runner/default-runtime-runner.mjs

@@ -9,6 +9,10 @@ import { determineDefaultRuntimeFailure } from "./default-runtime-errors.mjs";
 import { formatBatchDescriptor } from "./formatting.mjs";
 import { buildExecutionEnv } from "./template.mjs";
 import { readDatabaseUrl } from "./state-io.mjs";
+import {
+  buildFileTimeoutEnv,
+  formatFileTimeoutBudgetError,
+} from "../shared/file-timeout.mjs";
 
 export async function runHttpK6Batch(targetConfig, batch, lifecycle) {
   const baseUrl = targetConfig.testkit.local?.baseUrl;
@@ -72,20 +76,27 @@ async function runDalTask(targetConfig, task, databaseUrl, lifecycle) {
 
 export async function runDefaultRuntimeTask(targetConfig, task, args, lifecycle, firstLine) {
   const k6Binary = resolveK6Binary();
+  const getFirstLine = firstLine || defaultFirstLine;
   const summaryFile = buildDefaultRuntimeSummaryPath(targetConfig, task);
   fs.mkdirSync(path.dirname(summaryFile), { recursive: true });
   const startedAt = Date.now();
-  const result = await execa(
+  const fileTimeoutSeconds = targetConfig.testkit.execution.fileTimeoutSeconds;
+  const subprocess = execa(
     k6Binary,
     [...args.slice(0, 1), "--summary-export", summaryFile, ...args.slice(1)],
     {
       cwd: targetConfig.productDir,
-      env: buildExecutionEnv(targetConfig, {}, process.env),
+      env: buildExecutionEnv(
+        targetConfig,
+        buildFileTimeoutEnv(fileTimeoutSeconds, startedAt),
+        process.env
+      ),
       reject: false,
       cancelSignal: lifecycle.signal,
       forceKillAfterDelay: 5_000,
     }
   );
+  const { result, timedOut } = await settleDefaultRuntimeProcess(subprocess, fileTimeoutSeconds);
 
   const stdout = parseDefaultRuntimeOutput(result.stdout || "");
   const stderr = parseDefaultRuntimeOutput(result.stderr || "");
@@ -98,7 +109,9 @@ export async function runDefaultRuntimeTask(targetConfig, task, args, lifecycle,
     task,
     [...stdout.artifacts, ...stderr.artifacts]
   );
-  const runtimeError = determineDefaultRuntimeFailure(result, summary, firstLine);
+  const runtimeError = timedOut
+    ? formatFileTimeoutBudgetError(fileTimeoutSeconds)
+    : determineDefaultRuntimeFailure(result, summary, getFirstLine);
   const finishedAt = Date.now();
 
   return {
@@ -112,6 +125,35 @@ export async function runDefaultRuntimeTask(targetConfig, task, args, lifecycle,
   };
 }
 
+function defaultFirstLine(output) {
+  return String(output || "")
+    .split(/\r?\n/)
+    .map((line) => line.trim())
+    .find(Boolean) || null;
+}
+
+async function settleDefaultRuntimeProcess(subprocess, fileTimeoutSeconds) {
+  const timeoutMs = fileTimeoutSeconds * 1000 + 1_000;
+  let timeoutHandle = null;
+  let timedOut = false;
+
+  try {
+    return await Promise.race([
+      subprocess.then((result) => ({ result, timedOut })),
+      new Promise((resolve) => {
+        timeoutHandle = setTimeout(async () => {
+          timedOut = true;
+          subprocess.kill("SIGTERM");
+          const result = await subprocess.catch((error) => error);
+          resolve({ result, timedOut: true });
+        }, timeoutMs);
+      }),
+    ]);
+  } finally {
+    if (timeoutHandle) clearTimeout(timeoutHandle);
+  }
+}
+
 export function buildDefaultRuntimeSummaryPath(targetConfig, task) {
   return path.join(
     targetConfig.stateDir || path.join(targetConfig.productDir, ".testkit"),

package/lib/runner/execution-config.mjs

@@ -1,5 +1,13 @@
+import {
+  DEFAULT_FILE_TIMEOUT_SECONDS,
+  normalizeFileTimeoutSeconds,
+  parseFileTimeoutOption,
+} from "../shared/file-timeout.mjs";
+
 export const STACK_MODES = new Set(["shared", "pooled", "isolated"]);
 
+export { DEFAULT_FILE_TIMEOUT_SECONDS, parseFileTimeoutOption };
+
 export function parseWorkersOption(value) {
   return parsePositiveInteger(value, "--workers");
 }
@@ -27,6 +35,8 @@ export function resolveExecutionConfig({ cli = {}, repo = {} } = {}) {
     workers: cli.workers ?? repo.workers ?? 1,
     stackMode: cli.stackMode ?? repo.stackMode ?? "isolated",
     stackCount: cli.stackCount ?? repo.stackCount ?? null,
+    fileTimeoutSeconds:
+      cli.fileTimeoutSeconds ?? repo.fileTimeoutSeconds ?? DEFAULT_FILE_TIMEOUT_SECONDS,
   });
 }
 
@@ -35,6 +45,9 @@ export function normalizeExecutionConfig(input = {}) {
   const stackMode = normalizeStackMode(input.stackMode);
   const explicitStackCount =
     input.stackCount == null ? null : normalizePositiveInteger(input.stackCount, "execution.stackCount");
+  const fileTimeoutSeconds = normalizeFileTimeoutSeconds(
+    input.fileTimeoutSeconds ?? DEFAULT_FILE_TIMEOUT_SECONDS
+  );
 
   if (stackMode === "shared") {
     if (explicitStackCount !== null && explicitStackCount !== 1) {
@@ -44,6 +57,7 @@ export function normalizeExecutionConfig(input = {}) {
       workers,
       stackMode,
       stackCount: 1,
+      fileTimeoutSeconds,
     };
   }
 
@@ -52,6 +66,7 @@ export function normalizeExecutionConfig(input = {}) {
       workers,
       stackMode,
       stackCount: explicitStackCount ?? 1,
+      fileTimeoutSeconds,
     };
   }
 
@@ -64,6 +79,7 @@ export function normalizeExecutionConfig(input = {}) {
     workers,
     stackMode,
     stackCount: workers,
+    fileTimeoutSeconds,
   };
 }
 

package/lib/runner/execution-config.test.mjs

@@ -1,7 +1,9 @@
 import { describe, expect, it } from "vitest";
 import {
   buildStackIds,
+  DEFAULT_FILE_TIMEOUT_SECONDS,
   normalizeExecutionConfig,
+  parseFileTimeoutOption,
   parseStackCountOption,
   parseStackModeOption,
   parseWorkersOption,
@@ -13,27 +15,34 @@ import {
 describe("execution-config", () => {
   it("parses worker and stack CLI options", () => {
     expect(parseWorkersOption("8")).toBe(8);
+    expect(parseFileTimeoutOption("45")).toBe(45);
     expect(parseStackCountOption("2")).toBe(2);
     expect(parseStackModeOption("pooled")).toBe("pooled");
     expect(() => parseWorkersOption("0")).toThrow('Invalid --workers value "0"');
+    expect(() => parseFileTimeoutOption("0")).toThrow(
+      'Invalid --file-timeout-seconds value "0"'
+    );
     expect(() => parseStackModeOption("legacy")).toThrow('Invalid --stack-mode value "legacy"');
   });
 
   it("normalizes shared, pooled, and isolated execution shapes", () => {
     expect(normalizeExecutionConfig({ workers: 8, stackMode: "shared" })).toEqual({
       workers: 8,
+      fileTimeoutSeconds: DEFAULT_FILE_TIMEOUT_SECONDS,
       stackMode: "shared",
       stackCount: 1,
     });
 
     expect(normalizeExecutionConfig({ workers: 8, stackMode: "pooled", stackCount: 3 })).toEqual({
       workers: 8,
+      fileTimeoutSeconds: DEFAULT_FILE_TIMEOUT_SECONDS,
       stackMode: "pooled",
       stackCount: 3,
     });
 
     expect(normalizeExecutionConfig({ workers: 8, stackMode: "isolated" })).toEqual({
       workers: 8,
+      fileTimeoutSeconds: DEFAULT_FILE_TIMEOUT_SECONDS,
       stackMode: "isolated",
       stackCount: 8,
     });
@@ -53,10 +62,11 @@ describe("execution-config", () => {
     expect(
       resolveExecutionConfig({
         repo: { workers: 3, stackMode: "shared" },
-        cli: { workers: 6, stackMode: "pooled", stackCount: 2 },
+        cli: { workers: 6, fileTimeoutSeconds: 90, stackMode: "pooled", stackCount: 2 },
       })
     ).toEqual({
       workers: 6,
+      fileTimeoutSeconds: 90,
       stackMode: "pooled",
       stackCount: 2,
     });

package/lib/runner/reporting.mjs

@@ -135,6 +135,7 @@ export function buildRunArtifact({
       finishedAt: new Date(finishedAt).toISOString(),
       durationMs: finishedAt - startedAt,
       workers: execution.workers,
+      fileTimeoutSeconds: execution.fileTimeoutSeconds,
       workerCount,
       stackMode: execution.stackMode,
       stackCount,

package/lib/runner/reporting.test.mjs

@@ -53,6 +53,7 @@ describe("runner reporting", () => {
       finishedAt: 4000,
       execution: {
         workers: 2,
+        fileTimeoutSeconds: 60,
         stackMode: "shared",
         stackCount: 1,
       },
@@ -82,6 +83,7 @@ describe("runner reporting", () => {
     expect(artifact.schemaVersion).toBe(3);
     expect(artifact.run).toMatchObject({
       workers: 2,
+      fileTimeoutSeconds: 60,
       workerCount: 1,
       stackMode: "shared",
       stackCount: 1,

package/lib/runtime/index.d.ts

@@ -29,6 +29,11 @@ export interface RuntimeArtifactOptions {
   summary?: string;
 }
 
+export interface WaitForOptions {
+  description?: string;
+  intervalSeconds?: number;
+}
+
 export interface RuntimeEnv {
   BASE: string;
   MACHINE_ID?: string;
@@ -139,6 +144,12 @@ export declare const http: RuntimeHttpClient;
 
 export declare function file(data: unknown, filename?: string, contentType?: string): unknown;
 export declare function json<T = unknown>(response: Pick<RuntimeResponse, "body">): T;
+export declare function remainingTimeSeconds(): number;
+export declare function waitFor<T>(
+  read: () => T,
+  isReady: (value: T) => boolean,
+  options?: WaitForOptions
+): T;
 export declare function emitArtifact(
   name: string,
   data: unknown,

package/lib/runtime/index.mjs

@@ -1,6 +1,13 @@
 import rawHttp from "k6/http";
 import { Rate, Trend } from "k6/metrics";
 import { check, fail, group, sleep } from "k6";
+import {
+  formatWaitForTimeoutError,
+  normalizeWaitIntervalSeconds,
+  readFileTimeoutBudget,
+  remainingFileTimeoutMs,
+  remainingFileTimeoutSeconds,
+} from "../shared/file-timeout.mjs";
 
 export { check, fail, group, sleep };
 export { Rate, Trend };
@@ -34,3 +41,30 @@ export {
   makeRawReq,
   makeReq,
 } from "../runtime-src/k6/http.js";
+
+export function remainingTimeSeconds() {
+  return remainingFileTimeoutSeconds(readFileTimeoutBudget(__ENV), Date.now());
+}
+
+export function waitFor(read, isReady, options = {}) {
+  const intervalSeconds = normalizeWaitIntervalSeconds(options.intervalSeconds);
+  const description = String(options.description || "condition").trim() || "condition";
+  const budget = readFileTimeoutBudget(__ENV);
+  let lastValue = read();
+
+  while (true) {
+    if (isReady(lastValue)) {
+      return lastValue;
+    }
+
+    const remainingMs = remainingFileTimeoutMs(budget, Date.now());
+    if (remainingMs <= 0) {
+      break;
+    }
+
+    sleep(Math.min(intervalSeconds, remainingMs / 1000));
+    lastValue = read();
+  }
+
+  throw new Error(formatWaitForTimeoutError(description, budget.fileTimeoutSeconds));
+}

package/lib/setup/index.d.ts

@@ -50,6 +50,7 @@ export interface ServiceExecutionConfig {
 
 export interface TestkitExecutionConfig {
   workers?: number;
+  fileTimeoutSeconds?: number;
   stackMode?: "shared" | "pooled" | "isolated";
   stackCount?: number;
 }

package/lib/shared/file-timeout.mjs

@@ -0,0 +1,107 @@
+export const DEFAULT_FILE_TIMEOUT_SECONDS = 60;
+export const FILE_TIMEOUT_INTERVAL_SECONDS = 0.25;
+export const INTERNAL_FILE_TIMEOUT_SECONDS_ENV = "TESTKIT_INTERNAL_FILE_TIMEOUT_SECONDS";
+export const INTERNAL_FILE_DEADLINE_MS_ENV = "TESTKIT_INTERNAL_FILE_DEADLINE_MS";
+
+export function parseFileTimeoutOption(value) {
+  return parsePositiveInteger(value, "--file-timeout-seconds");
+}
+
+export function normalizeFileTimeoutSeconds(
+  value,
+  label = "execution.fileTimeoutSeconds"
+) {
+  return normalizePositiveInteger(value, label);
+}
+
+export function normalizeWaitIntervalSeconds(value) {
+  if (value == null) return FILE_TIMEOUT_INTERVAL_SECONDS;
+  const normalized = Number(value);
+  if (!Number.isFinite(normalized) || normalized <= 0) {
+    throw new Error("waitFor intervalSeconds must be a positive number.");
+  }
+  return normalized;
+}
+
+export function buildFileTimeoutEnv(fileTimeoutSeconds, startedAtMs) {
+  const normalizedTimeoutSeconds = normalizeFileTimeoutSeconds(fileTimeoutSeconds);
+  const normalizedStartedAtMs = normalizeTimestamp(startedAtMs, "startedAtMs");
+
+  return {
+    [INTERNAL_FILE_TIMEOUT_SECONDS_ENV]: String(normalizedTimeoutSeconds),
+    [INTERNAL_FILE_DEADLINE_MS_ENV]: String(
+      normalizedStartedAtMs + normalizedTimeoutSeconds * 1000
+    ),
+  };
+}
+
+export function readFileTimeoutBudget(env) {
+  if (!env || typeof env !== "object") {
+    throw new Error("Runtime file timeout budget is missing.");
+  }
+
+  return {
+    fileTimeoutSeconds: normalizeFileTimeoutSeconds(
+      env[INTERNAL_FILE_TIMEOUT_SECONDS_ENV],
+      INTERNAL_FILE_TIMEOUT_SECONDS_ENV
+    ),
+    deadlineMs: normalizeTimestamp(
+      env[INTERNAL_FILE_DEADLINE_MS_ENV],
+      INTERNAL_FILE_DEADLINE_MS_ENV
+    ),
+  };
+}
+
+export function remainingFileTimeoutMs(budget, nowMs = Date.now()) {
+  const normalizedNowMs = normalizeTimestamp(nowMs, "nowMs");
+  const deadlineMs = normalizeTimestamp(budget?.deadlineMs, "deadlineMs");
+  return Math.max(0, deadlineMs - normalizedNowMs);
+}
+
+export function remainingFileTimeoutSeconds(budget, nowMs = Date.now()) {
+  return remainingFileTimeoutMs(budget, nowMs) / 1000;
+}
+
+export function formatWaitForTimeoutError(description, fileTimeoutSeconds) {
+  const normalizedDescription = String(description || "condition").trim() || "condition";
+  const normalizedFileTimeoutSeconds = normalizeFileTimeoutSeconds(
+    fileTimeoutSeconds,
+    "fileTimeoutSeconds"
+  );
+  return (
+    `Timed out waiting for ${normalizedDescription} before the ` +
+    `${normalizedFileTimeoutSeconds}s test file timeout`
+  );
+}
+
+export function formatFileTimeoutBudgetError(fileTimeoutSeconds) {
+  const normalizedFileTimeoutSeconds = normalizeFileTimeoutSeconds(
+    fileTimeoutSeconds,
+    "fileTimeoutSeconds"
+  );
+  return `Default runtime exceeded the ${normalizedFileTimeoutSeconds}s test file timeout`;
+}
+
+function parsePositiveInteger(value, label) {
+  const parsed = Number.parseInt(String(value), 10);
+  if (!Number.isInteger(parsed) || parsed <= 0) {
+    throw new Error(`Invalid ${label} value "${value}". Expected a positive integer.`);
+  }
+  return parsed;
+}
+
+function normalizePositiveInteger(value, label) {
+  const parsed = Number(value);
+  if (!Number.isInteger(parsed) || parsed <= 0) {
+    throw new Error(`${label} must be a positive integer.`);
+  }
+  return parsed;
+}
+
+function normalizeTimestamp(value, label) {
+  const parsed = Number(value);
+  if (!Number.isInteger(parsed) || parsed <= 0) {
+    throw new Error(`${label} must be a positive integer timestamp.`);
+  }
+  return parsed;
+}

package/lib/shared/file-timeout.test.mjs

@@ -0,0 +1,64 @@
+import { describe, expect, it } from "vitest";
+import {
+  buildFileTimeoutEnv,
+  DEFAULT_FILE_TIMEOUT_SECONDS,
+  formatFileTimeoutBudgetError,
+  formatWaitForTimeoutError,
+  normalizeFileTimeoutSeconds,
+  normalizeWaitIntervalSeconds,
+  parseFileTimeoutOption,
+  readFileTimeoutBudget,
+  remainingFileTimeoutMs,
+  remainingFileTimeoutSeconds,
+} from "./file-timeout.mjs";
+
+describe("file-timeout", () => {
+  it("normalizes positive file timeout values", () => {
+    expect(parseFileTimeoutOption("45")).toBe(45);
+    expect(normalizeFileTimeoutSeconds(DEFAULT_FILE_TIMEOUT_SECONDS)).toBe(60);
+    expect(() => parseFileTimeoutOption("0")).toThrow(
+      'Invalid --file-timeout-seconds value "0"'
+    );
+    expect(() => normalizeFileTimeoutSeconds(0)).toThrow(
+      "execution.fileTimeoutSeconds must be a positive integer."
+    );
+  });
+
+  it("builds and reads runtime timeout budget env", () => {
+    const env = buildFileTimeoutEnv(45, 1_000);
+    expect(env).toEqual({
+      TESTKIT_INTERNAL_FILE_TIMEOUT_SECONDS: "45",
+      TESTKIT_INTERNAL_FILE_DEADLINE_MS: "46000",
+    });
+
+    expect(readFileTimeoutBudget(env)).toEqual({
+      fileTimeoutSeconds: 45,
+      deadlineMs: 46_000,
+    });
+  });
+
+  it("computes remaining file timeout budget", () => {
+    const budget = {
+      fileTimeoutSeconds: 45,
+      deadlineMs: 46_000,
+    };
+
+    expect(remainingFileTimeoutMs(budget, 40_000)).toBe(6_000);
+    expect(remainingFileTimeoutMs(budget, 47_000)).toBe(0);
+    expect(remainingFileTimeoutSeconds(budget, 44_500)).toBe(1.5);
+  });
+
+  it("normalizes wait intervals and timeout errors", () => {
+    expect(normalizeWaitIntervalSeconds()).toBe(0.25);
+    expect(normalizeWaitIntervalSeconds(0.5)).toBe(0.5);
+    expect(() => normalizeWaitIntervalSeconds(0)).toThrow(
+      "waitFor intervalSeconds must be a positive number."
+    );
+    expect(formatWaitForTimeoutError("cron worker pickup", 60)).toBe(
+      "Timed out waiting for cron worker pickup before the 60s test file timeout"
+    );
+    expect(formatFileTimeoutBudgetError(60)).toBe(
+      "Default runtime exceeded the 60s test file timeout"
+    );
+  });
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@elench/testkit",
-  "version": "0.1.39",
+  "version": "0.1.40",
   "description": "CLI for discovering and running local HTTP, DAL, and Playwright test suites",
   "type": "module",
   "types": "./lib/index.d.ts",