@elench/testkit 0.1.39 → 0.1.41

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

@@ -2,6 +2,7 @@ import type { AuthAdapter, HeaderBuilder, HttpSuiteConfig } from "../index";
 
 export interface LocalDatabaseConfig {
   provider: "local";
+  binding?: "shared" | "per-runtime";
   image?: string;
   password?: string;
   reset?: boolean;
@@ -33,25 +34,28 @@ export interface SkipConfig {
   suites?: SkipSuiteRule[];
 }
 
-export interface SuiteExecutionRule {
+export interface RuntimeConfig {
+  instances?: number;
+}
+
+export interface SuiteRequirementRule {
   selector: string;
-  stackMode: "shared" | "pooled" | "isolated";
+  locks?: string[];
 }
 
-export interface FileExecutionRule {
+export interface FileRequirementRule {
   path: string;
-  stackMode: "shared" | "pooled" | "isolated";
+  locks?: string[];
 }
 
-export interface ServiceExecutionConfig {
-  suites?: SuiteExecutionRule[];
-  files?: FileExecutionRule[];
+export interface ServiceRequirementConfig {
+  suites?: SuiteRequirementRule[];
+  files?: FileRequirementRule[];
 }
 
 export interface TestkitExecutionConfig {
   workers?: number;
-  stackMode?: "shared" | "pooled" | "isolated";
-  stackCount?: number;
+  fileTimeoutSeconds?: number;
 }
 
 export interface ServiceConfig {
@@ -75,8 +79,9 @@ export interface ServiceConfig {
   };
   migrate?: LifecycleConfig;
   seed?: LifecycleConfig;
+  runtime?: RuntimeConfig;
+  requirements?: ServiceRequirementConfig;
   skip?: SkipConfig;
-  execution?: ServiceExecutionConfig;
 }
 
 export interface TestkitSetup {

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.41",
   "description": "CLI for discovering and running local HTTP, DAL, and Playwright test suites",
   "type": "module",
   "types": "./lib/index.d.ts",

package/lib/runner/stack-manager.mjs

@@ -1,146 +0,0 @@
-import { buildStackIds } from "./execution-config.mjs";
-import {
-  cleanupStackContext,
-  createStackContext,
-  ensureStackContextReady,
-} from "./runtime-contexts.mjs";
-
-export function createStackManager({ productDir, graphs, execution, lifecycle }) {
-  const graphByKey = new Map(graphs.map((graph) => [graph.key, graph]));
-  const pools = new Map();
-
-  return {
-    async acquire(batch) {
-      const pool = getPool(pools, graphByKey, batch, execution, productDir, lifecycle);
-      while (true) {
-        if (lifecycle.isStopRequested()) {
-          throw lifecycle.signal.reason || new Error("testkit run interrupted");
-        }
-
-        const slot = claimSlot(pool, batch.accessMode);
-        if (!slot) {
-          await sleep(25);
-          continue;
-        }
-
-        try {
-          const context = await getReadyContext(slot, graphByKey, productDir, batch, lifecycle);
-          return {
-            slot,
-            context,
-          };
-        } catch (error) {
-          releaseSlot(slot, batch.accessMode);
-          await invalidateSlot(slot, lifecycle);
-          throw error;
-        }
-      }
-    },
-    async release(lease, options = {}) {
-      if (!lease?.slot) return;
-      releaseSlot(lease.slot, options.accessMode || lease.slot.lastAccessMode);
-      if (options.invalidate) {
-        await invalidateSlot(lease.slot, lifecycle);
-      }
-    },
-    async cleanupAll() {
-      for (const pool of pools.values()) {
-        for (const slot of pool.slots) {
-          await invalidateSlot(slot, lifecycle);
-        }
-      }
-    },
-  };
-}
-
-function getPool(pools, graphByKey, batch, execution, productDir, lifecycle) {
-  const key = `${batch.graphKey}:${batch.stackMode}`;
-  const existing = pools.get(key);
-  if (existing) return existing;
-
-  const graph = graphByKey.get(batch.graphKey);
-  if (!graph) {
-    throw new Error(`Unknown graph "${batch.graphKey}"`);
-  }
-
-  const slots = buildPoolStackIds(batch.stackMode, execution).map((stackId) => ({
-    graph,
-    stackId,
-    context: null,
-    activeSharedCount: 0,
-    exclusiveActive: false,
-    lastAccessMode: null,
-    contextPromise: null,
-  }));
-  const pool = {
-    productDir,
-    lifecycle,
-    slots,
-  };
-  pools.set(key, pool);
-  return pool;
-}
-
-function buildPoolStackIds(stackMode, execution) {
-  if (stackMode === "isolated") {
-    return Array.from({ length: execution.workers }, (_unused, index) => `isolated-${index + 1}`);
-  }
-  if (stackMode === "shared") {
-    return ["shared"];
-  }
-  return buildStackIds({
-    stackMode: "pooled",
-    stackCount: execution.stackCount,
-  });
-}
-
-function claimSlot(pool, accessMode) {
-  if (accessMode === "shared") {
-    const candidates = pool.slots.filter((slot) => !slot.exclusiveActive);
-    if (candidates.length === 0) return null;
-    const slot = [...candidates].sort((left, right) => left.activeSharedCount - right.activeSharedCount)[0];
-    slot.activeSharedCount += 1;
-    slot.lastAccessMode = "shared";
-    return slot;
-  }
-
-  const slot = pool.slots.find((candidate) => !candidate.exclusiveActive && candidate.activeSharedCount === 0);
-  if (!slot) return null;
-  slot.exclusiveActive = true;
-  slot.lastAccessMode = "exclusive";
-  return slot;
-}
-
-async function getReadyContext(slot, graphByKey, productDir, batch, lifecycle) {
-  if (!slot.context) {
-    slot.context = createStackContext(slot.stackId, slot.graph, productDir);
-    lifecycle.trackGraphContext(slot.context);
-  }
-  if (!slot.contextPromise) {
-    slot.contextPromise = Promise.resolve(slot.context);
-  }
-  await slot.contextPromise;
-  await ensureStackContextReady(slot.context, batch, lifecycle);
-  return slot.context;
-}
-
-function releaseSlot(slot, accessMode) {
-  if (accessMode === "shared") {
-    slot.activeSharedCount = Math.max(0, slot.activeSharedCount - 1);
-    return;
-  }
-  slot.exclusiveActive = false;
-}
-
-async function invalidateSlot(slot, lifecycle) {
-  if (!slot.context) return;
-  await cleanupStackContext(slot.context, lifecycle);
-  slot.context = null;
-  slot.contextPromise = null;
-  slot.activeSharedCount = 0;
-  slot.exclusiveActive = false;
-}
-
-function sleep(ms) {
-  return new Promise((resolve) => setTimeout(resolve, ms));
-}