@elench/testkit 0.1.40 → 0.1.42

package/README.md

@@ -1,8 +1,8 @@
 # @elench/testkit
 
 `@elench/testkit` discovers `*.testkit.ts` files, infers suite ownership from the
-filesystem, starts local services, provisions isolated local Postgres databases,
-and runs HTTP, DAL, and Playwright suites.
+filesystem, starts local services, provisions Docker-managed local Postgres
+databases, and runs HTTP, DAL, and Playwright suites.
 
 The package is now driven by `testkit.setup.ts`, not `testkit.config.json`.
 
@@ -21,15 +21,12 @@ npx @elench/testkit --type e2e
 npx @elench/testkit --type int,e2e,dal
 npx @elench/testkit --type pw
 
-# Shared local stack with parallel workers
-npx @elench/testkit --workers 8 --stack-mode shared
+# Parallel file execution
+npx @elench/testkit --workers 8
 
 # 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
-
 # Run a deterministic shard
 npx @elench/testkit --shard 1/3
 
@@ -70,8 +67,6 @@ export default defineTestkitSetup({
   execution: {
     workers: 8,
     fileTimeoutSeconds: 60,
-    stackMode: "shared",
-    stackCount: 1,
   },
   services: {
     api: service({
@@ -86,6 +81,18 @@ export default defineTestkitSetup({
       migrate: lifecycle("npm run db:migrate", {
         testkitCmd: "npm run db:migrate:testkit",
       }),
+      runtime: {
+        instances: 1,
+        maxConcurrentTasks: 4,
+      },
+      requirements: {
+        files: [
+          {
+            path: "src/api/routes/__testkit__/crawls-worker-concurrency.int.testkit.ts",
+            locks: ["global-worker-loop"],
+          },
+        ],
+      },
     }),
     frontend: service({
       ...nextService({
@@ -97,6 +104,9 @@ export default defineTestkitSetup({
       }),
       dependsOn: ["api"],
       envFiles: ["frontend/.env.testkit"],
+      runtime: {
+        instances: 1,
+      },
     }),
     billing: service({
       skip: {
@@ -121,10 +131,13 @@ export default defineTestkitSetup({
 `testkit.setup.ts` is optional for simple repos, but it is the primary escape hatch
 for:
 
-- worker and stack topology
+- worker count and per-file runtime budget
 - per-file wall clock timeout budget
 - multi-service graphs
-- local DB configuration
+- local runtime instance counts
+- per-runtime concurrent task caps
+- local DB binding configuration
+- explicit per-file or per-suite locks
 - migrate / seed commands
 - test-local migrate / seed overrides
 - named HTTP suite profiles
@@ -198,7 +211,7 @@ Example layouts:
 - `src/api/routes/__testkit__/auth/me.int.testkit.ts`
 - `src/db/__testkit__/sessions/count-type.dal.testkit.ts`
 - `frontend/__testkit__/navigation/navigation.pw.testkit.ts`
-- `avocado_api/internal/handler/__testkit__/repos/crud.int.testkit.ts`
+- `src/internal/handler/__testkit__/repos/crud.int.testkit.ts`
 
 `testkit` uses these suffixes automatically:
 
@@ -224,7 +237,8 @@ Suite names are inferred from the colocated path:
 services that define `database: localDatabase(...)`.
 
 - template databases are cached
-- stack databases are cloned from templates
+- runtime databases are cloned from templates when binding is `per-runtime`
+- shared databases are reused when binding is `shared`
 - template fingerprints are derived automatically from env files, migrate/seed
   config, and repo contents
 

package/bin/testkit.mjs

@@ -1,3 +1,8 @@
 #!/usr/bin/env node
 import { run } from "../lib/cli/index.mjs";
-run();
+
+run().catch((error) => {
+  setImmediate(() => {
+    throw error;
+  });
+});

package/lib/cli/args.mjs

@@ -2,8 +2,6 @@ import path from "path";
 import { normalizeTypeValues, parseSuiteSelectors } from "../runner/suite-selection.mjs";
 import {
   parseFileTimeoutOption,
-  parseStackCountOption,
-  parseStackModeOption,
   parseWorkersOption,
 } from "../runner/execution-config.mjs";
 
@@ -49,8 +47,6 @@ export function parseSuiteOption(values) {
 export {
   parseFileTimeoutOption,
   parseWorkersOption,
-  parseStackModeOption,
-  parseStackCountOption,
 };
 
 export function parseShardOption(value) {

package/lib/cli/args.test.mjs

@@ -2,8 +2,6 @@ import { describe, expect, it } from "vitest";
 import {
   parseFileTimeoutOption,
   parseShardOption,
-  parseStackCountOption,
-  parseStackModeOption,
   parseSuiteOption,
   parseTypeOption,
   parseWorkersOption,
@@ -61,13 +59,10 @@ 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");
   });
 
   it("parses and validates shards", () => {

package/lib/cli/index.mjs

@@ -3,8 +3,6 @@ import { loadConfigs } from "../config/index.mjs";
 import {
   parseFileTimeoutOption,
   parseShardOption,
-  parseStackCountOption,
-  parseStackModeOption,
   parseSuiteOption,
   parseTypeOption,
   parseWorkersOption,
@@ -13,7 +11,7 @@ import {
 } from "./args.mjs";
 import * as runner from "../runner/index.mjs";
 
-export function run() {
+export async function run(argv = process.argv) {
   const cli = cac("testkit");
 
   cli
@@ -27,8 +25,6 @@ export function run() {
     .option("--dir <path>", "Explicit product directory")
     .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")
     .option("--allow-partial-status", "Allow --write-status for filtered runs")
@@ -71,9 +67,6 @@ export function run() {
         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);
       const typeValues = parseTypeOption(options.type, positionalType);
       const suiteSelectors = parseSuiteOption(options.suite);
@@ -90,8 +83,6 @@ export function run() {
           fileNames,
           workers,
           fileTimeoutSeconds,
-          stackMode,
-          stackCount,
           shard,
           serviceFilter: options.service || null,
         },
@@ -100,5 +91,7 @@ export function run() {
     });
 
   cli.help();
-  cli.parse();
+  const parsed = cli.parse(argv, { run: false });
+  await cli.runMatchedCommand();
+  return parsed;
 }

package/lib/config/index.mjs

@@ -10,8 +10,10 @@ import {
 } from "../runner/suite-selection.mjs";
 import {
   DEFAULT_FILE_TIMEOUT_SECONDS,
+  normalizeDatabaseBinding,
   normalizeExecutionConfig,
-  normalizeStackModeValue,
+  normalizeRuntimeMaxConcurrentTasks,
+  normalizeRuntimeInstances,
 } from "../runner/execution-config.mjs";
 
 const TESTKIT_K6_BIN = "TESTKIT_K6_BIN";
@@ -116,12 +118,13 @@ function normalizeServiceConfig({
   const database = normalizeDatabaseConfig(explicitService, name);
   const migrate = normalizeLifecycle(explicitService.migrate);
   const seed = normalizeLifecycle(explicitService.seed);
+  const runtime = normalizeRuntimeConfig(explicitService.runtime, name);
   const skip = normalizeSkipConfig(explicitService.skip, {
     name,
     productDir,
     suites,
   });
-  const serviceExecution = normalizeServiceExecution(explicitService.execution, {
+  const requirements = normalizeServiceRequirements(explicitService.requirements, {
     name,
     suites,
   });
@@ -137,6 +140,7 @@ function normalizeServiceConfig({
     local,
     database,
     databaseFrom: explicitService.databaseFrom,
+    runtime,
     migrate,
     seed,
     dependsOn: explicitService.dependsOn || [],
@@ -157,11 +161,12 @@ function normalizeServiceConfig({
       database,
       databaseFrom: explicitService.databaseFrom,
       envFiles,
-      serviceExecution,
+      requirements,
       serviceEnv,
       migrate,
       seed,
       skip,
+      runtime,
       local,
     },
   };
@@ -240,6 +245,10 @@ function normalizeDatabaseConfig(explicitService, serviceName) {
 
   return {
     ...database,
+    binding: normalizeDatabaseBinding(
+      database.binding || "per-runtime",
+      `Service "${serviceName}" database.binding`
+    ),
     provider: "local",
     selectedBackend: "local",
     reset: database.reset !== false,
@@ -253,6 +262,26 @@ function normalizeDatabaseConfig(explicitService, serviceName) {
   };
 }
 
+function normalizeRuntimeConfig(value, serviceName) {
+  if (!value) {
+    return {
+      instances: 1,
+      maxConcurrentTasks: Number.POSITIVE_INFINITY,
+    };
+  }
+
+  return {
+    instances: normalizeRuntimeInstances(
+      value.instances ?? 1,
+      `Service "${serviceName}" runtime.instances`
+    ),
+    maxConcurrentTasks: normalizeRuntimeMaxConcurrentTasks(
+      value.maxConcurrentTasks,
+      `Service "${serviceName}" runtime.maxConcurrentTasks`
+    ),
+  };
+}
+
 function normalizeLifecycle(value) {
   if (!value) return undefined;
   if (!value.cmd && !value.testkitCmd) {
@@ -355,8 +384,8 @@ function normalizeSkipConfig(value, { name, productDir, suites }) {
   };
 }
 
-function normalizeServiceExecution(value, { name, suites }) {
-  if (!value) return { suites: [], files: [], fileStackModeByPath: new Map() };
+function normalizeServiceRequirements(value, { name, suites }) {
+  if (!value) return { suites: [], files: [], fileLocksByPath: new Map() };
 
   const discoveredSuites = [];
   const discoveredFiles = new Set();
@@ -376,25 +405,25 @@ function normalizeServiceExecution(value, { name, suites }) {
   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`);
+      throw new Error(`Service "${name}" requirements.suites entries must be objects`);
     }
     const selector = String(rule.selector || "").trim();
     if (!selector) {
-      throw new Error(`Service "${name}" execution.suites entries require a selector`);
+      throw new Error(`Service "${name}" requirements.suites entries require a selector`);
     }
     const parsed = parseSuiteSelectors([selector]);
     if (parsed.length !== 1) {
-      throw new Error(`Service "${name}" execution.suites["${selector}"] is invalid`);
+      throw new Error(`Service "${name}" requirements.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`
+        `Service "${name}" requirements.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}"`
+        `Service "${name}" defines duplicate requirements.suites selector "${parsedSelector.raw}"`
       );
     }
     const matched = discoveredSuites.some((suite) =>
@@ -402,15 +431,15 @@ function normalizeServiceExecution(value, { name, suites }) {
     );
     if (!matched) {
       throw new Error(
-        `Service "${name}" execution.suites selector "${parsedSelector.raw}" did not match any discovered suite`
+        `Service "${name}" requirements.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`
+      locks: normalizeRequirementLocks(
+        rule.locks,
+        `Service "${name}" requirements.suites["${parsedSelector.raw}"].locks`
       ),
     });
   }
@@ -419,28 +448,28 @@ function normalizeServiceExecution(value, { name, suites }) {
   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`);
+      throw new Error(`Service "${name}" requirements.files entries must be objects`);
     }
 
     const filePath = String(rule.path || "").trim();
     if (!filePath) {
-      throw new Error(`Service "${name}" execution.files[${index}] requires a path`);
+      throw new Error(`Service "${name}" requirements.files[${index}] requires a path`);
     }
     if (!discoveredFiles.has(filePath)) {
       throw new Error(
-        `Service "${name}" execution.files["${filePath}"] did not match any discovered test file`
+        `Service "${name}" requirements.files["${filePath}"] did not match any discovered test file`
       );
     }
     if (seenFiles.has(filePath)) {
-      throw new Error(`Service "${name}" defines duplicate execution.files path "${filePath}"`);
+      throw new Error(`Service "${name}" defines duplicate requirements.files path "${filePath}"`);
     }
 
     seenFiles.add(filePath);
     fileRules.push({
       path: filePath,
-      stackMode: normalizeStackModeValue(
-        rule.stackMode,
-        `Service "${name}" execution.files["${filePath}"].stackMode`
+      locks: normalizeRequirementLocks(
+        rule.locks,
+        `Service "${name}" requirements.files["${filePath}"].locks`
       ),
     });
   }
@@ -448,10 +477,28 @@ function normalizeServiceExecution(value, { name, suites }) {
   return {
     suites: suiteRules,
     files: fileRules,
-    fileStackModeByPath: new Map(fileRules.map((rule) => [rule.path, rule.stackMode])),
+    fileLocksByPath: new Map(fileRules.map((rule) => [rule.path, rule.locks])),
   };
 }
 
+function normalizeRequirementLocks(value, label) {
+  const input = Array.isArray(value) ? value : value == null ? [] : [value];
+  const seen = new Set();
+  const locks = [];
+
+  for (const rawLock of input) {
+    const lockName = String(rawLock || "").trim();
+    if (!lockName) {
+      throw new Error(`${label} entries must be non-empty strings`);
+    }
+    if (seen.has(lockName)) continue;
+    seen.add(lockName);
+    locks.push(lockName);
+  }
+
+  return locks.sort();
+}
+
 function inferEnvFiles(productDir, explicitService, local) {
   if (explicitService.envFile || explicitService.envFiles) {
     const files = [];
@@ -512,6 +559,7 @@ function validateServiceConfig({
   local,
   database,
   databaseFrom,
+  runtime,
   migrate,
   seed,
   dependsOn,
@@ -533,6 +581,14 @@ function validateServiceConfig({
   if (database && databaseFrom) {
     throw new Error(`Service "${name}" cannot define both database and databaseFrom`);
   }
+  if (runtime.instances < 1) {
+    throw new Error(`Service "${name}" runtime.instances must be a positive integer`);
+  }
+  if (runtime.maxConcurrentTasks <= 0) {
+    throw new Error(
+      `Service "${name}" runtime.maxConcurrentTasks must be a positive integer when provided`
+    );
+  }
 
   for (const depName of dependsOn || []) {
     if (depName === name) {
@@ -592,8 +648,6 @@ function normalizeRepoExecution(execution) {
     return normalizeExecutionConfig({
       workers: 1,
       fileTimeoutSeconds: DEFAULT_FILE_TIMEOUT_SECONDS,
-      stackMode: "isolated",
-      stackCount: 1,
     });
   }
   return normalizeExecutionConfig(execution);

package/lib/database/index.mjs

@@ -9,8 +9,8 @@ import {
 import {
   buildContainerName as buildContainerNameModel,
   buildDatabaseUrl as buildDatabaseUrlModel,
+  buildRuntimeDatabaseName as buildRuntimeDatabaseNameModel,
   buildTemplateDatabaseName as buildTemplateDatabaseNameModel,
-  buildWorkerDatabaseName as buildWorkerDatabaseNameModel,
   escapeIdentifier as escapeIdentifierModel,
   escapeSqlLiteral as escapeSqlLiteralModel,
   hashString as hashStringModel,
@@ -119,6 +119,7 @@ async function prepareLocalDatabase(config, hooks) {
   const db = config.testkit.database;
   const productDir = config.productDir;
   const serviceName = config.name;
+  const bindingKey = resolveDatabaseBindingKey(config);
   const lockDir = getLocalLocksDir(productDir);
   const cacheDir = getLocalServiceCacheDir(productDir, serviceName);
   fs.mkdirSync(lockDir, { recursive: true });
@@ -133,8 +134,8 @@ async function prepareLocalDatabase(config, hooks) {
     await ensureTemplateDatabase(config, infra, cacheDir, templateFingerprint, hooks);
   });
 
-  await withLock(path.join(lockDir, `runtime-${serviceName}-${hashString(config.stateDir, 10)}.lock`), async () => {
-    await ensureWorkerClone(config, infra, cacheDir, templateFingerprint);
+  await withLock(path.join(lockDir, `runtime-${serviceName}-${hashString(bindingKey, 10)}.lock`), async () => {
+    await ensureRuntimeClone(config, infra, cacheDir, templateFingerprint, bindingKey);
   });
 }
 
@@ -172,14 +173,14 @@ async function ensureTemplateDatabase(config, infra, cacheDir, templateFingerpri
   writeLocalCacheState(cacheDir, infra, desiredDbName, templateFingerprint);
 }
 
-async function ensureWorkerClone(config, infra, cacheDir, templateFingerprint) {
+async function ensureRuntimeClone(config, infra, cacheDir, templateFingerprint, bindingKey) {
   const serviceName = config.name;
   const templateDbName = readStateValue(path.join(cacheDir, "template_database_name"));
   if (!templateDbName) {
     throw new Error(`Missing template database for service "${serviceName}"`);
   }
 
-  const desiredDbName = buildWorkerDatabaseName(serviceName, config.stateDir, templateFingerprint);
+  const desiredDbName = buildRuntimeDatabaseName(serviceName, bindingKey, templateFingerprint);
   const existingDbName = readStateValue(path.join(config.stateDir, "local_database_name"));
   const existingFingerprint = readStateValue(path.join(config.stateDir, "local_template_fingerprint"));
   const needsReset =
@@ -206,6 +207,17 @@ async function ensureWorkerClone(config, infra, cacheDir, templateFingerprint) {
   fs.writeFileSync(path.join(config.stateDir, "local_container_name"), infra.containerName);
 }
 
+function resolveDatabaseBindingKey(config) {
+  const binding = config.testkit.database?.binding || "per-runtime";
+  if (binding === "shared") {
+    return `${config.name}:shared`;
+  }
+  if (config.runtimeId) {
+    return `${config.name}:${config.runtimeId}`;
+  }
+  return `${config.name}:${config.stateDir}`;
+}
+
 async function destroyLocalRuntimeDatabase(productDir, stateDir) {
   const dbName = readStateValue(path.join(stateDir, "local_database_name"));
   if (!dbName) return;
@@ -420,8 +432,8 @@ function buildTemplateDatabaseName(serviceName, fingerprint) {
   return buildTemplateDatabaseNameModel(serviceName, fingerprint);
 }
 
-function buildWorkerDatabaseName(serviceName, stateDir, fingerprint) {
-  return buildWorkerDatabaseNameModel(serviceName, stateDir, fingerprint);
+function buildRuntimeDatabaseName(serviceName, bindingKey, fingerprint) {
+  return buildRuntimeDatabaseNameModel(serviceName, bindingKey, fingerprint);
 }
 
 function writeLocalInfraState(infraDir, infra) {

package/lib/database/naming.mjs

@@ -19,9 +19,9 @@ export function buildTemplateDatabaseName(serviceName, fingerprint) {
   );
 }
 
-export function buildWorkerDatabaseName(serviceName, stateDir, fingerprint) {
+export function buildRuntimeDatabaseName(serviceName, bindingKey, fingerprint) {
   return limitIdentifier(
-    `tk_${slugSegment(serviceName)}_${hashString(stateDir, 10)}_${fingerprint.slice(0, 12)}`,
+    `tk_${slugSegment(serviceName)}_${hashString(bindingKey, 10)}_${fingerprint.slice(0, 12)}`,
     63
   );
 }

package/lib/database/naming.test.mjs

@@ -2,8 +2,8 @@ import { describe, expect, it } from "vitest";
 import {
   buildContainerName,
   buildDatabaseUrl,
+  buildRuntimeDatabaseName,
   buildTemplateDatabaseName,
-  buildWorkerDatabaseName,
   escapeIdentifier,
   escapeSqlLiteral,
   slugSegment,
@@ -15,7 +15,7 @@ describe("database-naming", () => {
     expect(buildTemplateDatabaseName("api", "1234567890abcdef1234")).toBe(
       "tk_tpl_api_1234567890abcdef"
     );
-    expect(buildWorkerDatabaseName("api", "/tmp/state", "abcdef1234567890")).toMatch(
+    expect(buildRuntimeDatabaseName("api", "/tmp/state", "abcdef1234567890")).toMatch(
       /^tk_api_[a-f0-9]{10}_abcdef123456$/
     );
     expect(