@elench/testkit 0.1.16 → 0.1.18

package/lib/runner.mjs

@@ -1,1165 +0,0 @@
-import fs from "fs";
-import path from "path";
-import { spawn } from "child_process";
-import net from "net";
-import { execa, execaCommand } from "execa";
-import { resolveDalBinary, resolveServiceCwd } from "./config.mjs";
-import {
-  cleanupOrphanedLocalInfrastructure,
-  destroyRuntimeDatabase,
-  destroyServiceDatabaseCache,
-  isDatabaseStateDir,
-  prepareDatabaseRuntime,
-  showServiceDatabaseStatus,
-} from "./database.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 startedAt = Date.now();
-  const results = await Promise.all(
-    configs.map(async (config, targetSlot) => {
-      console.log(`\n══ ${config.name} ══`);
-      return runService(config, configMap, suiteType, suiteNames, opts, {
-        targetSlot,
-        targetSpan,
-      });
-    })
-  );
-
-  printRunSummary(results, Date.now() - startedAt);
-  if (results.some((result) => result.failed)) process.exit(1);
-}
-
-export async function destroy(config) {
-  if (!fs.existsSync(config.stateDir)) return;
-
-  const runtimeStateDirs = findRuntimeStateDirs(config.stateDir);
-  for (const stateDir of runtimeStateDirs) {
-    await destroyRuntimeDatabase({
-      productDir: config.productDir,
-      stateDir,
-    });
-  }
-
-  await destroyServiceDatabaseCache(config.productDir, config.name);
-  fs.rmSync(config.stateDir, { recursive: true, force: true });
-  await cleanupOrphanedLocalInfrastructure(config.productDir);
-}
-
-export function showStatus(config) {
-  if (!fs.existsSync(config.stateDir)) {
-    console.log("No state — run tests first.");
-  } else {
-    printStateDir(config.stateDir, "  ");
-  }
-  showServiceDatabaseStatus(config.productDir, config.name);
-}
-
-async function runService(targetConfig, configMap, suiteType, suiteNames, opts, runtimeSlot) {
-  const startedAt = Date.now();
-  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 {
-      name: targetConfig.name,
-      failed: false,
-      skipped: true,
-      suiteCount: 0,
-      completedSuiteCount: 0,
-      failedSuiteCount: 0,
-      durationMs: Date.now() - startedAt,
-      workers: [],
-      errors: [],
-    };
-  }
-
-  const runtimeConfigs = resolveRuntimeConfigs(targetConfig, configMap);
-  fs.mkdirSync(targetConfig.stateDir, { recursive: true });
-
-  const jobs = Math.max(1, Math.min(opts.jobs || 1, suites.length));
-  const workerPlans = buildWorkerPlans(
-    targetConfig,
-    runtimeConfigs,
-    suites,
-    jobs,
-    runtimeSlot
-  );
-
-  const results = await Promise.allSettled(workerPlans.map((plan) => runWorkerPlan(plan)));
-  let failed = false;
-  const workers = [];
-  const errors = [];
-  let failedSuiteCount = 0;
-  let completedSuiteCount = 0;
-
-  for (const result of results) {
-    if (result.status === "rejected") {
-      failed = true;
-      console.error(result.reason);
-      errors.push(formatError(result.reason));
-      continue;
-    }
-    workers.push(result.value);
-    completedSuiteCount += result.value.completedSuiteCount;
-    failedSuiteCount += result.value.failedSuiteCount;
-    if (result.value.failed) failed = true;
-  }
-
-  return {
-    name: targetConfig.name,
-    failed,
-    skipped: false,
-    suiteCount: suites.length,
-    completedSuiteCount,
-    failedSuiteCount,
-    durationMs: Date.now() - startedAt,
-    workers,
-    errors,
-  };
-}
-
-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;
-}
-
-function applyShard(suites, shard) {
-  if (!shard) return suites;
-  return suites.filter((_, index) => index % shard.total === shard.index - 1);
-}
-
-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;
-}
-
-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;
-}
-
-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);
-}
-
-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;
-  }
-
-  for (const bucket of buckets) {
-    bucket.suites.sort((a, b) => a.orderIndex - b.orderIndex);
-  }
-
-  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,
-      })
-    );
-  }
-
-  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]);
-    }
-  }
-
-  return runtimeConfigs.map((config) =>
-    resolveWorkerConfig(
-      config,
-      targetConfig,
-      workerId,
-      workerStateDir,
-      portMap,
-      baseUrlByService,
-      readyUrlByService,
-      urlMappings
-    )
-  );
-}
-
-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;
-}
-
-function resolveWorkerConfig(
-  config,
-  targetConfig,
-  workerId,
-  workerStateDir,
-  portMap,
-  baseUrlByService,
-  readyUrlByService,
-  urlMappings
-) {
-  const stateDir = resolveServiceStateDir(workerStateDir, targetConfig.name, config);
-  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.provider === "neon" &&
-          config.testkit.database.branchName !== undefined
-            ? finalizeString(config.testkit.database.branchName, context)
-            : config.testkit.database.provider === "neon"
-              ? `${targetConfig.name}-${config.name}-w${workerId}-testkit`
-              : undefined,
-      }
-    : 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,
-    },
-  };
-}
-
-async function runWorkerPlan(plan) {
-  const startedAt = Date.now();
-  console.log(
-    `\n══ ${plan.targetConfig.name} worker ${plan.workerId} (${plan.suites.length} suite${plan.suites.length === 1 ? "" : "s"}) ══`
-  );
-
-  let startedServices = [];
-  let failed = false;
-  const suiteResults = [];
-  let fatalError = null;
-
-  try {
-    await prepareDatabases(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);
-      suiteResults.push(result);
-      if (result.failed) failed = true;
-    }
-  } catch (error) {
-    fatalError = error;
-    failed = true;
-    throw error;
-  } finally {
-    await stopLocalServices(startedServices);
-  }
-
-  return {
-    workerId: plan.workerId,
-    failed,
-    fatalError: fatalError ? formatError(fatalError) : null,
-    durationMs: Date.now() - startedAt,
-    suiteCount: plan.suites.length,
-    completedSuiteCount: suiteResults.length,
-    failedSuiteCount: suiteResults.filter((result) => result.failed).length,
-    suites: suiteResults,
-  };
-}
-
-async function prepareDatabases(runtimeConfigs) {
-  for (const config of runtimeConfigs) {
-    await prepareDatabaseRuntime(config, {
-      runMigrate: config.testkit.migrate
-        ? (databaseUrl) => runMigrate(config, databaseUrl)
-        : null,
-      runSeed: config.testkit.seed ? (databaseUrl) => runSeed(config, databaseUrl) : null,
-    });
-  }
-}
-
-async function runMigrate(config, databaseUrl) {
-  const migrate = config.testkit.migrate;
-  if (!migrate) return;
-
-  const env = buildExecutionEnv(config);
-  if (databaseUrl) env.DATABASE_URL = databaseUrl;
-
-  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 runSeed(config, databaseUrl) {
-  const seed = config.testkit.seed;
-  if (!seed) return;
-
-  const env = buildExecutionEnv(config);
-  if (databaseUrl) env.DATABASE_URL = databaseUrl;
-
-  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 started;
-}
-
-async function startLocalService(config) {
-  const cwd = resolveServiceCwd(config.productDir, config.testkit.local.cwd);
-  const env = buildExecutionEnv(config, 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);
-
-  console.log(`Starting ${config.workerLabel}:${config.name}: ${config.testkit.local.start}`);
-  const child = spawn(config.testkit.local.start, {
-    cwd,
-    env,
-    detached: true,
-    shell: true,
-    stdio: ["ignore", "pipe", "pipe"],
-  });
-
-  const outputDrains = [
-    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, outputDrains);
-    throw error;
-  }
-
-  return { name: config.name, child, outputDrains };
-}
-
-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);
-  }
-
-  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 startedAt = Date.now();
-  let failed = false;
-  const failedFiles = [];
-  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("k6", ["run", "-e", `BASE_URL=${baseUrl}`, absFile], {
-        cwd: targetConfig.productDir,
-        env: buildExecutionEnv(targetConfig),
-        stdio: "inherit",
-      });
-    } catch {
-      failed = true;
-      failedFiles.push(file);
-    }
-  });
-
-  return buildSuiteResult(suite, failed, startedAt, failedFiles);
-}
-
-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();
-  const startedAt = Date.now();
-  let failed = false;
-  const failedFiles = [];
-  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: buildExecutionEnv(targetConfig),
-        stdio: "inherit",
-      });
-    } catch {
-      failed = true;
-      failedFiles.push(file);
-    }
-  });
-
-  return buildSuiteResult(suite, failed, startedAt, failedFiles);
-}
-
-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 cwd = resolveServiceCwd(targetConfig.productDir, local.cwd);
-  const files = suite.files.map((file) =>
-    path.relative(cwd, path.join(targetConfig.productDir, file))
-  );
-  const startedAt = Date.now();
-
-  try {
-    await execa("npx", ["playwright", "test", ...files], {
-      cwd,
-      env: buildPlaywrightEnv(targetConfig, local.baseUrl),
-      stdio: "inherit",
-    });
-    return buildSuiteResult(suite, false, startedAt);
-  } catch {
-    return buildSuiteResult(suite, true, startedAt);
-  }
-}
-
-async function stopLocalServices(started) {
-  for (const service of [...started].reverse()) {
-    await stopChildProcess(service.child, service.outputDrains);
-  }
-}
-
-async function stopChildProcess(child, outputDrains = []) {
-  if (!child) return;
-  if (child.exitCode !== null) {
-    await Promise.all(outputDrains);
-    return;
-  }
-
-  killChildProcess(child, "SIGTERM");
-  const exited = await Promise.race([
-    new Promise((resolve) => child.once("exit", () => resolve(true))),
-    sleep(5_000).then(() => false),
-  ]);
-
-  if (!exited && child.exitCode === null) {
-    killChildProcess(child, "SIGKILL");
-    await new Promise((resolve) => child.once("exit", resolve));
-  }
-
-  await Promise.all(outputDrains);
-}
-
-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}`);
-}
-
-function needsLocalRuntime(suites) {
-  return suites.some((suite) => suite.type !== "dal");
-}
-
-function resolveServiceStateDir(workerStateDir, targetName, config) {
-  const dbSource = config.testkit.databaseFrom || config.name;
-  return getWorkerServiceStateDir(workerStateDir, targetName, dbSource);
-}
-
-function getWorkerServiceStateDir(workerStateDir, targetName, serviceName) {
-  if (targetName === serviceName) {
-    return workerStateDir;
-  }
-  return path.join(workerStateDir, "deps", serviceName);
-}
-
-function buildExecutionEnv(config, extraEnv = {}) {
-  return {
-    ...process.env,
-    ...(config.testkit.serviceEnv || {}),
-    ...extraEnv,
-  };
-}
-
-function buildPlaywrightEnv(config, baseUrl) {
-  return buildExecutionEnv(config, {
-    BASE_URL: baseUrl,
-    PLAYWRIGHT_HTML_OPEN: "never",
-    PLAYWRIGHT_SKIP_VALIDATE_HOST_REQUIREMENTS:
-      process.env.PLAYWRIGHT_SKIP_VALIDATE_HOST_REQUIREMENTS || "1",
-    TESTKIT_MANAGED_SERVERS: "1",
-    TESTKIT_WORKER_ID: String(config.workerId),
-  });
-}
-
-function buildSuiteResult(suite, failed, startedAt, failedFiles = []) {
-  return {
-    name: suite.name,
-    type: suite.type,
-    framework: suite.framework,
-    failed,
-    fileCount: suite.files.length,
-    failedFiles,
-    durationMs: Date.now() - startedAt,
-  };
-}
-
-function printRunSummary(results, durationMs) {
-  const totalServices = results.length;
-  const executedServices = results.filter((result) => !result.skipped);
-  const skippedServices = results.filter((result) => result.skipped);
-  const failedServices = executedServices.filter((result) => result.failed);
-  const passedServices = executedServices.filter((result) => !result.failed);
-  const totalSuites = executedServices.reduce((sum, result) => sum + result.suiteCount, 0);
-  const completedSuites = executedServices.reduce(
-    (sum, result) => sum + result.completedSuiteCount,
-    0
-  );
-  const failedSuites = executedServices.reduce((sum, result) => sum + result.failedSuiteCount, 0);
-  const passedSuites = completedSuites - failedSuites;
-
-  console.log("\n══ Summary ══");
-  console.log(
-    [
-      `services ${passedServices.length}/${executedServices.length} passed`,
-      `suites ${passedSuites}/${totalSuites} passed`,
-      skippedServices.length > 0 ? `${skippedServices.length} skipped` : null,
-      `duration ${formatDuration(durationMs)}`,
-    ]
-      .filter(Boolean)
-      .join("  ·  ")
-  );
-
-  for (const result of results) {
-    const status = result.skipped ? "SKIP" : result.failed ? "FAIL" : "PASS";
-    const detail = result.skipped ? "no matching suites" : formatServiceSummary(result);
-    console.log(
-      `${status.padEnd(4)} ${result.name.padEnd(longestServiceName(results))}  ${detail}  ·  ${formatDuration(result.durationMs)}`
-    );
-
-    if (result.failed) {
-      const failedSuiteResults = result.workers.flatMap((worker) =>
-        worker.suites.filter((suite) => suite.failed)
-      );
-      for (const suite of failedSuiteResults) {
-        const fileDetail =
-          suite.failedFiles.length > 0 ? `  (${suite.failedFiles.join(", ")})` : "";
-        console.log(
-          `  - ${suite.type}:${suite.name} [${suite.framework}]${fileDetail} · ${formatDuration(suite.durationMs)}`
-        );
-      }
-      for (const error of result.errors) {
-        console.log(`  - worker error: ${error}`);
-      }
-    }
-  }
-
-  if (failedServices.length > 0) {
-    console.log(`\nResult: FAILED (${failedServices.length}/${totalServices} services failed)`);
-    return;
-  }
-
-  console.log("\nResult: PASSED");
-}
-
-function longestServiceName(results) {
-  return results.reduce((max, result) => Math.max(max, result.name.length), 4);
-}
-
-function formatDuration(durationMs) {
-  const totalSeconds = Math.max(0, Math.round(durationMs / 1000));
-  const minutes = Math.floor(totalSeconds / 60);
-  const seconds = totalSeconds % 60;
-  if (minutes === 0) return `${seconds}s`;
-  return `${minutes}m ${String(seconds).padStart(2, "0")}s`;
-}
-
-function formatError(error) {
-  if (error instanceof Error) return error.message;
-  return String(error);
-}
-
-function formatServiceSummary(result) {
-  const passedSuites = result.completedSuiteCount - result.failedSuiteCount;
-  const notRun = result.suiteCount - result.completedSuiteCount;
-  let detail = `${passedSuites}/${result.suiteCount} suites passed`;
-  if (notRun > 0) {
-    detail += `, ${notRun} not run`;
-  }
-  return detail;
-}
-
-function killChildProcess(child, signal) {
-  if (!child?.pid) return;
-
-  try {
-    process.kill(-child.pid, signal);
-    return;
-  } catch (error) {
-    if (error?.code !== "ESRCH") {
-      // Fall back to the direct child if process-group signalling is unavailable.
-    } else {
-      return;
-    }
-  }
-
-  try {
-    child.kill(signal);
-  } catch (error) {
-    if (error?.code !== "ESRCH") throw error;
-  }
-}
-
-function readDatabaseUrl(stateDir) {
-  return readStateValue(path.join(stateDir, "database_url"));
-}
-
-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}`);
-  }
-}
-
-function pipeOutput(stream, prefix) {
-  if (!stream) return Promise.resolve();
-
-  let pending = "";
-  return new Promise((resolve) => {
-    let settled = false;
-    const settle = () => {
-      if (settled) return;
-      settled = true;
-      resolve();
-    };
-
-    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}`);
-      }
-      settle();
-    });
-    stream.on("close", settle);
-    stream.on("error", settle);
-  });
-}
-
-async function runWithConcurrency(items, limit, handler) {
-  const concurrency = Math.max(1, Math.min(limit || 1, items.length || 1));
-  let nextIndex = 0;
-
-  const workers = Array.from({ length: concurrency }, async () => {
-    while (nextIndex < items.length) {
-      const current = nextIndex;
-      nextIndex += 1;
-      await handler(items[current], current);
-    }
-  });
-
-  await Promise.all(workers);
-}
-
-function sleep(ms) {
-  return new Promise((resolve) => setTimeout(resolve, ms));
-}
-
-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;
-}
-
-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}` : ""}}"`);
-    }
-  });
-}
-
-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;
-  }
-}
-
-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 });
-    if (isDatabaseStateDir(dir)) {
-      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);
-}