@elench/testkit 0.1.36 → 0.1.38

package/lib/config/index.mjs

@@ -101,7 +101,10 @@ function normalizeServiceConfig({
 }) {
   const local = normalizeLocalConfig(name, explicitService, discoveredService, productDir);
   const envFiles = inferEnvFiles(productDir, explicitService, local);
-  const serviceEnv = loadServiceEnv(productDir, envFiles);
+  const serviceEnv = {
+    ...loadServiceEnv(productDir, envFiles),
+    ...(explicitService.env || {}),
+  };
   const database = normalizeDatabaseConfig(explicitService, name);
   const migrate = normalizeLifecycle(explicitService.migrate);
   const seed = normalizeLifecycle(explicitService.seed);
@@ -151,7 +154,10 @@ function normalizeServiceConfig({
 }
 
 function normalizeLocalConfig(name, explicitService, discoveredService, productDir) {
-  if (explicitService.local) {
+  if (Object.prototype.hasOwnProperty.call(explicitService, "local")) {
+    if (explicitService.local === false) {
+      return undefined;
+    }
     return {
       ...explicitService.local,
       cwd: explicitService.local.cwd || ".",

package/lib/runner/artifacts.mjs

@@ -7,6 +7,7 @@ import {
 } from "../timing/index.mjs";
 
 const TIMINGS_FILENAME = "timings.json";
+const RESULT_ARTIFACTS_DIRNAME = "artifacts";
 
 export function writeRunArtifact(productDir, artifact) {
   const resultsDir = path.join(productDir, ".testkit", "results");
@@ -21,6 +22,65 @@ export function writeStatusArtifact(productDir, artifact) {
   );
 }
 
+export function resetResultArtifacts(productDir) {
+  fs.rmSync(path.join(productDir, ".testkit", "results", RESULT_ARTIFACTS_DIRNAME), {
+    recursive: true,
+    force: true,
+  });
+}
+
+export function persistTaskArtifacts(productDir, task, emittedArtifacts) {
+  if (!Array.isArray(emittedArtifacts) || emittedArtifacts.length === 0) return [];
+
+  const artifactsDir = path.join(
+    productDir,
+    ".testkit",
+    "results",
+    RESULT_ARTIFACTS_DIRNAME,
+    sanitizePathSegment(task.serviceName || "service")
+  );
+  fs.mkdirSync(artifactsDir, { recursive: true });
+
+  return emittedArtifacts.map((artifact, index) => {
+    const fileName = `task-${task.id}-${String(index + 1).padStart(2, "0")}-${sanitizePathSegment(artifact.name || "artifact")}.json`;
+    const relativePath = path.join(
+      ".testkit",
+      "results",
+      RESULT_ARTIFACTS_DIRNAME,
+      sanitizePathSegment(task.serviceName || "service"),
+      fileName
+    );
+    const absolutePath = path.join(productDir, relativePath);
+    const payload = {
+      schemaVersion: 1,
+      source: "testkit-runtime-artifact",
+      service: task.serviceName,
+      suite: {
+        key: task.suiteKey,
+        name: task.suiteName,
+        type: task.type,
+      },
+      file: task.file,
+      taskId: task.id,
+      index,
+      name: artifact.name,
+      kind: artifact.kind || null,
+      summary: artifact.summary || null,
+      contentType: artifact.contentType || "application/json",
+      emittedAt: artifact.emittedAt || null,
+      data: artifact.data,
+    };
+    fs.writeFileSync(absolutePath, `${JSON.stringify(payload, null, 2)}\n`);
+    return {
+      name: payload.name,
+      kind: payload.kind,
+      summary: payload.summary,
+      contentType: payload.contentType,
+      path: normalizePath(relativePath),
+    };
+  });
+}
+
 export function loadTimings(productDir) {
   const filePath = path.join(productDir, ".testkit", TIMINGS_FILENAME);
   if (!fs.existsSync(filePath)) {
@@ -41,3 +101,15 @@ export function saveTimings(productDir, timings, updates) {
   fs.mkdirSync(rootDir, { recursive: true });
   fs.writeFileSync(path.join(rootDir, TIMINGS_FILENAME), JSON.stringify(next, null, 2));
 }
+
+function sanitizePathSegment(value) {
+  return String(value)
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9._-]+/g, "-")
+    .replace(/^-+|-+$/g, "") || "artifact";
+}
+
+function normalizePath(filePath) {
+  return filePath.split(path.sep).join("/");
+}

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

@@ -3,6 +3,8 @@ import path from "path";
 import { execa } from "execa";
 import { bundleK6File } from "../bundler/index.mjs";
 import { resolveK6Binary } from "../config/index.mjs";
+import { persistTaskArtifacts } from "./artifacts.mjs";
+import { RUNTIME_ARTIFACT_MARKER } from "../runtime-src/k6/artifacts.js";
 import { determineDefaultRuntimeFailure } from "./default-runtime-errors.mjs";
 import { formatBatchDescriptor } from "./formatting.mjs";
 import { buildExecutionEnv } from "./template.mjs";
@@ -85,10 +87,17 @@ export async function runDefaultRuntimeTask(targetConfig, task, args, lifecycle,
     }
   );
 
-  if (result.stdout) process.stdout.write(result.stdout);
-  if (result.stderr) process.stderr.write(result.stderr);
+  const stdout = parseDefaultRuntimeOutput(result.stdout || "");
+  const stderr = parseDefaultRuntimeOutput(result.stderr || "");
+  if (stdout.visibleOutput) process.stdout.write(stdout.visibleOutput);
+  if (stderr.visibleOutput) process.stderr.write(stderr.visibleOutput);
 
   const summary = readDefaultRuntimeSummary(summaryFile);
+  const runtimeArtifacts = persistTaskArtifacts(
+    targetConfig.productDir,
+    task,
+    [...stdout.artifacts, ...stderr.artifacts]
+  );
   const runtimeError = determineDefaultRuntimeFailure(result, summary, firstLine);
   const finishedAt = Date.now();
 
@@ -99,6 +108,7 @@ export async function runDefaultRuntimeTask(targetConfig, task, args, lifecycle,
     durationMs: finishedAt - startedAt,
     startedAt,
     finishedAt,
+    artifacts: runtimeArtifacts,
   };
 }
 
@@ -117,3 +127,42 @@ export function readDefaultRuntimeSummary(filePath) {
     return null;
   }
 }
+
+function parseDefaultRuntimeOutput(output) {
+  if (!output) {
+    return {
+      visibleOutput: "",
+      artifacts: [],
+    };
+  }
+
+  const visibleLines = [];
+  const artifacts = [];
+  for (const line of output.split(/\r?\n/)) {
+    const rawPayload = extractArtifactPayload(line);
+    if (rawPayload !== null) {
+      try {
+        artifacts.push(JSON.parse(decodeURIComponent(rawPayload)));
+      } catch {
+        visibleLines.push(line);
+      }
+      continue;
+    }
+    visibleLines.push(line);
+  }
+
+  return {
+    visibleOutput: visibleLines.join("\n"),
+    artifacts,
+  };
+}
+
+function extractArtifactPayload(line) {
+  if (line.startsWith(RUNTIME_ARTIFACT_MARKER)) {
+    return line.slice(RUNTIME_ARTIFACT_MARKER.length);
+  }
+
+  const k6ConsoleMatch = line.match(/msg="TESTKIT_ARTIFACT:(.*)"(?:\s+source=console)?$/);
+  if (!k6ConsoleMatch) return null;
+  return k6ConsoleMatch[1];
+}

package/lib/runner/orchestrator.mjs

@@ -16,7 +16,13 @@ import {
 } from "./results.mjs";
 import { buildRunArtifact, buildStatusArtifact } from "./reporting.mjs";
 import { buildRunSummaryLines, formatError } from "./formatting.mjs";
-import { loadTimings, saveTimings, writeRunArtifact, writeStatusArtifact } from "./artifacts.mjs";
+import {
+  loadTimings,
+  resetResultArtifacts,
+  saveTimings,
+  writeRunArtifact,
+  writeStatusArtifact,
+} from "./artifacts.mjs";
 import {
   cleanupRunById,
   cleanupRuns,
@@ -39,6 +45,7 @@ export async function runAll(configs, typeValues, suiteSelectors, opts, allConfi
   const telemetry = configs[0]?.telemetry || null;
   const productDir = configs[0]?.productDir || process.cwd();
   await cleanupStaleRuns(productDir);
+  resetResultArtifacts(productDir);
   const metadata = {
     git: collectGitMetadata(productDir),
     host: {

package/lib/runner/results.mjs

@@ -45,6 +45,7 @@ export function buildServiceTrackers(servicePlans, startedAt) {
               error: null,
               reason: null,
               status: "not_run",
+              artifacts: [],
             },
           ];
         }),
@@ -57,6 +58,7 @@ export function buildServiceTrackers(servicePlans, startedAt) {
             error: null,
             reason: file.reason,
             status: "skipped",
+            artifacts: [],
           },
         ]),
       ]),
@@ -118,6 +120,7 @@ export function recordTaskOutcome(trackers, task, outcome, finishedAt = Date.now
     existingFileResult.error = outcome.error;
     existingFileResult.reason = outcome.reason || null;
     existingFileResult.status = status;
+    existingFileResult.artifacts = Array.isArray(outcome.artifacts) ? outcome.artifacts : [];
   } else {
     suite.fileResultsByPath.set(normalizedPath, {
       path: normalizedPath,
@@ -126,6 +129,7 @@ export function recordTaskOutcome(trackers, task, outcome, finishedAt = Date.now
       error: outcome.error,
       reason: outcome.reason || null,
       status,
+      artifacts: Array.isArray(outcome.artifacts) ? outcome.artifacts : [],
     });
   }
   if (status === "failed" && !suite.failedFileSet.has(task.file)) {
@@ -243,6 +247,9 @@ function finalizeSuite(suite) {
       durationMs: file.durationMs,
       error: file.error,
       reason: file.reason,
+      ...(Array.isArray(file.artifacts) && file.artifacts.length > 0
+        ? { artifacts: file.artifacts }
+        : {}),
     }));
 
   return {

package/lib/runner/state-io.mjs

@@ -5,6 +5,29 @@ export function readDatabaseUrl(stateDir) {
   return readStateValue(path.join(stateDir, "database_url"));
 }
 
+export function readDatabaseInfo(stateDir) {
+  return parseDatabaseUrl(readDatabaseUrl(stateDir));
+}
+
+export function parseDatabaseUrl(databaseUrl) {
+  if (!databaseUrl) return null;
+
+  try {
+    const parsed = new URL(databaseUrl);
+    const port = Number(parsed.port || "5432");
+    return {
+      url: databaseUrl,
+      host: parsed.hostname,
+      port: Number.isInteger(port) && port > 0 ? port : 5432,
+      database: parsed.pathname.replace(/^\//, ""),
+      user: decodeURIComponent(parsed.username || ""),
+      password: decodeURIComponent(parsed.password || ""),
+    };
+  } catch {
+    return null;
+  }
+}
+
 export function readStateValue(filePath) {
   if (!fs.existsSync(filePath)) return null;
   return fs.readFileSync(filePath, "utf8").trim();

package/lib/runner/template.mjs

@@ -1,4 +1,5 @@
 import path from "path";
+import { readDatabaseInfo } from "./state-io.mjs";
 
 const PORT_STRIDE = 100;
 
@@ -6,6 +7,14 @@ export function resolveWorkerRuntimeConfigs(targetConfig, runtimeConfigs, worker
   const portMap = buildPortMap(runtimeConfigs, workerId);
   const baseUrlByService = new Map();
   const readyUrlByService = new Map();
+  const stateDirByService = new Map();
+
+  for (const config of runtimeConfigs) {
+    stateDirByService.set(
+      config.name,
+      resolveServiceStateDir(workerStateDir, targetConfig.name, config)
+    );
+  }
 
   for (const config of runtimeConfigs) {
     if (!config.testkit.local) continue;
@@ -16,6 +25,7 @@ export function resolveWorkerRuntimeConfigs(targetConfig, runtimeConfigs, worker
         portMap,
         baseUrlByService,
         readyUrlByService,
+        stateDirByService,
       })
     );
     readyUrlByService.set(
@@ -25,6 +35,7 @@ export function resolveWorkerRuntimeConfigs(targetConfig, runtimeConfigs, worker
         portMap,
         baseUrlByService,
         readyUrlByService,
+        stateDirByService,
       })
     );
   }
@@ -51,6 +62,7 @@ export function resolveWorkerRuntimeConfigs(targetConfig, runtimeConfigs, worker
       portMap,
       baseUrlByService,
       readyUrlByService,
+      stateDirByService,
       urlMappings
     )
   );
@@ -90,6 +102,7 @@ export function resolveWorkerConfig(
   portMap,
   baseUrlByService,
   readyUrlByService,
+  stateDirByService,
   urlMappings
 ) {
   const stateDir = resolveServiceStateDir(workerStateDir, targetConfig.name, config);
@@ -101,6 +114,7 @@ export function resolveWorkerConfig(
     portMap,
     baseUrlByService,
     readyUrlByService,
+    stateDirByService,
     urlMappings,
   };
 
@@ -143,12 +157,7 @@ export function resolveWorkerConfig(
         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),
-          ])
-        ),
+        env: { ...(config.testkit.local.env || {}) },
       }
     : undefined;
 
@@ -163,6 +172,7 @@ export function resolveWorkerConfig(
       database,
       migrate,
       seed,
+      templateContext: context,
       local,
     },
   };
@@ -182,10 +192,11 @@ export function getWorkerServiceStateDir(workerStateDir, targetName, serviceName
 
 export function buildExecutionEnv(config, extraEnv = {}, processEnv = process.env) {
   const inheritedEnv = { ...processEnv };
+  const templateContext = config.testkit?.templateContext;
   const env = {
     ...inheritedEnv,
-    ...(config.testkit.serviceEnv || {}),
-    ...extraEnv,
+    ...resolveEnvTemplates(config.testkit.serviceEnv || {}, templateContext),
+    ...resolveEnvTemplates(extraEnv, templateContext),
     TESTKIT_ACTIVE: "1",
     ...(config.workerId ? { TESTKIT_WORKER_ID: String(config.workerId) } : {}),
   };
@@ -266,12 +277,61 @@ export function resolveTemplateString(value, context) {
         }
         return readyUrl;
       }
+      case "dbUrl":
+      case "dbHost":
+      case "dbPort":
+      case "dbName":
+      case "dbUser":
+      case "dbPassword": {
+        const serviceName = arg || context.serviceName;
+        return resolveDatabaseTemplateValue(token, serviceName, context);
+      }
       default:
         throw new Error(`Unsupported template token "{${token}${arg ? `:${arg}` : ""}}"`);
     }
   });
 }
 
+function resolveEnvTemplates(values, templateContext) {
+  return Object.fromEntries(
+    Object.entries(values || {}).map(([key, value]) => [
+      key,
+      typeof value === "string" && templateContext ? finalizeString(value, templateContext) : value,
+    ])
+  );
+}
+
+function resolveDatabaseTemplateValue(token, serviceName, context) {
+  const stateDir = context.stateDirByService?.get(serviceName);
+  if (!stateDir) {
+    throw new Error(`Unknown database placeholder for service "${serviceName}"`);
+  }
+
+  const info = readDatabaseInfo(stateDir);
+  if (!info) {
+    throw new Error(
+      `Database placeholder "{${token}:${serviceName}}" is unavailable before "${serviceName}" database preparation`
+    );
+  }
+
+  switch (token) {
+    case "dbUrl":
+      return info.url;
+    case "dbHost":
+      return info.host;
+    case "dbPort":
+      return String(info.port);
+    case "dbName":
+      return info.database;
+    case "dbUser":
+      return info.user;
+    case "dbPassword":
+      return info.password;
+    default:
+      throw new Error(`Unsupported database placeholder "{${token}:${serviceName}}"`);
+  }
+}
+
 export function rewriteUrlPort(rawUrl, port) {
   try {
     const original = new URL(rawUrl);

package/lib/runner/template.test.mjs

@@ -1,3 +1,6 @@
+import fs from "fs";
+import os from "os";
+import path from "path";
 import { describe, expect, it } from "vitest";
 import {
   buildExecutionEnv,
@@ -51,6 +54,14 @@ describe("runner-template", () => {
   });
 
   it("resolves template strings and URL rewrites", () => {
+    const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "testkit-template-"));
+    const apiStateDir = path.join(tmpDir, "api");
+    fs.mkdirSync(apiStateDir, { recursive: true });
+    fs.writeFileSync(
+      path.join(apiStateDir, "database_url"),
+      "postgres://testkit:testkit@127.0.0.1:55432/onix_db"
+    );
+
     const context = {
       workerId: 2,
       targetName: "frontend",
@@ -62,11 +73,15 @@ describe("runner-template", () => {
       ]),
       baseUrlByService: new Map([["api", "http://127.0.0.1:3100"]]),
       readyUrlByService: new Map([["api", "http://127.0.0.1:3100/health"]]),
+      stateDirByService: new Map([["api", apiStateDir]]),
       urlMappings: [["http://api:3000", "http://127.0.0.1:3100"]],
     };
 
     expect(resolveTemplateString("{worker}:{target}:{service}", context)).toBe("2:frontend:frontend");
     expect(resolveTemplateString("{baseUrl:api}", context)).toBe("http://127.0.0.1:3100");
+    expect(resolveTemplateString("{dbHost:api}:{dbPort:api}/{dbName:api}", context)).toBe(
+      "127.0.0.1:55432/onix_db"
+    );
     expect(finalizeString("API={baseUrl:api} OLD=http://api:3000", context)).toBe(
       "API=http://127.0.0.1:3100 OLD=http://127.0.0.1:3100"
     );
@@ -76,6 +91,7 @@ describe("runner-template", () => {
   });
 
   it("builds worker runtime configs and execution env", () => {
+    const workerStateDir = fs.mkdtempSync(path.join(os.tmpdir(), "testkit-worker-"));
     const api = makeRuntimeConfig("api", {
       cwd: ".",
       start: "npm run api",
@@ -98,26 +114,29 @@ describe("runner-template", () => {
       readyUrl: "http://127.0.0.1:{port}",
       env: {
         NEXT_PUBLIC_API_URL: "{baseUrl:api}",
+        ONIX_DB_HOST: "{dbHost:api}",
       },
     });
 
-    const resolved = resolveWorkerRuntimeConfigs(frontend, [api, frontend], 2, "/tmp/w2");
+    const resolved = resolveWorkerRuntimeConfigs(frontend, [api, frontend], 2, workerStateDir);
     expect(resolved[0].testkit.local.port).toBe(3100);
-    expect(resolved[1].testkit.local.env.NEXT_PUBLIC_API_URL).toBe("http://127.0.0.1:3100");
-    expect(resolveServiceStateDir("/tmp/w2", "frontend", api)).toBe("/tmp/w2/deps/api");
-    expect(getWorkerServiceStateDir("/tmp/w2", "frontend", "frontend")).toBe("/tmp/w2");
+    expect(resolved[1].testkit.local.env.NEXT_PUBLIC_API_URL).toBe("{baseUrl:api}");
+    expect(resolveServiceStateDir(workerStateDir, "frontend", api)).toBe(
+      `${workerStateDir}/deps/api`
+    );
+    expect(getWorkerServiceStateDir(workerStateDir, "frontend", "frontend")).toBe(workerStateDir);
+
+    fs.mkdirSync(path.join(workerStateDir, "deps", "api"), { recursive: true });
+    fs.writeFileSync(
+      path.join(workerStateDir, "deps", "api", "database_url"),
+      "postgres://testkit:testkit@127.0.0.1:55432/onix_db"
+    );
 
     expect(
       buildExecutionEnv(
+        resolved[1],
         {
-          workerId: 2,
-          testkit: {
-            serviceEnv: {
-              API_KEY: "secret",
-            },
-          },
-        },
-        {
+          ...resolved[1].testkit.local.env,
           DATABASE_URL: "gone",
         },
         {
@@ -126,7 +145,8 @@ describe("runner-template", () => {
       )
     ).toEqual({
       PATH: "/usr/bin",
-      API_KEY: "secret",
+      NEXT_PUBLIC_API_URL: "http://127.0.0.1:3100",
+      ONIX_DB_HOST: "127.0.0.1",
       TESTKIT_ACTIVE: "1",
       TESTKIT_WORKER_ID: "2",
     });

package/lib/runtime/index.d.ts

@@ -23,6 +23,12 @@ export interface RuntimeOptions {
   thresholds?: Record<string, unknown>;
 }
 
+export interface RuntimeArtifactOptions {
+  contentType?: string;
+  kind?: string;
+  summary?: string;
+}
+
 export interface RuntimeEnv {
   BASE: string;
   MACHINE_ID?: string;
@@ -133,6 +139,11 @@ export declare const http: RuntimeHttpClient;
 
 export declare function file(data: unknown, filename?: string, contentType?: string): unknown;
 export declare function json<T = unknown>(response: Pick<RuntimeResponse, "body">): T;
+export declare function emitArtifact(
+  name: string,
+  data: unknown,
+  options?: RuntimeArtifactOptions
+): void;
 export declare function contains<T extends Record<string, unknown>>(
   rows: T[],
   field: keyof T | string,

package/lib/runtime/index.mjs

@@ -10,6 +10,9 @@ export function file(data, filename, contentType) {
   return rawHttp.file(data, filename, contentType);
 }
 
+export {
+  emitArtifact,
+} from "../runtime-src/k6/artifacts.js";
 export {
   allMatch,
   contains,

package/lib/runtime-src/k6/artifacts.js

@@ -0,0 +1,36 @@
+export const RUNTIME_ARTIFACT_MARKER = "TESTKIT_ARTIFACT:";
+
+export function emitArtifact(name, data, options = {}) {
+  const normalizedName = normalizeArtifactName(name);
+  const payload = encodeURIComponent(
+    JSON.stringify({
+      name: normalizedName,
+      kind: normalizeOptionalString(options.kind),
+      summary: normalizeOptionalString(options.summary),
+      contentType: normalizeContentType(options.contentType),
+      data,
+      emittedAt: new Date().toISOString(),
+    })
+  );
+  console.log(
+    `${RUNTIME_ARTIFACT_MARKER}${payload}`
+  );
+}
+
+function normalizeArtifactName(name) {
+  if (typeof name !== "string" || name.trim().length === 0) {
+    throw new Error("emitArtifact(name, data) requires a non-empty artifact name");
+  }
+  return name.trim();
+}
+
+function normalizeOptionalString(value) {
+  if (value === undefined || value === null) return null;
+  const normalized = String(value).trim();
+  return normalized.length > 0 ? normalized : null;
+}
+
+function normalizeContentType(value) {
+  const normalized = normalizeOptionalString(value);
+  return normalized || "application/json";
+}

package/lib/setup/index.d.ts

@@ -40,9 +40,10 @@ export interface ServiceConfig {
   discovery?: {
     roots?: string[];
   };
+  env?: Record<string, string>;
   envFile?: string;
   envFiles?: string[];
-  local?: {
+  local?: false | {
     baseUrl: string;
     cwd?: string;
     env?: Record<string, string>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@elench/testkit",
-  "version": "0.1.36",
+  "version": "0.1.38",
   "description": "CLI for discovering and running local HTTP, DAL, and Playwright test suites",
   "type": "module",
   "types": "./lib/index.d.ts",