@elench/testkit 0.1.11 → 0.1.13

package/README.md

@@ -28,6 +28,13 @@ npx @elench/testkit e2e
 npx @elench/testkit --framework playwright
 npx @elench/testkit --framework k6
 
+# Parallelize with isolated worker stacks
+npx @elench/testkit --jobs 3
+
+# Run a deterministic shard
+npx @elench/testkit --shard 1/3
+npx @elench/testkit --jobs 2 --shard 2/3
+
 # Specific service / suite
 npx @elench/testkit frontend e2e -s auth
 npx @elench/testkit bourne int -s health
@@ -41,10 +48,11 @@ npx @elench/testkit destroy
 
 1. **Discovery** — reads `runner.manifest.json` for services, suites, files, and frameworks
 2. **Config** — reads `testkit.config.json` for local runtime, migration, dependency, and database settings
+   Per-service `.env` files declared in config are loaded when present.
 3. **Database** — provisions a Neon branch when a service declares one
 4. **Seed** — runs optional product seed commands against the provisioned database
 5. **Runtime** — starts required local services, waits for readiness, and injects test env
-6. **Execution** — runs `k6` suites file-by-file and Playwright suites suite-by-suite
+6. **Execution** — distributes suites across isolated worker stacks, runs `k6` suites file-by-file, and runs Playwright suites suite-by-suite
 7. **Cleanup** — stops local processes and preserves `.testkit/` state for inspection or later destroy
 
 ## File roles
@@ -52,6 +60,42 @@ npx @elench/testkit destroy
 - `runner.manifest.json`: canonical test inventory
 - `testkit.config.json`: local execution and provisioning config
 
+`testkit.config.json` can also declare:
+
+- `envFile` / `envFiles` for service-specific environment loading
+- `databaseFrom` for dependency services that must share another service's `DATABASE_URL`
+
+## Parallel execution
+
+`@elench/testkit` can run suites in parallel with `--jobs <n>`.
+
+Each worker gets its own:
+- Neon branch
+- `.testkit` state subtree
+- local service ports
+
+This keeps suites isolated while still reusing one stack per worker across multiple assigned suites.
+
+Use `--shard <i/n>` to split the selected suite set deterministically before worker scheduling.
+
+## Suite metadata
+
+`runner.manifest.json` remains the source of truth for suites. Optional per-suite `testkit` metadata can tune execution:
+
+```json
+{
+  "name": "health",
+  "files": ["tests/example.js"],
+  "testkit": {
+    "maxFileConcurrency": 2,
+    "weight": 3
+  }
+}
+```
+
+- `maxFileConcurrency`: k6-only opt-in for running files within the suite concurrently
+- `weight`: optional scheduling weight when distributing suites across workers
+
 ## Schema
 
 See [testkit-config-schema.md](testkit-config-schema.md).

package/lib/cli.mjs

@@ -13,6 +13,10 @@ export function run() {
     .command("[first] [second] [third]", "Run test suites (int, e2e, dal, all)")
     .option("-s, --suite <name>", "Run specific suite(s)", { default: [] })
     .option("--dir <path>", "Explicit product directory")
+    .option("--jobs <n>", "Number of isolated worker stacks per service", {
+      default: "1",
+    })
+    .option("--shard <i/n>", "Run only shard i of n at suite granularity")
     .option("--framework <name>", "Filter by framework (k6, playwright, all)", {
       default: "all",
     })
@@ -84,9 +88,42 @@ export function run() {
         );
       }
 
+      const jobs = Number.parseInt(String(options.jobs), 10);
+      if (!Number.isInteger(jobs) || jobs <= 0) {
+        throw new Error(`Invalid --jobs value "${options.jobs}". Expected a positive integer.`);
+      }
+
+      let shard = null;
+      if (options.shard) {
+        const match = String(options.shard).match(/^(\d+)\/(\d+)$/);
+        if (!match) {
+          throw new Error(
+            `Invalid --shard value "${options.shard}". Expected the form "i/n", e.g. 1/3.`
+          );
+        }
+        const index = Number.parseInt(match[1], 10);
+        const total = Number.parseInt(match[2], 10);
+        if (index <= 0 || total <= 0 || index > total) {
+          throw new Error(
+            `Invalid --shard value "${options.shard}". Expected 1 <= i <= n.`
+          );
+        }
+        shard = { index, total };
+      }
+
       const suiteType = type || "all";
       const suiteNames = Array.isArray(options.suite) ? options.suite : [options.suite].filter(Boolean);
-      await runner.runAll(configs, suiteType, suiteNames, options, allConfigs);
+      await runner.runAll(
+        configs,
+        suiteType,
+        suiteNames,
+        {
+          ...options,
+          jobs,
+          shard,
+        },
+        allConfigs
+      );
     });
 
   cli.help();

package/lib/config.mjs

@@ -68,13 +68,17 @@ export function loadConfigs(opts = {}) {
     }
 
     validateMergedService(name, runnerService, serviceConfig, productDir);
+    const serviceEnv = loadServiceEnv(productDir, serviceConfig);
 
     return {
       name,
       productDir,
       stateDir: path.join(productDir, ".testkit", name),
       suites: runnerService.suites,
-      testkit: serviceConfig,
+      testkit: {
+        ...serviceConfig,
+        serviceEnv,
+      },
     };
   });
 }
@@ -161,6 +165,31 @@ function loadRunnerManifest(productDir) {
             `Service "${serviceName}" suite "${suite.name}" uses unsupported framework "${framework}"`
           );
         }
+
+        if (suite.testkit !== undefined) {
+          if (!isObject(suite.testkit)) {
+            throw new Error(
+              `Service "${serviceName}" suite "${suite.name}" testkit config must be an object`
+            );
+          }
+          if (
+            suite.testkit.maxFileConcurrency !== undefined &&
+            (!Number.isInteger(suite.testkit.maxFileConcurrency) ||
+              suite.testkit.maxFileConcurrency <= 0)
+          ) {
+            throw new Error(
+              `Service "${serviceName}" suite "${suite.name}" testkit.maxFileConcurrency must be a positive integer`
+            );
+          }
+          if (
+            suite.testkit.weight !== undefined &&
+            (!Number.isInteger(suite.testkit.weight) || suite.testkit.weight <= 0)
+          ) {
+            throw new Error(
+              `Service "${serviceName}" suite "${suite.name}" testkit.weight must be a positive integer`
+            );
+          }
+        }
       }
     }
   }
@@ -203,6 +232,20 @@ function validateConfigCoverage(runner, config) {
         );
       }
     }
+
+    const databaseFrom = config.services[serviceName].databaseFrom;
+    if (databaseFrom) {
+      if (!config.services[databaseFrom]) {
+        throw new Error(
+          `Service "${serviceName}" databaseFrom "${databaseFrom}" is missing from ${TESTKIT_CONFIG}`
+        );
+      }
+      if (!runner.services[databaseFrom]) {
+        throw new Error(
+          `Service "${serviceName}" databaseFrom "${databaseFrom}" is missing from ${RUNNER_MANIFEST}`
+        );
+      }
+    }
   }
 }
 
@@ -238,7 +281,11 @@ export function isSiblingProduct(name) {
 
 function validateMergedService(name, runnerService, serviceConfig, productDir) {
   const usesLocalExecution = Object.values(runnerService.suites).some((suites) =>
-    suites.some((suite) => suite.framework !== "k6" || !isDalSuiteType(suite, runnerService, suites))
+    suites.some(
+      (suite) =>
+        (suite.framework && suite.framework !== "k6") ||
+        !isDalSuiteType(suite, runnerService, suites)
+    )
   );
 
   if (usesLocalExecution && !isObject(serviceConfig.local)) {
@@ -281,6 +328,7 @@ function validateMergedService(name, runnerService, serviceConfig, productDir) {
       );
     }
   }
+
 }
 
 function validateServiceConfig(name, service, configPath) {
@@ -294,6 +342,27 @@ function validateServiceConfig(name, service, configPath) {
     }
   }
 
+  if (service.databaseFrom !== undefined && typeof service.databaseFrom !== "string") {
+    throw new Error(`Service "${name}" databaseFrom must be a string`);
+  }
+
+  if (service.database !== undefined && service.databaseFrom !== undefined) {
+    throw new Error(
+      `Service "${name}" cannot define both database and databaseFrom`
+    );
+  }
+
+  if (service.envFile !== undefined && typeof service.envFile !== "string") {
+    throw new Error(`Service "${name}" envFile must be a string`);
+  }
+
+  if (
+    service.envFiles !== undefined &&
+    (!Array.isArray(service.envFiles) || service.envFiles.some((v) => typeof v !== "string"))
+  ) {
+    throw new Error(`Service "${name}" envFiles must be an array of strings`);
+  }
+
   if (service.database !== undefined) {
     if (!isObject(service.database)) {
       throw new Error(`Service "${name}" database must be an object`);
@@ -339,6 +408,12 @@ function validateServiceConfig(name, service, configPath) {
     requireString(service.local, "start", `Service "${name}" local.start`);
     requireString(service.local, "baseUrl", `Service "${name}" local.baseUrl`);
     requireString(service.local, "readyUrl", `Service "${name}" local.readyUrl`);
+    if (
+      service.local.port !== undefined &&
+      (!Number.isInteger(service.local.port) || service.local.port <= 0)
+    ) {
+      throw new Error(`Service "${name}" local.port must be a positive integer`);
+    }
     if (service.local.cwd !== undefined && typeof service.local.cwd !== "string") {
       throw new Error(`Service "${name}" local.cwd must be a string`);
     }
@@ -354,6 +429,23 @@ function validateServiceConfig(name, service, configPath) {
   }
 }
 
+function loadServiceEnv(productDir, serviceConfig) {
+  const env = {};
+  for (const envFile of getServiceEnvFiles(serviceConfig)) {
+    Object.assign(env, parseDotenv(resolveServiceCwd(productDir, envFile)));
+  }
+  return env;
+}
+
+function getServiceEnvFiles(serviceConfig) {
+  const files = [];
+  if (serviceConfig.envFile) files.push(serviceConfig.envFile);
+  if (Array.isArray(serviceConfig.envFiles)) {
+    files.push(...serviceConfig.envFiles);
+  }
+  return files;
+}
+
 function requireString(obj, key, label) {
   if (typeof obj[key] !== "string" || obj[key].length === 0) {
     throw new Error(`${label} must be a non-empty string`);

package/lib/runner.mjs

@@ -13,54 +13,36 @@ import {
 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]));
-  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;
-  }
+  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 (failed) process.exit(1);
+  if (results.some(Boolean)) process.exit(1);
 }
 
 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,
-  });
+  if (!fs.existsSync(config.stateDir)) return;
 
-  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,
-        });
-      }
-    }
+  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 });
@@ -75,8 +57,11 @@ export function showStatus(config) {
   printStateDir(config.stateDir, "  ");
 }
 
-async function runService(targetConfig, configMap, suiteType, suiteNames, opts) {
-  const suites = collectSuites(targetConfig, suiteType, suiteNames, opts.framework);
+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`
@@ -87,25 +72,25 @@ async function runService(targetConfig, configMap, suiteType, suiteNames, opts)
   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);
+  const jobs = Math.max(1, Math.min(opts.jobs || 1, suites.length));
+  const workerPlans = buildWorkerPlans(
+    targetConfig,
+    runtimeConfigs,
+    suites,
+    jobs,
+    runtimeSlot
+  );
 
-    if (needsLocalRuntime(suites)) {
-      startedServices = await startLocalServices(runtimeConfigs, targetConfig);
-    }
+  const results = await Promise.allSettled(workerPlans.map((plan) => runWorkerPlan(plan)));
+  let failed = false;
 
-    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;
+  for (const result of results) {
+    if (result.status === "rejected") {
+      failed = true;
+      console.error(result.reason);
+      continue;
     }
-  } finally {
-    await stopLocalServices(startedServices);
+    if (result.value) failed = true;
   }
 
   return failed;
@@ -119,23 +104,40 @@ function collectSuites(config, suiteType, suiteNames, frameworkFilter) {
 
   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) {
@@ -175,39 +177,310 @@ function resolveRuntimeConfigs(targetConfig, configMap) {
   return ordered;
 }
 
-async function prepareDatabases(runtimeConfigs, targetConfig) {
+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.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,
+    },
+  };
+}
+
+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);
+  }
+
+  return failed;
+}
+
+async function prepareDatabases(runtimeConfigs) {
   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 });
+    fs.mkdirSync(config.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_BRANCH_NAME: db.branchName,
       NEON_RESET: db.reset === false ? "false" : "true",
-      STATE_DIR: stateDir,
+      STATE_DIR: config.stateDir,
     });
 
-    fs.writeFileSync(path.join(stateDir, "neon_project_id"), db.projectId);
+    fs.writeFileSync(path.join(config.stateDir, "neon_project_id"), db.projectId);
   }
 }
 
-async function runMigrations(runtimeConfigs, targetConfig) {
+async function runMigrations(runtimeConfigs) {
   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);
+    const env = buildExecutionEnv(config);
+    const dbUrl = readDatabaseUrl(config.stateDir);
     if (dbUrl) env.DATABASE_URL = dbUrl;
 
-    console.log(`\n── migrate:${config.name} ──`);
+    console.log(`\n── migrate:${config.workerLabel}:${config.name} ──`);
     await execaCommand(migrate.cmd, {
       cwd: resolveServiceCwd(config.productDir, migrate.cwd),
       env,
@@ -217,17 +490,16 @@ async function runMigrations(runtimeConfigs, targetConfig) {
   }
 }
 
-async function runSeeds(runtimeConfigs, targetConfig) {
+async function runSeeds(runtimeConfigs) {
   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);
+    const env = buildExecutionEnv(config);
+    const dbUrl = readDatabaseUrl(config.stateDir);
     if (dbUrl) env.DATABASE_URL = dbUrl;
 
-    console.log(`\n── seed:${config.name} ──`);
+    console.log(`\n── seed:${config.workerLabel}:${config.name} ──`);
     await execaCommand(seed.cmd, {
       cwd: resolveServiceCwd(config.productDir, seed.cwd),
       env,
@@ -237,14 +509,13 @@ async function runSeeds(runtimeConfigs, targetConfig) {
   }
 }
 
-async function startLocalServices(runtimeConfigs, targetConfig) {
+async function startLocalServices(runtimeConfigs) {
   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);
+      const proc = await startLocalService(config);
       started.push(proc);
     }
   } catch (error) {
@@ -255,25 +526,22 @@ async function startLocalServices(runtimeConfigs, targetConfig) {
   return started;
 }
 
-async function startLocalService(config, stateDir) {
+async function startLocalService(config) {
   const cwd = resolveServiceCwd(config.productDir, config.testkit.local.cwd);
-  const env = {
-    ...process.env,
-    ...config.testkit.local.env,
-  };
-  const port = portFromUrl(config.testkit.local.baseUrl);
+  const env = buildExecutionEnv(config, config.testkit.local.env);
+  const port = config.testkit.local.port || numericPortFromUrl(config.testkit.local.baseUrl);
   if (port) {
-    env.PORT = port;
+    env.PORT = String(port);
   }
 
-  const dbUrl = readDatabaseUrl(stateDir);
+  const dbUrl = readDatabaseUrl(config.stateDir);
   if (dbUrl) {
     env.DATABASE_URL = dbUrl;
   }
 
   await assertLocalServicePortsAvailable(config);
 
-  console.log(`Starting ${config.name}: ${config.testkit.local.start}`);
+  console.log(`Starting ${config.workerLabel}:${config.name}: ${config.testkit.local.start}`);
   const child = spawn(config.testkit.local.start, {
     cwd,
     env,
@@ -281,15 +549,14 @@ async function startLocalService(config, stateDir) {
     stdio: ["ignore", "pipe", "pipe"],
   });
 
-  pipeOutput(child.stdout, `[${config.name}]`);
-  pipeOutput(child.stderr, `[${config.name}]`);
+  pipeOutput(child.stdout, `[${config.workerLabel}:${config.name}]`);
+  pipeOutput(child.stderr, `[${config.workerLabel}:${config.name}]`);
 
-  const readyTimeoutMs =
-    config.testkit.local.readyTimeoutMs || DEFAULT_READY_TIMEOUT_MS;
+  const readyTimeoutMs = config.testkit.local.readyTimeoutMs || DEFAULT_READY_TIMEOUT_MS;
 
   try {
     await waitForReady({
-      name: config.name,
+      name: `${config.workerLabel}:${config.name}`,
       url: config.testkit.local.readyUrl,
       timeoutMs: readyTimeoutMs,
       process: child,
@@ -302,9 +569,9 @@ async function startLocalService(config, stateDir) {
   return { name: config.name, child };
 }
 
-async function runSuite(targetConfig, suite, stateDir) {
+async function runSuite(targetConfig, suite) {
   if (suite.type === "dal") {
-    return runDalSuite(targetConfig, suite, stateDir);
+    return runDalSuite(targetConfig, suite);
   }
 
   if (suite.framework === "playwright") {
@@ -327,43 +594,44 @@ async function runHttpK6Suite(targetConfig, suite) {
   }
 
   let failed = false;
-  for (const file of suite.files) {
+  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: process.env,
+        env: buildExecutionEnv(targetConfig),
         stdio: "inherit",
       });
     } catch {
       failed = true;
     }
-  }
+  });
 
   return { failed };
 }
 
-async function runDalSuite(targetConfig, suite, stateDir) {
-  const databaseUrl = readDatabaseUrl(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;
-
-  for (const file of suite.files) {
+  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,
+        env: buildExecutionEnv(targetConfig),
         stdio: "inherit",
       });
     } catch {
       failed = true;
     }
-  }
+  });
 
   return { failed };
 }
@@ -377,17 +645,14 @@ async function runPlaywrightSuite(targetConfig, suite) {
   }
 
   const cwd = resolveServiceCwd(targetConfig.productDir, local.cwd);
-  const files = suite.files.map((file) => path.relative(cwd, path.join(targetConfig.productDir, file)));
+  const files = suite.files.map((file) =>
+    path.relative(cwd, path.join(targetConfig.productDir, file))
+  );
 
   try {
     await execa("npx", ["playwright", "test", ...files], {
       cwd,
-      env: {
-        ...process.env,
-        BASE_URL: local.baseUrl,
-        PLAYWRIGHT_HTML_OPEN: "never",
-        TESTKIT_MANAGED_SERVERS: "1",
-      },
+      env: buildPlaywrightEnv(targetConfig, local.baseUrl),
       stdio: "inherit",
     });
     return { failed: false };
@@ -442,11 +707,54 @@ function needsLocalRuntime(suites) {
   return suites.some((suite) => suite.type !== "dal");
 }
 
-function getServiceStateDir(targetConfig, serviceName) {
-  if (targetConfig.name === serviceName) {
-    return targetConfig.stateDir;
+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(targetConfig.stateDir, "deps", serviceName);
+  return path.join(workerStateDir, "deps", serviceName);
+}
+
+function buildExecutionEnv(config, extraEnv = {}) {
+  return {
+    ...process.env,
+    ...(config.testkit.serviceEnv || {}),
+    ...extraEnv,
+  };
+}
+
+function buildPlaywrightEnv(config, baseUrl) {
+  const env = 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),
+  });
+
+  const browsersPath = resolvePlaywrightBrowsersPath(env.PLAYWRIGHT_BROWSERS_PATH);
+  if (browsersPath) {
+    env.PLAYWRIGHT_BROWSERS_PATH = browsersPath;
+  }
+
+  return env;
+}
+
+function resolvePlaywrightBrowsersPath(configuredPath) {
+  const home = process.env.HOME;
+  if (home) {
+    const fallback = path.join(home, ".cache", "ms-playwright");
+    if (fs.existsSync(fallback)) {
+      return fallback;
+    }
+  }
+
+  return configuredPath;
 }
 
 function readDatabaseUrl(stateDir) {
@@ -490,14 +798,112 @@ function pipeOutput(stream, prefix) {
   });
 }
 
+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 portFromUrl(rawUrl) {
+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);
-    return url.port || null;
+    const port = Number(url.port);
+    return Number.isInteger(port) && port > 0 ? port : null;
   } catch {
     return null;
   }
@@ -517,7 +923,8 @@ async function assertLocalServicePortsAvailable(config) {
 
     if (await isPortInUse(socket)) {
       throw new Error(
-        `Cannot start "${config.name}" because ${key} is already in use. Stop the existing process and rerun testkit.`
+        `Cannot start "${config.workerLabel}:${config.name}" because ${key} is already in use. ` +
+          `Stop the existing process and rerun testkit.`
       );
     }
   }
@@ -572,3 +979,29 @@ async function isPortInUse({ host, port }) {
     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);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@elench/testkit",
-  "version": "0.1.11",
+  "version": "0.1.13",
   "description": "CLI for running manifest-defined local test suites across k6 and Playwright",
   "type": "module",
   "bin": {