@elench/testkit 0.1.10 → 0.1.11

package/lib/runner.mjs

@@ -1,461 +1,574 @@
 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);
-    return;
+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;
+
+export async function runAll(configs, suiteType, suiteNames, opts, allConfigs = configs) {
+  const configMap = new Map(allConfigs.map((config) => [config.name, config]));
+  let failed = false;
+
+  for (const config of configs) {
+    console.log(`\n══ ${config.name} ══`);
+    const serviceFailed = await runService(config, configMap, suiteType, suiteNames, opts);
+    if (serviceFailed) failed = true;
   }
 
-  // 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);
-    })
-  );
+  if (failed) process.exit(1);
+}
 
-  // Summarize
-  const summary = configs.map((c, i) => {
-    const r = results[i];
-    const ok = r.status === "fulfilled" && !r.value;
-    return `  ${ok ? "✓" : "✗"} ${c.name}`;
+export async function destroy(config) {
+  const runtimeServices = [];
+  if (config.testkit.dependsOn) {
+    for (const depName of config.testkit.dependsOn) {
+      runtimeServices.push({
+        name: depName,
+        stateDir: path.join(config.stateDir, "deps", depName),
+        testkit: null,
+      });
+    }
+  }
+  runtimeServices.push({
+    name: config.name,
+    stateDir: config.stateDir,
+    testkit: config.testkit,
   });
-  console.log(`\n── Summary ──\n${summary.join("\n")}`);
 
-  const anyFailed = results.some(
-    (r) => r.status === "rejected" || r.value === true
-  );
-  if (anyFailed) process.exit(1);
+  for (const runtime of runtimeServices) {
+    if (!fs.existsSync(runtime.stateDir)) continue;
+    const dbFile = path.join(runtime.stateDir, "neon_branch_id");
+    if (fs.existsSync(dbFile)) {
+      const serviceConfig =
+        runtime.name === config.name
+          ? config.testkit
+          : { database: { projectId: readStateValue(path.join(runtime.stateDir, "neon_project_id")) } };
+
+      const projectId = serviceConfig.database?.projectId;
+      if (projectId) {
+        await runScript("neon-down.sh", {
+          NEON_PROJECT_ID: projectId,
+          STATE_DIR: runtime.stateDir,
+        });
+      }
+    }
+  }
+
+  fs.rmSync(config.stateDir, { recursive: true, force: true });
 }
 
-/**
- * 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,
-  });
+export function showStatus(config) {
+  if (!fs.existsSync(config.stateDir)) {
+    console.log("No state — run tests first.");
+    return;
+  }
+
+  printStateDir(config.stateDir, "  ");
 }
 
-/**
- * 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,
-  });
+async function runService(targetConfig, configMap, suiteType, suiteNames, opts) {
+  const suites = collectSuites(targetConfig, suiteType, suiteNames, opts.framework);
+  if (suites.length === 0) {
+    console.log(
+      `No test files for ${targetConfig.name} type="${suiteType}" suites=${suiteNames.join(",") || "all"} — skipping`
+    );
+    return false;
+  }
+
+  const runtimeConfigs = resolveRuntimeConfigs(targetConfig, configMap);
+  fs.mkdirSync(targetConfig.stateDir, { recursive: true });
+
+  let startedServices = [];
+  let failed = false;
+
+  try {
+    await prepareDatabases(runtimeConfigs, targetConfig);
+    await runMigrations(runtimeConfigs, targetConfig);
+    await runSeeds(runtimeConfigs, targetConfig);
+
+    if (needsLocalRuntime(suites)) {
+      startedServices = await startLocalServices(runtimeConfigs, targetConfig);
+    }
+
+    for (const suite of suites) {
+      console.log(`\n── ${suite.type}:${suite.name} (${suite.framework}) ──`);
+      const result = await runSuite(targetConfig, suite, targetConfig.stateDir);
+      if (result.failed) failed = true;
+    }
+  } finally {
+    await stopLocalServices(startedServices);
+  }
+
+  return failed;
 }
 
-/**
- * Generate fly-env.sh and start/create the Fly machine.
- */
-export async function flyUp(config) {
-  const { productDir, stateDir, manifest } = config;
-  const tk = manifest.testkit;
-
-  // 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}"`);
-  }
-  for (const k of tk.fly.secrets || []) {
-    envLines.push(`  --env "${k}=\${${k}}"`);  // shell substitution at source-time
-  }
-  const flyEnvPath = path.join(stateDir, "fly-env.sh");
-  fs.writeFileSync(flyEnvPath, `FLY_ENV_ARGS=(\n${envLines.join("\n")}\n)\n`);
-
-  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 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 = [];
+
+  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,
+      });
+    }
+  }
+
+  return suites;
 }
 
-/**
- * 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 orderedTypes(types) {
+  const ordered = [];
+  for (const known of TYPE_ORDER) {
+    if (types.includes(known)) ordered.push(known);
+  }
+  for (const type of types) {
+    if (!ordered.includes(type)) ordered.push(type);
+  }
+  return ordered;
 }
 
-/**
- * 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 });
-
-  // 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"));
-  }
-
-  // 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}"`);
-  }
-  for (const k of dep.fly.secrets || []) {
-    envLines.push(`  --env "${k}=\${${k}}"`);  // shell substitution at source-time
-  }
-  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,
-  });
+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;
 }
 
-/**
- * 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,
-  });
+async function prepareDatabases(runtimeConfigs, targetConfig) {
+  for (const config of runtimeConfigs) {
+    const db = config.testkit.database;
+    if (!db) continue;
+
+    requireNeonApiKey();
+
+    const stateDir = getServiceStateDir(targetConfig, config.name);
+    fs.mkdirSync(stateDir, { recursive: true });
+
+    await runScript("neon-up.sh", {
+      NEON_PROJECT_ID: db.projectId,
+      NEON_DB_NAME: db.dbName,
+      NEON_BRANCH_NAME: db.branchName || `${targetConfig.name}-${config.name}-testkit`,
+      NEON_RESET: db.reset === false ? "false" : "true",
+      STATE_DIR: stateDir,
+    });
+
+    fs.writeFileSync(path.join(stateDir, "neon_project_id"), db.projectId);
+  }
 }
 
-/**
- * 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,
-  });
+async function runMigrations(runtimeConfigs, targetConfig) {
+  for (const config of runtimeConfigs) {
+    const migrate = config.testkit.migrate;
+    if (!migrate) continue;
+
+    const stateDir = getServiceStateDir(targetConfig, config.name);
+    const env = { ...process.env };
+    const dbUrl = readDatabaseUrl(stateDir);
+    if (dbUrl) env.DATABASE_URL = dbUrl;
+
+    console.log(`\n── migrate:${config.name} ──`);
+    await execaCommand(migrate.cmd, {
+      cwd: resolveServiceCwd(config.productDir, migrate.cwd),
+      env,
+      stdio: "inherit",
+      shell: true,
+    });
+  }
 }
 
-/**
- * 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 runSeeds(runtimeConfigs, targetConfig) {
+  for (const config of runtimeConfigs) {
+    const seed = config.testkit.seed;
+    if (!seed) continue;
+
+    const stateDir = getServiceStateDir(targetConfig, config.name);
+    const env = { ...process.env };
+    const dbUrl = readDatabaseUrl(stateDir);
+    if (dbUrl) env.DATABASE_URL = dbUrl;
+
+    console.log(`\n── seed:${config.name} ──`);
+    await execaCommand(seed.cmd, {
+      cwd: resolveServiceCwd(config.productDir, seed.cwd),
+      env,
+      stdio: "inherit",
+      shell: true,
+    });
+  }
+}
+
+async function startLocalServices(runtimeConfigs, targetConfig) {
+  const started = [];
+
+  try {
+    for (const config of runtimeConfigs) {
+      if (!config.testkit.local) continue;
+      const stateDir = getServiceStateDir(targetConfig, config.name);
+      const proc = await startLocalService(config, stateDir);
+      started.push(proc);
     }
+  } catch (error) {
+    await stopLocalServices(started);
+    throw error;
   }
 
-  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,
+  return started;
+}
+
+async function startLocalService(config, stateDir) {
+  const cwd = resolveServiceCwd(config.productDir, config.testkit.local.cwd);
+  const env = {
+    ...process.env,
+    ...config.testkit.local.env,
+  };
+  const port = portFromUrl(config.testkit.local.baseUrl);
+  if (port) {
+    env.PORT = port;
+  }
+
+  const dbUrl = readDatabaseUrl(stateDir);
+  if (dbUrl) {
+    env.DATABASE_URL = dbUrl;
+  }
+
+  await assertLocalServicePortsAvailable(config);
+
+  console.log(`Starting ${config.name}: ${config.testkit.local.start}`);
+  const child = spawn(config.testkit.local.start, {
+    cwd,
+    env,
+    shell: true,
+    stdio: ["ignore", "pipe", "pipe"],
   });
-  fs.rmSync(stateDir, { recursive: true, force: true });
+
+  pipeOutput(child.stdout, `[${config.name}]`);
+  pipeOutput(child.stderr, `[${config.name}]`);
+
+  const readyTimeoutMs =
+    config.testkit.local.readyTimeoutMs || DEFAULT_READY_TIMEOUT_MS;
+
+  try {
+    await waitForReady({
+      name: config.name,
+      url: config.testkit.local.readyUrl,
+      timeoutMs: readyTimeoutMs,
+      process: child,
+    });
+  } catch (error) {
+    await stopChildProcess(child);
+    throw error;
+  }
+
+  return { name: config.name, child };
 }
 
-/**
- * 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 runSuite(targetConfig, suite, stateDir) {
+  if (suite.type === "dal") {
+    return runDalSuite(targetConfig, suite, stateDir);
+  }
+
+  if (suite.framework === "playwright") {
+    return runPlaywrightSuite(targetConfig, suite);
+  }
+
+  if (suite.framework === "k6" && HTTP_K6_TYPES.has(suite.type)) {
+    return runHttpK6Suite(targetConfig, suite);
+  }
 
-  // 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();
+  throw new Error(
+    `Unsupported suite combination for ${targetConfig.name}: type=${suite.type} framework=${suite.framework}`
+  );
+}
 
-  // 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]}`);
+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);
+  for (const file of suite.files) {
+    const absFile = path.join(targetConfig.productDir, file);
     try {
-      await execaCommand(`k6 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 };
 }
 
-/**
- * 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();
-
-  // Read DATABASE_URL from neon state
-  const databaseUrl = fs.readFileSync(path.join(stateDir, "database_url"), "utf8").trim();
-
-  // Build -e flags
-  const envFlags = [`-e DATABASE_URL=${databaseUrl}`];
-  for (const key of tk.dal?.secrets || []) {
-    envFlags.push(`-e ${key}=${process.env[key]}`);
+async function runDalSuite(targetConfig, suite, stateDir) {
+  const databaseUrl = readDatabaseUrl(stateDir);
+  if (!databaseUrl) {
+    throw new Error(`Service "${targetConfig.name}" requires a database for DAL suites`);
   }
-  const envStr = envFlags.join(" ");
 
+  const k6Binary = resolveDalBinary();
   let failed = false;
-  for (const file of files) {
-    const absFile = path.join(productDir, file);
+
+  for (const file of suite.files) {
+    const absFile = path.join(targetConfig.productDir, file);
     try {
-      await execaCommand(`${k6Binary} run ${envStr} ${absFile}`, { stdio: "inherit" });
-    } catch (err) {
+      await execa(k6Binary, ["run", "-e", `DATABASE_URL=${databaseUrl}`, 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,
-  });
-  // 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);
+  return { failed };
 }
 
-/**
- * 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;
-
-  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",
+      },
+      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();
-  }
-  console.log(`\n── pre: ${suite.name} ──`);
-  await execaCommand(suite.pre, { stdio: "inherit", cwd: productDir, env, shell: true });
+function needsLocalRuntime(suites) {
+  return suites.some((suite) => suite.type !== "dal");
 }
 
-/**
- * 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 getServiceStateDir(targetConfig, serviceName) {
+  if (targetConfig.name === serviceName) {
+    return targetConfig.stateDir;
+  }
+  return path.join(targetConfig.stateDir, "deps", serviceName);
+}
 
-  // Collect suites from manifest, partitioned by flow
-  const types = suiteType === "all"
-    ? Object.keys(manifest.suites)
-    : [suiteType === "int" ? "integration" : suiteType];
+function readDatabaseUrl(stateDir) {
+  return readStateValue(path.join(stateDir, "database_url"));
+}
 
-  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 readStateValue(filePath) {
+  if (!fs.existsSync(filePath)) return null;
+  return fs.readFileSync(filePath, "utf8").trim();
+}
+
+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 });
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
 
-  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)),
-      ]);
-    }
+function portFromUrl(rawUrl) {
+  try {
+    const url = new URL(rawUrl);
+    return url.port || null;
+  } catch {
+    return null;
+  }
+}
 
-    // Phase 2: Database (unchanged)
-    await neonUp(config);
-    await migrate(config);
-    neonReady = true;
+async function assertLocalServicePortsAvailable(config) {
+  const endpoints = [config.testkit.local.baseUrl, config.testkit.local.readyUrl];
+  const seen = new Set();
 
-    // Phase 3: Deploy primary + deps in parallel
-    await Promise.all([
-      flyUp(config),
-      ...deps.map(dep => flyUpDep(config, dep)),
-    ]);
+  for (const endpoint of endpoints) {
+    const socket = socketFromUrl(endpoint);
+    if (!socket) continue;
 
-    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)),
-      ]);
+    const key = `${socket.host}:${socket.port}`;
+    if (seen.has(key)) continue;
+    seen.add(key);
+
+    if (await isPortInUse(socket)) {
+      throw new Error(
+        `Cannot start "${config.name}" because ${key} is already in use. Stop the existing process and rerun testkit.`
+      );
     }
   }
+}
 
-  // DAL flow: neon → migrate → run suite pre hooks → run DAL tests
-  if (dalFiles.length) {
-    if (!neonReady) {
-      await neonUp(config);
-      await migrate(config);
-    }
-    for (const suite of dalSuites) {
-      await runSuitePre(config, suite);
-      const result = await runDalTests(config, suite.files);
-      if (result?.failed) failed = true;
-    }
+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;
   }
+}
 
-  return failed;
+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);
+  });
 }