@elench/testkit 0.1.39 → 0.1.41

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,11 +21,11 @@ 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
 
-# Two reusable local stacks for browser-heavy suites
-npx @elench/testkit --workers 6 --stack-mode pooled --stack-count 2
+# One file-level wall clock budget for every suite file
+npx @elench/testkit --file-timeout-seconds 60
 
 # Run a deterministic shard
 npx @elench/testkit --shard 1/3
@@ -66,8 +66,7 @@ import {
 export default defineTestkitSetup({
   execution: {
     workers: 8,
-    stackMode: "shared",
-    stackCount: 1,
+    fileTimeoutSeconds: 60,
   },
   services: {
     api: service({
@@ -82,6 +81,17 @@ export default defineTestkitSetup({
       migrate: lifecycle("npm run db:migrate", {
         testkitCmd: "npm run db:migrate:testkit",
       }),
+      runtime: {
+        instances: 1,
+      },
+      requirements: {
+        files: [
+          {
+            path: "src/api/routes/__testkit__/crawls-worker-concurrency.int.testkit.ts",
+            locks: ["global-worker-loop"],
+          },
+        ],
+      },
     }),
     frontend: service({
       ...nextService({
@@ -93,6 +103,9 @@ export default defineTestkitSetup({
       }),
       dependsOn: ["api"],
       envFiles: ["frontend/.env.testkit"],
+      runtime: {
+        instances: 1,
+      },
     }),
     billing: service({
       skip: {
@@ -117,9 +130,12 @@ 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
+- local DB binding configuration
+- explicit per-file or per-suite locks
 - migrate / seed commands
 - test-local migrate / seed overrides
 - named HTTP suite profiles
@@ -168,7 +184,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
@@ -180,7 +209,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:
 
@@ -206,7 +235,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/lib/cli/args.mjs

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

package/lib/cli/args.test.mjs

@@ -1,8 +1,7 @@
 import { describe, expect, it } from "vitest";
 import {
+  parseFileTimeoutOption,
   parseShardOption,
-  parseStackCountOption,
-  parseStackModeOption,
   parseSuiteOption,
   parseTypeOption,
   parseWorkersOption,
@@ -59,10 +58,11 @@ describe("cli-args", () => {
 
   it("parses and validates execution options", () => {
     expect(parseWorkersOption("3")).toBe(3);
-    expect(parseStackCountOption("2")).toBe(2);
-    expect(parseStackModeOption("pooled")).toBe("pooled");
+    expect(parseFileTimeoutOption("45")).toBe(45);
     expect(() => parseWorkersOption("0")).toThrow("Invalid --workers value");
-    expect(() => parseStackModeOption("legacy")).toThrow("Invalid --stack-mode value");
+    expect(() => parseFileTimeoutOption("0")).toThrow(
+      "Invalid --file-timeout-seconds value"
+    );
   });
 
   it("parses and validates shards", () => {

package/lib/cli/index.mjs

@@ -1,9 +1,8 @@
 import { cac } from "cac";
 import { loadConfigs } from "../config/index.mjs";
 import {
+  parseFileTimeoutOption,
   parseShardOption,
-  parseStackCountOption,
-  parseStackModeOption,
   parseSuiteOption,
   parseTypeOption,
   parseWorkersOption,
@@ -24,13 +23,8 @@ 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("--stack-count <n>", "Number of prepared stacks when stack-mode=pooled")
+    .option("--workers <n>", "Number of test executors for the whole run")
+    .option("--file-timeout-seconds <n>", "Per-file wall-clock timeout in seconds")
     .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")
@@ -68,10 +62,11 @@ export function run() {
         return;
       }
 
-      const workers = parseWorkersOption(options.workers);
-      const stackMode = parseStackModeOption(options.stackMode);
-      const stackCount =
-        options.stackCount == null ? null : parseStackCountOption(options.stackCount);
+      const workers = options.workers == null ? null : parseWorkersOption(options.workers);
+      const fileTimeoutSeconds =
+        options.fileTimeoutSeconds == null
+          ? null
+          : parseFileTimeoutOption(options.fileTimeoutSeconds);
       const shard = parseShardOption(options.shard);
       const typeValues = parseTypeOption(options.type, positionalType);
       const suiteSelectors = parseSuiteOption(options.suite);
@@ -87,8 +82,7 @@ export function run() {
           typeValues,
           fileNames,
           workers,
-          stackMode,
-          stackCount,
+          fileTimeoutSeconds,
           shard,
           serviceFilter: options.service || null,
         },

package/lib/config/index.mjs

@@ -8,7 +8,12 @@ import {
   parseSuiteSelectors,
   suiteSelectionType,
 } from "../runner/suite-selection.mjs";
-import { normalizeExecutionConfig, normalizeStackModeValue } from "../runner/execution-config.mjs";
+import {
+  DEFAULT_FILE_TIMEOUT_SECONDS,
+  normalizeDatabaseBinding,
+  normalizeExecutionConfig,
+  normalizeRuntimeInstances,
+} from "../runner/execution-config.mjs";
 
 const TESTKIT_K6_BIN = "TESTKIT_K6_BIN";
 const DEFAULT_LOCAL_IMAGE = "pgvector/pgvector:pg16";
@@ -112,12 +117,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,
   });
@@ -133,6 +139,7 @@ function normalizeServiceConfig({
     local,
     database,
     databaseFrom: explicitService.databaseFrom,
+    runtime,
     migrate,
     seed,
     dependsOn: explicitService.dependsOn || [],
@@ -153,11 +160,12 @@ function normalizeServiceConfig({
       database,
       databaseFrom: explicitService.databaseFrom,
       envFiles,
-      serviceExecution,
+      requirements,
       serviceEnv,
       migrate,
       seed,
       skip,
+      runtime,
       local,
     },
   };
@@ -236,6 +244,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,
@@ -249,6 +261,21 @@ function normalizeDatabaseConfig(explicitService, serviceName) {
   };
 }
 
+function normalizeRuntimeConfig(value, serviceName) {
+  if (!value) {
+    return {
+      instances: 1,
+    };
+  }
+
+  return {
+    instances: normalizeRuntimeInstances(
+      value.instances ?? 1,
+      `Service "${serviceName}" runtime.instances`
+    ),
+  };
+}
+
 function normalizeLifecycle(value) {
   if (!value) return undefined;
   if (!value.cmd && !value.testkitCmd) {
@@ -351,8 +378,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();
@@ -372,25 +399,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) =>
@@ -398,15 +425,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`
       ),
     });
   }
@@ -415,28 +442,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`
       ),
     });
   }
@@ -444,10 +471,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 = [];
@@ -508,6 +553,7 @@ function validateServiceConfig({
   local,
   database,
   databaseFrom,
+  runtime,
   migrate,
   seed,
   dependsOn,
@@ -529,6 +575,9 @@ 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`);
+  }
 
   for (const depName of dependsOn || []) {
     if (depName === name) {
@@ -587,8 +636,7 @@ function normalizeRepoExecution(execution) {
   if (!execution) {
     return normalizeExecutionConfig({
       workers: 1,
-      stackMode: "isolated",
-      stackCount: 1,
+      fileTimeoutSeconds: DEFAULT_FILE_TIMEOUT_SECONDS,
     });
   }
   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(