@elench/testkit 0.1.10 → 0.1.12

package/lib/runner.mjs

@@ -1,461 +1,973 @@
 import fs from "fs";
 import path from "path";
+import { spawn } from "child_process";
+import net from "net";
+import { execa, execaCommand } from "execa";
 import { runScript } from "./exec.mjs";
-import { execaCommand } from "execa";
-import { requireFlyToken, resolveDalBinary } from "./config.mjs";
-
-const HTTP_SUITE_TYPES = new Set(["integration", "e2e", "load"]);
-
-/**
- * Run multiple service configs in parallel.
- * Single service: runs directly. Multiple: Promise.allSettled.
- */
-export async function runAll(configs, suiteType, suiteNames, opts) {
-  if (configs.length === 1) {
-    const failed = await runService(configs[0], suiteType, suiteNames, opts);
-    if (failed) process.exit(1);
+import {
+  requireNeonApiKey,
+  resolveDalBinary,
+  resolveServiceCwd,
+} from "./config.mjs";
+
+const TYPE_ORDER = ["dal", "integration", "e2e", "load"];
+const HTTP_K6_TYPES = new Set(["integration", "e2e", "load"]);
+const DEFAULT_READY_TIMEOUT_MS = 120_000;
+const PORT_STRIDE = 100;
+
+export async function runAll(configs, suiteType, suiteNames, opts, allConfigs = configs) {
+  const configMap = new Map(allConfigs.map((config) => [config.name, config]));
+  const targetSpan = Math.max(1, opts.jobs || 1);
+  const results = await Promise.all(
+    configs.map(async (config, targetSlot) => {
+      console.log(`\n══ ${config.name} ══`);
+      return runService(config, configMap, suiteType, suiteNames, opts, {
+        targetSlot,
+        targetSpan,
+      });
+    })
+  );
+
+  if (results.some(Boolean)) process.exit(1);
+}
+
+export async function destroy(config) {
+  if (!fs.existsSync(config.stateDir)) return;
+
+  const runtimeStateDirs = findRuntimeStateDirs(config.stateDir);
+  for (const stateDir of runtimeStateDirs) {
+    const projectId = readStateValue(path.join(stateDir, "neon_project_id"));
+    if (!projectId) continue;
+
+    await runScript("neon-down.sh", {
+      NEON_PROJECT_ID: projectId,
+      STATE_DIR: stateDir,
+    });
+  }
+
+  fs.rmSync(config.stateDir, { recursive: true, force: true });
+}
+
+export function showStatus(config) {
+  if (!fs.existsSync(config.stateDir)) {
+    console.log("No state — run tests first.");
     return;
   }
 
-  // Multiple services — run in parallel
-  const results = await Promise.allSettled(
-    configs.map(async (config) => {
-      console.log(`\n══ ${config.name} ══`);
-      return runService(config, suiteType, suiteNames, opts);
-    })
+  printStateDir(config.stateDir, "  ");
+}
+
+async function runService(targetConfig, configMap, suiteType, suiteNames, opts, runtimeSlot) {
+  const suites = applyShard(
+    collectSuites(targetConfig, suiteType, suiteNames, opts.framework),
+    opts.shard
   );
+  if (suites.length === 0) {
+    console.log(
+      `No test files for ${targetConfig.name} type="${suiteType}" suites=${suiteNames.join(",") || "all"} — skipping`
+    );
+    return false;
+  }
 
-  // Summarize
-  const summary = configs.map((c, i) => {
-    const r = results[i];
-    const ok = r.status === "fulfilled" && !r.value;
-    return `  ${ok ? "✓" : "✗"} ${c.name}`;
-  });
-  console.log(`\n── Summary ──\n${summary.join("\n")}`);
+  const runtimeConfigs = resolveRuntimeConfigs(targetConfig, configMap);
+  fs.mkdirSync(targetConfig.stateDir, { recursive: true });
 
-  const anyFailed = results.some(
-    (r) => r.status === "rejected" || r.value === true
+  const jobs = Math.max(1, Math.min(opts.jobs || 1, suites.length));
+  const workerPlans = buildWorkerPlans(
+    targetConfig,
+    runtimeConfigs,
+    suites,
+    jobs,
+    runtimeSlot
   );
-  if (anyFailed) process.exit(1);
-}
-
-/**
- * Build the Docker image and push to Fly registry.
- */
-export async function build(config) {
-  const { productDir, manifest, stateDir } = config;
-  const tk = manifest.testkit;
-  await runScript("fly-build.sh", {
-    FLY_APP: tk.fly.app,
-    FLY_ORG: tk.fly.org,
-    API_DIR: productDir,
-    DOCKERFILE_DIR: tk.dockerfile ? path.join(productDir, tk.dockerfile) : productDir,
-    STATE_DIR: stateDir,
-  });
+
+  const results = await Promise.allSettled(workerPlans.map((plan) => runWorkerPlan(plan)));
+  let failed = false;
+
+  for (const result of results) {
+    if (result.status === "rejected") {
+      failed = true;
+      console.error(result.reason);
+      continue;
+    }
+    if (result.value) failed = true;
+  }
+
+  return failed;
 }
 
-/**
- * Ensure Neon branch exists and reset test data.
- */
-export async function neonUp(config) {
-  const { stateDir, manifest } = config;
-  const tk = manifest.testkit;
-  await runScript("neon-up.sh", {
-    NEON_PROJECT_ID: tk.neon.projectId,
-    NEON_DB_NAME: tk.neon.dbName,
-    NEON_BRANCH_NAME: tk.neon.branchName || `${config.name}-test`,
-    NEON_RESET: tk.neon.reset === false ? "false" : "true",
-    STATE_DIR: stateDir,
-  });
+function collectSuites(config, suiteType, suiteNames, frameworkFilter) {
+  const types =
+    suiteType === "all"
+      ? orderedTypes(Object.keys(config.suites))
+      : [suiteType === "int" ? "integration" : suiteType];
+
+  const selectedNames = new Set(suiteNames);
+  const suites = [];
+  let orderIndex = 0;
+
+  for (const type of types) {
+    for (const suite of config.suites[type] || []) {
+      const framework = suite.framework || "k6";
+      if (selectedNames.size > 0 && !selectedNames.has(suite.name)) continue;
+      if (frameworkFilter && frameworkFilter !== "all" && framework !== frameworkFilter) continue;
+
+      suites.push({
+        ...suite,
+        framework,
+        type,
+        orderIndex,
+        sortKey: `${type}:${suite.name}`,
+        weight:
+          suite.testkit?.weight ||
+          (framework === "playwright"
+            ? Math.max(2, suite.files.length)
+            : Math.max(1, suite.files.length)),
+        maxFileConcurrency:
+          framework === "k6" ? suite.testkit?.maxFileConcurrency || 1 : 1,
+      });
+      orderIndex += 1;
+    }
+  }
+
+  return suites;
 }
 
-/**
- * Generate fly-env.sh and start/create the Fly machine.
- */
-export async function flyUp(config) {
-  const { productDir, stateDir, manifest } = config;
-  const tk = manifest.testkit;
+function applyShard(suites, shard) {
+  if (!shard) return suites;
+  return suites.filter((_, index) => index % shard.total === shard.index - 1);
+}
 
-  // Generate fly-env.sh from manifest (bash array for safe quoting)
-  const envLines = [];
-  for (const [k, v] of Object.entries(tk.fly.env || {})) {
-    envLines.push(`  --env "${k}=${v}"`);
+function orderedTypes(types) {
+  const ordered = [];
+  for (const known of TYPE_ORDER) {
+    if (types.includes(known)) ordered.push(known);
   }
-  for (const k of tk.fly.secrets || []) {
-    envLines.push(`  --env "${k}=\${${k}}"`);  // shell substitution at source-time
+  for (const type of types) {
+    if (!ordered.includes(type)) ordered.push(type);
   }
-  const flyEnvPath = path.join(stateDir, "fly-env.sh");
-  fs.writeFileSync(flyEnvPath, `FLY_ENV_ARGS=(\n${envLines.join("\n")}\n)\n`);
+  return ordered;
+}
 
-  await runScript("fly-up.sh", {
-    FLY_APP: tk.fly.app,
-    FLY_ORG: tk.fly.org,
-    FLY_REGION: tk.fly.region || "lhr",
-    FLY_PORT: tk.fly.port,
-    FLY_ENV_FILE: flyEnvPath,
-    STATE_DIR: stateDir,
-  });
+function resolveRuntimeConfigs(targetConfig, configMap) {
+  const ordered = [];
+  const visiting = new Set();
+  const seen = new Set();
+
+  const visit = (config) => {
+    if (seen.has(config.name)) return;
+    if (visiting.has(config.name)) {
+      throw new Error(`Dependency cycle detected involving "${config.name}"`);
+    }
+
+    visiting.add(config.name);
+    for (const depName of config.testkit.dependsOn || []) {
+      const dep = configMap.get(depName);
+      if (!dep) {
+        throw new Error(`Service "${config.name}" depends on unknown service "${depName}"`);
+      }
+      visit(dep);
+    }
+    visiting.delete(config.name);
+    seen.add(config.name);
+    ordered.push(config);
+  };
+
+  visit(targetConfig);
+  return ordered;
 }
 
-/**
- * Build a dependent service's Docker image.
- */
-async function buildDep(config, dep) {
-  const { productDir, stateDir } = config;
-  const depStateDir = path.join(stateDir, "deps", dep.name);
-  fs.mkdirSync(depStateDir, { recursive: true });
-  await runScript("fly-build.sh", {
-    FLY_APP: dep.fly.app,
-    FLY_ORG: dep.fly.org,
-    API_DIR: productDir,
-    DOCKERFILE_DIR: path.join(productDir, dep.dockerfile),
-    STATE_DIR: depStateDir,
-  });
+function buildWorkerPlans(targetConfig, runtimeConfigs, suites, jobs, runtimeSlot) {
+  const buckets = distributeSuites(suites, jobs);
+  return buckets
+    .map((bucket, index) =>
+      createWorkerPlan(targetConfig, runtimeConfigs, bucket.suites, index + 1, runtimeSlot)
+    )
+    .filter(Boolean);
 }
 
-/**
- * Deploy a dependent service's Fly machine.
- * Copies database_url from primary, generates fly-env.sh, calls fly-up.sh.
- */
-async function flyUpDep(config, dep) {
-  const { stateDir } = config;
-  const depStateDir = path.join(stateDir, "deps", dep.name);
-  fs.mkdirSync(depStateDir, { recursive: true });
+function distributeSuites(suites, jobs) {
+  const buckets = Array.from({ length: jobs }, () => ({
+    suites: [],
+    totalWeight: 0,
+  }));
+  const ordered = [...suites].sort(
+    (a, b) => b.weight - a.weight || a.sortKey.localeCompare(b.sortKey)
+  );
+
+  for (const suite of ordered) {
+    let bestBucket = buckets[0];
+    for (const bucket of buckets.slice(1)) {
+      if (bucket.totalWeight < bestBucket.totalWeight) {
+        bestBucket = bucket;
+        continue;
+      }
+      if (
+        bucket.totalWeight === bestBucket.totalWeight &&
+        bucket.suites.length < bestBucket.suites.length
+      ) {
+        bestBucket = bucket;
+      }
+    }
+
+    bestBucket.suites.push(suite);
+    bestBucket.totalWeight += suite.weight;
+  }
 
-  // Copy database_url from primary state dir
-  const primaryDbUrl = path.join(stateDir, "database_url");
-  if (fs.existsSync(primaryDbUrl)) {
-    fs.copyFileSync(primaryDbUrl, path.join(depStateDir, "database_url"));
+  for (const bucket of buckets) {
+    bucket.suites.sort((a, b) => a.orderIndex - b.orderIndex);
   }
 
-  // Generate fly-env.sh for dependent (bash array for safe quoting)
-  const envLines = [];
-  for (const [k, v] of Object.entries(dep.fly.env || {})) {
-    envLines.push(`  --env "${k}=${v}"`);
+  return buckets.filter((bucket) => bucket.suites.length > 0);
+}
+
+function createWorkerPlan(targetConfig, runtimeConfigs, suites, workerId, runtimeSlot) {
+  if (suites.length === 0) return null;
+
+  const workerStateDir = path.join(targetConfig.stateDir, "workers", `worker-${workerId}`);
+  const workerRuntimeConfigs = resolveWorkerRuntimeConfigs(
+    targetConfig,
+    runtimeConfigs,
+    workerId,
+    workerStateDir,
+    runtimeSlot
+  );
+  const workerTargetConfig = workerRuntimeConfigs.find(
+    (config) => config.name === targetConfig.name
+  );
+
+  return {
+    workerId,
+    suites,
+    runtimeConfigs: workerRuntimeConfigs,
+    targetConfig: workerTargetConfig,
+  };
+}
+
+function resolveWorkerRuntimeConfigs(
+  targetConfig,
+  runtimeConfigs,
+  workerId,
+  workerStateDir,
+  runtimeSlot
+) {
+  const portMap = buildPortMap(runtimeConfigs, workerId, runtimeSlot);
+  const baseUrlByService = new Map();
+  const readyUrlByService = new Map();
+
+  for (const config of runtimeConfigs) {
+    if (!config.testkit.local) continue;
+    baseUrlByService.set(
+      config.name,
+      resolveRuntimeUrl(config.testkit.local.baseUrl, config.name, targetConfig, workerId, {
+        workerStateDir,
+        portMap,
+        baseUrlByService,
+        readyUrlByService,
+      })
+    );
+    readyUrlByService.set(
+      config.name,
+      resolveRuntimeUrl(config.testkit.local.readyUrl, config.name, targetConfig, workerId, {
+        workerStateDir,
+        portMap,
+        baseUrlByService,
+        readyUrlByService,
+      })
+    );
   }
-  for (const k of dep.fly.secrets || []) {
-    envLines.push(`  --env "${k}=\${${k}}"`);  // shell substitution at source-time
+
+  const urlMappings = [];
+  for (const config of runtimeConfigs) {
+    if (!config.testkit.local) continue;
+    const resolvedBaseUrl = baseUrlByService.get(config.name);
+    const resolvedReadyUrl = readyUrlByService.get(config.name);
+    if (resolvedBaseUrl) {
+      urlMappings.push([config.testkit.local.baseUrl, resolvedBaseUrl]);
+    }
+    if (resolvedReadyUrl) {
+      urlMappings.push([config.testkit.local.readyUrl, resolvedReadyUrl]);
+    }
   }
-  const flyEnvPath = path.join(depStateDir, "fly-env.sh");
-  fs.writeFileSync(flyEnvPath, `FLY_ENV_ARGS=(\n${envLines.join("\n")}\n)\n`);
 
-  await runScript("fly-up.sh", {
-    FLY_APP: dep.fly.app,
-    FLY_ORG: dep.fly.org,
-    FLY_REGION: dep.fly.region || "lhr",
-    FLY_PORT: dep.fly.port,
-    FLY_ENV_FILE: flyEnvPath,
-    STATE_DIR: depStateDir,
-  });
+  return runtimeConfigs.map((config) =>
+    resolveWorkerConfig(
+      config,
+      targetConfig,
+      workerId,
+      workerStateDir,
+      portMap,
+      baseUrlByService,
+      readyUrlByService,
+      urlMappings
+    )
+  );
 }
 
-/**
- * Stop a dependent service's Fly machine.
- */
-async function flyDownDep(config, dep) {
-  const depStateDir = path.join(config.stateDir, "deps", dep.name);
-  await runScript("fly-down.sh", {
-    FLY_APP: dep.fly.app,
-    STATE_DIR: depStateDir,
-  });
+function buildPortMap(runtimeConfigs, workerId, runtimeSlot) {
+  const portMap = new Map();
+  const seen = new Map();
+  const offset = PORT_STRIDE * ((workerId - 1) + runtimeSlot.targetSlot * runtimeSlot.targetSpan);
+
+  for (const config of runtimeConfigs) {
+    if (!config.testkit.local) continue;
+
+    const basePort = config.testkit.local.port || numericPortFromUrl(config.testkit.local.baseUrl);
+    if (!basePort) continue;
+
+    const actualPort = basePort + offset;
+    const existing = seen.get(actualPort);
+    if (existing) {
+      throw new Error(
+        `Worker port collision: services "${existing}" and "${config.name}" both resolve to ${actualPort}. ` +
+          `Assign distinct local.port/baseUrl ports in testkit.config.json.`
+      );
+    }
+    seen.set(actualPort, config.name);
+    portMap.set(config.name, actualPort);
+  }
+
+  return portMap;
 }
 
-/**
- * Stop the Fly machine (preserved for reuse).
- */
-export async function flyDown(config) {
-  const { stateDir, manifest } = config;
-  await runScript("fly-down.sh", {
-    FLY_APP: manifest.testkit.fly.app,
-    STATE_DIR: stateDir,
-  });
+function resolveWorkerConfig(
+  config,
+  targetConfig,
+  workerId,
+  workerStateDir,
+  portMap,
+  baseUrlByService,
+  readyUrlByService,
+  urlMappings
+) {
+  const stateDir = getWorkerServiceStateDir(workerStateDir, targetConfig.name, config.name);
+  const context = {
+    workerId,
+    serviceName: config.name,
+    targetName: targetConfig.name,
+    serviceStateDir: stateDir,
+    portMap,
+    baseUrlByService,
+    readyUrlByService,
+    urlMappings,
+  };
+
+  const database = config.testkit.database
+    ? {
+        ...config.testkit.database,
+        branchName:
+          config.testkit.database.branchName !== undefined
+            ? finalizeString(config.testkit.database.branchName, context)
+            : `${targetConfig.name}-${config.name}-w${workerId}-testkit`,
+      }
+    : undefined;
+
+  const migrate = config.testkit.migrate
+    ? {
+        ...config.testkit.migrate,
+        cmd: finalizeString(config.testkit.migrate.cmd, context),
+        cwd:
+          config.testkit.migrate.cwd !== undefined
+            ? finalizeString(config.testkit.migrate.cwd, context)
+            : config.testkit.migrate.cwd,
+      }
+    : undefined;
+
+  const seed = config.testkit.seed
+    ? {
+        ...config.testkit.seed,
+        cmd: finalizeString(config.testkit.seed.cmd, context),
+        cwd:
+          config.testkit.seed.cwd !== undefined
+            ? finalizeString(config.testkit.seed.cwd, context)
+            : config.testkit.seed.cwd,
+      }
+    : undefined;
+
+  const local = config.testkit.local
+    ? {
+        ...config.testkit.local,
+        start: finalizeString(config.testkit.local.start, context),
+        cwd:
+          config.testkit.local.cwd !== undefined
+            ? finalizeString(config.testkit.local.cwd, context)
+            : config.testkit.local.cwd,
+        port: portMap.get(config.name) || config.testkit.local.port,
+        baseUrl: baseUrlByService.get(config.name),
+        readyUrl: readyUrlByService.get(config.name),
+        env: Object.fromEntries(
+          Object.entries(config.testkit.local.env || {}).map(([key, value]) => [
+            key,
+            finalizeString(String(value), context),
+          ])
+        ),
+      }
+    : undefined;
+
+  return {
+    ...config,
+    stateDir,
+    workerId,
+    workerLabel: `w${workerId}`,
+    targetName: targetConfig.name,
+    testkit: {
+      ...config.testkit,
+      database,
+      migrate,
+      seed,
+      local,
+    },
+  };
 }
 
-/**
- * Destroy machine + neon branch + state.
- * Destroys dependent machines first, then primary.
- */
-export async function destroy(config) {
-  const { stateDir, manifest } = config;
-  const tk = manifest.testkit;
-
-  // Destroy dependents first
-  for (const dep of tk.depends || []) {
-    const depStateDir = path.join(stateDir, "deps", dep.name);
-    if (fs.existsSync(depStateDir)) {
-      await runScript("fly-destroy.sh", { FLY_APP: dep.fly.app, STATE_DIR: depStateDir });
+async function runWorkerPlan(plan) {
+  console.log(
+    `\n══ ${plan.targetConfig.name} worker ${plan.workerId} (${plan.suites.length} suite${plan.suites.length === 1 ? "" : "s"}) ══`
+  );
+
+  let startedServices = [];
+  let failed = false;
+
+  try {
+    await prepareDatabases(plan.runtimeConfigs);
+    await runMigrations(plan.runtimeConfigs);
+    await runSeeds(plan.runtimeConfigs);
+
+    if (needsLocalRuntime(plan.suites)) {
+      startedServices = await startLocalServices(plan.runtimeConfigs);
     }
+
+    for (const suite of plan.suites) {
+      console.log(
+        `\n── ${plan.targetConfig.workerLabel} ${suite.type}:${suite.name} (${suite.framework}) ──`
+      );
+      const result = await runSuite(plan.targetConfig, suite);
+      if (result.failed) failed = true;
+    }
+  } finally {
+    await stopLocalServices(startedServices);
   }
 
-  await runScript("fly-destroy.sh", { FLY_APP: tk.fly.app, STATE_DIR: stateDir });
-  await runScript("neon-down.sh", {
-    NEON_PROJECT_ID: tk.neon.projectId,
-    STATE_DIR: stateDir,
-  });
-  fs.rmSync(stateDir, { recursive: true, force: true });
+  return failed;
 }
 
-/**
- * Run k6 test files against the Fly machine (HTTP tests).
- */
-export async function runTests(config, files) {
-  const { productDir, stateDir, manifest } = config;
-  const tk = manifest.testkit;
+async function prepareDatabases(runtimeConfigs) {
+  for (const config of runtimeConfigs) {
+    const db = config.testkit.database;
+    if (!db) continue;
+
+    requireNeonApiKey();
+    fs.mkdirSync(config.stateDir, { recursive: true });
 
-  // Read state files
-  const baseUrl = fs.readFileSync(path.join(stateDir, "fly_hostname"), "utf8").trim();
-  const machineId = fs.readFileSync(path.join(stateDir, "fly_machine_id"), "utf8").trim();
+    await runScript("neon-up.sh", {
+      NEON_PROJECT_ID: db.projectId,
+      NEON_DB_NAME: db.dbName,
+      NEON_BRANCH_NAME: db.branchName,
+      NEON_RESET: db.reset === false ? "false" : "true",
+      STATE_DIR: config.stateDir,
+    });
 
-  // Build -e flags
-  const envFlags = [`-e BASE_URL=${baseUrl}`, `-e MACHINE_ID=${machineId}`];
-  for (const key of tk.k6?.secrets || []) {
-    envFlags.push(`-e ${key}=${process.env[key]}`);
+    fs.writeFileSync(path.join(config.stateDir, "neon_project_id"), db.projectId);
   }
-  const envStr = envFlags.join(" ");
+}
 
-  let failed = false;
-  for (const file of files) {
-    const absFile = path.join(productDir, file);
-    try {
-      await execaCommand(`k6 run ${envStr} ${absFile}`, { stdio: "inherit" });
-    } catch (err) {
-      failed = true;
+async function runMigrations(runtimeConfigs) {
+  for (const config of runtimeConfigs) {
+    const migrate = config.testkit.migrate;
+    if (!migrate) continue;
+
+    const env = { ...process.env };
+    const dbUrl = readDatabaseUrl(config.stateDir);
+    if (dbUrl) env.DATABASE_URL = dbUrl;
+
+    console.log(`\n── migrate:${config.workerLabel}:${config.name} ──`);
+    await execaCommand(migrate.cmd, {
+      cwd: resolveServiceCwd(config.productDir, migrate.cwd),
+      env,
+      stdio: "inherit",
+      shell: true,
+    });
+  }
+}
+
+async function runSeeds(runtimeConfigs) {
+  for (const config of runtimeConfigs) {
+    const seed = config.testkit.seed;
+    if (!seed) continue;
+
+    const env = { ...process.env };
+    const dbUrl = readDatabaseUrl(config.stateDir);
+    if (dbUrl) env.DATABASE_URL = dbUrl;
+
+    console.log(`\n── seed:${config.workerLabel}:${config.name} ──`);
+    await execaCommand(seed.cmd, {
+      cwd: resolveServiceCwd(config.productDir, seed.cwd),
+      env,
+      stdio: "inherit",
+      shell: true,
+    });
+  }
+}
+
+async function startLocalServices(runtimeConfigs) {
+  const started = [];
+
+  try {
+    for (const config of runtimeConfigs) {
+      if (!config.testkit.local) continue;
+      const proc = await startLocalService(config);
+      started.push(proc);
     }
+  } catch (error) {
+    await stopLocalServices(started);
+    throw error;
   }
-  return { failed };
+
+  return started;
 }
 
-/**
- * Run k6 DAL test files directly against Neon (no Fly machine).
- */
-export async function runDalTests(config, files) {
-  const { productDir, stateDir, manifest } = config;
-  const tk = manifest.testkit;
-  const k6Binary = resolveDalBinary();
+async function startLocalService(config) {
+  const cwd = resolveServiceCwd(config.productDir, config.testkit.local.cwd);
+  const env = {
+    ...process.env,
+    ...config.testkit.local.env,
+  };
+  const port = config.testkit.local.port || numericPortFromUrl(config.testkit.local.baseUrl);
+  if (port) {
+    env.PORT = String(port);
+  }
+
+  const dbUrl = readDatabaseUrl(config.stateDir);
+  if (dbUrl) {
+    env.DATABASE_URL = dbUrl;
+  }
+
+  await assertLocalServicePortsAvailable(config);
 
-  // Read DATABASE_URL from neon state
-  const databaseUrl = fs.readFileSync(path.join(stateDir, "database_url"), "utf8").trim();
+  console.log(`Starting ${config.workerLabel}:${config.name}: ${config.testkit.local.start}`);
+  const child = spawn(config.testkit.local.start, {
+    cwd,
+    env,
+    shell: true,
+    stdio: ["ignore", "pipe", "pipe"],
+  });
+
+  pipeOutput(child.stdout, `[${config.workerLabel}:${config.name}]`);
+  pipeOutput(child.stderr, `[${config.workerLabel}:${config.name}]`);
+
+  const readyTimeoutMs = config.testkit.local.readyTimeoutMs || DEFAULT_READY_TIMEOUT_MS;
+
+  try {
+    await waitForReady({
+      name: `${config.workerLabel}:${config.name}`,
+      url: config.testkit.local.readyUrl,
+      timeoutMs: readyTimeoutMs,
+      process: child,
+    });
+  } catch (error) {
+    await stopChildProcess(child);
+    throw error;
+  }
+
+  return { name: config.name, child };
+}
+
+async function runSuite(targetConfig, suite) {
+  if (suite.type === "dal") {
+    return runDalSuite(targetConfig, suite);
+  }
+
+  if (suite.framework === "playwright") {
+    return runPlaywrightSuite(targetConfig, suite);
+  }
+
+  if (suite.framework === "k6" && HTTP_K6_TYPES.has(suite.type)) {
+    return runHttpK6Suite(targetConfig, suite);
+  }
 
-  // Build -e flags
-  const envFlags = [`-e DATABASE_URL=${databaseUrl}`];
-  for (const key of tk.dal?.secrets || []) {
-    envFlags.push(`-e ${key}=${process.env[key]}`);
+  throw new Error(
+    `Unsupported suite combination for ${targetConfig.name}: type=${suite.type} framework=${suite.framework}`
+  );
+}
+
+async function runHttpK6Suite(targetConfig, suite) {
+  const baseUrl = targetConfig.testkit.local?.baseUrl;
+  if (!baseUrl) {
+    throw new Error(`Service "${targetConfig.name}" requires local.baseUrl for HTTP k6 suites`);
   }
-  const envStr = envFlags.join(" ");
 
   let failed = false;
-  for (const file of files) {
-    const absFile = path.join(productDir, file);
+  await runWithConcurrency(suite.files, suite.maxFileConcurrency, async (file) => {
+    const absFile = path.join(targetConfig.productDir, file);
+    console.log(`·· ${targetConfig.workerLabel}:${suite.name} → ${file}`);
     try {
-      await execaCommand(`${k6Binary} run ${envStr} ${absFile}`, { stdio: "inherit" });
-    } catch (err) {
+      await execa("k6", ["run", "-e", `BASE_URL=${baseUrl}`, absFile], {
+        cwd: targetConfig.productDir,
+        env: process.env,
+        stdio: "inherit",
+      });
+    } catch {
       failed = true;
     }
-  }
+  });
+
   return { failed };
 }
 
-/**
- * Delete the Neon branch (so neonUp creates a fresh fork from prod).
- */
-async function neonReset(config) {
-  const { stateDir, manifest } = config;
-  const tk = manifest.testkit;
-  console.log("Deleting Neon branch for fresh fork...");
-  await runScript("neon-down.sh", {
-    NEON_PROJECT_ID: tk.neon.projectId,
-    STATE_DIR: stateDir,
+async function runDalSuite(targetConfig, suite) {
+  const databaseUrl = readDatabaseUrl(targetConfig.stateDir);
+  if (!databaseUrl) {
+    throw new Error(`Service "${targetConfig.name}" requires a database for DAL suites`);
+  }
+
+  const k6Binary = resolveDalBinary();
+  let failed = false;
+  await runWithConcurrency(suite.files, suite.maxFileConcurrency, async (file) => {
+    const absFile = path.join(targetConfig.productDir, file);
+    console.log(`·· ${targetConfig.workerLabel}:${suite.name} → ${file}`);
+    try {
+      await execa(k6Binary, ["run", "-e", `DATABASE_URL=${databaseUrl}`, absFile], {
+        cwd: targetConfig.productDir,
+        env: process.env,
+        stdio: "inherit",
+      });
+    } catch {
+      failed = true;
+    }
   });
-  // Clear branch state so neonUp creates a new one
-  const branchFile = path.join(stateDir, "neon_branch_id");
-  if (fs.existsSync(branchFile)) fs.unlinkSync(branchFile);
-  const dbUrlFile = path.join(stateDir, "database_url");
-  if (fs.existsSync(dbUrlFile)) fs.unlinkSync(dbUrlFile);
-}
 
-/**
- * Run database migrations from local source against the test branch.
- * If migrations fail, nukes the Neon branch and retries on a fresh fork.
- * A second failure means a real migration bug — throws.
- */
-async function migrate(config) {
-  const { productDir, stateDir, manifest } = config;
-  const migrateCmd = manifest.testkit.migrate?.cmd;
-  if (!migrateCmd) return;
+  return { failed };
+}
 
-  const dbUrlPath = path.join(stateDir, "database_url");
-  const env = { ...process.env };
-  if (fs.existsSync(dbUrlPath)) {
-    env.DATABASE_URL = fs.readFileSync(dbUrlPath, "utf8").trim();
+async function runPlaywrightSuite(targetConfig, suite) {
+  const local = targetConfig.testkit.local;
+  if (!local?.baseUrl) {
+    throw new Error(
+      `Service "${targetConfig.name}" requires local.baseUrl for Playwright suites`
+    );
   }
 
-  const execOpts = { stdio: "inherit", cwd: productDir, env, shell: true };
+  const cwd = resolveServiceCwd(targetConfig.productDir, local.cwd);
+  const files = suite.files.map((file) =>
+    path.relative(cwd, path.join(targetConfig.productDir, file))
+  );
 
-  console.log("\n── migrate ──");
   try {
-    await execaCommand(migrateCmd, execOpts);
-    return;
-  } catch (err) {
-    console.log("\nMigration failed — resetting Neon branch and retrying...\n");
+    await execa("npx", ["playwright", "test", ...files], {
+      cwd,
+      env: {
+        ...process.env,
+        BASE_URL: local.baseUrl,
+        PLAYWRIGHT_HTML_OPEN: "never",
+        TESTKIT_MANAGED_SERVERS: "1",
+        TESTKIT_WORKER_ID: String(targetConfig.workerId),
+      },
+      stdio: "inherit",
+    });
+    return { failed: false };
+  } catch {
+    return { failed: true };
   }
+}
 
-  // Nuke and retry: fresh fork from prod, clean goose state
-  await neonReset(config);
-  await neonUp(config);
-
-  // Re-read DATABASE_URL from fresh branch
-  if (fs.existsSync(dbUrlPath)) {
-    env.DATABASE_URL = fs.readFileSync(dbUrlPath, "utf8").trim();
+async function stopLocalServices(started) {
+  for (const service of [...started].reverse()) {
+    await stopChildProcess(service.child);
   }
+}
 
-  try {
-    await execaCommand(migrateCmd, execOpts);
-  } catch (retryErr) {
-    throw new Error(`Migration failed on fresh branch — likely a bug in your migration SQL:\n${retryErr.message}`);
+async function stopChildProcess(child) {
+  if (!child || child.exitCode !== null) return;
+
+  child.kill("SIGTERM");
+  const exited = await Promise.race([
+    new Promise((resolve) => child.once("exit", () => resolve(true))),
+    sleep(5_000).then(() => false),
+  ]);
+
+  if (!exited && child.exitCode === null) {
+    child.kill("SIGKILL");
+    await new Promise((resolve) => child.once("exit", resolve));
   }
 }
 
-/**
- * Show state directory contents.
- */
-export function showStatus(config) {
-  const { stateDir } = config;
-  if (!fs.existsSync(stateDir)) {
-    console.log("No state — run tests first.");
-    return;
-  }
-  for (const file of fs.readdirSync(stateDir)) {
-    if (file === "fly-env.sh") continue;
-    const filePath = path.join(stateDir, file);
-    if (fs.statSync(filePath).isDirectory()) continue;
-    const val = fs.readFileSync(filePath, "utf8").trim();
-    console.log(`  ${file}: ${val}`);
-  }
-
-  // Show dependent state dirs
-  const depsDir = path.join(stateDir, "deps");
-  if (fs.existsSync(depsDir)) {
-    for (const depName of fs.readdirSync(depsDir)) {
-      const depDir = path.join(depsDir, depName);
-      if (!fs.statSync(depDir).isDirectory()) continue;
-      console.log(`  ── dep: ${depName} ──`);
-      for (const file of fs.readdirSync(depDir)) {
-        if (file === "fly-env.sh") continue;
-        const filePath = path.join(depDir, file);
-        if (fs.statSync(filePath).isDirectory()) continue;
-        const val = fs.readFileSync(filePath, "utf8").trim();
-        console.log(`    ${file}: ${val}`);
-      }
+async function waitForReady({ name, url, timeoutMs, process }) {
+  const start = Date.now();
+
+  while (Date.now() - start < timeoutMs) {
+    if (process.exitCode !== null) {
+      throw new Error(`Service "${name}" exited before becoming ready`);
     }
+
+    try {
+      const response = await fetch(url);
+      if (response.ok) return;
+    } catch {
+      // Service still warming up.
+    }
+
+    await sleep(1_000);
   }
+
+  throw new Error(`Timed out waiting for "${name}" to become ready at ${url}`);
 }
 
-/**
- * Run a suite's `pre` command if defined.
- * Executes in the product directory with DATABASE_URL available.
- */
-async function runSuitePre(config, suite) {
-  if (!suite.pre) return;
-  const { productDir, stateDir } = config;
-  const dbUrlPath = path.join(stateDir, "database_url");
-  const env = { ...process.env };
-  if (fs.existsSync(dbUrlPath)) {
-    env.DATABASE_URL = fs.readFileSync(dbUrlPath, "utf8").trim();
+function needsLocalRuntime(suites) {
+  return suites.some((suite) => suite.type !== "dal");
+}
+
+function getWorkerServiceStateDir(workerStateDir, targetName, serviceName) {
+  if (targetName === serviceName) {
+    return workerStateDir;
   }
-  console.log(`\n── pre: ${suite.name} ──`);
-  await execaCommand(suite.pre, { stdio: "inherit", cwd: productDir, env, shell: true });
+  return path.join(workerStateDir, "deps", serviceName);
 }
 
-/**
- * Run a single service: orchestrate HTTP and/or DAL test flows.
- * Returns true if any tests failed.
- */
-async function runService(config, suiteType, suiteNames, opts) {
-  const { manifest, stateDir } = config;
+function readDatabaseUrl(stateDir) {
+  return readStateValue(path.join(stateDir, "database_url"));
+}
 
-  // Collect suites from manifest, partitioned by flow
-  const types = suiteType === "all"
-    ? Object.keys(manifest.suites)
-    : [suiteType === "int" ? "integration" : suiteType];
+function readStateValue(filePath) {
+  if (!fs.existsSync(filePath)) return null;
+  return fs.readFileSync(filePath, "utf8").trim();
+}
 
-  let httpSuites = [];
-  let dalSuites = [];
-  for (const type of types) {
-    const suites = manifest.suites[type] || [];
-    for (const suite of suites) {
-      if (suiteNames.length && !suiteNames.includes(suite.name)) continue;
-      if (type === "dal") {
-        dalSuites.push(suite);
-      } else {
-        httpSuites.push(suite);
-      }
+function printStateDir(dir, indent) {
+  for (const file of fs.readdirSync(dir)) {
+    const filePath = path.join(dir, file);
+    if (fs.statSync(filePath).isDirectory()) {
+      console.log(`${indent}${file}/`);
+      printStateDir(filePath, `${indent}  `);
+      continue;
     }
+    const value = fs.readFileSync(filePath, "utf8").trim();
+    console.log(`${indent}${file}: ${value}`);
   }
+}
 
-  const httpFiles = httpSuites.flatMap((s) => s.files);
-  const dalFiles = dalSuites.flatMap((s) => s.files);
+function pipeOutput(stream, prefix) {
+  if (!stream) return;
 
-  if (!httpFiles.length && !dalFiles.length) {
-    console.log(`No test files for ${config.name} type="${suiteType}" suites=${suiteNames.join(",") || "all"} — skipping`);
-    return false;
-  }
+  let pending = "";
+  stream.on("data", (chunk) => {
+    pending += chunk.toString();
+    const lines = pending.split(/\r?\n/);
+    pending = lines.pop() || "";
+    for (const line of lines) {
+      if (line.length > 0) console.log(`${prefix} ${line}`);
+    }
+  });
+  stream.on("end", () => {
+    if (pending.length > 0) {
+      console.log(`${prefix} ${pending}`);
+    }
+  });
+}
 
-  fs.mkdirSync(stateDir, { recursive: true });
+async function runWithConcurrency(items, limit, handler) {
+  const concurrency = Math.max(1, Math.min(limit || 1, items.length || 1));
+  let nextIndex = 0;
 
-  let failed = false;
-  let neonReady = false;
-
-  // HTTP flow: build → neon → migrate → fly → run → fly down
-  if (httpFiles.length) {
-    requireFlyToken(config.name);
-    const deps = manifest.testkit.depends || [];
-
-    // Phase 1: Build primary + deps in parallel
-    if (opts.build) {
-      await Promise.all([
-        build(config),
-        ...deps.map(dep => buildDep(config, dep)),
-      ]);
+  const workers = Array.from({ length: concurrency }, async () => {
+    while (nextIndex < items.length) {
+      const current = nextIndex;
+      nextIndex += 1;
+      await handler(items[current], current);
     }
+  });
 
-    // Phase 2: Database (unchanged)
-    await neonUp(config);
-    await migrate(config);
-    neonReady = true;
+  await Promise.all(workers);
+}
 
-    // Phase 3: Deploy primary + deps in parallel
-    await Promise.all([
-      flyUp(config),
-      ...deps.map(dep => flyUpDep(config, dep)),
-    ]);
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
 
-    try {
-      for (const suite of httpSuites) {
-        await runSuitePre(config, suite);
-      }
-      const result = await runTests(config, httpFiles);
-      if (result?.failed) failed = true;
-    } finally {
-      // Phase 5: Teardown primary + deps in parallel
-      await Promise.allSettled([
-        flyDown(config),
-        ...deps.map(dep => flyDownDep(config, dep)),
-      ]);
+function resolveRuntimeUrl(rawUrl, serviceName, targetConfig, workerId, context) {
+  const resolved = resolveTemplateString(rawUrl, {
+    ...context,
+    targetName: targetConfig.name,
+    workerId,
+    serviceName,
+  });
+  const actualPort = context.portMap.get(serviceName);
+  return actualPort ? rewriteUrlPort(resolved, actualPort) : resolved;
+}
+
+function finalizeString(value, context) {
+  let resolved = resolveTemplateString(value, context);
+  for (const [source, destination] of context.urlMappings || []) {
+    if (source && destination && source !== destination) {
+      resolved = resolved.split(source).join(destination);
     }
   }
+  return resolved;
+}
 
-  // DAL flow: neon → migrate → run suite pre hooks → run DAL tests
-  if (dalFiles.length) {
-    if (!neonReady) {
-      await neonUp(config);
-      await migrate(config);
+function resolveTemplateString(value, context) {
+  if (typeof value !== "string") return value;
+
+  return value.replace(/\{([a-zA-Z]+)(?::([a-zA-Z0-9_-]+))?\}/g, (_match, token, arg) => {
+    switch (token) {
+      case "worker":
+        return String(context.workerId);
+      case "target":
+        return context.targetName;
+      case "service":
+        return context.serviceName;
+      case "stateDir":
+        return context.serviceStateDir;
+      case "port": {
+        const serviceName = arg || context.serviceName;
+        const port = context.portMap.get(serviceName);
+        if (!port) {
+          throw new Error(`Unknown port placeholder for service "${serviceName}"`);
+        }
+        return String(port);
+      }
+      case "baseUrl": {
+        const serviceName = arg || context.serviceName;
+        const baseUrl = context.baseUrlByService.get(serviceName);
+        if (!baseUrl) {
+          throw new Error(`Unknown baseUrl placeholder for service "${serviceName}"`);
+        }
+        return baseUrl;
+      }
+      case "readyUrl": {
+        const serviceName = arg || context.serviceName;
+        const readyUrl = context.readyUrlByService.get(serviceName);
+        if (!readyUrl) {
+          throw new Error(`Unknown readyUrl placeholder for service "${serviceName}"`);
+        }
+        return readyUrl;
+      }
+      default:
+        throw new Error(`Unsupported template token "{${token}${arg ? `:${arg}` : ""}}"`);
     }
-    for (const suite of dalSuites) {
-      await runSuitePre(config, suite);
-      const result = await runDalTests(config, suite.files);
-      if (result?.failed) failed = true;
+  });
+}
+
+function rewriteUrlPort(rawUrl, port) {
+  try {
+    const original = new URL(rawUrl);
+    if (!original.port) return rawUrl;
+
+    const rewritten = new URL(rawUrl);
+    rewritten.port = String(port);
+
+    let next = rewritten.toString();
+    if (!rawUrl.endsWith("/") && original.pathname === "/" && next.endsWith("/")) {
+      next = next.slice(0, -1);
     }
+    return next;
+  } catch {
+    return rawUrl;
   }
+}
 
-  return failed;
+function numericPortFromUrl(rawUrl) {
+  try {
+    const url = new URL(rawUrl);
+    const port = Number(url.port);
+    return Number.isInteger(port) && port > 0 ? port : null;
+  } catch {
+    return null;
+  }
+}
+
+async function assertLocalServicePortsAvailable(config) {
+  const endpoints = [config.testkit.local.baseUrl, config.testkit.local.readyUrl];
+  const seen = new Set();
+
+  for (const endpoint of endpoints) {
+    const socket = socketFromUrl(endpoint);
+    if (!socket) continue;
+
+    const key = `${socket.host}:${socket.port}`;
+    if (seen.has(key)) continue;
+    seen.add(key);
+
+    if (await isPortInUse(socket)) {
+      throw new Error(
+        `Cannot start "${config.workerLabel}:${config.name}" because ${key} is already in use. ` +
+          `Stop the existing process and rerun testkit.`
+      );
+    }
+  }
+}
+
+function socketFromUrl(rawUrl) {
+  try {
+    const url = new URL(rawUrl);
+    const port = Number(url.port);
+    if (!Number.isInteger(port) || port <= 0) return null;
+
+    const host = normalizeSocketHost(url.hostname);
+    return host ? { host, port } : null;
+  } catch {
+    return null;
+  }
+}
+
+function normalizeSocketHost(hostname) {
+  if (!hostname || hostname === "localhost") return "127.0.0.1";
+  if (hostname === "[::1]") return "::1";
+  return hostname;
+}
+
+async function isPortInUse({ host, port }) {
+  return new Promise((resolve, reject) => {
+    const socket = new net.Socket();
+    let settled = false;
+
+    const finish = (value, error = null) => {
+      if (settled) return;
+      settled = true;
+      socket.destroy();
+      if (error) {
+        reject(error);
+        return;
+      }
+      resolve(value);
+    };
+
+    socket.setTimeout(1_000);
+    socket.once("connect", () => finish(true));
+    socket.once("timeout", () => finish(false));
+    socket.once("error", (error) => {
+      if (["ECONNREFUSED", "EHOSTUNREACH", "ENOTFOUND"].includes(error.code)) {
+        finish(false);
+        return;
+      }
+      finish(false, error);
+    });
+
+    socket.connect(port, host);
+  });
+}
+
+function findRuntimeStateDirs(rootDir) {
+  const found = [];
+
+  const visit = (dir) => {
+    if (!fs.existsSync(dir)) return;
+    const entries = fs.readdirSync(dir, { withFileTypes: true });
+    const hasRuntimeFiles = entries.some(
+      (entry) =>
+        entry.isFile() &&
+        (entry.name === "neon_project_id" || entry.name === "neon_branch_id")
+    );
+    if (hasRuntimeFiles) {
+      found.push(dir);
+    }
+
+    for (const entry of entries) {
+      if (entry.isDirectory()) {
+        visit(path.join(dir, entry.name));
+      }
+    }
+  };
+
+  visit(rootDir);
+  return found.sort((a, b) => b.length - a.length);
 }