@elench/testkit 0.1.54 → 0.1.56

package/lib/cli/viewer.mjs

@@ -16,6 +16,14 @@ export function loadLatestRunArtifact(productDir) {
   return JSON.parse(fs.readFileSync(artifactPath, "utf8"));
 }
 
+export function loadCurrentRunArtifact(productDir) {
+  const livePath = path.join(productDir, ".testkit", "results", "live.json");
+  if (fs.existsSync(livePath)) {
+    return JSON.parse(fs.readFileSync(livePath, "utf8"));
+  }
+  return loadLatestRunArtifact(productDir);
+}
+
 export function resolveFileSubject(runArtifact, selector = null, serviceFilter = null) {
   const files = collectFiles(runArtifact, serviceFilter);
   if (files.length === 0) {
@@ -108,6 +116,25 @@ export function formatFileDetail(productDir, runArtifact, subject, options = {})
     for (const line of triageLines) lines.push(`  ${line}`);
   }
 
+  const setupOperations = getSetupOperationsForService(runArtifact, subject.service.name);
+  if (setupOperations.length > 0) {
+    lines.push("");
+    lines.push("Setup:");
+    for (const operation of setupOperations.slice(0, 8)) {
+      const duration = operation.durationMs == null ? "" : ` ${formatDuration(operation.durationMs)}`;
+      const suffix = operation.summary ? ` ${operation.summary}` : "";
+      lines.push(`  ${operation.status} ${operation.stage}${duration}${suffix}`);
+      if (operation.logRef?.path) lines.push(`    ${operation.logRef.path}`);
+      if (operation.error) lines.push(`    ${operation.error}`);
+      if (operation.logRef?.path) {
+        const setupLogPath = path.join(productDir, operation.logRef.path);
+        for (const line of readLogTail(setupLogPath, 4).slice(-4)) {
+          lines.push(`    ${line}`);
+        }
+      }
+    }
+  }
+
   const artifacts = collectArtifactEntries(productDir, runArtifact, subject.file.path, subject.service.name);
   if (artifacts.length > 0) {
     lines.push("");
@@ -148,11 +175,24 @@ export function getServiceLogRefs(runArtifact, serviceName) {
   return (runArtifact.logs?.services || []).filter((entry) => entry.serviceName === serviceName);
 }
 
+export function getSetupOperationsForService(runArtifact, serviceName) {
+  return (runArtifact.setup?.operations || [])
+    .filter((entry) => entry.serviceName === serviceName)
+    .sort(
+      (left, right) =>
+        String(left.startedAt || "").localeCompare(String(right.startedAt || "")) ||
+        String(left.stage || "").localeCompare(String(right.stage || ""))
+    );
+}
+
 export function formatArtifactPreview(payload, maxLines = 6) {
   if (!payload) return ["artifact payload missing"];
   if (payload.kind === "agentic-query") {
     return formatAgenticArtifact(payload, maxLines);
   }
+  if (payload.kind === "testkit.scenario") {
+    return formatScenarioArtifact(payload, maxLines);
+  }
   if (payload.kind === "testkit.http-traces") {
     return formatHttpTraceArtifact(payload, maxLines);
   }
@@ -193,12 +233,39 @@ function formatHttpTraceArtifact(payload, maxLines) {
   return lines;
 }
 
+function formatScenarioArtifact(payload, maxLines) {
+  const artifact = payload.data || {};
+  const lines = [];
+  if (artifact.scenarioName) lines.push(`Scenario: ${artifact.scenarioName}`);
+  if (artifact.seed) lines.push(`Seed: ${artifact.seed}`);
+  const choiceEntries = Object.entries(artifact.choices || {});
+  if (choiceEntries.length > 0) {
+    lines.push(
+      `Choices: ${choiceEntries
+        .map(([key, value]) => `${key}=${formatScenarioChoiceValue(value)}`)
+        .join(", ")}`
+    );
+  }
+  const failedStep = (artifact.steps || []).find((step) => step.status === "failed");
+  if (failedStep) {
+    lines.push(`Failed Step: ${failedStep.name}`);
+  } else if (Array.isArray(artifact.steps) && artifact.steps.length > 0) {
+    lines.push(`Steps: ${artifact.steps.map((step) => step.name).join(" -> ")}`);
+  }
+  return lines.slice(0, maxLines);
+}
+
 function rankFailureDetails(details) {
   return [...(Array.isArray(details) ? details : [])].sort((left, right) => {
     return failureDetailRank(left) - failureDetailRank(right) || String(left?.key || "").localeCompare(String(right?.key || ""));
   });
 }
 
+function formatScenarioChoiceValue(value) {
+  if (typeof value === "string") return value;
+  return JSON.stringify(value);
+}
+
 function failureDetailRank(detail) {
   if (detail?.kind === "http-assertion") return 1;
   if (detail?.request && detail?.response) return 2;

package/lib/config/discovery.mjs

@@ -5,6 +5,7 @@ const TESTKIT_DIRNAME = "__testkit__";
 const DISCOVERY_RULES = [
   { suffix: ".int.testkit.ts", type: "integration", framework: "k6" },
   { suffix: ".e2e.testkit.ts", type: "e2e", framework: "k6" },
+  { suffix: ".scenario.testkit.ts", type: "scenario", framework: "k6" },
   { suffix: ".dal.testkit.ts", type: "dal", framework: "k6" },
   { suffix: ".load.testkit.ts", type: "load", framework: "k6" },
   { suffix: ".pw.testkit.ts", type: "e2e", framework: "playwright" },

package/lib/config/discovery.test.mjs

@@ -19,6 +19,7 @@ describe("filesystem-discovery", () => {
 
     writeFile(productDir, "src/api/routes/__testkit__/auth/me.int.testkit.ts");
     writeFile(productDir, "src/api/routes/__testkit__/health/ready.int.testkit.ts");
+    writeFile(productDir, "src/api/routes/__testkit__/journeys/smoke.scenario.testkit.ts");
     writeFile(productDir, "frontend/app/__testkit__/homepage/homepage.pw.testkit.ts");
 
     const suites = discoverSuites(productDir, {
@@ -46,6 +47,13 @@ describe("filesystem-discovery", () => {
         framework: "k6",
       },
     ]);
+    expect(suites.api.scenario).toEqual([
+      {
+        name: "journeys",
+        files: ["src/api/routes/__testkit__/journeys/smoke.scenario.testkit.ts"],
+        framework: "k6",
+      },
+    ]);
     expect(suites.frontend.e2e).toEqual([
       {
         name: "homepage",

package/lib/database/index.mjs

@@ -36,25 +36,25 @@ const LOCAL_POLL_INTERVAL_MS = 1_000;
 const LOCAL_DROP_DATABASE_TIMEOUT_MS = 15_000;
 const LOCAL_DROP_DATABASE_POLL_INTERVAL_MS = 250;
 
-export async function prepareDatabaseRuntime(config) {
+export async function prepareDatabaseRuntime(config, options = {}) {
   const db = config.testkit.database;
   if (!db) return;
 
   fs.mkdirSync(config.stateDir, { recursive: true });
   if (db.provider === "local") {
-    await prepareLocalDatabase(config);
+    await prepareLocalDatabase(config, options);
     return;
   }
 
   throw new Error(`Unsupported database provider "${db.provider}"`);
 }
 
-export async function captureDatabaseTemplateSnapshot(config, outputPath) {
+export async function captureDatabaseTemplateSnapshot(config, outputPath, options = {}) {
   if (!config.testkit.database || config.testkit.database.provider !== "local") {
     throw new Error(`Service "${config.name}" does not use a local testkit database`);
   }
 
-  await prepareDatabaseRuntime(config);
+  await prepareDatabaseRuntime(config, options);
   const cacheDir = getLocalServiceCacheDir(config.productDir, config.name);
   const templateDbName = readStateValue(path.join(cacheDir, "template_database_name"));
   if (!templateDbName) {
@@ -66,7 +66,41 @@ export async function captureDatabaseTemplateSnapshot(config, outputPath) {
     throw new Error(`Missing local database container for service "${config.name}"`);
   }
 
-  return captureTemplateSnapshot(config, outputPath, buildDatabaseUrl(infra, templateDbName));
+  const snapshotOperation = options.setupRegistry?.start({
+    config,
+    stage: "template:snapshot",
+    kind: "database-snapshot",
+    summary: `snapshot: ${path.relative(config.productDir, outputPath)}`,
+  });
+  try {
+    const output = await captureTemplateSnapshot(
+      config,
+      outputPath,
+      buildDatabaseUrl(infra, templateDbName),
+      {
+        reporter: options.reporter || null,
+        logRecord: snapshotOperation?._logRecord || null,
+      }
+    );
+    const finished = snapshotOperation
+      ? options.setupRegistry.finish(snapshotOperation, {
+          status: "passed",
+          summary: `snapshot: ${path.relative(config.productDir, outputPath)}`,
+        })
+      : null;
+    if (finished) options.reporter?.setupOperationFinished?.(finished);
+    return output;
+  } catch (error) {
+    const finished = snapshotOperation
+      ? options.setupRegistry.finish(snapshotOperation, {
+          status: "failed",
+          summary: `snapshot: ${path.relative(config.productDir, outputPath)}`,
+          error: error?.message || error,
+        })
+      : null;
+    if (finished) options.reporter?.setupOperationFinished?.(finished);
+    throw error;
+  }
 }
 
 export async function destroyRuntimeDatabase({ productDir, stateDir }) {
@@ -138,7 +172,7 @@ export function showServiceDatabaseStatus(productDir, serviceName) {
   return true;
 }
 
-async function prepareLocalDatabase(config) {
+async function prepareLocalDatabase(config, options = {}) {
   const db = config.testkit.database;
   const productDir = config.productDir;
   const serviceName = config.name;
@@ -154,7 +188,7 @@ async function prepareLocalDatabase(config) {
   );
 
   await withLock(path.join(lockDir, `template-${serviceName}.lock`), async () => {
-    await ensureTemplateDatabase(config, infra, cacheDir, templateFingerprint);
+    await ensureTemplateDatabase(config, infra, cacheDir, templateFingerprint, options);
   });
 
   await withLock(path.join(lockDir, `runtime-${serviceName}-${hashString(bindingKey, 10)}.lock`), async () => {
@@ -162,7 +196,7 @@ async function prepareLocalDatabase(config) {
   });
 }
 
-async function ensureTemplateDatabase(config, infra, cacheDir, templateFingerprint) {
+async function ensureTemplateDatabase(config, infra, cacheDir, templateFingerprint, options = {}) {
   const serviceName = config.name;
   const existingFingerprint = readStateValue(path.join(cacheDir, "template_fingerprint"));
   const existingDbName = readStateValue(path.join(cacheDir, "template_database_name"));
@@ -173,6 +207,12 @@ async function ensureTemplateDatabase(config, infra, cacheDir, templateFingerpri
     existingDbName &&
     (await databaseExists(infra, existingDbName))
   ) {
+    options.setupRegistry?.recordCached({
+      config,
+      stage: "template",
+      kind: "database-template",
+      summary: "template cache hit",
+    });
     writeLocalCacheState(cacheDir, infra, existingDbName, templateFingerprint);
     return;
   }
@@ -186,11 +226,45 @@ async function ensureTemplateDatabase(config, infra, cacheDir, templateFingerpri
 
   const templateUrl = buildDatabaseUrl(infra, desiredDbName);
   await createEmptyDatabase(infra, desiredDbName);
+  const templateOperation = options.setupRegistry?.start({
+    config,
+    stage: "template",
+    kind: "database-template",
+    summary: "template rebuild",
+    recordLog: false,
+  });
   try {
-    await runTemplateStage(config, "migrate", templateUrl);
-    await runTemplateStage(config, "seed", templateUrl);
-    await runTemplateStage(config, "verify", templateUrl);
+    await runTemplateStage(config, "migrate", templateUrl, {
+      reporter: options.reporter || null,
+      setupRegistry: options.setupRegistry || null,
+      parentOperation: templateOperation,
+    });
+    await runTemplateStage(config, "seed", templateUrl, {
+      reporter: options.reporter || null,
+      setupRegistry: options.setupRegistry || null,
+      parentOperation: templateOperation,
+    });
+    await runTemplateStage(config, "verify", templateUrl, {
+      reporter: options.reporter || null,
+      setupRegistry: options.setupRegistry || null,
+      parentOperation: templateOperation,
+    });
+    const finished = templateOperation
+      ? options.setupRegistry.finish(templateOperation, {
+          status: "passed",
+          summary: "template rebuild",
+        })
+      : null;
+    if (finished) options.reporter?.setupOperationFinished?.(finished);
   } catch (error) {
+    const finished = templateOperation
+      ? options.setupRegistry.finish(templateOperation, {
+          status: "failed",
+          summary: "template rebuild",
+          error: error?.message || error,
+        })
+      : null;
+    if (finished) options.reporter?.setupOperationFinished?.(finished);
     await dropDatabaseIfExists(infra, desiredDbName);
     throw error;
   }

package/lib/database/template-steps.mjs

@@ -6,8 +6,9 @@ import {
   collectConfiguredInputs,
   runConfiguredSteps,
 } from "../runner/template-steps.mjs";
+import { captureOutput } from "../runner/processes.mjs";
 
-export async function runTemplateStage(config, stageName, databaseUrl) {
+export async function runTemplateStage(config, stageName, databaseUrl, options = {}) {
   const steps = config.testkit.database?.template?.[stageName] || [];
   if (steps.length === 0) return;
 
@@ -21,6 +22,9 @@ export async function runTemplateStage(config, stageName, databaseUrl) {
     steps,
     env,
     labelPrefix: `template:${stageName}`,
+    reporter: options.reporter || null,
+    setupRegistry: options.setupRegistry || null,
+    parentOperation: options.parentOperation || null,
   });
 }
 
@@ -32,12 +36,12 @@ export function collectTemplateInputs(productDir, template = {}) {
   });
 }
 
-export async function captureTemplateSnapshot(config, outputPath, databaseUrl) {
+export async function captureTemplateSnapshot(config, outputPath, databaseUrl, options = {}) {
   const templateDbUrl = databaseUrl;
   const absoluteOutputPath = path.resolve(config.productDir, outputPath);
   fs.mkdirSync(path.dirname(absoluteOutputPath), { recursive: true });
 
-  await execa(
+  const child = execa(
     "pg_dump",
     [
       "--schema-only",
@@ -53,19 +57,54 @@ export async function captureTemplateSnapshot(config, outputPath, databaseUrl) {
         ...buildExecutionEnv(config, {}, process.env),
         DATABASE_URL: templateDbUrl,
       },
-      stdio: "inherit",
+      stdout: "pipe",
+      stderr: "pipe",
+      reject: false,
     }
   );
+  const liveWriter =
+    options.reporter?.outputMode === "debug"
+      ? (line) => options.reporter.writeDebugLine?.(line)
+      : null;
+  const logRecord = options.logRecord || null;
+  const drains = [
+    captureOutput(child.stdout, {
+      livePrefix: `[${config.runtimeLabel || config.name}:${config.name}]`,
+      liveWriter,
+      onLine(line) {
+        if (logRecord) logRecord.stream.write(`${new Date().toISOString()} [stdout] ${line}\n`);
+      },
+    }),
+    captureOutput(child.stderr, {
+      livePrefix: `[${config.runtimeLabel || config.name}:${config.name}]`,
+      liveWriter,
+      onLine(line) {
+        if (logRecord) logRecord.stream.write(`${new Date().toISOString()} [stderr] ${line}\n`);
+      },
+    }),
+  ];
+  const result = await child;
+  await Promise.all(drains);
+  if (result.exitCode !== 0) {
+    throw new Error(result.shortMessage || result.stderr || result.stdout || "pg_dump failed");
+  }
 
   sanitizeSnapshotFile(absoluteOutputPath);
   return absoluteOutputPath;
 }
 
-function sanitizeSnapshotFile(filePath) {
+export function sanitizeSnapshotFile(filePath) {
   const dump = fs.readFileSync(filePath, "utf8");
   const sanitized = dump
     .split("\n")
-    .filter((line) => line.trim() !== "SET transaction_timeout = 0;")
+    .filter((line) => {
+      const trimmed = line.trim();
+      return (
+        trimmed !== "SET transaction_timeout = 0;" &&
+        !trimmed.startsWith("\\restrict ") &&
+        !trimmed.startsWith("\\unrestrict ")
+      );
+    })
     .join("\n");
 
   if (sanitized !== dump) {

package/lib/database/template-steps.test.mjs

@@ -0,0 +1,43 @@
+import fs from "fs";
+import os from "os";
+import path from "path";
+import { afterEach, describe, expect, it } from "vitest";
+import { sanitizeSnapshotFile } from "./template-steps.mjs";
+
+const tempDirs = [];
+
+afterEach(() => {
+  while (tempDirs.length > 0) {
+    fs.rmSync(tempDirs.pop(), { recursive: true, force: true });
+  }
+});
+
+function makeTempDir(prefix) {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), prefix));
+  tempDirs.push(dir);
+  return dir;
+}
+
+describe("template snapshot sanitization", () => {
+  it("removes volatile pg_dump control lines", () => {
+    const dir = makeTempDir("testkit-template-snapshot-");
+    const filePath = path.join(dir, "schema.sql");
+    fs.writeFileSync(
+      filePath,
+      [
+        "SET statement_timeout = 0;",
+        "SET transaction_timeout = 0;",
+        "\\restrict abc123",
+        "CREATE TABLE public.widgets (id integer);",
+        "\\unrestrict abc123",
+        "",
+      ].join("\n")
+    );
+
+    sanitizeSnapshotFile(filePath);
+
+    expect(fs.readFileSync(filePath, "utf8")).toBe(
+      ["SET statement_timeout = 0;", "CREATE TABLE public.widgets (id integer);", ""].join("\n")
+    );
+  });
+});

package/lib/index.d.ts

@@ -38,6 +38,55 @@ export interface HttpSuiteContext<TSetup = unknown> {
   session: TSetup | null;
 }
 
+export interface ScenarioStepResult {
+  name: string;
+  status: "passed" | "failed";
+  startedAt?: string;
+  finishedAt?: string;
+  durationMs?: number;
+  failureCount?: number;
+  error?: string;
+}
+
+export interface ScenarioResource<TValue = unknown> {
+  get(): TValue;
+}
+
+export interface ScenarioRuntime {
+  readonly seed: string;
+  readonly scenarioName: string | null;
+  choose<TChoice extends unknown[]>(
+    name: string,
+    choices: TChoice
+  ): TChoice[number];
+  choose<TShape extends Record<string, unknown>>(
+    name: string,
+    shape: TShape
+  ): TShape;
+  maybe(name: string, probability?: number): boolean;
+  note<TValue = unknown>(name: string, value: TValue): TValue;
+  pick<TChoice extends unknown[]>(name: string, choices: TChoice): TChoice[number];
+  resource<TValue = unknown>(
+    name: string,
+    factory: () => TValue,
+    options?: { scope?: "file" | "scenario" | "step" }
+  ): ScenarioResource<TValue>;
+  step<TValue = unknown>(name: string, fn: () => TValue): TValue;
+  snapshot(): {
+    schemaVersion: number;
+    seed: string;
+    scenarioName: string | null;
+    choices: Record<string, unknown>;
+    notes: Record<string, unknown>;
+    resources: Array<{ name: string; scope: "file" | "scenario" | "step" }>;
+    steps: ScenarioStepResult[];
+  };
+}
+
+export interface ScenarioSuiteContext<TSetup = unknown> extends HttpSuiteContext<TSetup> {
+  scenario: ScenarioRuntime;
+}
+
 export interface HttpSuiteConfig<TSetup = unknown> {
   auth?: AuthAdapter<TSetup> | null;
   env?: RuntimeEnv;
@@ -68,6 +117,15 @@ export declare function defineHttpSuite<TSetup = unknown>(
   run: (context: HttpSuiteContext<TSetup>) => unknown
 ): TestkitSuite<TSetup>;
 
+export declare function defineScenarioSuite<TSetup = unknown>(
+  run: (context: ScenarioSuiteContext<TSetup>) => unknown
+): TestkitSuite<TSetup>;
+
+export declare function defineScenarioSuite<TSetup = unknown>(
+  config: HttpSuiteConfig<TSetup>,
+  run: (context: ScenarioSuiteContext<TSetup>) => unknown
+): TestkitSuite<TSetup>;
+
 export declare function defineDalSuite<TSetup = unknown>(
   run: (context: DalSuiteContext<TSetup>) => unknown
 ): TestkitSuite<TSetup>;

package/lib/index.mjs

@@ -4,6 +4,9 @@ export {
 export {
   defineHttpSuite,
 } from "./runtime-src/k6/suite.js";
+export {
+  defineScenarioSuite,
+} from "./runtime-src/k6/scenario-suite.js";
 
 export function createAuthAdapter({ setup, headers } = {}) {
   return {

package/lib/runner/artifacts.mjs

@@ -9,11 +9,20 @@ import {
 const TIMINGS_FILENAME = "timings.json";
 const RESULT_ARTIFACTS_DIRNAME = "artifacts";
 const RESULT_LOGS_DIRNAME = "logs";
+const RESULT_SETUP_DIRNAME = "setup";
+const LIVE_ARTIFACT_FILENAME = "live.json";
 
 export function writeRunArtifact(productDir, artifact) {
   const resultsDir = path.join(productDir, ".testkit", "results");
   fs.mkdirSync(resultsDir, { recursive: true });
   fs.writeFileSync(path.join(resultsDir, "latest.json"), JSON.stringify(artifact, null, 2));
+  fs.rmSync(path.join(resultsDir, LIVE_ARTIFACT_FILENAME), { force: true });
+}
+
+export function writeLiveRunArtifact(productDir, artifact) {
+  const resultsDir = path.join(productDir, ".testkit", "results");
+  fs.mkdirSync(resultsDir, { recursive: true });
+  fs.writeFileSync(path.join(resultsDir, LIVE_ARTIFACT_FILENAME), JSON.stringify(artifact, null, 2));
 }
 
 export function writeStatusArtifact(productDir, artifact) {
@@ -32,6 +41,13 @@ export function resetResultArtifacts(productDir) {
     recursive: true,
     force: true,
   });
+  fs.rmSync(path.join(productDir, ".testkit", "results", RESULT_SETUP_DIRNAME), {
+    recursive: true,
+    force: true,
+  });
+  fs.rmSync(path.join(productDir, ".testkit", "results", LIVE_ARTIFACT_FILENAME), {
+    force: true,
+  });
 }
 
 export function persistTaskArtifacts(productDir, task, emittedArtifacts) {

package/lib/runner/default-runtime-runner.mjs

@@ -95,7 +95,10 @@ export async function runDefaultRuntimeTask(
       env: buildTaskExecutionEnv(
         targetConfig,
         lease,
-        buildFileTimeoutEnv(fileTimeoutSeconds, startedAt),
+        {
+          ...buildFileTimeoutEnv(fileTimeoutSeconds, startedAt),
+          ...(task.scenarioSeed ? { TESTKIT_SCENARIO_SEED: task.scenarioSeed } : {}),
+        },
         process.env
       ),
       reject: false,

package/lib/runner/logs.mjs

@@ -2,21 +2,26 @@ import fs from "fs";
 import path from "path";
 
 const RESULT_LOGS_DIRNAME = "logs";
+const RESULT_SETUP_DIRNAME = "setup";
 
 export function createRunLogRegistry(productDir) {
-  const records = new Map();
+  const serviceRecords = new Map();
+  const setupRecords = new Map();
 
   return {
     ensureServiceLogRecord(config) {
       const key = `${config.runtimeLabel || config.name}:${config.name}`;
-      const existing = records.get(key);
+      const existing = serviceRecords.get(key);
       if (existing) return existing;
 
       const fileName = `${sanitizePathSegment(config.runtimeLabel || config.name)}__${sanitizePathSegment(config.name)}.log`;
       const relativePath = path.join(".testkit", "results", RESULT_LOGS_DIRNAME, fileName);
       const absolutePath = path.join(productDir, relativePath);
       fs.mkdirSync(path.dirname(absolutePath), { recursive: true });
-      const stream = fs.createWriteStream(absolutePath, { flags: "a" });
+      const stream = fs.createWriteStream(absolutePath, {
+        fd: fs.openSync(absolutePath, "a"),
+        flags: "a",
+      });
       const record = {
         key,
         serviceName: config.name,
@@ -25,7 +30,32 @@ export function createRunLogRegistry(productDir) {
         absolutePath,
         stream,
       };
-      records.set(key, record);
+      serviceRecords.set(key, record);
+      return record;
+    },
+    ensureSetupLogRecord(config, stage) {
+      const key = `${config.runtimeLabel || config.name}:${config.name}:${stage}`;
+      const existing = setupRecords.get(key);
+      if (existing) return existing;
+
+      const fileName = `${sanitizePathSegment(config.runtimeLabel || config.name)}__${sanitizePathSegment(config.name)}__${sanitizePathSegment(stage)}.log`;
+      const relativePath = path.join(".testkit", "results", RESULT_SETUP_DIRNAME, fileName);
+      const absolutePath = path.join(productDir, relativePath);
+      fs.mkdirSync(path.dirname(absolutePath), { recursive: true });
+      const stream = fs.createWriteStream(absolutePath, {
+        fd: fs.openSync(absolutePath, "a"),
+        flags: "a",
+      });
+      const record = {
+        key,
+        serviceName: config.name,
+        runtimeLabel: config.runtimeLabel || config.name,
+        stage,
+        path: normalizePath(relativePath),
+        absolutePath,
+        stream,
+      };
+      setupRecords.set(key, record);
       return record;
     },
     append(record, streamName, line) {
@@ -33,7 +63,7 @@ export function createRunLogRegistry(productDir) {
       record.stream.write(`${new Date().toISOString()} [${streamName}] ${line}\n`);
     },
     listServiceLogs() {
-      return [...records.values()]
+      return [...serviceRecords.values()]
         .map((record) => ({
           serviceName: record.serviceName,
           runtimeLabel: record.runtimeLabel,
@@ -45,8 +75,26 @@ export function createRunLogRegistry(productDir) {
             left.runtimeLabel.localeCompare(right.runtimeLabel)
         );
     },
+    listSetupLogs() {
+      return [...setupRecords.values()]
+        .map((record) => ({
+          serviceName: record.serviceName,
+          runtimeLabel: record.runtimeLabel,
+          stage: record.stage,
+          path: record.path,
+        }))
+        .sort(
+          (left, right) =>
+            left.serviceName.localeCompare(right.serviceName) ||
+            left.runtimeLabel.localeCompare(right.runtimeLabel) ||
+            left.stage.localeCompare(right.stage)
+        );
+    },
     closeAll() {
-      for (const record of records.values()) {
+      for (const record of serviceRecords.values()) {
+        record.stream.end();
+      }
+      for (const record of setupRecords.values()) {
         record.stream.end();
       }
     },