@elench/testkit 0.1.49 → 0.1.50

package/README.md

@@ -119,7 +119,7 @@ export default defineTestkitSetup({
       ...nextService({
         cwd: "frontend",
         port: 3000,
-        start: "exec ./node_modules/.bin/next start --port {port}",
+        start: "./node_modules/.bin/next start --port {port}",
         env: {
           NEXT_DIST_DIR: "{prepareDir}/dist",
           NEXT_PUBLIC_API_URL: "{baseUrl:api}",

package/lib/config/index.mjs

@@ -212,7 +212,7 @@ function inferLocalRuntime(productDir, cwd) {
   if (detectNextApp(absoluteCwd)) {
     return {
       cwd,
-      start: "exec ./node_modules/.bin/next dev -p {port}",
+      start: "./node_modules/.bin/next dev -p {port}",
       port: 3000,
       baseUrl: "http://127.0.0.1:{port}",
       readyUrl: "http://127.0.0.1:{port}",
@@ -223,7 +223,7 @@ function inferLocalRuntime(productDir, cwd) {
   if (fs.existsSync(path.join(absoluteCwd, "cmd", "server"))) {
     return {
       cwd,
-      start: "exec go run ./cmd/server",
+      start: "go run ./cmd/server",
       port: 3000,
       baseUrl: "http://127.0.0.1:{port}",
       readyUrl: "http://127.0.0.1:{port}/health",
@@ -234,7 +234,7 @@ function inferLocalRuntime(productDir, cwd) {
   if (fs.existsSync(path.join(absoluteCwd, "package.json")) && fs.existsSync(path.join(absoluteCwd, "src"))) {
     return {
       cwd,
-      start: "exec ./node_modules/.bin/tsx watch src/index.ts",
+      start: "./node_modules/.bin/tsx watch src/index.ts",
       port: 3000,
       baseUrl: "http://127.0.0.1:{port}",
       readyUrl: "http://127.0.0.1:{port}/health",

package/lib/database/index.mjs

@@ -33,6 +33,8 @@ const LOCAL_PASSWORD = "testkit";
 const LOCAL_ADMIN_DB = "postgres";
 const LOCAL_READY_TIMEOUT_MS = 60_000;
 const LOCAL_POLL_INTERVAL_MS = 1_000;
+const LOCAL_DROP_DATABASE_TIMEOUT_MS = 15_000;
+const LOCAL_DROP_DATABASE_POLL_INTERVAL_MS = 250;
 
 export async function prepareDatabaseRuntime(config) {
   const db = config.testkit.database;
@@ -398,18 +400,78 @@ async function cloneDatabaseFromTemplate(infra, dbName, templateDbName) {
 }
 
 async function dropDatabaseIfExists(infra, dbName) {
-  await runAdminQuery(infra, [
-    "-c",
-    [
-      `SELECT pg_terminate_backend(pid)`,
-      `FROM pg_stat_activity`,
-      `WHERE datname = '${escapeSqlLiteral(dbName)}' AND pid <> pg_backend_pid();`,
-    ].join(" "),
-  ]);
-  await runAdminQuery(infra, [
-    "-c",
-    `DROP DATABASE IF EXISTS "${escapeIdentifier(dbName)}"`,
-  ]);
+  await dropDatabaseWithForceOrDrain(infra, dbName);
+}
+
+export async function dropDatabaseWithForceOrDrain(infra, dbName, hooks = {}) {
+  const runAdminQueryFn = hooks.runAdminQuery || runAdminQuery;
+  const databaseExistsFn = hooks.databaseExists || databaseExists;
+  const sleepFn = hooks.sleep || sleep;
+
+  try {
+    await runAdminQueryFn(infra, [
+      "-c",
+      `DROP DATABASE IF EXISTS "${escapeIdentifier(dbName)}" WITH (FORCE)`,
+    ]);
+    return;
+  } catch (error) {
+    if (!isUnsupportedForceDropError(error)) {
+      throw error;
+    }
+  }
+
+  if (!(await databaseExistsFn(infra, dbName))) {
+    return;
+  }
+
+  let restoreConnections = false;
+  try {
+    await runAdminQueryFn(infra, [
+      "-c",
+      `ALTER DATABASE "${escapeIdentifier(dbName)}" WITH ALLOW_CONNECTIONS false`,
+    ]);
+    restoreConnections = true;
+    await waitForDatabaseConnectionsToDrain(infra, dbName, {
+      runAdminQuery: runAdminQueryFn,
+      sleep: sleepFn,
+    });
+    await runAdminQueryFn(infra, [
+      "-c",
+      `DROP DATABASE IF EXISTS "${escapeIdentifier(dbName)}"`,
+    ]);
+    restoreConnections = false;
+  } finally {
+    if (restoreConnections && (await databaseExistsFn(infra, dbName))) {
+      await runAdminQueryFn(infra, [
+        "-c",
+        `ALTER DATABASE "${escapeIdentifier(dbName)}" WITH ALLOW_CONNECTIONS true`,
+      ]).catch(() => {
+        // Best-effort restoration for failed fallback drops.
+      });
+    }
+  }
+}
+
+export async function waitForDatabaseConnectionsToDrain(infra, dbName, hooks = {}) {
+  const runAdminQueryFn = hooks.runAdminQuery || runAdminQuery;
+  const sleepFn = hooks.sleep || sleep;
+  const now = hooks.now || Date.now;
+  const timeoutMs = hooks.timeoutMs ?? LOCAL_DROP_DATABASE_TIMEOUT_MS;
+  const deadline = now() + timeoutMs;
+
+  while (true) {
+    await terminateDatabaseConnections(infra, dbName, runAdminQueryFn);
+    const remainingConnections = await countDatabaseConnections(infra, dbName, runAdminQueryFn);
+    if (remainingConnections === 0) {
+      return;
+    }
+    if (now() >= deadline) {
+      throw new Error(
+        `Timed out waiting for database "${dbName}" connections to close (${remainingConnections} remaining)`
+      );
+    }
+    await sleepFn(LOCAL_DROP_DATABASE_POLL_INTERVAL_MS);
+  }
 }
 
 async function runAdminQuery(infra, args) {
@@ -431,6 +493,37 @@ async function runAdminQuery(infra, args) {
   return stdout;
 }
 
+async function terminateDatabaseConnections(infra, dbName, runAdminQueryFn) {
+  await runAdminQueryFn(infra, [
+    "-c",
+    [
+      "SELECT pg_terminate_backend(pid)",
+      "FROM pg_stat_activity",
+      `WHERE datname = '${escapeSqlLiteral(dbName)}' AND pid <> pg_backend_pid();`,
+    ].join(" "),
+  ]);
+}
+
+async function countDatabaseConnections(infra, dbName, runAdminQueryFn) {
+  const result = await runAdminQueryFn(infra, [
+    "-tAc",
+    [
+      "SELECT COUNT(*)",
+      "FROM pg_stat_activity",
+      `WHERE datname = '${escapeSqlLiteral(dbName)}' AND pid <> pg_backend_pid();`,
+    ].join(" "),
+  ]);
+  return Number.parseInt(result.trim(), 10) || 0;
+}
+
+function isUnsupportedForceDropError(error) {
+  const text = `${error?.shortMessage || ""}\n${error?.stderr || ""}\n${error?.stdout || ""}\n${error?.message || ""}`;
+  return (
+    text.includes('syntax error at or near "WITH"') ||
+    text.includes('option "force"')
+  );
+}
+
 async function computeTemplateFingerprint(config) {
   return computeTemplateFingerprintModel(config);
 }

package/lib/database/index.test.mjs

@@ -0,0 +1,95 @@
+import { describe, expect, it } from "vitest";
+import {
+  dropDatabaseWithForceOrDrain,
+  waitForDatabaseConnectionsToDrain,
+} from "./index.mjs";
+
+describe("database lifecycle helpers", () => {
+  it("uses DROP DATABASE ... WITH (FORCE) when supported", async () => {
+    const calls = [];
+
+    await dropDatabaseWithForceOrDrain(
+      { containerName: "pg", password: "pw", user: "user" },
+      "demo",
+      {
+        async runAdminQuery(_infra, args) {
+          calls.push(args);
+          return "";
+        },
+      }
+    );
+
+    expect(calls).toEqual([["-c", 'DROP DATABASE IF EXISTS "demo" WITH (FORCE)']]);
+  });
+
+  it("falls back to draining connections when forced drop is unsupported", async () => {
+    const calls = [];
+    const counts = ["2", "0"];
+
+    await dropDatabaseWithForceOrDrain(
+      { containerName: "pg", password: "pw", user: "user" },
+      "demo",
+      {
+        async runAdminQuery(_infra, args) {
+          calls.push(args);
+          if (args[1] === 'DROP DATABASE IF EXISTS "demo" WITH (FORCE)') {
+            const error = new Error('syntax error at or near "WITH"');
+            error.stderr = 'ERROR: syntax error at or near "WITH"';
+            throw error;
+          }
+          if (args[0] === "-tAc") {
+            return counts.shift() || "0";
+          }
+          return "";
+        },
+        async databaseExists() {
+          return true;
+        },
+        async sleep() {},
+      }
+    );
+
+    expect(calls).toEqual([
+      ["-c", 'DROP DATABASE IF EXISTS "demo" WITH (FORCE)'],
+      ["-c", 'ALTER DATABASE "demo" WITH ALLOW_CONNECTIONS false'],
+      [
+        "-c",
+        "SELECT pg_terminate_backend(pid) FROM pg_stat_activity WHERE datname = 'demo' AND pid <> pg_backend_pid();",
+      ],
+      [
+        "-tAc",
+        "SELECT COUNT(*) FROM pg_stat_activity WHERE datname = 'demo' AND pid <> pg_backend_pid();",
+      ],
+      [
+        "-c",
+        "SELECT pg_terminate_backend(pid) FROM pg_stat_activity WHERE datname = 'demo' AND pid <> pg_backend_pid();",
+      ],
+      [
+        "-tAc",
+        "SELECT COUNT(*) FROM pg_stat_activity WHERE datname = 'demo' AND pid <> pg_backend_pid();",
+      ],
+      ["-c", 'DROP DATABASE IF EXISTS "demo"'],
+    ]);
+  });
+
+  it("times out clearly while waiting for lingering connections to drain", async () => {
+    let now = 0;
+    await expect(() =>
+      waitForDatabaseConnectionsToDrain(
+        { containerName: "pg", password: "pw", user: "user" },
+        "demo",
+        {
+          async runAdminQuery(_infra, args) {
+            if (args[0] === "-tAc") return "1";
+            return "";
+          },
+          async sleep() {
+            now += 10;
+          },
+          now: () => now,
+          timeoutMs: 20,
+        }
+      )
+    ).rejects.toThrow(/Timed out waiting for database "demo" connections to close/);
+  });
+});

package/lib/runner/processes.mjs

@@ -1,8 +1,22 @@
 import { spawn } from "child_process";
 
+export function normalizeServiceStartCommand(command) {
+  if (typeof command !== "string") {
+    throw new Error("Service start command must be a string");
+  }
+
+  const trimmed = command.trim();
+  if (trimmed.length === 0) {
+    throw new Error("Service start command must not be empty");
+  }
+
+  return trimmed.replace(/^exec\s+/u, "");
+}
+
 export function startDetachedCommand(command, cwd, env) {
+  const normalizedCommand = normalizeServiceStartCommand(command);
   if (process.platform === "win32") {
-    return spawn(command, {
+    return spawn(normalizedCommand, {
       cwd,
       env,
       detached: true,
@@ -12,7 +26,7 @@ export function startDetachedCommand(command, cwd, env) {
   }
 
   const shell = process.env.SHELL || "/bin/sh";
-  return spawn(shell, ["-lc", `exec ${command}`], {
+  return spawn(shell, ["-lc", `exec ${normalizedCommand}`], {
     cwd,
     env,
     detached: true,

package/lib/runner/processes.test.mjs

@@ -0,0 +1,21 @@
+import { describe, expect, it } from "vitest";
+import { normalizeServiceStartCommand } from "./processes.mjs";
+
+describe("runner processes", () => {
+  it("strips a single leading exec prefix for backward compatibility", () => {
+    expect(normalizeServiceStartCommand("exec node server.mjs")).toBe("node server.mjs");
+    expect(normalizeServiceStartCommand("  exec ./node_modules/.bin/next dev -p {port}  ")).toBe(
+      "./node_modules/.bin/next dev -p {port}"
+    );
+  });
+
+  it("leaves plain commands unchanged", () => {
+    expect(normalizeServiceStartCommand("node server.mjs")).toBe("node server.mjs");
+  });
+
+  it("rejects empty commands", () => {
+    expect(() => normalizeServiceStartCommand("   ")).toThrow(
+      /Service start command must not be empty/
+    );
+  });
+});

package/lib/runner/results.mjs

@@ -114,7 +114,7 @@ export function recordTaskOutcome(trackers, task, outcome, finishedAt = Date.now
   const normalizedPath = normalizePathSeparators(task.file);
   const existingFileResult = suite.fileResultsByPath.get(normalizedPath);
   const status = normalizeOutcomeStatus(outcome);
-  if (status !== "skipped") {
+  if (status !== "skipped" && status !== "not_run") {
     suite.completedFileCount += 1;
   }
   if (existingFileResult) {
@@ -291,6 +291,7 @@ function formatFrameworkForArtifact(framework) {
 }
 
 function normalizeOutcomeStatus(outcome) {
+  if (outcome?.status === "not_run") return "not_run";
   if (outcome?.status === "skipped") return "skipped";
   return outcome?.failed ? "failed" : "passed";
 }

package/lib/runner/results.test.mjs

@@ -307,6 +307,67 @@ describe("runner results", () => {
     ]);
   });
 
+  it("preserves not-run task outcomes in suite and service summaries", () => {
+    const trackers = buildServiceTrackers(
+      [
+        {
+          skipped: false,
+          config: {
+            name: "api",
+            testkit: {
+              database: {
+                selectedBackend: null,
+              },
+            },
+          },
+          suites: [
+            {
+              name: "health",
+              type: "integration",
+              framework: "k6",
+              files: ["tests/a.int.testkit.ts", "tests/b.int.testkit.ts"],
+              orderIndex: 0,
+            },
+          ],
+        },
+      ],
+      1000
+    );
+
+    recordTaskOutcome(
+      trackers,
+      {
+        serviceName: "api",
+        suiteKey: "integration:health",
+        file: "tests/a.int.testkit.ts",
+      },
+      {
+        failed: false,
+        status: "not_run",
+        reason: "Graph initialization failed",
+        durationMs: 0,
+        error: null,
+      },
+      1000
+    );
+
+    const result = finalizeServiceResult(trackers.get("api"), 1000, 1200);
+
+    expect(result.completedFileCount).toBe(0);
+    expect(result.passedFileCount).toBe(0);
+    expect(result.failedFileCount).toBe(0);
+    expect(result.skippedFileCount).toBe(0);
+    expect(result.notRunFileCount).toBe(2);
+    expect(result.suites[0].files).toContainEqual({
+      path: "tests/a.int.testkit.ts",
+      failed: false,
+      status: "not_run",
+      durationMs: 0,
+      error: null,
+      reason: "Graph initialization failed",
+    });
+  });
+
   it("summarizes mixed db backends", () => {
     expect(
       summarizeDbBackend([{ dbBackend: "local" }, { dbBackend: "neon" }])

package/lib/runner/runtime-manager.mjs

@@ -1,6 +1,7 @@
 import fs from "fs";
 import path from "path";
 import { buildRuntimeIds } from "./execution-config.mjs";
+import { formatError } from "./formatting.mjs";
 import {
   cleanupRuntimeInstanceContext,
   createRuntimeInstanceContext,
@@ -11,6 +12,7 @@ export function createRuntimeManager({ productDir, graphs, lifecycle, hooks = {}
   const graphByKey = new Map(graphs.map((graph) => [graph.key, graph]));
   const pools = new Map();
   const locks = new Map();
+  const failedGraphs = new Map();
   let nextLeaseCounter = 1;
   const runtimeHooks = {
     cleanupRuntimeInstanceContext,
@@ -22,6 +24,9 @@ export function createRuntimeManager({ productDir, graphs, lifecycle, hooks = {}
 
   return {
     canAcquire(task) {
+      if (failedGraphs.has(task.graphKey)) {
+        return false;
+      }
       const pool = getPool(pools, graphByKey, task, productDir, lifecycle);
       if (!locksAvailable(locks, task.locks || [])) {
         return false;
@@ -64,6 +69,9 @@ export function createRuntimeManager({ productDir, graphs, lifecycle, hooks = {}
         releaseLocks(locks, task.locks || [], leaseId);
         cleanupLeaseDir({ leaseDir: path.join(slot.context?.runtimeDir || productDir, "leases", leaseId) });
         await drainRuntimeSlot(slot, lifecycle, runtimeHooks);
+        if (!lifecycle.isStopRequested()) {
+          markGraphFailed(failedGraphs, task.graphKey, formatError(error));
+        }
         throw error;
       }
     },
@@ -104,6 +112,27 @@ export function createRuntimeManager({ productDir, graphs, lifecycle, hooks = {}
         }))
         .sort((left, right) => String(left.graphKey).localeCompare(String(right.graphKey)));
     },
+    drainFailedTasks(queue) {
+      const drained = [];
+      for (let index = queue.length - 1; index >= 0; index -= 1) {
+        const task = queue[index];
+        const message = failedGraphs.get(task.graphKey);
+        if (!message) continue;
+
+        queue.splice(index, 1);
+        drained.push({
+          task,
+          reason: `Not run because runtime graph failed to initialize: ${message}`,
+          message,
+          graph: graphByKey.get(task.graphKey) || {
+            key: task.graphKey,
+            targetNames: [task.targetName],
+          },
+        });
+      }
+
+      return drained.reverse();
+    },
   };
 }
 
@@ -218,6 +247,11 @@ function releaseLocks(lockMap, lockNames, leaseId) {
   }
 }
 
+function markGraphFailed(failedGraphs, graphKey, message) {
+  if (!graphKey || failedGraphs.has(graphKey)) return;
+  failedGraphs.set(graphKey, message);
+}
+
 function sleep(ms) {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }

package/lib/runner/runtime-manager.test.mjs

@@ -203,4 +203,50 @@ describe("runtime-manager", () => {
     await manager.release(leaseTwo);
     await manager.cleanupAll();
   });
+
+  it("blocks a graph after fatal runtime initialization failure and drains remaining tasks", async () => {
+    const productDir = makeTempDir("testkit-runtime-manager-");
+    const manager = createRuntimeManager({
+      productDir,
+      lifecycle: makeLifecycle(),
+      graphs: [
+        {
+          key: "api",
+          dirName: "api",
+          targetNames: ["api"],
+          instanceCount: 1,
+          maxConcurrentTasks: 1,
+        },
+      ],
+      hooks: {
+        ...makeHooks({ created: [], ready: [], cleaned: [] }),
+        async ensureRuntimeInstanceReady() {
+          throw new Error("prepare failed");
+        },
+      },
+    });
+
+    const firstTask = makeTask(1, { file: "tests/a.int.testkit.ts", targetName: "api" });
+    const secondTask = makeTask(2, { file: "tests/b.int.testkit.ts", targetName: "api" });
+
+    await expect(manager.acquire(firstTask)).rejects.toThrow(/prepare failed/);
+    expect(manager.canAcquire(secondTask)).toBe(false);
+
+    const queue = [secondTask];
+    expect(manager.drainFailedTasks(queue)).toEqual([
+      {
+        task: secondTask,
+        reason: "Not run because runtime graph failed to initialize: prepare failed",
+        message: "prepare failed",
+        graph: {
+          key: "api",
+          dirName: "api",
+          targetNames: ["api"],
+          instanceCount: 1,
+          maxConcurrentTasks: 1,
+        },
+      },
+    ]);
+    expect(queue).toEqual([]);
+  });
 });

package/lib/runner/worker-loop.mjs

@@ -36,6 +36,27 @@ export async function runWorker(
         runtimeManager.canAcquire(candidate)
       );
       if (!task) {
+        const blockedTasks = runtimeManager.drainFailedTasks(queue);
+        if (blockedTasks.length > 0) {
+          const now = Date.now();
+          const recordedGraphs = new Set();
+          for (const blocked of blockedTasks) {
+            recordTaskOutcome(trackers, blocked.task, {
+              failed: false,
+              status: "not_run",
+              reason: blocked.reason,
+              durationMs: 0,
+              startedAt: now,
+              finishedAt: now,
+              error: null,
+            });
+            if (!recordedGraphs.has(blocked.graph.key)) {
+              recordGraphError(trackers, blocked.graph, blocked.message, now);
+              recordedGraphs.add(blocked.graph.key);
+            }
+          }
+          continue;
+        }
         if (queue.length === 0) break;
         await new Promise((resolve) => setTimeout(resolve, 10));
         continue;

package/lib/setup/index.mjs

@@ -85,7 +85,7 @@ export function nextService(options = {}) {
     ...service(options),
     local: {
       cwd,
-      start: options.start || "exec ./node_modules/.bin/next dev -p {port}",
+      start: options.start || "./node_modules/.bin/next dev -p {port}",
       port,
       baseUrl,
       readyUrl: options.readyUrl || baseUrl,
@@ -105,7 +105,7 @@ export function tsxService(options = {}) {
     ...service(options),
     local: {
       cwd,
-      start: options.start || `exec ./node_modules/.bin/tsx watch ${entry}`,
+      start: options.start || `./node_modules/.bin/tsx watch ${entry}`,
       port,
       baseUrl,
       readyUrl: options.readyUrl || `${baseUrl}${options.readyPath || "/health"}`,
@@ -196,12 +196,12 @@ export {
 
 function defaultGoStartCommand(options) {
   if (options.command) {
-    return `exec go run ${options.command}`;
+    return `go run ${options.command}`;
   }
   if (options.entrypoint) {
-    return `exec go run ${options.entrypoint}`;
+    return `go run ${options.entrypoint}`;
   }
-  return "exec go run ./cmd/server";
+  return "go run ./cmd/server";
 }
 
 function requiredNumber(value, label) {

package/lib/setup/index.test.mjs

@@ -0,0 +1,26 @@
+import { describe, expect, it } from "vitest";
+import { goService, nextService, tsxService } from "./index.mjs";
+
+describe("setup helpers", () => {
+  it("emits plain next start commands without an exec prefix", () => {
+    const config = nextService({ port: 3000 });
+
+    expect(config.local.start).toBe("./node_modules/.bin/next dev -p {port}");
+  });
+
+  it("emits plain tsx start commands without an exec prefix", () => {
+    const config = tsxService({ port: 3000, entry: "src/server.ts" });
+
+    expect(config.local.start).toBe("./node_modules/.bin/tsx watch src/server.ts");
+  });
+
+  it("emits plain go start commands without an exec prefix", () => {
+    expect(goService({ port: 3000 }).local.start).toBe("go run ./cmd/server");
+    expect(goService({ port: 3000, entrypoint: "./cmd/api" }).local.start).toBe(
+      "go run ./cmd/api"
+    );
+    expect(goService({ port: 3000, command: "./cmd/worker" }).local.start).toBe(
+      "go run ./cmd/worker"
+    );
+  });
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@elench/testkit",
-  "version": "0.1.49",
+  "version": "0.1.50",
   "description": "CLI for discovering and running local HTTP, DAL, and Playwright test suites",
   "type": "module",
   "types": "./lib/index.d.ts",