@elench/testkit 0.1.38 → 0.1.40

package/lib/runner/worker-loop.mjs

@@ -1,11 +1,6 @@
 import { formatError } from "./formatting.mjs";
 import { runDalBatch, runHttpK6Batch } from "./default-runtime-runner.mjs";
 import { runPlaywrightBatch } from "./playwright-runner.mjs";
-import {
-  cleanupWorker,
-  ensureWorkerGraph,
-  resetCurrentGraph,
-} from "./runtime-contexts.mjs";
 
 const HTTP_K6_TYPES = new Set(["integration", "e2e", "load"]);
 
@@ -14,7 +9,6 @@ export function createWorker(workerId, productDir) {
     workerId,
     productDir,
     currentGraphKey: null,
-    graphContexts: new Map(),
     graphSwitches: 0,
     taskCount: 0,
   };
@@ -23,7 +17,7 @@ export function createWorker(workerId, productDir) {
 export async function runWorker(
   worker,
   queue,
-  graphByKey,
+  stackManager,
   trackers,
   timingUpdates,
   lifecycle,
@@ -32,7 +26,7 @@ export async function runWorker(
   recordGraphError
 ) {
   const startedAt = Date.now();
-  console.log(`\n══ global worker ${worker.workerId} ══`);
+  console.log(`\n══ worker ${worker.workerId} ══`);
   const errors = [];
 
   try {
@@ -41,9 +35,14 @@ export async function runWorker(
       const batch = claimNextBatch(queue, worker.currentGraphKey);
       if (!batch) break;
 
+      let lease = null;
       try {
-        const context = await ensureWorkerGraph(worker, batch, graphByKey, lifecycle);
-        const outcomes = await runBatch(context, batch, lifecycle);
+        if (worker.currentGraphKey && worker.currentGraphKey !== batch.graphKey) {
+          worker.graphSwitches += 1;
+        }
+        worker.currentGraphKey = batch.graphKey;
+        lease = await stackManager.acquire(batch);
+        const outcomes = await runBatch(lease.context, batch, lifecycle);
         for (const outcome of outcomes) {
           recordTaskOutcome(trackers, outcome.task, outcome);
           timingUpdates.push({
@@ -52,15 +51,19 @@ export async function runWorker(
           });
           worker.taskCount += 1;
         }
+        await stackManager.release(lease, { accessMode: batch.accessMode });
       } catch (error) {
         const message = formatError(error);
         errors.push(message);
-        recordGraphError(trackers, graphByKey.get(batch.graphKey), message);
-        await resetCurrentGraph(worker, lifecycle);
+        recordGraphError(trackers, { assignedTargets: lease?.context?.assignedTargets || [batch.targetName] }, message);
+        await stackManager.release(lease, {
+          accessMode: batch.accessMode,
+          invalidate: lease !== null,
+        });
       }
     }
   } finally {
-    await cleanupWorker(worker, lifecycle);
+    worker.currentGraphKey = null;
   }
 
   return {
@@ -76,7 +79,7 @@ export async function runWorker(
 async function runBatch(context, batch, lifecycle) {
   const targetConfig = context.configByName.get(batch.targetName);
   if (!targetConfig) {
-    throw new Error(`Worker graph missing target config "${batch.targetName}"`);
+    throw new Error(`Stack is missing target config "${batch.targetName}"`);
   }
 
   if (batch.framework === "playwright") {

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

@@ -33,6 +33,28 @@ export interface SkipConfig {
   suites?: SkipSuiteRule[];
 }
 
+export interface SuiteExecutionRule {
+  selector: string;
+  stackMode: "shared" | "pooled" | "isolated";
+}
+
+export interface FileExecutionRule {
+  path: string;
+  stackMode: "shared" | "pooled" | "isolated";
+}
+
+export interface ServiceExecutionConfig {
+  suites?: SuiteExecutionRule[];
+  files?: FileExecutionRule[];
+}
+
+export interface TestkitExecutionConfig {
+  workers?: number;
+  fileTimeoutSeconds?: number;
+  stackMode?: "shared" | "pooled" | "isolated";
+  stackCount?: number;
+}
+
 export interface ServiceConfig {
   database?: LocalDatabaseConfig;
   databaseFrom?: string;
@@ -55,9 +77,11 @@ export interface ServiceConfig {
   migrate?: LifecycleConfig;
   seed?: LifecycleConfig;
   skip?: SkipConfig;
+  execution?: ServiceExecutionConfig;
 }
 
 export interface TestkitSetup {
+  execution?: TestkitExecutionConfig;
   profiles?: {
     http?: Record<string, HttpSuiteConfig>;
   };

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