@elench/testkit 0.1.37 → 0.1.39

package/lib/runner/orchestrator.mjs

@@ -35,6 +35,8 @@ import {
   safeHostname,
   safeUsername,
 } from "./metadata.mjs";
+import { resolveExecutionConfig } from "./execution-config.mjs";
+import { createStackManager } from "./stack-manager.mjs";
 import { createWorker, runWorker } from "./worker-loop.mjs";
 import { findUnmatchedRequestedFiles, isFullRunSelection } from "./selection.mjs";
 import { uploadTelemetryArtifact } from "../telemetry/index.mjs";
@@ -88,10 +90,22 @@ export async function runAll(configs, typeValues, suiteSelectors, opts, allConfi
     );
   }
 
-  const servicePlans = collectServicePlans(configs, configMap, typeValues, suiteSelectors, opts);
+  const execution = resolveExecutionConfig({
+    cli: opts,
+    repo: configs[0]?.testkit?.execution || null,
+  });
+  const servicePlans = collectServicePlans(
+    configs,
+    configMap,
+    typeValues,
+    suiteSelectors,
+    opts,
+    execution
+  );
   const trackers = buildServiceTrackers(servicePlans, startedAt);
   const executedPlans = servicePlans.filter((plan) => !plan.skipped);
   let workerCount = 0;
+  let stackCount = 0;
   let exitCode = 0;
   const lifecycle = createRunLifecycle(productDir);
   lifecycle.markRunning();
@@ -104,36 +118,46 @@ export async function runAll(configs, typeValues, suiteSelectors, opts, allConfi
       const timings = loadTimings(productDir);
       const graphs = buildRuntimeGraphs(executedPlans);
       const queue = buildTaskQueue(executedPlans, graphs, timings);
-      workerCount = Math.max(1, Math.min(opts.jobs || 1, queue.length));
-      const graphByKey = new Map(graphs.map((graph) => [graph.key, graph]));
+      workerCount = Math.max(1, Math.min(execution.workers, queue.length));
+      stackCount = execution.stackMode === "shared" ? 1 : execution.stackCount;
       const workers = Array.from({ length: workerCount }, (_unused, index) =>
         createWorker(index + 1, productDir)
       );
+      const stackManager = createStackManager({
+        productDir,
+        graphs,
+        execution,
+        lifecycle,
+      });
       const timingUpdates = [];
 
-      const workerResults = await Promise.allSettled(
-        workers.map((worker) =>
-          runWorker(
-            worker,
-            queue,
-            graphByKey,
-            trackers,
-            timingUpdates,
-            lifecycle,
-            claimNextBatch,
-            recordTaskOutcome,
-            recordGraphError
+      try {
+        const workerResults = await Promise.allSettled(
+          workers.map((worker) =>
+            runWorker(
+              worker,
+              queue,
+              stackManager,
+              trackers,
+              timingUpdates,
+              lifecycle,
+              claimNextBatch,
+              recordTaskOutcome,
+              recordGraphError
+            )
           )
-        )
-      );
+        );
 
-      for (const result of workerResults) {
-        if (result.status === "rejected") {
-          const message = formatError(result.reason);
-          for (const tracker of trackers.values()) {
-            if (!tracker.skipped) addTrackerError(tracker, message);
+        for (const result of workerResults) {
+          if (result.status === "rejected") {
+            const message = formatError(result.reason);
+            for (const tracker of trackers.values()) {
+              if (!tracker.skipped) addTrackerError(tracker, message);
+            }
           }
         }
+      } finally {
+        await stackManager.cleanupAll();
       }
 
       saveTimings(productDir, timings, timingUpdates);
@@ -148,8 +172,9 @@ export async function runAll(configs, typeValues, suiteSelectors, opts, allConfi
       results,
       startedAt,
       finishedAt,
-      requestedJobs: opts.jobs || 1,
+      execution,
       workerCount,
+      stackCount,
       typeValues,
       suiteSelectors,
       fileNames: requestedFiles,
@@ -192,7 +217,7 @@ export async function runAll(configs, typeValues, suiteSelectors, opts, allConfi
   }
 }
 
-function collectServicePlans(configs, configMap, typeValues, suiteSelectors, opts) {
+function collectServicePlans(configs, configMap, typeValues, suiteSelectors, opts, execution) {
   return configs.map((config) => {
     console.log(`\n══ ${config.name} ══`);
     const suites = applyShard(
@@ -206,6 +231,7 @@ function collectServicePlans(configs, configMap, typeValues, suiteSelectors, opt
       );
       return {
         config,
+        execution,
         skipped: true,
         suites: [],
         runtimeConfigs: [],
@@ -217,6 +243,7 @@ function collectServicePlans(configs, configMap, typeValues, suiteSelectors, opt
     const runtimeConfigs = resolveRuntimeConfigs(config, configMap);
     return {
       config,
+      execution,
       skipped: false,
       suites,
       runtimeConfigs,

package/lib/runner/planning.mjs

@@ -4,6 +4,7 @@ import {
   matchesSuiteSelectors,
   suiteSelectionType,
 } from "./suite-selection.mjs";
+import { resolveBatchAccessMode, resolveBatchStackMode } from "./execution-config.mjs";
 
 const TYPE_ORDER = ["dal", "integration", "e2e", "load"];
 
@@ -63,7 +64,6 @@ export function collectSuites(config, typeValues, suiteSelectors, fileNames = []
         selectedSuiteFiles,
         opts
       );
-
       suites.push({
         ...suite,
         files,
@@ -181,6 +181,7 @@ export function buildTaskQueue(servicePlans, graphs, timings) {
 
     for (const suite of plan.suites) {
       for (const file of suite.files) {
+        const stackMode = resolveTaskStackMode(plan.config, plan.execution, suite, file);
         const timingKey = buildTimingKey(plan.config.name, suite, file);
         tasks.push({
           id: nextId,
@@ -191,6 +192,12 @@ export function buildTaskQueue(servicePlans, graphs, timings) {
           suiteName: suite.name,
           type: suite.type,
           framework: suite.framework,
+          stackMode,
+          accessMode: resolveBatchAccessMode({
+            framework: suite.framework,
+            type: suite.type,
+            stackMode,
+          }),
           orderIndex: suite.orderIndex,
           file,
           timingKey,
@@ -233,7 +240,9 @@ export function claimNextBatch(queue, preferredGraphKey) {
         candidate.type === seed.type &&
         candidate.graphKey === seed.graphKey &&
         candidate.targetName === seed.targetName &&
-        candidate.suiteKey === seed.suiteKey
+        candidate.suiteKey === seed.suiteKey &&
+        candidate.stackMode === seed.stackMode &&
+        candidate.accessMode === seed.accessMode
       ) {
         tasks.push(candidate);
         queue.splice(cursor, 1);
@@ -253,6 +262,8 @@ export function claimNextBatch(queue, preferredGraphKey) {
     targetName: seed.targetName,
     framework: seed.framework,
     type: seed.type,
+    stackMode: seed.stackMode,
+    accessMode: seed.accessMode,
     tasks,
   };
 }
@@ -313,6 +324,35 @@ function applySkipRules(config, displayType, suiteName, files, opts = {}) {
   };
 }
 
+function resolveSuiteStackMode(config, displayType, suiteName) {
+  const defaultStackMode = config.testkit.execution.stackMode;
+  const rules = config.testkit.serviceExecution?.suites || [];
+  const matchedRule = rules.find((rule) =>
+    matchesSuiteSelectors(displayType, suiteName, [rule.selector])
+  );
+  return resolveBatchStackMode(defaultStackMode, matchedRule?.stackMode || null);
+}
+
+function resolveTaskStackMode(config, execution, suite, file) {
+  const effectiveExecution = execution || config.testkit.execution;
+  const normalizedFile = normalizePathSeparators(file);
+  const fileOverride = config.testkit.serviceExecution?.fileStackModeByPath?.get(normalizedFile);
+  if (fileOverride) {
+    return resolveBatchStackMode(effectiveExecution.stackMode, fileOverride);
+  }
+  return resolveSuiteStackMode(
+    {
+      ...config,
+      testkit: {
+        ...config.testkit,
+        execution: effectiveExecution,
+      },
+    },
+    suite.displayType,
+    suite.name
+  );
+}
+
 export function buildGraphDirName(runtimeNames) {
   const slug = runtimeNames.map(slugSegment).join("__");
   return slug.length > 0 ? slug : "graph";

package/lib/runner/planning.test.mjs

@@ -10,12 +10,24 @@ import {
 } from "./planning.mjs";
 
 function makeConfig(name, extras = {}) {
+  const providedTestkit = extras.testkit || {};
   return {
     name,
     suites: extras.suites || {},
-    testkit: {
-      dependsOn: extras.dependsOn || [],
-    },
+      testkit: {
+        dependsOn: extras.dependsOn || providedTestkit.dependsOn || [],
+        execution: providedTestkit.execution || {
+          workers: 1,
+          stackMode: "isolated",
+          stackCount: 1,
+        },
+        serviceExecution: providedTestkit.serviceExecution || {
+          suites: [],
+          files: [],
+          fileStackModeByPath: new Map(),
+        },
+        ...providedTestkit,
+      },
     ...extras,
   };
 }
@@ -55,6 +67,17 @@ describe("runner-planning", () => {
           },
         ],
       },
+      testkit: {
+        dependsOn: [],
+        execution: {
+          workers: 1,
+          stackMode: "shared",
+          stackCount: 1,
+        },
+        serviceExecution: {
+          suites: [],
+        },
+      },
     });
 
     expect(collectSuites(config, ["int"], [], [])[0]).toMatchObject({
@@ -100,6 +123,14 @@ describe("runner-planning", () => {
       },
       testkit: {
         dependsOn: [],
+        execution: {
+          workers: 1,
+          stackMode: "shared",
+          stackCount: 1,
+        },
+        serviceExecution: {
+          suites: [],
+        },
         skip: {
           fileReasonByPath: new Map([
             ["__testkit__/billing/a.int.testkit.ts", "Billing is stubbed"],
@@ -136,6 +167,90 @@ describe("runner-planning", () => {
     ]);
   });
 
+  it("applies file-level stack isolation overrides within the same suite", () => {
+    const api = makeConfig("api", {
+      suites: {
+        integration: [
+          {
+            name: "routes",
+            framework: "k6",
+            files: [
+              "src/api/routes/__testkit__/health.int.testkit.ts",
+              "src/api/routes/__testkit__/crawls-worker-concurrency.int.testkit.ts",
+            ],
+            orderIndex: 0,
+            weight: 2,
+            maxFileConcurrency: 1,
+          },
+        ],
+      },
+      testkit: {
+        execution: {
+          workers: 8,
+          stackMode: "shared",
+          stackCount: 1,
+        },
+        serviceExecution: {
+          suites: [],
+          files: [
+            {
+              path: "src/api/routes/__testkit__/crawls-worker-concurrency.int.testkit.ts",
+              stackMode: "isolated",
+            },
+          ],
+          fileStackModeByPath: new Map([
+            [
+              "src/api/routes/__testkit__/crawls-worker-concurrency.int.testkit.ts",
+              "isolated",
+            ],
+          ]),
+        },
+      },
+    });
+
+    const graphs = buildRuntimeGraphs([
+      {
+        config: api,
+        skipped: false,
+        runtimeConfigs: [api],
+        runtimeNames: ["api"],
+        runtimeKey: "api",
+        suites: collectSuites(api, ["int"], [], []),
+      },
+    ]);
+
+    const queue = buildTaskQueue(
+      [
+        {
+          config: api,
+          skipped: false,
+          runtimeConfigs: [api],
+          runtimeNames: ["api"],
+          runtimeKey: "api",
+          assignedGraphKey: "api",
+          suites: collectSuites(api, ["int"], [], []),
+        },
+      ],
+      graphs,
+      { files: {} }
+    );
+
+    expect(queue).toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({
+          file: "src/api/routes/__testkit__/health.int.testkit.ts",
+          stackMode: "shared",
+          accessMode: "shared",
+        }),
+        expect.objectContaining({
+          file: "src/api/routes/__testkit__/crawls-worker-concurrency.int.testkit.ts",
+          stackMode: "isolated",
+          accessMode: "exclusive",
+        }),
+      ])
+    );
+  });
+
   it("applies shards, builds graphs, queues tasks, and claims batches", () => {
     const api = makeConfig("api");
     const frontend = makeConfig("frontend");
@@ -155,6 +270,8 @@ describe("runner-planning", () => {
             orderIndex: 0,
             weight: 2,
             maxFileConcurrency: 2,
+            stackMode: "isolated",
+            accessMode: "exclusive",
           },
         ],
       },
@@ -173,6 +290,8 @@ describe("runner-planning", () => {
             orderIndex: 0,
             weight: 2,
             maxFileConcurrency: 1,
+            stackMode: "isolated",
+            accessMode: "exclusive",
           },
         ],
       },
@@ -191,6 +310,7 @@ describe("runner-planning", () => {
     const firstBatch = claimNextBatch(queue, "api|frontend");
     expect(firstBatch.tasks).toHaveLength(1);
     expect(firstBatch.framework).toBe("playwright");
+    expect(firstBatch.accessMode).toBe("exclusive");
 
     const secondBatch = claimNextBatch(queue, "api|frontend");
     expect(secondBatch.tasks).toHaveLength(1);
@@ -219,6 +339,8 @@ describe("runner-planning", () => {
             orderIndex: 0,
             weight: 3,
             maxFileConcurrency: 2,
+            stackMode: "isolated",
+            accessMode: "exclusive",
           },
         ],
       },
@@ -236,4 +358,54 @@ describe("runner-planning", () => {
     expect(secondBatch.tasks).toHaveLength(1);
     expect(secondBatch.framework).toBe("playwright");
   });
+
+  it("applies typed suite execution rules from config", () => {
+    const config = makeConfig("api", {
+      suites: {
+        integration: [{ name: "health", files: ["__testkit__/health/health.int.testkit.ts"] }],
+      },
+      testkit: {
+        dependsOn: [],
+        execution: {
+          workers: 8,
+          stackMode: "shared",
+          stackCount: 1,
+        },
+        serviceExecution: {
+          suites: [{ selector: { kind: "typed", type: "int", name: "health", raw: "int:health" }, stackMode: "isolated" }],
+        },
+      },
+    });
+
+    const graphs = buildRuntimeGraphs([
+      {
+        config,
+        skipped: false,
+        runtimeConfigs: [config],
+        runtimeNames: ["api"],
+        runtimeKey: "api",
+        suites: collectSuites(config, ["int"], [], []),
+      },
+    ]);
+    const queue = buildTaskQueue(
+      [
+        {
+          config,
+          skipped: false,
+          runtimeConfigs: [config],
+          runtimeNames: ["api"],
+          runtimeKey: "api",
+          assignedGraphKey: "api",
+          suites: collectSuites(config, ["int"], [], []),
+        },
+      ],
+      graphs,
+      { files: {} }
+    );
+
+    expect(queue[0]).toMatchObject({
+      stackMode: "isolated",
+      accessMode: "exclusive",
+    });
+  });
 });

package/lib/runner/playwright-config.test.mjs

@@ -26,7 +26,7 @@ function makeTempDir(prefix) {
 describe("runner-playwright-config", () => {
   it("uses a shard-local output directory under the state dir", async () => {
     const productDir = makeTempDir("testkit-playwright-product-");
-    const stateDir = path.join(productDir, ".testkit", "worker-3");
+    const stateDir = path.join(productDir, ".testkit", "stack-3");
     const cwd = path.join(productDir, "frontend");
     fs.mkdirSync(cwd, { recursive: true });
     fs.writeFileSync(

package/lib/runner/playwright-runner.mjs

@@ -19,7 +19,7 @@ export async function runPlaywrightBatch(targetConfig, batch, lifecycle) {
   }
 
   console.log(
-    `\n── ${targetConfig.workerLabel} playwright:${targetConfig.name} (${batch.tasks.length} file${batch.tasks.length === 1 ? "" : "s"})${formatPlaywrightBatchFiles(batch)} ──`
+    `\n── ${targetConfig.stackLabel} playwright:${targetConfig.name} (${batch.tasks.length} file${batch.tasks.length === 1 ? "" : "s"})${formatPlaywrightBatchFiles(batch)} ──`
   );
 
   const cwd = resolveServiceCwd(targetConfig.productDir, local.cwd);
@@ -41,7 +41,7 @@ export async function runPlaywrightBatch(targetConfig, batch, lifecycle) {
   );
 
   if (result.stderr) {
-    printBufferedOutput(result.stderr, `[${targetConfig.workerLabel}:${targetConfig.name}:playwright]`);
+    printBufferedOutput(result.stderr, `[${targetConfig.stackLabel}:${targetConfig.name}:playwright]`);
   }
 
   const parsed = parsePlaywrightJsonResults(result.stdout, cwd);

package/lib/runner/readiness.mjs

@@ -54,11 +54,11 @@ export async function assertLocalServicePortsAvailable(config, isPortInUse) {
       const owner = findPortOwner(config.productDir, socket);
       const ownerDetail = owner
         ? owner.active
-          ? ` Active testkit run ${formatRunSummary(owner.manifest)} owns ${key} via ${owner.service.workerLabel}:${owner.service.serviceName}.`
+          ? ` Active testkit run ${formatRunSummary(owner.manifest)} owns ${key} via ${owner.service.stackLabel}:${owner.service.serviceName}.`
           : ` Stale testkit run ${formatRunSummary(owner.manifest)} owns ${key}.`
         : "";
       throw new Error(
-        `Cannot start "${config.workerLabel}:${config.name}" because ${key} is already in use. ` +
+        `Cannot start "${config.stackLabel}:${config.name}" because ${key} is already in use. ` +
           `Stop the existing process and rerun testkit.${ownerDetail}`
       );
     }

package/lib/runner/reporting.mjs

@@ -94,8 +94,9 @@ export function buildRunArtifact({
   results,
   startedAt,
   finishedAt,
-  requestedJobs,
+  execution,
   workerCount,
+  stackCount,
   typeValues,
   suiteSelectors,
   fileNames,
@@ -133,8 +134,10 @@ export function buildRunArtifact({
       startedAt: new Date(startedAt).toISOString(),
       finishedAt: new Date(finishedAt).toISOString(),
       durationMs: finishedAt - startedAt,
-      requestedJobs,
+      workers: execution.workers,
       workerCount,
+      stackMode: execution.stackMode,
+      stackCount,
       dbBackend,
       types: typeValues,
       suiteSelectors: suiteSelectors.map((selector) => selector.raw),

package/lib/runner/reporting.test.mjs

@@ -51,8 +51,13 @@ describe("runner reporting", () => {
       results,
       startedAt: 1000,
       finishedAt: 4000,
-      requestedJobs: 2,
+      execution: {
+        workers: 2,
+        stackMode: "shared",
+        stackCount: 1,
+      },
       workerCount: 1,
+      stackCount: 1,
       typeValues: ["all"],
       suiteSelectors: [],
       fileNames: [],
@@ -75,6 +80,12 @@ describe("runner reporting", () => {
 
     expect(artifact.product.name).toBe("my-product");
     expect(artifact.schemaVersion).toBe(3);
+    expect(artifact.run).toMatchObject({
+      workers: 2,
+      workerCount: 1,
+      stackMode: "shared",
+      stackCount: 1,
+    });
     expect(artifact.summary.services).toEqual({
       total: 1,
       passed: 1,