@elench/testkit 0.1.38 → 0.1.39

package/README.md

@@ -21,8 +21,11 @@ npx @elench/testkit --type e2e
 npx @elench/testkit --type int,e2e,dal
 npx @elench/testkit --type pw
 
-# Parallelize with isolated worker stacks
-npx @elench/testkit --jobs 3
+# Shared local stack with parallel workers
+npx @elench/testkit --workers 8 --stack-mode shared
+
+# Two reusable local stacks for browser-heavy suites
+npx @elench/testkit --workers 6 --stack-mode pooled --stack-count 2
 
 # Run a deterministic shard
 npx @elench/testkit --shard 1/3
@@ -61,6 +64,11 @@ import {
 } from "@elench/testkit/setup";
 
 export default defineTestkitSetup({
+  execution: {
+    workers: 8,
+    stackMode: "shared",
+    stackCount: 1,
+  },
   services: {
     api: service({
       ...tsxService({
@@ -109,6 +117,7 @@ export default defineTestkitSetup({
 `testkit.setup.ts` is optional for simple repos, but it is the primary escape hatch
 for:
 
+- worker and stack topology
 - multi-service graphs
 - local DB configuration
 - migrate / seed commands
@@ -197,7 +206,7 @@ Suite names are inferred from the colocated path:
 services that define `database: localDatabase(...)`.
 
 - template databases are cached
-- worker databases are cloned from templates
+- stack databases are cloned from templates
 - template fingerprints are derived automatically from env files, migrate/seed
   config, and repo contents
 

package/lib/cli/args.mjs

@@ -1,5 +1,10 @@
 import path from "path";
 import { normalizeTypeValues, parseSuiteSelectors } from "../runner/suite-selection.mjs";
+import {
+  parseStackCountOption,
+  parseStackModeOption,
+  parseWorkersOption,
+} from "../runner/execution-config.mjs";
 
 export const POSITIONAL_TYPES = new Set(["int", "e2e", "dal", "load", "pw", "all"]);
 export const LIFECYCLE = new Set(["status", "destroy", "cleanup"]);
@@ -40,13 +45,7 @@ export function parseSuiteOption(values) {
   return parseSuiteSelectors(input);
 }
 
-export function parseJobsOption(value) {
-  const jobs = Number.parseInt(String(value), 10);
-  if (!Number.isInteger(jobs) || jobs <= 0) {
-    throw new Error(`Invalid --jobs value "${value}". Expected a positive integer.`);
-  }
-  return jobs;
-}
+export { parseWorkersOption, parseStackModeOption, parseStackCountOption };
 
 export function parseShardOption(value) {
   if (!value) return null;

package/lib/cli/args.test.mjs

@@ -1,9 +1,11 @@
 import { describe, expect, it } from "vitest";
 import {
-  parseJobsOption,
   parseShardOption,
+  parseStackCountOption,
+  parseStackModeOption,
   parseSuiteOption,
   parseTypeOption,
+  parseWorkersOption,
   resolveRequestedFiles,
   resolveCliSelection,
 } from "./args.mjs";
@@ -55,9 +57,12 @@ describe("cli-args", () => {
     ]);
   });
 
-  it("parses and validates jobs", () => {
-    expect(parseJobsOption("3")).toBe(3);
-    expect(() => parseJobsOption("0")).toThrow("Invalid --jobs value");
+  it("parses and validates execution options", () => {
+    expect(parseWorkersOption("3")).toBe(3);
+    expect(parseStackCountOption("2")).toBe(2);
+    expect(parseStackModeOption("pooled")).toBe("pooled");
+    expect(() => parseWorkersOption("0")).toThrow("Invalid --workers value");
+    expect(() => parseStackModeOption("legacy")).toThrow("Invalid --stack-mode value");
   });
 
   it("parses and validates shards", () => {

package/lib/cli/index.mjs

@@ -1,10 +1,12 @@
 import { cac } from "cac";
 import { loadConfigs } from "../config/index.mjs";
 import {
-  parseJobsOption,
   parseShardOption,
+  parseStackCountOption,
+  parseStackModeOption,
   parseSuiteOption,
   parseTypeOption,
+  parseWorkersOption,
   resolveRequestedFiles,
   resolveCliSelection,
 } from "./args.mjs";
@@ -22,9 +24,13 @@ 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("--jobs <n>", "Number of isolated worker stacks for the whole run", {
+    .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("--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")
     .option("--allow-partial-status", "Allow --write-status for filtered runs")
@@ -62,7 +68,10 @@ export function run() {
         return;
       }
 
-      const jobs = parseJobsOption(options.jobs);
+      const workers = parseWorkersOption(options.workers);
+      const stackMode = parseStackModeOption(options.stackMode);
+      const stackCount =
+        options.stackCount == null ? null : parseStackCountOption(options.stackCount);
       const shard = parseShardOption(options.shard);
       const typeValues = parseTypeOption(options.type, positionalType);
       const suiteSelectors = parseSuiteOption(options.suite);
@@ -77,7 +86,9 @@ export function run() {
           ...options,
           typeValues,
           fileNames,
-          jobs,
+          workers,
+          stackMode,
+          stackCount,
           shard,
           serviceFilter: options.service || null,
         },

package/lib/config/index.mjs

@@ -8,6 +8,7 @@ import {
   parseSuiteSelectors,
   suiteSelectionType,
 } from "../runner/suite-selection.mjs";
+import { normalizeExecutionConfig, normalizeStackModeValue } from "../runner/execution-config.mjs";
 
 const TESTKIT_K6_BIN = "TESTKIT_K6_BIN";
 const DEFAULT_LOCAL_IMAGE = "pgvector/pgvector:pg16";
@@ -22,6 +23,7 @@ export function parseDotenv(filePath) {
 export async function loadConfigs(opts = {}) {
   const productDir = resolveProductDir(process.cwd(), opts.dir);
   const { setup, setupFile } = await loadTestkitSetup(productDir);
+  const execution = normalizeRepoExecution(setup.execution);
   const explicitServices = setup.services || {};
   const discovery = discoverProject(productDir, explicitServices);
   const serviceNames = new Set([
@@ -37,6 +39,7 @@ export async function loadConfigs(opts = {}) {
         productDir,
         setup,
         setupFile,
+        execution,
         explicitService: explicitServices[name] || {},
         discoveredService: discovery.services[name] || null,
         suites: discovery.suitesByService[name] || {},
@@ -95,6 +98,7 @@ function normalizeServiceConfig({
   productDir,
   setup,
   setupFile,
+  execution,
   explicitService,
   discoveredService,
   suites,
@@ -113,6 +117,10 @@ function normalizeServiceConfig({
     productDir,
     suites,
   });
+  const serviceExecution = normalizeServiceExecution(explicitService.execution, {
+    name,
+    suites,
+  });
 
   if (!explicitService.databaseFrom && !database && (migrate || seed)) {
     throw new Error(
@@ -140,10 +148,12 @@ function normalizeServiceConfig({
     telemetry: normalizeTelemetryConfig(setup.telemetry),
     suites,
     testkit: {
+      execution,
       dependsOn: explicitService.dependsOn || [],
       database,
       databaseFrom: explicitService.databaseFrom,
       envFiles,
+      serviceExecution,
       serviceEnv,
       migrate,
       seed,
@@ -341,6 +351,103 @@ function normalizeSkipConfig(value, { name, productDir, suites }) {
   };
 }
 
+function normalizeServiceExecution(value, { name, suites }) {
+  if (!value) return { suites: [], files: [], fileStackModeByPath: new Map() };
+
+  const discoveredSuites = [];
+  const discoveredFiles = new Set();
+  for (const [type, typedSuites] of Object.entries(suites || {})) {
+    for (const suite of typedSuites || []) {
+      discoveredSuites.push({
+        displayType: suiteSelectionType(type, suite.framework || "k6"),
+        name: suite.name,
+      });
+      for (const file of suite.files || []) {
+        discoveredFiles.add(file);
+      }
+    }
+  }
+
+  const suiteRules = [];
+  const seenSelectors = new Set();
+  for (const rule of value.suites || []) {
+    if (!rule || typeof rule !== "object") {
+      throw new Error(`Service "${name}" execution.suites entries must be objects`);
+    }
+    const selector = String(rule.selector || "").trim();
+    if (!selector) {
+      throw new Error(`Service "${name}" execution.suites entries require a selector`);
+    }
+    const parsed = parseSuiteSelectors([selector]);
+    if (parsed.length !== 1) {
+      throw new Error(`Service "${name}" execution.suites["${selector}"] is invalid`);
+    }
+    const parsedSelector = parsed[0];
+    if (parsedSelector.kind !== "typed") {
+      throw new Error(
+        `Service "${name}" execution.suites["${selector}"] must use a typed selector like int:health`
+      );
+    }
+    if (seenSelectors.has(parsedSelector.raw)) {
+      throw new Error(
+        `Service "${name}" defines duplicate execution.suites selector "${parsedSelector.raw}"`
+      );
+    }
+    const matched = discoveredSuites.some((suite) =>
+      matchesSuiteSelectors(suite.displayType, suite.name, [parsedSelector])
+    );
+    if (!matched) {
+      throw new Error(
+        `Service "${name}" execution.suites selector "${parsedSelector.raw}" did not match any discovered suite`
+      );
+    }
+    seenSelectors.add(parsedSelector.raw);
+    suiteRules.push({
+      selector: parsedSelector,
+      stackMode: normalizeStackModeValue(
+        rule.stackMode,
+        `Service "${name}" execution.suites["${parsedSelector.raw}"].stackMode`
+      ),
+    });
+  }
+
+  const fileRules = [];
+  const seenFiles = new Set();
+  for (const [index, rule] of (value.files || []).entries()) {
+    if (!rule || typeof rule !== "object") {
+      throw new Error(`Service "${name}" execution.files entries must be objects`);
+    }
+
+    const filePath = String(rule.path || "").trim();
+    if (!filePath) {
+      throw new Error(`Service "${name}" execution.files[${index}] requires a path`);
+    }
+    if (!discoveredFiles.has(filePath)) {
+      throw new Error(
+        `Service "${name}" execution.files["${filePath}"] did not match any discovered test file`
+      );
+    }
+    if (seenFiles.has(filePath)) {
+      throw new Error(`Service "${name}" defines duplicate execution.files path "${filePath}"`);
+    }
+
+    seenFiles.add(filePath);
+    fileRules.push({
+      path: filePath,
+      stackMode: normalizeStackModeValue(
+        rule.stackMode,
+        `Service "${name}" execution.files["${filePath}"].stackMode`
+      ),
+    });
+  }
+
+  return {
+    suites: suiteRules,
+    files: fileRules,
+    fileStackModeByPath: new Map(fileRules.map((rule) => [rule.path, rule.stackMode])),
+  };
+}
+
 function inferEnvFiles(productDir, explicitService, local) {
   if (explicitService.envFile || explicitService.envFiles) {
     const files = [];
@@ -476,6 +583,17 @@ function normalizeTelemetryConfig(telemetry) {
   };
 }
 
+function normalizeRepoExecution(execution) {
+  if (!execution) {
+    return normalizeExecutionConfig({
+      workers: 1,
+      stackMode: "isolated",
+      stackCount: 1,
+    });
+  }
+  return normalizeExecutionConfig(execution);
+}
+
 function normalizePath(value) {
   return String(value || "")
     .split(path.sep)

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

@@ -17,7 +17,7 @@ export async function runHttpK6Batch(targetConfig, batch, lifecycle) {
   }
 
   console.log(
-    `\n── ${targetConfig.workerLabel} ${batch.type}:${batch.tasks[0].suiteName}${formatBatchDescriptor(batch)} ──`
+    `\n── ${targetConfig.stackLabel} ${batch.type}:${batch.tasks[0].suiteName}${formatBatchDescriptor(batch)} ──`
   );
 
   return Promise.all(
@@ -32,7 +32,7 @@ export async function runDalBatch(targetConfig, batch, lifecycle) {
   }
 
   console.log(
-    `\n── ${targetConfig.workerLabel} ${batch.type}:${batch.tasks[0].suiteName}${formatBatchDescriptor(batch)} ──`
+    `\n── ${targetConfig.stackLabel} ${batch.type}:${batch.tasks[0].suiteName}${formatBatchDescriptor(batch)} ──`
   );
 
   return Promise.all(
@@ -46,7 +46,7 @@ async function runHttpK6Task(targetConfig, task, baseUrl, lifecycle) {
     serviceName: targetConfig.name,
     sourceFile: path.join(targetConfig.productDir, task.file),
   });
-  console.log(`·· ${targetConfig.workerLabel}:${task.suiteName} → ${task.file}`);
+  console.log(`·· ${targetConfig.stackLabel}:${task.suiteName} → ${task.file}`);
   return runDefaultRuntimeTask(
     targetConfig,
     task,
@@ -61,7 +61,7 @@ async function runDalTask(targetConfig, task, databaseUrl, lifecycle) {
     serviceName: targetConfig.name,
     sourceFile: path.join(targetConfig.productDir, task.file),
   });
-  console.log(`·· ${targetConfig.workerLabel}:${task.suiteName} → ${task.file}`);
+  console.log(`·· ${targetConfig.stackLabel}:${task.suiteName} → ${task.file}`);
   return runDefaultRuntimeTask(
     targetConfig,
     task,

package/lib/runner/execution-config.mjs

@@ -0,0 +1,108 @@
+export const STACK_MODES = new Set(["shared", "pooled", "isolated"]);
+
+export function parseWorkersOption(value) {
+  return parsePositiveInteger(value, "--workers");
+}
+
+export function parseStackCountOption(value) {
+  return parsePositiveInteger(value, "--stack-count");
+}
+
+export function parseStackModeOption(value) {
+  return normalizeStackModeValue(value, "--stack-mode");
+}
+
+export function normalizeStackModeValue(value, label = "execution.stackMode") {
+  const normalized = String(value || "").trim();
+  if (!STACK_MODES.has(normalized)) {
+    throw new Error(
+      `Invalid ${label} value "${value}". Expected one of: shared, pooled, isolated.`
+    );
+  }
+  return normalized;
+}
+
+export function resolveExecutionConfig({ cli = {}, repo = {} } = {}) {
+  return normalizeExecutionConfig({
+    workers: cli.workers ?? repo.workers ?? 1,
+    stackMode: cli.stackMode ?? repo.stackMode ?? "isolated",
+    stackCount: cli.stackCount ?? repo.stackCount ?? null,
+  });
+}
+
+export function normalizeExecutionConfig(input = {}) {
+  const workers = normalizePositiveInteger(input.workers, "execution.workers");
+  const stackMode = normalizeStackMode(input.stackMode);
+  const explicitStackCount =
+    input.stackCount == null ? null : normalizePositiveInteger(input.stackCount, "execution.stackCount");
+
+  if (stackMode === "shared") {
+    if (explicitStackCount !== null && explicitStackCount !== 1) {
+      throw new Error(`execution.stackCount must be 1 when stackMode is "shared".`);
+    }
+    return {
+      workers,
+      stackMode,
+      stackCount: 1,
+    };
+  }
+
+  if (stackMode === "pooled") {
+    return {
+      workers,
+      stackMode,
+      stackCount: explicitStackCount ?? 1,
+    };
+  }
+
+  if (explicitStackCount !== null && explicitStackCount !== workers) {
+    throw new Error(
+      `execution.stackCount must equal execution.workers when stackMode is "isolated".`
+    );
+  }
+  return {
+    workers,
+    stackMode,
+    stackCount: workers,
+  };
+}
+
+export function buildStackIds(execution) {
+  if (execution.stackMode === "shared") {
+    return ["shared"];
+  }
+
+  return Array.from({ length: execution.stackCount }, (_unused, index) => `stack-${index + 1}`);
+}
+
+export function resolveBatchStackMode(defaultMode, suiteMode = null) {
+  if (suiteMode == null) return defaultMode;
+  return normalizeStackMode(suiteMode);
+}
+
+export function resolveBatchAccessMode({ framework, type, stackMode }) {
+  if (stackMode === "isolated") return "exclusive";
+  if ((framework || "k6") === "playwright") return "exclusive";
+  if (type === "dal") return "exclusive";
+  return "shared";
+}
+
+function normalizeStackMode(value) {
+  return normalizeStackModeValue(value, "execution.stackMode");
+}
+
+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;
+}

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

@@ -0,0 +1,101 @@
+import { describe, expect, it } from "vitest";
+import {
+  buildStackIds,
+  normalizeExecutionConfig,
+  parseStackCountOption,
+  parseStackModeOption,
+  parseWorkersOption,
+  resolveBatchAccessMode,
+  resolveBatchStackMode,
+  resolveExecutionConfig,
+} from "./execution-config.mjs";
+
+describe("execution-config", () => {
+  it("parses worker and stack CLI options", () => {
+    expect(parseWorkersOption("8")).toBe(8);
+    expect(parseStackCountOption("2")).toBe(2);
+    expect(parseStackModeOption("pooled")).toBe("pooled");
+    expect(() => parseWorkersOption("0")).toThrow('Invalid --workers 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,
+      stackMode: "shared",
+      stackCount: 1,
+    });
+
+    expect(normalizeExecutionConfig({ workers: 8, stackMode: "pooled", stackCount: 3 })).toEqual({
+      workers: 8,
+      stackMode: "pooled",
+      stackCount: 3,
+    });
+
+    expect(normalizeExecutionConfig({ workers: 8, stackMode: "isolated" })).toEqual({
+      workers: 8,
+      stackMode: "isolated",
+      stackCount: 8,
+    });
+  });
+
+  it("rejects invalid stack-count combinations", () => {
+    expect(() =>
+      normalizeExecutionConfig({ workers: 8, stackMode: "shared", stackCount: 2 })
+    ).toThrow('execution.stackCount must be 1 when stackMode is "shared"');
+
+    expect(() =>
+      normalizeExecutionConfig({ workers: 8, stackMode: "isolated", stackCount: 2 })
+    ).toThrow('execution.stackCount must equal execution.workers when stackMode is "isolated"');
+  });
+
+  it("applies CLI values over repo execution defaults", () => {
+    expect(
+      resolveExecutionConfig({
+        repo: { workers: 3, stackMode: "shared" },
+        cli: { workers: 6, stackMode: "pooled", stackCount: 2 },
+      })
+    ).toEqual({
+      workers: 6,
+      stackMode: "pooled",
+      stackCount: 2,
+    });
+  });
+
+  it("builds stack ids from the normalized execution shape", () => {
+    expect(buildStackIds({ stackMode: "shared", stackCount: 1 })).toEqual(["shared"]);
+    expect(buildStackIds({ stackMode: "pooled", stackCount: 2 })).toEqual([
+      "stack-1",
+      "stack-2",
+    ]);
+  });
+
+  it("resolves batch stack and access modes", () => {
+    expect(resolveBatchStackMode("shared", null)).toBe("shared");
+    expect(resolveBatchStackMode("shared", "isolated")).toBe("isolated");
+
+    expect(
+      resolveBatchAccessMode({
+        framework: "k6",
+        type: "integration",
+        stackMode: "shared",
+      })
+    ).toBe("shared");
+
+    expect(
+      resolveBatchAccessMode({
+        framework: "playwright",
+        type: "e2e",
+        stackMode: "pooled",
+      })
+    ).toBe("exclusive");
+
+    expect(
+      resolveBatchAccessMode({
+        framework: "k6",
+        type: "dal",
+        stackMode: "shared",
+      })
+    ).toBe("exclusive");
+  });
+});

package/lib/runner/lifecycle.mjs

@@ -21,7 +21,7 @@ export function createRunLifecycle(productDir) {
     interruptReason: null,
     services: [],
     graphDirs: [],
-    workerStateDirs: [],
+    stackStateDirs: [],
     runtimeStateDirs: [],
   };
   const signalListeners = [];
@@ -66,7 +66,7 @@ export function createRunLifecycle(productDir) {
     trackGraphContext(context) {
       mutate((draft) => {
         pushUnique(draft.graphDirs, context.graphDir);
-        pushUnique(draft.workerStateDirs, context.workerStateDir);
+        pushUnique(draft.stackStateDirs, context.stackStateDir);
         for (const runtimeConfig of context.runtimeConfigs || []) {
           if (runtimeConfig.stateDir) pushUnique(draft.runtimeStateDirs, runtimeConfig.stateDir);
         }
@@ -78,7 +78,7 @@ export function createRunLifecycle(productDir) {
         draft.services = draft.services.filter((service) => service.pid !== child.pid);
         draft.services.push({
           serviceName: config.name,
-          workerLabel: config.workerLabel,
+          stackLabel: config.stackLabel,
           command: config.testkit.local?.start || null,
           cwd,
           pid: child.pid,
@@ -195,8 +195,8 @@ export function findPortOwner(productDir, { host, port }) {
 }
 
 export function formatRunSummary(manifest) {
-  const workerLabels = [...new Set((manifest.services || []).map((service) => service.workerLabel).filter(Boolean))];
-  return `${manifest.runId} pid=${manifest.pid}${workerLabels.length > 0 ? ` workers=${workerLabels.join(",")}` : ""}`;
+  const stackLabels = [...new Set((manifest.services || []).map((service) => service.stackLabel).filter(Boolean))];
+  return `${manifest.runId} pid=${manifest.pid}${stackLabels.length > 0 ? ` stacks=${stackLabels.join(",")}` : ""}`;
 }
 
 export function isPidRunning(pid) {
@@ -220,8 +220,8 @@ async function cleanupRunManifest(productDir, manifest, { removeRuntimeState = f
       await destroyRuntimeDatabase({ productDir, stateDir });
     }
 
-    for (const workerStateDir of [...new Set(manifest.workerStateDirs || [])].sort((a, b) => b.length - a.length)) {
-      fs.rmSync(workerStateDir, { recursive: true, force: true });
+    for (const stackStateDir of [...new Set(manifest.stackStateDirs || [])].sort((a, b) => b.length - a.length)) {
+      fs.rmSync(stackStateDir, { recursive: true, force: true });
     }
 
     for (const graphDir of [...new Set(manifest.graphDirs || [])].sort((a, b) => b.length - a.length)) {