@elench/testkit 0.1.13 → 0.1.15

package/README.md

@@ -1,6 +1,6 @@
 # @elench/testkit
 
-CLI that reads `runner.manifest.json` plus `testkit.config.json` from a product repo, starts the required local services, provisions Neon branches when configured, and runs manifest-defined suites across `k6` and Playwright.
+CLI that reads `runner.manifest.json` plus `testkit.config.json` from a product repo, starts the required local services, provisions the selected database backend, and runs manifest-defined suites across `k6` and Playwright.
 
 ## Prerequisites
 
@@ -11,6 +11,8 @@ sudo apt-get install -y jq
 
 For DAL suites, `@elench/testkit` ships its own `k6` SQL binary. For suites using a Neon branch, set `NEON_API_KEY` in the product `.env`, shell, or `.envrc`.
 
+Local database mode uses Docker-managed `postgres:16` containers. `testkit` creates and reuses template databases automatically, then clones per-worker databases from those templates for fast reruns.
+
 ## Usage
 
 ```bash
@@ -24,6 +26,10 @@ npx @elench/testkit int
 npx @elench/testkit dal
 npx @elench/testkit e2e
 
+# Force a database backend
+npx @elench/testkit --db-backend local
+npx @elench/testkit --db-backend neon
+
 # Filter by framework
 npx @elench/testkit --framework playwright
 npx @elench/testkit --framework k6
@@ -49,12 +55,14 @@ npx @elench/testkit destroy
 1. **Discovery** — reads `runner.manifest.json` for services, suites, files, and frameworks
 2. **Config** — reads `testkit.config.json` for local runtime, migration, dependency, and database settings
    Per-service `.env` files declared in config are loaded when present.
-3. **Database** — provisions a Neon branch when a service declares one
+3. **Database** — provisions the selected backend (`neon` or Docker-managed `local`) when a service declares one
 4. **Seed** — runs optional product seed commands against the provisioned database
 5. **Runtime** — starts required local services, waits for readiness, and injects test env
 6. **Execution** — distributes suites across isolated worker stacks, runs `k6` suites file-by-file, and runs Playwright suites suite-by-suite
 7. **Cleanup** — stops local processes and preserves `.testkit/` state for inspection or later destroy
 
+Each run ends with a compact summary that shows per-service pass/fail status, suite totals, failed suites, and total duration.
+
 ## File roles
 
 - `runner.manifest.json`: canonical test inventory
@@ -64,6 +72,9 @@ npx @elench/testkit destroy
 
 - `envFile` / `envFiles` for service-specific environment loading
 - `databaseFrom` for dependency services that must share another service's `DATABASE_URL`
+- `database.defaultBackend` / `database.backends` to switch between Neon and local Postgres
+- `database.template.inputs` to define the local template cache invalidation inputs
+- `migrate.backends` / `seed.backends` for backend-specific command overrides
 
 ## Parallel execution
 
@@ -71,6 +82,7 @@ npx @elench/testkit destroy
 
 Each worker gets its own:
 - Neon branch
+- or cloned local Postgres database
 - `.testkit` state subtree
 - local service ports
 

package/lib/cli.mjs

@@ -16,6 +16,7 @@ export function run() {
     .option("--jobs <n>", "Number of isolated worker stacks per service", {
       default: "1",
     })
+    .option("--db-backend <name>", "Database backend override (neon, local)")
     .option("--shard <i/n>", "Run only shard i of n at suite granularity")
     .option("--framework <name>", "Filter by framework (k6, playwright, all)", {
       default: "all",
@@ -63,7 +64,7 @@ export function run() {
         );
       }
 
-      const allConfigs = loadConfigs({ dir: options.dir });
+      const allConfigs = loadConfigs({ dir: options.dir, dbBackend: options.dbBackend });
       const configs = service
         ? allConfigs.filter((config) => config.name === service)
         : allConfigs;

package/lib/config.mjs

@@ -5,6 +5,7 @@ import { fileURLToPath } from "url";
 const RUNNER_MANIFEST = "runner.manifest.json";
 const TESTKIT_CONFIG = "testkit.config.json";
 const VALID_FRAMEWORKS = new Set(["k6", "playwright"]);
+const VALID_DB_PROVIDERS = new Set(["neon", "local"]);
 
 /**
  * Parse a .env file into an object. Supports KEY=VALUE, KEY='VALUE', KEY="VALUE".
@@ -67,8 +68,20 @@ export function loadConfigs(opts = {}) {
       );
     }
 
-    validateMergedService(name, runnerService, serviceConfig, productDir);
+    const resolvedDatabase = resolveSelectedDatabase(name, serviceConfig, opts.dbBackend);
     const serviceEnv = loadServiceEnv(productDir, serviceConfig);
+    const selectedBackend = resolvedDatabase?.selectedBackend;
+    const resolvedMigrate = resolveLifecycleConfig(serviceConfig.migrate, selectedBackend);
+    const resolvedSeed = resolveLifecycleConfig(serviceConfig.seed, selectedBackend);
+    validateMergedService(
+      name,
+      runnerService,
+      serviceConfig,
+      resolvedDatabase,
+      resolvedMigrate,
+      resolvedSeed,
+      productDir
+    );
 
     return {
       name,
@@ -77,6 +90,10 @@ export function loadConfigs(opts = {}) {
       suites: runnerService.suites,
       testkit: {
         ...serviceConfig,
+        database: resolvedDatabase,
+        migrate: resolvedMigrate,
+        seed: resolvedSeed,
+        envFiles: getServiceEnvFiles(serviceConfig),
         serviceEnv,
       },
     };
@@ -279,7 +296,15 @@ export function isSiblingProduct(name) {
   );
 }
 
-function validateMergedService(name, runnerService, serviceConfig, productDir) {
+function validateMergedService(
+  name,
+  runnerService,
+  serviceConfig,
+  resolvedDatabase,
+  resolvedMigrate,
+  resolvedSeed,
+  productDir
+) {
   const usesLocalExecution = Object.values(runnerService.suites).some((suites) =>
     suites.some(
       (suite) =>
@@ -302,6 +327,16 @@ function validateMergedService(name, runnerService, serviceConfig, productDir) {
     }
   }
 
+  if (
+    resolvedDatabase?.provider === "local" &&
+    (serviceConfig.migrate || serviceConfig.seed) &&
+    resolvedDatabase.template.inputs.length === 0
+  ) {
+    throw new Error(
+      `Service "${name}" uses local database provisioning with migrations or seeds, so database.template.inputs must list the files/directories that define the template cache`
+    );
+  }
+
   if (serviceConfig.local?.cwd) {
     const cwdPath = resolveServiceCwd(productDir, serviceConfig.local.cwd);
     if (!fs.existsSync(cwdPath)) {
@@ -311,20 +346,20 @@ function validateMergedService(name, runnerService, serviceConfig, productDir) {
     }
   }
 
-  if (serviceConfig.migrate?.cwd) {
-    const cwdPath = resolveServiceCwd(productDir, serviceConfig.migrate.cwd);
+  if (resolvedMigrate?.cwd) {
+    const cwdPath = resolveServiceCwd(productDir, resolvedMigrate.cwd);
     if (!fs.existsSync(cwdPath)) {
       throw new Error(
-        `Service "${name}" migrate.cwd does not exist: ${serviceConfig.migrate.cwd}`
+        `Service "${name}" migrate.cwd does not exist: ${resolvedMigrate.cwd}`
       );
     }
   }
 
-  if (serviceConfig.seed?.cwd) {
-    const cwdPath = resolveServiceCwd(productDir, serviceConfig.seed.cwd);
+  if (resolvedSeed?.cwd) {
+    const cwdPath = resolveServiceCwd(productDir, resolvedSeed.cwd);
     if (!fs.existsSync(cwdPath)) {
       throw new Error(
-        `Service "${name}" seed.cwd does not exist: ${serviceConfig.seed.cwd}`
+        `Service "${name}" seed.cwd does not exist: ${resolvedSeed.cwd}`
       );
     }
   }
@@ -367,38 +402,24 @@ function validateServiceConfig(name, service, configPath) {
     if (!isObject(service.database)) {
       throw new Error(`Service "${name}" database must be an object`);
     }
-    const db = service.database;
-    if (db.provider !== "neon") {
-      throw new Error(`Service "${name}" database.provider must be "neon"`);
-    }
-    requireString(db, "projectId", `Service "${name}" database.projectId`);
-    requireString(db, "dbName", `Service "${name}" database.dbName`);
-    if (db.branchName !== undefined && typeof db.branchName !== "string") {
-      throw new Error(`Service "${name}" database.branchName must be a string`);
-    }
-    if (db.reset !== undefined && typeof db.reset !== "boolean") {
-      throw new Error(`Service "${name}" database.reset must be a boolean`);
+
+    if (service.database.provider !== undefined) {
+      validateDatabaseProviderConfig(name, service.database, `Service "${name}" database`);
+    } else if (service.database.backends !== undefined) {
+      validateMultiBackendDatabaseConfig(name, service.database);
+    } else {
+      throw new Error(
+        `Service "${name}" database must define either provider or backends`
+      );
     }
   }
 
   if (service.migrate !== undefined) {
-    if (!isObject(service.migrate)) {
-      throw new Error(`Service "${name}" migrate must be an object`);
-    }
-    requireString(service.migrate, "cmd", `Service "${name}" migrate.cmd`);
-    if (service.migrate.cwd !== undefined && typeof service.migrate.cwd !== "string") {
-      throw new Error(`Service "${name}" migrate.cwd must be a string`);
-    }
+    validateLifecycleConfig(name, service.migrate, "migrate");
   }
 
   if (service.seed !== undefined) {
-    if (!isObject(service.seed)) {
-      throw new Error(`Service "${name}" seed must be an object`);
-    }
-    requireString(service.seed, "cmd", `Service "${name}" seed.cmd`);
-    if (service.seed.cwd !== undefined && typeof service.seed.cwd !== "string") {
-      throw new Error(`Service "${name}" seed.cwd must be a string`);
-    }
+    validateLifecycleConfig(name, service.seed, "seed");
   }
 
   if (service.local !== undefined) {
@@ -446,6 +467,189 @@ function getServiceEnvFiles(serviceConfig) {
   return files;
 }
 
+function resolveSelectedDatabase(name, serviceConfig, requestedBackend) {
+  if (!serviceConfig.database) return undefined;
+
+  const database = serviceConfig.database;
+  if (database.provider !== undefined) {
+    if (requestedBackend && requestedBackend !== database.provider) {
+      throw new Error(
+        `Service "${name}" does not define database backend "${requestedBackend}". Available: ${database.provider}`
+      );
+    }
+
+    return {
+      ...database,
+      provider: database.provider,
+      selectedBackend: database.provider,
+      reset: database.reset !== false,
+      template: normalizeTemplateConfig(database.template),
+    };
+  }
+
+  const backends = database.backends || {};
+  const selectedBackend =
+    requestedBackend ||
+    process.env.TESTKIT_DB_BACKEND ||
+    database.defaultBackend ||
+    Object.keys(backends)[0];
+
+  if (!selectedBackend || !backends[selectedBackend]) {
+    throw new Error(
+      `Service "${name}" does not define database backend "${selectedBackend || "undefined"}"`
+    );
+  }
+
+  const backend = backends[selectedBackend];
+  return {
+    ...backend,
+    provider: backend.provider,
+    selectedBackend,
+    reset: database.reset !== false,
+    template: normalizeTemplateConfig(database.template),
+  };
+}
+
+function validateMultiBackendDatabaseConfig(name, database) {
+  if (
+    database.defaultBackend !== undefined &&
+    (typeof database.defaultBackend !== "string" || !database.defaultBackend.length)
+  ) {
+    throw new Error(`Service "${name}" database.defaultBackend must be a non-empty string`);
+  }
+  if (database.reset !== undefined && typeof database.reset !== "boolean") {
+    throw new Error(`Service "${name}" database.reset must be a boolean`);
+  }
+  if (database.template !== undefined) {
+    validateTemplateConfig(name, database.template, `Service "${name}" database.template`);
+  }
+  if (!isObject(database.backends) || Object.keys(database.backends).length === 0) {
+    throw new Error(`Service "${name}" database.backends must be a non-empty object`);
+  }
+
+  for (const [backendName, backendConfig] of Object.entries(database.backends)) {
+    if (!isObject(backendConfig)) {
+      throw new Error(
+        `Service "${name}" database.backends.${backendName} must be an object`
+      );
+    }
+    validateDatabaseProviderConfig(
+      name,
+      backendConfig,
+      `Service "${name}" database.backends.${backendName}`
+    );
+  }
+
+  if (database.defaultBackend && !database.backends[database.defaultBackend]) {
+    throw new Error(
+      `Service "${name}" database.defaultBackend "${database.defaultBackend}" is missing from database.backends`
+    );
+  }
+}
+
+function validateDatabaseProviderConfig(name, db, label) {
+  if (!VALID_DB_PROVIDERS.has(db.provider)) {
+    throw new Error(
+      `${label}.provider must be one of: ${[...VALID_DB_PROVIDERS].join(", ")}`
+    );
+  }
+
+  if (db.reset !== undefined && typeof db.reset !== "boolean") {
+    throw new Error(`${label}.reset must be a boolean`);
+  }
+  if (db.template !== undefined) {
+    validateTemplateConfig(name, db.template, `${label}.template`);
+  }
+
+  if (db.provider === "neon") {
+    requireString(db, "projectId", `${label}.projectId`);
+    requireString(db, "dbName", `${label}.dbName`);
+    if (db.branchName !== undefined && typeof db.branchName !== "string") {
+      throw new Error(`${label}.branchName must be a string`);
+    }
+    return;
+  }
+
+  if (db.image !== undefined && typeof db.image !== "string") {
+    throw new Error(`${label}.image must be a string`);
+  }
+  if (db.user !== undefined && typeof db.user !== "string") {
+    throw new Error(`${label}.user must be a string`);
+  }
+  if (db.password !== undefined && typeof db.password !== "string") {
+    throw new Error(`${label}.password must be a string`);
+  }
+}
+
+function validateTemplateConfig(name, template, label) {
+  if (!isObject(template)) {
+    throw new Error(`${label} must be an object`);
+  }
+  if (
+    template.inputs !== undefined &&
+    (!Array.isArray(template.inputs) || template.inputs.some((value) => typeof value !== "string"))
+  ) {
+    throw new Error(`${label}.inputs must be an array of strings`);
+  }
+}
+
+function normalizeTemplateConfig(template) {
+  return {
+    inputs: Array.isArray(template?.inputs) ? [...template.inputs] : [],
+  };
+}
+
+function validateLifecycleConfig(name, value, label) {
+  if (!isObject(value)) {
+    throw new Error(`Service "${name}" ${label} must be an object`);
+  }
+
+  if (value.cmd !== undefined) {
+    requireString(value, "cmd", `Service "${name}" ${label}.cmd`);
+  }
+  if (value.cwd !== undefined && typeof value.cwd !== "string") {
+    throw new Error(`Service "${name}" ${label}.cwd must be a string`);
+  }
+
+  if (value.backends !== undefined) {
+    if (!isObject(value.backends)) {
+      throw new Error(`Service "${name}" ${label}.backends must be an object`);
+    }
+    for (const [backendName, override] of Object.entries(value.backends)) {
+      if (!isObject(override)) {
+        throw new Error(
+          `Service "${name}" ${label}.backends.${backendName} must be an object`
+        );
+      }
+      if (override.cmd !== undefined) {
+        requireString(override, "cmd", `Service "${name}" ${label}.backends.${backendName}.cmd`);
+      }
+      if (override.cwd !== undefined && typeof override.cwd !== "string") {
+        throw new Error(
+          `Service "${name}" ${label}.backends.${backendName}.cwd must be a string`
+        );
+      }
+    }
+  }
+
+  if (value.cmd === undefined && value.backends === undefined) {
+    throw new Error(`Service "${name}" ${label} must define cmd or backends`);
+  }
+}
+
+function resolveLifecycleConfig(value, selectedBackend) {
+  if (!value) return value;
+
+  const override =
+    selectedBackend && isObject(value.backends) ? value.backends[selectedBackend] || {} : {};
+  const resolved = {
+    ...value,
+    ...override,
+  };
+  delete resolved.backends;
+  return resolved;
+}
+
 function requireString(obj, key, label) {
   if (typeof obj[key] !== "string" || obj[key].length === 0) {
     throw new Error(`${label} must be a non-empty string`);